SDK reference

Reference for @usewire/sdk 0.3.x. The wire format mirrors the server’s /api/v1/sdk/* responses; the OpenAPI spec is the canonical contract.

Methods

Method	Blocks?	What it does
`connect(options?)`	Yes	Full connect: prompt, wait for the user to pick a container, return a `Connection`
`beginConnect(options?)`	No	Start a connect handshake, return a persistable `PendingConnection` handle
`checkConnection(pending)`	No	Single poll of a pending handshake: `Connection` when ready, `null` while pending
`getStatus(apiKey)`	No	Live container and connection snapshot
`claim(apiKey, options?)`	Yes	Mint a claim link, prompt the user, resolve when the container is permanent
`getClaimUrl(apiKey)`	No	Mint a claim link and nothing else
`disconnect(apiKey)`	No	Revoke the connection; the install identity survives

Blocking methods poll every 2 seconds with a 5-minute default timeout.

Types

TypeScript

interface Connection {
  mcpUrl: string;           // MCP endpoint, Bearer auth with apiKey
  apiUrl: string;           // REST base, same auth
  apiKey: string;           // container-scoped credential
  containerId: string;
  containerName: string;
  orgSlug: string | null;
  expiresAt: Date | null;   // non-null only for ephemeral containers
  agentId: string;
  credentialId: string;
  deviceKey: DeviceKey;     // persist to reuse the install identity
  connectedAt: Date;
  label?: string;
  installId: string;          // 0.9.0+: stable per agent, user, and container; not a credential
  agentUserId: string | null; // 0.10.0+: pairwise per agent; null on an unclaimed trial
  appUserId: string | null;   // deprecated since 0.10.0: same value as agentUserId
}

interface PendingConnection {
  userCode: string;         // show this to the user
  url: string;              // connect-screen URL
  nonce: string;
  deviceKey: DeviceKey;
  expiresAt: Date;          // handshake lapses after ~10 minutes
  label?: string;
}

interface ClaimLink {
  url: string;              // single-use, valid 30 minutes
  expiresAt: Date;
}

interface StatusSnapshot {
  container: {
    id: string;
    name: string;
    mcpEndpoint: string;
    organizationSlug: string;
    isEphemeral: boolean;
    createdAt: Date;
    ephemeralExpiresAt: Date | null;
  };
  connection: {
    id: string;
    connectedAt: Date;
    lastUsedAt: Date | null;
    label: string | null;
  };
  agent: { id: string; name: string; verified: boolean };
}

// claim() resolves with the snapshot plus a top-level expiry
interface ClaimResult extends StatusSnapshot {
  expiresAt: Date | null;   // null once permanent
}

interface DeviceKey {
  credentialId: string;     // assigned on first connect
  publicKey: string;
  privateJwk: JsonWebKey;
}

PendingConnection and DeviceKey are plain data and survive a JSON round-trip, so they can be persisted anywhere.

installId and agentUserId are what an agent that brings a manifest keeps instead of the API key, to read its installs later from its own server. appUserId is the name 0.9.0 used for agentUserId, and still holds the same value. See Installs and webhooks.

Errors

Rejected promises throw WireSdkError with a code and, when the server responded, an HTTP status.

Code	Meaning
`NOT_CONNECTED`	A method needing an apiKey was called without one
`NONCE_EXPIRED`	The connect handshake lapsed before the user finished
`POLL_TIMEOUT`	`connect()` gave up after its timeout; start a fresh connect
`CLAIM_TIMEOUT`	`claim()` gave up waiting; the link stays valid for 30 minutes
`ALREADY_CLAIMED`	The container is already permanent
`UNAUTHORIZED`	The apiKey is invalid or was revoked

Runtime support

Node 18+, Cloudflare Workers, Deno, Bun. The blocking connect() and claim() assume they can put a prompt in front of the user; in environments where they can’t, use the non-blocking primitives and present the code or link through your own surface.

Source

github.com/usewire/wire-sdk · @usewire/sdk on npm · MIT licensed.