@carrierllc/sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @carrierllc/sdk
 
-Typed client for one connectivity intent, and for the product an operator defines.
+TypeScript client for the Carrier API, the hosted MCP server, and the `carrier` CLI. `intents.create` issues one eSIM. `call` uses an OpenAPI operation id. `Mcp` speaks Streamable HTTP. `Cli` runs the binary with an argument list. `restTools`, `mcpTools`, and `cliTools` return plain tool objects. Pass `inputSchema` through the Vercel AI SDK `jsonSchema()` helper. This package does not depend on that SDK.
 
 ```ts
 import { Carrier } from "@carrierllc/sdk"
@@ -15,4 +15,24 @@ const intent = await carrier.intents.create(
 
 `intents.create` posts to `/v1/connectivity/intents`. The same idempotency key and body return the original intent. `products.create` posts to `/v1/connectivity/products`. The price on a product is catalogue data. Neither call debits a wallet.
 
-`npm install @carrierllc/sdk` works after the connectivity release on main publishes this version. Until that release, call the HTTP intent. The published tarball is the compiled `dist` build.
+```ts
+import { Cli, Mcp, restTools } from "@carrierllc/sdk"
+
+const accounts = await carrier.call("list_reseller_accounts")
+const issued = await carrier.call("create_connectivity_intent", {
+  body: { plan: "test_global_1gb" },
+  idempotencyKey: "order_123",
+})
+
+const session = new Mcp(process.env.ESIMVAULT_API_TOKEN ?? "")
+const tools = await session.listTools()
+await session.callTool("list_subscribers", { limit: 5 })
+
+const cli = new Cli()
+await cli.run(["subscribers", "list", "--limit", "5"])
+const agentTools = restTools(carrier)
+```
+
+`new Mcp(token, { auth: "bearer" })` sends an OAuth access token or a Clerk organization API key. The default sends `?TOKEN=` to `https://mcp.carrier.llc/mcp`. `Cli` never invokes a shell. Catalog entries marked `internal` do not accept a customer API key.
+
+`npm install @carrierllc/sdk@0.2.1` installs this surface. `0.1.0` only creates connectivity intents and products. The published tarball is the compiled `dist` output, including the generated operation catalog.

package/dist/adapters.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Dependency-free tool definitions for the Vercel AI SDK and other agent runtimes.
+ *
+ * Each tool has `description`, `inputSchema`, and `execute`. Pass `inputSchema`
+ * through the AI SDK `jsonSchema()` helper. This module does not import that SDK.
+ */
+import { Carrier } from "./client.js";
+import { Cli } from "./cli.js";
+import { Mcp } from "./mcp.js";
+export interface CarrierTool {
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** Same object as inputSchema, for AI SDK v4 `parameters`. */
+    parameters: Record<string, unknown>;
+    execute: (input: Record<string, unknown>) => Promise<unknown>;
+}
+/** One tool per OpenAPI operation. `execute` calls `carrier.call`. */
+export declare function restTools(carrier: Carrier): Record<string, CarrierTool>;
+/** One tool per MCP tool advertised by `session.listTools()`. */
+export declare function mcpTools(session: Mcp): Promise<Record<string, CarrierTool>>;
+/** One tool per catalogued CLI command. Extra flags go in `args`. */
+export declare function cliTools(cli: Cli): Record<string, CarrierTool>;

package/dist/adapters.js

@@ -0,0 +1,83 @@
+/**
+ * Dependency-free tool definitions for the Vercel AI SDK and other agent runtimes.
+ *
+ * Each tool has `description`, `inputSchema`, and `execute`. Pass `inputSchema`
+ * through the AI SDK `jsonSchema()` helper. This module does not import that SDK.
+ */
+import { cliCommands, operations } from "./catalog.js";
+import { CarrierError } from "./error.js";
+import { argumentsToCall, inputSchema } from "./operations.js";
+/** One tool per OpenAPI operation. `execute` calls `carrier.call`. */
+export function restTools(carrier) {
+    const tools = {};
+    for (const spec of operations()) {
+        const schema = inputSchema(spec);
+        tools[spec.id] = {
+            description: `${spec.summary} (${spec.method} ${spec.path}, ${spec.security})`,
+            inputSchema: schema,
+            parameters: schema,
+            execute: (input) => carrier.call(spec.id, argumentsToCall(spec, input)),
+        };
+    }
+    return tools;
+}
+/** One tool per MCP tool advertised by `session.listTools()`. */
+export async function mcpTools(session) {
+    const tools = {};
+    for (const advertised of await session.listTools()) {
+        if (!isRecord(advertised) || typeof advertised.name !== "string")
+            continue;
+        const name = advertised.name;
+        const schema = isRecord(advertised.inputSchema)
+            ? advertised.inputSchema
+            : { type: "object", properties: {} };
+        tools[name] = {
+            description: typeof advertised.description === "string" && advertised.description !== "" ? advertised.description : name,
+            inputSchema: schema,
+            parameters: schema,
+            execute: (input) => session.callTool(name, input),
+        };
+    }
+    return tools;
+}
+/** One tool per catalogued CLI command. Extra flags go in `args`. */
+export function cliTools(cli) {
+    const tools = {};
+    for (const command of cliCommands()) {
+        const tokens = command.invocation.split(" ").slice(1);
+        const schema = {
+            type: "object",
+            properties: {
+                args: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Flags and values after the command name.",
+                },
+            },
+            additionalProperties: false,
+        };
+        tools[`cli_${tokens.join("_")}`] = {
+            description: `${command.summary} Flags: ${flagText(command)}.`,
+            inputSchema: schema,
+            parameters: schema,
+            execute: (input) => cli.run([...tokens, ...stringArgs(input.args)]),
+        };
+    }
+    return tools;
+}
+function flagText(command) {
+    if (command.options.length === 0)
+        return "no flags";
+    return command.options.map((option) => option.flags).join(", ");
+}
+function stringArgs(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new CarrierError(400, "invalid_argument", "CLI tool args must be a list of strings.");
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/catalog.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Operation and CLI catalogs generated from the public contract.
+ */
+import type { OperationId } from "./operation-ids.js";
+export interface Param {
+    name: string;
+    required: boolean;
+}
+export interface Operation {
+    id: OperationId;
+    method: string;
+    path: string;
+    tag: string;
+    summary: string;
+    security: "bearer" | "public" | "internal" | "storefront";
+    body: boolean;
+    bodyRequired: boolean;
+    pathParams: Param[];
+    queryParams: Param[];
+    headerParams: Param[];
+}
+export interface CliOption {
+    flags: string;
+    description: string;
+    required: boolean;
+}
+export interface CliCommand {
+    invocation: string;
+    domain: string;
+    summary: string;
+    write: boolean;
+    transport: string;
+    tool: string | null;
+    restMethod: string | null;
+    restPath: string | null;
+    options: CliOption[];
+}
+export declare const HEADER_FIELDS: Record<string, string>;
+export declare const operationCatalog: Operation[];
+export declare const cliCatalog: CliCommand[];
+export declare function operations(): Operation[];
+export declare function cliCommands(): CliCommand[];
+export declare function operation(operationId: string): Operation;
+export declare function commandForArgs(args: string[]): CliCommand | undefined;

package/dist/catalog.js

@@ -0,0 +1,45 @@
+/**
+ * Operation and CLI catalogs generated from the public contract.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CarrierError } from "./error.js";
+export const HEADER_FIELDS = {
+    "Idempotency-Key": "idempotency_key",
+    "X-Idempotency-Key": "idempotency_key",
+    "X-Confirm-Token": "confirm_token",
+    "stripe-signature": "stripe_signature",
+};
+const dataDir = join(dirname(fileURLToPath(import.meta.url)), "data");
+export const operationCatalog = loadJson("operations.json");
+export const cliCatalog = loadJson("cli.json");
+const byId = new Map(operationCatalog.map((item) => [item.id, item]));
+export function operations() {
+    return operationCatalog;
+}
+export function cliCommands() {
+    return cliCatalog;
+}
+export function operation(operationId) {
+    const found = byId.get(operationId);
+    if (!found) {
+        throw new CarrierError(400, "unknown_operation", `Unknown operation ${operationId}.`);
+    }
+    return found;
+}
+export function commandForArgs(args) {
+    let best;
+    let bestLength = -1;
+    for (const command of cliCatalog) {
+        const tokens = command.invocation.split(" ").slice(1);
+        if (tokens.length > bestLength && tokens.every((token, index) => args[index] === token)) {
+            best = command;
+            bestLength = tokens.length;
+        }
+    }
+    return best;
+}
+function loadJson(name) {
+    return JSON.parse(readFileSync(join(dataDir, name), "utf8"));
+}

package/dist/cli.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Runner for the carrier CLI. Arguments are passed as a list, never through a shell.
+ */
+import { type CliCommand } from "./catalog.js";
+export interface CliResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type CliRunner = (binary: string, args: string[]) => Promise<CliResult>;
+export interface CliOptions {
+    /** Executable name. Defaults to `carrier`. */
+    binary?: string;
+    /** Replace process execution in tests. */
+    runner?: CliRunner;
+    /** Reject commands that are not in the catalog. Defaults to true. */
+    strict?: boolean;
+}
+export declare class Cli {
+    readonly binary: string;
+    private readonly runner;
+    private readonly strict;
+    constructor(options?: CliOptions);
+    /** Every command in the published catalog. */
+    commands(): CliCommand[];
+    /** Return one catalog entry, such as `carrier subscribers list`. */
+    describe(invocation: string): CliCommand;
+    /** Run carrier with args. Strict mode rejects commands missing from the catalog. */
+    run(args: string[]): Promise<CliResult>;
+}

package/dist/cli.js

@@ -0,0 +1,70 @@
+/**
+ * Runner for the carrier CLI. Arguments are passed as a list, never through a shell.
+ */
+import { spawn } from "node:child_process";
+import { cliCommands, commandForArgs } from "./catalog.js";
+import { CarrierError } from "./error.js";
+export class Cli {
+    binary;
+    runner;
+    strict;
+    constructor(options = {}) {
+        const binary = options.binary ?? "carrier";
+        if (binary.trim() === "" || binary.includes("\u0000")) {
+            throw new CarrierError(400, "invalid_cli", "The carrier binary path is not valid.");
+        }
+        this.binary = binary;
+        this.runner = options.runner ?? subprocessRunner;
+        this.strict = options.strict ?? true;
+    }
+    /** Every command in the published catalog. */
+    commands() {
+        return cliCommands();
+    }
+    /** Return one catalog entry, such as `carrier subscribers list`. */
+    describe(invocation) {
+        const found = cliCommands().find((command) => command.invocation === invocation);
+        if (!found)
+            throw new CarrierError(400, "unknown_command", `Unknown command ${invocation}.`);
+        return found;
+    }
+    /** Run carrier with args. Strict mode rejects commands missing from the catalog. */
+    async run(args) {
+        const argv = validateArgs(args);
+        if (this.strict && commandForArgs(argv) === undefined) {
+            const joined = argv.length > 0 ? argv.join(" ") : "(empty)";
+            throw new CarrierError(400, "unknown_command", `Unknown command carrier ${joined}.`);
+        }
+        return this.runner(this.binary, argv);
+    }
+}
+function validateArgs(args) {
+    for (const arg of args) {
+        if (typeof arg !== "string" || arg.includes("\u0000")) {
+            throw new CarrierError(400, "invalid_argument", "CLI arguments must be strings without NUL bytes.");
+        }
+    }
+    return [...args];
+}
+function subprocessRunner(binary, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(binary, args, { shell: false });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            const message = error.code === "ENOENT" ? `Could not run ${binary}.` : error.message;
+            reject(new CarrierError(0, "cli_not_found", message));
+        });
+        child.on("close", (code) => {
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}

package/dist/client.d.ts

@@ -1,9 +1,12 @@
 /**
  * Typed client for the connectivity API.
  *
- * `intents.create` is the call that issues one eSIM. `products.create` writes
- * a plan. Neither call debits a wallet.
+ * `intents.create` is the call that issues one eSIM. `call` reaches every
+ * public OpenAPI operation. `products.create` writes a plan. Neither call
+ * debits a wallet.
  */
+import type { OperationId } from "./operation-ids.js";
+import { type CallParams } from "./operations.js";
 import type { ConnectivityIntent, ConnectivityPlan, IdempotentRequest, IntentCreateParams, ProductCreateParams } from "./types.js";
 export interface CarrierOptions {
     /** Defaults to https://api.carrier.llc. No trailing slash required. */
@@ -22,5 +25,8 @@ export declare class Carrier {
         create: (body: ProductCreateParams, options: IdempotentRequest) => Promise<ConnectivityPlan>;
     };
     constructor(apiKey: string, options?: CarrierOptions);
+    /** Call any operation id from the public OpenAPI document. */
+    call(operationId: OperationId, params?: CallParams): Promise<unknown>;
     private post;
+    private request;
 }

package/dist/client.js

@@ -1,11 +1,14 @@
 /**
  * Typed client for the connectivity API.
  *
- * `intents.create` is the call that issues one eSIM. `products.create` writes
- * a plan. Neither call debits a wallet.
+ * `intents.create` is the call that issues one eSIM. `call` reaches every
+ * public OpenAPI operation. `products.create` writes a plan. Neither call
+ * debits a wallet.
  */
 import { CarrierError, errorFromBody } from "./error.js";
 import { requireIdempotencyKey } from "./idempotency.js";
+import { prepareCall } from "./operations.js";
+import { USER_AGENT } from "./version.js";
 export class Carrier {
     apiKey;
     baseUrl;
@@ -26,19 +29,39 @@ export class Carrier {
             create: (body, request) => this.post("/v1/connectivity/products", body, request.idempotencyKey),
         };
     }
+    /** Call any operation id from the public OpenAPI document. */
+    async call(operationId, params = {}) {
+        const prepared = prepareCall(operationId, params);
+        return this.request(prepared.method, prepared.path, prepared);
+    }
     async post(path, body, idempotencyKey) {
-        const key = requireIdempotencyKey(idempotencyKey);
+        return this.request("POST", path, { body, idempotencyKey });
+    }
+    async request(method, path, options) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        for (const [key, value] of Object.entries(options.query ?? {}))
+            url.searchParams.set(key, value);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": USER_AGENT,
+        };
+        for (const [name, value] of Object.entries(options.headers ?? {})) {
+            if (["authorization", "accept", "user-agent", "content-type", "host"].includes(name.toLowerCase())) {
+                throw new CarrierError(400, "invalid_header", `${name} is set by the client.`);
+            }
+            headers[name] = value;
+        }
+        let payload;
+        if (options.body !== undefined) {
+            payload = JSON.stringify(options.body);
+            headers["Content-Type"] = "application/json";
+        }
+        if (options.idempotencyKey !== undefined)
+            headers["Idempotency-Key"] = requireIdempotencyKey(options.idempotencyKey);
         let response;
         try {
-            response = await this.fetchImpl(`${this.baseUrl}${path}`, {
-                method: "POST",
-                headers: {
-                    Authorization: `Bearer ${this.apiKey}`,
-                    "Content-Type": "application/json",
-                    "Idempotency-Key": key,
-                },
-                body: JSON.stringify(body),
-            });
+            response = await this.fetchImpl(url.toString(), { method, headers, body: payload });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "Network request failed.";