agentsim 0.1.1

package/README.md

@@ -0,0 +1,87 @@
+# agentsim
+
+TypeScript/JavaScript SDK for AgentSIM — autonomous OTP relay for AI agents. Zero runtime dependencies. Works in Node.js 18+, Bun, Deno, and Edge runtimes.
+
+## Install
+
+```bash
+npm install agentsim
+# or: bun add agentsim
+```
+
+## Quickstart
+
+```typescript
+import { provision } from "agentsim";
+
+// Using AsyncDisposable (TypeScript 5.2+, recommended)
+await using num = await provision({ agentId: "checkout-bot", country: "US" });
+await enterPhoneNumber(num.number);            // "+14155552671"
+const otp = await num.waitForOtp({ timeout: 60 });
+await enterOtp(otp.otpCode);                   // "847291"
+// number auto-released via [Symbol.asyncDispose]
+```
+
+```typescript
+// Manual release (Node 18, no using declaration)
+const num = await provision({ agentId: "checkout-bot" });
+try {
+  const otp = await num.waitForOtp();
+} finally {
+  await num.release();
+}
+```
+
+## Auth
+
+Set `AGENTSIM_API_KEY` in your environment, or pass `apiKey` to the client constructor:
+
+```typescript
+import { AgentSimClient } from "agentsim";
+const client = new AgentSimClient({ apiKey: "asm_live_xxx" });
+```
+
+Get your API key at [agentsim.dev/dashboard](https://agentsim.dev/dashboard).
+
+## API
+
+### `provision(options)`
+
+Provisions a number and returns a `NumberSession`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `agentId` | `string` | required | Identifier for your agent |
+| `country` | `string` | `"US"` | ISO country code |
+| `ttlSeconds` | `number` | `3600` | Auto-release after N seconds |
+| `webhookUrl` | `string` | — | POST OTPs here as they arrive |
+| `apiKey` | `string` | env var | Override `AGENTSIM_API_KEY` |
+
+### `num.waitForOtp(options?)`
+
+Waits for an OTP to arrive on the provisioned number.
+
+| Option | Type | Default |
+|--------|------|---------|
+| `timeout` | `number` | `60` |
+
+Returns `{ otpCode: string, confidence: number | null, method: string | null }`.
+
+Throws `OtpTimeoutError` if no OTP arrives within `timeout` seconds.
+
+### `num.release()`
+
+Releases the number back to the pool early. Called automatically by `[Symbol.asyncDispose]`.
+
+## Error Reference
+
+| Class | When |
+|-------|------|
+| `AuthenticationError` | Missing or invalid API key |
+| `PoolExhaustedError` | No numbers available in requested country |
+| `OtpTimeoutError` | No OTP arrived within timeout |
+| `RateLimitError` | Too many requests |
+
+## Supported Countries
+
+US, GB, DE, FR, NL, EE

package/dist/client.d.ts

@@ -0,0 +1,54 @@
+export interface ProvisionOptions {
+    agentId: string;
+    country?: string;
+    serviceUrl?: string;
+    ttlSeconds?: number;
+    webhookUrl?: string;
+}
+export interface ReregistrationInfo {
+    newNumber: string;
+    country: string;
+}
+export interface OtpResult {
+    otpCode: string;
+    confidence: number | null;
+    method: string | null;
+    fromNumber: string | null;
+    receivedAt: string;
+    messageId: string | null;
+}
+export interface SmsMessage {
+    id: string;
+    fromNumber: string;
+    toNumber: string;
+    otpCode: string | null;
+    otpConfidence: string | null;
+    otpMethod: string | null;
+    otpConsumed: boolean;
+    otpConsumedAt: string | null;
+    webhookDelivered: boolean;
+    receivedAt: string;
+}
+export interface WaitForOtpOptions {
+    timeout?: number;
+    autoReroute?: boolean;
+    maxReroutes?: number;
+    onReregistrationNeeded?: (info: ReregistrationInfo) => Promise<void>;
+}
+export interface ProvisionedNumberData {
+    session_id: string;
+    number: string;
+    country: string;
+    agent_id: string;
+    status: string;
+    expires_at: string;
+}
+export declare class AgentSimClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey?: string, options?: {
+        baseUrl?: string;
+    });
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAuBD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrD,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CAkC3E"}

package/dist/client.js

@@ -0,0 +1,59 @@
+import { fromApiError, AgentSimError } from "./errors.js";
+const DEFAULT_BASE_URL = "https://api.agentsim.dev/v1";
+function getApiKey() {
+    // Support both Node.js and Deno environments
+    if (typeof process !== "undefined" && process.env["AGENTSIM_API_KEY"]) {
+        return process.env["AGENTSIM_API_KEY"];
+    }
+    if (typeof Deno !== "undefined") {
+        const key = Deno.env.get("AGENTSIM_API_KEY");
+        if (key)
+            return key;
+    }
+    return "";
+}
+function getBaseUrl() {
+    if (typeof process !== "undefined" && process.env["AGENTSIM_BASE_URL"]) {
+        return process.env["AGENTSIM_BASE_URL"];
+    }
+    return DEFAULT_BASE_URL;
+}
+export class AgentSimClient {
+    apiKey;
+    baseUrl;
+    constructor(apiKey, options) {
+        this.apiKey = apiKey ?? getApiKey();
+        this.baseUrl = (options?.baseUrl ?? getBaseUrl()).replace(/\/$/, "");
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const init = {
+            method,
+            headers: {
+                "x-api-key": this.apiKey,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        };
+        if (body !== undefined) {
+            init.body = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await fetch(url, init);
+        }
+        catch (err) {
+            throw new AgentSimError(`Network error: ${err}`, "network_error");
+        }
+        if (response.status === 204)
+            return undefined;
+        const data = await response.json().catch(() => ({}));
+        if (!response.ok) {
+            const code = typeof data["error"] === "string" ? data["error"] : "unknown_error";
+            const message = typeof data["message"] === "string" ? data["message"] : response.statusText;
+            throw fromApiError(code, message, response.status, data);
+        }
+        return data;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAuD1D,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AAEvD,SAAS,SAAS;IAChB,6CAA6C;IAC7C,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACtE,OAAO,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,MAAM,GAAG,GAAI,IAAwD,CAAC,GAAG,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;QAClG,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;IACtB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,UAAU;IACjB,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACvE,OAAO,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,MAAM,OAAO,cAAc;IACR,MAAM,CAAS;IACf,OAAO,CAAS;IAEjC,YAAY,MAAe,EAAE,OAA8B;QACzD,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,SAAS,EAAE,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,IAAY,EAAE,IAAc;QAC3D,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QACrC,MAAM,IAAI,GAAgB;YACxB,MAAM;YACN,OAAO,EAAE;gBACP,WAAW,EAAE,IAAI,CAAC,MAAM;gBACxB,cAAc,EAAE,kBAAkB;gBAClC,QAAQ,EAAE,kBAAkB;aAC7B;SACF,CAAC;QAEF,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CAAC,kBAAkB,GAAG,EAAE,EAAE,eAAe,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,SAAyB,CAAC;QAE9D,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAA4B,CAAC;QAEhF,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;YACjF,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;YAC5F,MAAM,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC3D,CAAC;QAED,OAAO,IAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client.test.d.ts.map

package/dist/client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.d.ts","sourceRoot":"","sources":["../src/client.test.ts"],"names":[],"mappings":""}

package/dist/client.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { provision, PoolExhaustedError, OtpTimeoutError } from "./index.js";
+import { AgentSimClient } from "./client.js";
+const PROVISION_RESPONSE = {
+    session_id: "sess-abc123",
+    number: "+15551234567",
+    country: "US",
+    agent_id: "test-bot",
+    status: "active",
+    expires_at: "2026-03-16T20:00:00Z",
+};
+function makeFetch(status, body) {
+    return vi.fn().mockResolvedValue({
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: String(status),
+        json: async () => body,
+    });
+}
+describe("AgentSIM TypeScript SDK", () => {
+    let client;
+    beforeEach(() => {
+        client = new AgentSimClient("test-key", {
+            baseUrl: "https://api.agentsim.io/v1",
+        });
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it("provisions a session", async () => {
+        vi.stubGlobal("fetch", makeFetch(201, PROVISION_RESPONSE));
+        const session = await provision({ agentId: "test-bot" }, client);
+        expect(session.number).toBe("+15551234567");
+        expect(session.sessionId).toBe("sess-abc123");
+    });
+    it("throws PoolExhaustedError on 503", async () => {
+        vi.stubGlobal("fetch", makeFetch(503, { error: "pool_exhausted", message: "No US numbers available" }));
+        await expect(provision({ agentId: "test-bot" }, client)).rejects.toBeInstanceOf(PoolExhaustedError);
+    });
+    it("waits for OTP", async () => {
+        vi.stubGlobal("fetch", vi
+            .fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 201,
+            statusText: "201",
+            json: async () => PROVISION_RESPONSE,
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            statusText: "200",
+            json: async () => ({
+                otp_code: "123456",
+                confidence: 0.99,
+                method: "regex",
+                from_number: "+15550000000",
+                received_at: "2026-03-16T18:00:00Z",
+                message_id: "msg-xyz",
+            }),
+        }));
+        const session = await provision({ agentId: "test-bot" }, client);
+        const result = await session.waitForOtp({ timeout: 30 });
+        expect(result.otpCode).toBe("123456");
+    });
+    it("throws OtpTimeoutError on 408", async () => {
+        vi.stubGlobal("fetch", vi
+            .fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 201,
+            statusText: "201",
+            json: async () => PROVISION_RESPONSE,
+        })
+            .mockResolvedValueOnce({
+            ok: false,
+            status: 408,
+            statusText: "408",
+            json: async () => ({
+                error: "otp_timeout",
+                message: "No OTP received within timeout",
+            }),
+        }));
+        const session = await provision({ agentId: "test-bot" }, client);
+        await expect(session.waitForOtp({ timeout: 30 })).rejects.toBeInstanceOf(OtpTimeoutError);
+    });
+    it("release calls DELETE", async () => {
+        vi.stubGlobal("fetch", vi
+            .fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 201,
+            statusText: "201",
+            json: async () => PROVISION_RESPONSE,
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 204,
+            statusText: "204",
+            json: async () => ({}),
+        }));
+        const session = await provision({ agentId: "test-bot" }, client);
+        await expect(session.release()).resolves.toBeUndefined();
+    });
+});
+//# sourceMappingURL=client.test.js.map

package/dist/client.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../src/client.test.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+export declare class AgentSimError extends Error {
+    readonly code: string;
+    readonly statusCode: number | undefined;
+    constructor(message: string, code: string, statusCode?: number);
+}
+export declare class AuthenticationError extends AgentSimError {
+    constructor(message?: string);
+}
+export declare class ForbiddenError extends AgentSimError {
+    constructor(message?: string);
+}
+export declare class PoolExhaustedError extends AgentSimError {
+    readonly country: string;
+    readonly availableCountries: string[];
+    constructor(message?: string, country?: string, availableCountries?: string[]);
+}
+export declare class SessionNotFoundError extends AgentSimError {
+    constructor(message?: string);
+}
+export declare class OtpTimeoutError extends AgentSimError {
+    constructor(message?: string);
+}
+export declare class RateLimitError extends AgentSimError {
+    constructor(message?: string);
+}
+export declare class CountryNotAllowedError extends AgentSimError {
+    readonly country: string;
+    readonly plan: string;
+    readonly allowed: string[];
+    constructor(message?: string, country?: string, plan?: string, allowed?: string[]);
+}
+export declare class ValidationError extends AgentSimError {
+    readonly details: unknown;
+    constructor(message?: string, details?: unknown);
+}
+export declare class ApiError extends AgentSimError {
+    constructor(message?: string, code?: string, statusCode?: number);
+}
+export declare function fromApiError(code: string, message: string, statusCode: number, data?: Record<string, unknown>): AgentSimError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAM/D;AAED,qBAAa,mBAAoB,SAAQ,aAAa;gBACxC,OAAO,SAAgC;CAIpD;AAED,qBAAa,cAAe,SAAQ,aAAa;gBACnC,OAAO,SAA4C;CAIhE;AAED,qBAAa,kBAAmB,SAAQ,aAAa;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE,CAAC;gBAGpC,OAAO,SAAgD,EACvD,OAAO,SAAK,EACZ,kBAAkB,GAAE,MAAM,EAAO;CAOpC;AAED,qBAAa,oBAAqB,SAAQ,aAAa;gBACzC,OAAO,SAAuB;CAI3C;AAED,qBAAa,eAAgB,SAAQ,aAAa;gBACpC,OAAO,SAA+C;CAInE;AAED,qBAAa,cAAe,SAAQ,aAAa;gBACnC,OAAO,SAAyB;CAI7C;AAED,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;gBAGzB,OAAO,SAAgD,EACvD,OAAO,SAAK,EACZ,IAAI,SAAK,EACT,OAAO,GAAE,MAAM,EAAO;CAQzB;AAED,qBAAa,eAAgB,SAAQ,aAAa;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;gBAEd,OAAO,SAAsB,EAAE,OAAO,CAAC,EAAE,OAAO;CAK7D;AAED,qBAAa,QAAS,SAAQ,aAAa;gBAC7B,OAAO,SAAsC,EAAE,IAAI,SAAmB,EAAE,UAAU,SAAM;CAIrG;AAkBD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,aAAa,CAUf"}

package/dist/errors.js

@@ -0,0 +1,97 @@
+export class AgentSimError extends Error {
+    code;
+    statusCode;
+    constructor(message, code, statusCode) {
+        super(message);
+        this.name = "AgentSimError";
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+export class AuthenticationError extends AgentSimError {
+    constructor(message = "Invalid or missing API key.") {
+        super(message, "unauthorized", 401);
+        this.name = "AuthenticationError";
+    }
+}
+export class ForbiddenError extends AgentSimError {
+    constructor(message = "API key revoked or lacking permissions.") {
+        super(message, "forbidden", 403);
+        this.name = "ForbiddenError";
+    }
+}
+export class PoolExhaustedError extends AgentSimError {
+    country;
+    availableCountries;
+    constructor(message = "No numbers available in the requested pool.", country = "", availableCountries = []) {
+        super(message, "pool_exhausted", 503);
+        this.name = "PoolExhaustedError";
+        this.country = country;
+        this.availableCountries = availableCountries;
+    }
+}
+export class SessionNotFoundError extends AgentSimError {
+    constructor(message = "Session not found.") {
+        super(message, "not_found", 404);
+        this.name = "SessionNotFoundError";
+    }
+}
+export class OtpTimeoutError extends AgentSimError {
+    constructor(message = "No OTP received within the timeout period.") {
+        super(message, "otp_timeout", 408);
+        this.name = "OtpTimeoutError";
+    }
+}
+export class RateLimitError extends AgentSimError {
+    constructor(message = "Rate limit exceeded.") {
+        super(message, "rate_limited", 429);
+        this.name = "RateLimitError";
+    }
+}
+export class CountryNotAllowedError extends AgentSimError {
+    country;
+    plan;
+    allowed;
+    constructor(message = "Country not available on your current plan.", country = "", plan = "", allowed = []) {
+        super(message, "country_not_allowed_on_plan", 403);
+        this.name = "CountryNotAllowedError";
+        this.country = country;
+        this.plan = plan;
+        this.allowed = allowed;
+    }
+}
+export class ValidationError extends AgentSimError {
+    details;
+    constructor(message = "Validation error.", details) {
+        super(message, "validation_error", 422);
+        this.name = "ValidationError";
+        this.details = details;
+    }
+}
+export class ApiError extends AgentSimError {
+    constructor(message = "An unexpected API error occurred.", code = "internal_error", statusCode = 500) {
+        super(message, code, statusCode);
+        this.name = "ApiError";
+    }
+}
+const CODE_MAP = {
+    unauthorized: (m) => new AuthenticationError(m),
+    forbidden: (m) => new ForbiddenError(m),
+    not_found: (m) => new SessionNotFoundError(m),
+    otp_timeout: (m) => new OtpTimeoutError(m),
+    rate_limited: (m) => new RateLimitError(m),
+    validation_error: (m) => new ValidationError(m),
+    country_not_allowed_on_plan: (m, d) => new CountryNotAllowedError(m, typeof d?.["country"] === "string" ? d["country"] : "", typeof d?.["plan"] === "string" ? d["plan"] : "", Array.isArray(d?.["allowed"]) ? d["allowed"] : []),
+};
+export function fromApiError(code, message, statusCode, data) {
+    if (code === "pool_exhausted") {
+        const country = typeof data?.["country"] === "string" ? data["country"] : "";
+        const availableCountries = Array.isArray(data?.["available_countries"])
+            ? data["available_countries"]
+            : [];
+        return new PoolExhaustedError(message, country, availableCountries);
+    }
+    const factory = CODE_MAP[code];
+    return factory ? factory(message, data) : new ApiError(message, code, statusCode);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { AgentSimClient } from "./client.js";
+import { NumberSession } from "./session.js";
+import type { ProvisionOptions } from "./client.js";
+export { AgentSimClient } from "./client.js";
+export { NumberSession } from "./session.js";
+export type { ProvisionOptions, OtpResult, SmsMessage, WaitForOtpOptions, ReregistrationInfo } from "./client.js";
+export { AgentSimError, AuthenticationError, ForbiddenError, PoolExhaustedError, SessionNotFoundError, OtpTimeoutError, RateLimitError, ValidationError, ApiError, } from "./errors.js";
+/**
+ * Provision a real mobile number for the given agent. Starts a billable session.
+ *
+ * **Billing:** $0.99 per session on the Builder plan. Free on Hobby (10 sessions/month limit).
+ * Sessions that end with an `OtpTimeoutError` are NOT billed.
+ *
+ * Returns a `NumberSession` implementing `AsyncDisposable` — use `await using`
+ * in TypeScript 5.2+ for automatic release, or call `num.release()` manually.
+ *
+ * @example
+ * ```ts
+ * await using num = await provision({ agentId: "checkout-bot" });
+ * const otp = await num.waitForOtp({ timeout: 60 });
+ * ```
+ */
+export declare function provision(options: ProvisionOptions, clientOrApiKey?: AgentSimClient | string): Promise<NumberSession>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAyB,MAAM,aAAa,CAAC;AAE3E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAClH,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,eAAe,EACf,QAAQ,GACT,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,gBAAgB,EACzB,cAAc,CAAC,EAAE,cAAc,GAAG,MAAM,GACvC,OAAO,CAAC,aAAa,CAAC,CAkBxB"}

package/dist/index.js

@@ -0,0 +1,38 @@
+import { AgentSimClient } from "./client.js";
+import { NumberSession } from "./session.js";
+export { AgentSimClient } from "./client.js";
+export { NumberSession } from "./session.js";
+export { AgentSimError, AuthenticationError, ForbiddenError, PoolExhaustedError, SessionNotFoundError, OtpTimeoutError, RateLimitError, ValidationError, ApiError, } from "./errors.js";
+/**
+ * Provision a real mobile number for the given agent. Starts a billable session.
+ *
+ * **Billing:** $0.99 per session on the Builder plan. Free on Hobby (10 sessions/month limit).
+ * Sessions that end with an `OtpTimeoutError` are NOT billed.
+ *
+ * Returns a `NumberSession` implementing `AsyncDisposable` — use `await using`
+ * in TypeScript 5.2+ for automatic release, or call `num.release()` manually.
+ *
+ * @example
+ * ```ts
+ * await using num = await provision({ agentId: "checkout-bot" });
+ * const otp = await num.waitForOtp({ timeout: 60 });
+ * ```
+ */
+export async function provision(options, clientOrApiKey) {
+    let client;
+    if (clientOrApiKey instanceof AgentSimClient) {
+        client = clientOrApiKey;
+    }
+    else {
+        client = new AgentSimClient(clientOrApiKey);
+    }
+    const data = await client.request("POST", "/sessions", {
+        agent_id: options.agentId,
+        ...(options.country !== undefined ? { country: options.country } : {}),
+        ...(options.serviceUrl !== undefined ? { service_url: options.serviceUrl } : {}),
+        ttl_seconds: options.ttlSeconds ?? 3600,
+        ...(options.webhookUrl ? { webhook_url: options.webhookUrl } : {}),
+    });
+    return new NumberSession(client, data);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,eAAe,EACf,QAAQ,GACT,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,OAAyB,EACzB,cAAwC;IAExC,IAAI,MAAsB,CAAC;IAE3B,IAAI,cAAc,YAAY,cAAc,EAAE,CAAC;QAC7C,MAAM,GAAG,cAAc,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,IAAI,cAAc,CAAC,cAAc,CAAC,CAAC;IAC9C,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAwB,MAAM,EAAE,WAAW,EAAE;QAC5E,QAAQ,EAAE,OAAO,CAAC,OAAO;QACzB,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,WAAW,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;QACvC,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACnE,CAAC,CAAC;IAEH,OAAO,IAAI,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AACzC,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,27 @@
+import type { AgentSimClient, OtpResult, ProvisionedNumberData, SmsMessage, WaitForOtpOptions } from "./client.js";
+export declare class NumberSession implements AsyncDisposable {
+    private readonly client;
+    private released;
+    private _number;
+    private _country;
+    readonly sessionId: string;
+    readonly agentId: string;
+    readonly expiresAt: string;
+    readonly status: string;
+    get number(): string;
+    get country(): string;
+    constructor(client: AgentSimClient, data: ProvisionedNumberData);
+    private _pollOtp;
+    /**
+     * Wait for an OTP to arrive on the provisioned number.
+     *
+     * Throws `OtpTimeoutError` if no OTP is received within the timeout period.
+     * Sessions that time out are NOT billed — the $0.99 charge applies only to
+     * successfully provisioned sessions that do not time out.
+     */
+    waitForOtp(options?: WaitForOtpOptions): Promise<OtpResult>;
+    getMessages(): Promise<SmsMessage[]>;
+    release(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,qBAAqB,EAAsB,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIvI,qBAAa,aAAc,YAAW,eAAe;IAcjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAbzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IAEzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,IAAI,MAAM,IAAI,MAAM,CAAyB;IAC7C,IAAI,OAAO,IAAI,MAAM,CAA0B;gBAG5B,MAAM,EAAE,cAAc,EACvC,IAAI,EAAE,qBAAqB;YAUf,QAAQ;IAwBtB;;;;;;OAMG;IACG,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,SAAS,CAAC;IAqD/D,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IA8BpC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAOxB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7C"}

package/dist/session.js

@@ -0,0 +1,102 @@
+import { OtpTimeoutError } from "./errors.js";
+const DEFAULT_FALLBACK_CHAIN = ["US", "GB", "DE", "FR", "NL", "EE"];
+export class NumberSession {
+    client;
+    released = false;
+    _number;
+    _country;
+    sessionId;
+    agentId;
+    expiresAt;
+    status;
+    get number() { return this._number; }
+    get country() { return this._country; }
+    constructor(client, data) {
+        this.client = client;
+        this.sessionId = data.session_id;
+        this._number = data.number;
+        this._country = data.country;
+        this.agentId = data.agent_id;
+        this.expiresAt = data.expires_at;
+        this.status = data.status;
+    }
+    async _pollOtp(timeout) {
+        const data = await this.client.request("POST", `/sessions/${this.sessionId}/wait`, { timeout_seconds: timeout });
+        return {
+            otpCode: data.otp_code,
+            confidence: data.confidence,
+            method: data.method,
+            fromNumber: data.from_number,
+            receivedAt: data.received_at,
+            messageId: data.message_id,
+        };
+    }
+    /**
+     * Wait for an OTP to arrive on the provisioned number.
+     *
+     * Throws `OtpTimeoutError` if no OTP is received within the timeout period.
+     * Sessions that time out are NOT billed — the $0.99 charge applies only to
+     * successfully provisioned sessions that do not time out.
+     */
+    async waitForOtp(options = {}) {
+        const timeout = options.timeout ?? 60;
+        const autoReroute = options.autoReroute ?? false;
+        const maxReroutes = options.maxReroutes ?? 2;
+        const onReregistrationNeeded = options.onReregistrationNeeded;
+        if (!autoReroute)
+            return this._pollOtp(timeout);
+        // Build reroute chain: remaining countries after the current one
+        const currentIdx = DEFAULT_FALLBACK_CHAIN.indexOf(this._country);
+        const rerouteChain = currentIdx >= 0
+            ? [...DEFAULT_FALLBACK_CHAIN.slice(currentIdx + 1), ...DEFAULT_FALLBACK_CHAIN.slice(0, currentIdx)]
+            : [...DEFAULT_FALLBACK_CHAIN];
+        let reroutesUsed = 0;
+        let chainIdx = 0;
+        while (true) {
+            try {
+                return await this._pollOtp(timeout);
+            }
+            catch (err) {
+                if (!(err instanceof OtpTimeoutError) ||
+                    reroutesUsed >= maxReroutes ||
+                    chainIdx >= rerouteChain.length) {
+                    throw err;
+                }
+                const nextCountry = rerouteChain[chainIdx++];
+                reroutesUsed++;
+                const rerouteData = await this.client.request("POST", `/sessions/${this.sessionId}/reroute`, { country: nextCountry });
+                this._number = rerouteData.new_number;
+                this._country = rerouteData.country;
+                if (onReregistrationNeeded) {
+                    const info = { newNumber: this._number, country: this._country };
+                    await onReregistrationNeeded(info);
+                }
+            }
+        }
+    }
+    async getMessages() {
+        const data = await this.client.request("GET", `/sessions/${this.sessionId}/messages`);
+        return data.messages.map((m) => ({
+            id: m.id,
+            fromNumber: m.from_number,
+            toNumber: m.to_number,
+            otpCode: m.otp_code,
+            otpConfidence: m.otp_confidence,
+            otpMethod: m.otp_method,
+            otpConsumed: m.otp_consumed,
+            otpConsumedAt: m.otp_consumed_at,
+            webhookDelivered: m.webhook_delivered,
+            receivedAt: m.received_at,
+        }));
+    }
+    async release() {
+        if (!this.released) {
+            this.released = true;
+            await this.client.request("DELETE", `/sessions/${this.sessionId}`);
+        }
+    }
+    async [Symbol.asyncDispose]() {
+        await this.release();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "agentsim",
+  "version": "0.1.1",
+  "description": "AgentSIM TypeScript SDK — autonomous OTP relay for AI agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc --outDir dist",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.8"
+  },
+  "keywords": ["agents", "otp", "sms", "ai", "automation"],
+  "license": "MIT",
+  "author": "AgentSIM <hello@agentsim.dev>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentsim/agentsim"
+  },
+  "homepage": "https://agentsim.dev",
+  "bugs": "https://github.com/agentsim/agentsim/issues",
+  "engines": {
+    "node": ">=18"
+  }
+}