Home / SDK / JavaScript

JavaScript SDK

Draft Interface documented; the package is not yet published and the API is not live. Also available: Python SDK.

Installation

The package name @ametios/sdk is provisional — the package is not published to npm yet. The install command and client surface below describe the planned interface. Registry publication is on the roadmap.

Illustrative referencePlanned install command. Requires Node.js 20+.
npm install @ametios/sdk

Authentication

The client reads an API key from the environment. Keys are scoped to a tenant at issuance (see API authentication). Never commit a key; load it from the environment or a secret manager.

Illustrative referenceClient construction. The endpoint URL is illustrative — no live endpoint exists in v1.
const { AmetiOS } = require("@ametios/sdk");

const client = new AmetiOS({
  apiKey: process.env.AMETIOS_API_KEY, // required
  tenant: {
    organization: "org_9f2",
    workspace: "ws_billing",
    environment: "staging",
  },
  // endpoint is illustrative; the API is not live in v1
  endpoint: "https://api.ametios.dev/v1",
});

First governed action

The walkthrough below mirrors the execution chain: propose an action, let the platform authorize it, execute the governed transaction, and collect the evidence receipt.

Illustrative referenceFirst governed action: propose → authorize → execute → receipt.
const { AmetiOS } = require("@ametios/sdk");

async function main() {
  const client = new AmetiOS({
    apiKey: process.env.AMETIOS_API_KEY,
    tenant: {
      organization: "org_9f2",
      workspace: "ws_billing",
      environment: "staging",
    },
  });

  // 1. Propose: validated against the registered action schema (stage 1).
  const proposal = await client.actions.propose({
    schema: "billing.invoice.issue",
    schemaVersion: "1.2.0",
    inputs: { customer_id: "cus_88412", amount_cents: 45000, currency: "USD" },
    expectations: { expected_value_cents: 45000, expected_cost_cents: 12, risk_tier: "low" },
  });
  console.log("proposed:", proposal.actionId);

  // 2. Authorize: deterministic policy evaluation (stage 4).
  const decision = await client.actions.authorize(proposal.actionId);
  console.log("decision:", decision.decision); // allow | deny | require-approval
  if (decision.decision === "deny") {
    console.log("denied by rule:", decision.trace.matchedRule);
    return;
  }
  if (decision.decision === "require-approval") {
    console.log("parked for approval:", decision.approval.approvalId);
    return; // a human decides; see the approval-inbox reference
  }

  // 3. Execute the governed transaction (stage 5).
  const result = await client.actions.execute(proposal.actionId);
  console.log("executed in", result.durationMs, "ms");

  // 4. Collect the evidence receipt (stage 6) and verify it locally.
  const receipt = await client.receipts.get(result.receiptId);
  const ok = client.receipts.verify(receipt);
  console.log("receipt valid:", ok, "| hash:", receipt.receiptHash);
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

Client surface

MethodDescriptionStatus
new AmetiOS(options)Construct a tenant-scoped clientDraft
client.actions.propose(input)Validate and submit an action proposalDraft
client.actions.authorize(actionId)Run deterministic policy evaluationDraft
client.actions.execute(actionId)Execute the governed transactionDraft
client.receipts.get(receiptId)Fetch an evidence receiptDraft
client.receipts.verify(receipt)Verify a receipt locally (hash recomputation)Draft
client.approvals.decide(approvalId, decision)Record a human approval decisionRoadmap

Related: Python SDK (same surface), API reference (the endpoints this SDK will wrap), quickstart (run the chain locally today).