@carrierllc/sdk 0.1.0 → 0.2.0

package/dist/idempotency.d.ts

@@ -1,2 +1,4 @@
 /** Same limits as the API, so a bad key fails before a request is sent. */
 export declare function requireIdempotencyKey(key: string | undefined): string;
+/** Reject a path segment that could escape the resource URL. */
+export declare function requirePathId(value: string, label: string): string;

package/dist/idempotency.js

@@ -15,3 +15,10 @@ export function requireIdempotencyKey(key) {
     }
     return key;
 }
+/** Reject a path segment that could escape the resource URL. */
+export function requirePathId(value, label) {
+    if (value.trim() === "" || /[/\\?#]/.test(value) || value.includes("..")) {
+        throw new CarrierError(400, "invalid_id", `${label} is not a valid id.`);
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -1,3 +1,10 @@
+export { cliTools, mcpTools, restTools, type CarrierTool } from "./adapters.js";
+export { cliCommands, operations, type CliCommand, type Operation } from "./catalog.js";
+export { Cli, type CliOptions, type CliResult, type CliRunner } from "./cli.js";
 export { Carrier, type CarrierOptions } from "./client.js";
 export { CarrierError } from "./error.js";
+export { DEFAULT_MCP_URL, Mcp, PROTOCOL_VERSION, type McpOptions } from "./mcp.js";
+export type { OperationId } from "./operation-ids.js";
+export type { CallParams } from "./operations.js";
+export { SDK_VERSION } from "./version.js";
 export type { ConnectivityEsim, ConnectivityIntent, ConnectivityPlan, IdempotentRequest, IntentCreateParams, IntentStatus, PlanPrice, ProductCreateParams, } from "./types.js";

package/dist/index.js

@@ -1,2 +1,7 @@
+export { cliTools, mcpTools, restTools } from "./adapters.js";
+export { cliCommands, operations } from "./catalog.js";
+export { Cli } from "./cli.js";
 export { Carrier } from "./client.js";
 export { CarrierError } from "./error.js";
+export { DEFAULT_MCP_URL, Mcp, PROTOCOL_VERSION } from "./mcp.js";
+export { SDK_VERSION } from "./version.js";

package/dist/mcp.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Streamable HTTP client for the hosted Carrier MCP server.
+ *
+ * `auth: "token"` sends an eSIMVault reseller token as `?TOKEN=`.
+ * `auth: "bearer"` sends an OAuth access token or a Clerk organization API key.
+ */
+export declare const DEFAULT_MCP_URL = "https://mcp.carrier.llc/mcp";
+export declare const PROTOCOL_VERSION = "2025-11-25";
+export interface McpOptions {
+    /** Defaults to https://mcp.carrier.llc/mcp. */
+    url?: string;
+    /** `token` uses ?TOKEN=. `bearer` uses Authorization. Defaults to token. */
+    auth?: "token" | "bearer";
+    /** Override fetch in tests. */
+    fetch?: typeof fetch;
+}
+export declare class Mcp {
+    private readonly token;
+    private readonly url;
+    private readonly auth;
+    private readonly fetchImpl;
+    private sessionId;
+    private protocol;
+    private connected;
+    private nextId;
+    constructor(token: string, options?: McpOptions);
+    /** Initialize a session and send notifications/initialized. */
+    connect(): Promise<Record<string, unknown>>;
+    /** Return the tools advertised for this session. */
+    listTools(): Promise<unknown[]>;
+    /** Call one MCP tool and return the tool result object. */
+    callTool(name: string, args?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** Call any MCP method. The session is opened on the first call. */
+    request(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    private ensureConnected;
+    private notify;
+    private rpc;
+    private send;
+    private endpoint;
+    private headers;
+}

package/dist/mcp.js

@@ -0,0 +1,173 @@
+/**
+ * Streamable HTTP client for the hosted Carrier MCP server.
+ *
+ * `auth: "token"` sends an eSIMVault reseller token as `?TOKEN=`.
+ * `auth: "bearer"` sends an OAuth access token or a Clerk organization API key.
+ */
+import { CarrierError } from "./error.js";
+import { SDK_VERSION, USER_AGENT } from "./version.js";
+export const DEFAULT_MCP_URL = "https://mcp.carrier.llc/mcp";
+export const PROTOCOL_VERSION = "2025-11-25";
+const ACCEPTED_PROTOCOL_VERSIONS = new Set(["2025-11-25", "2025-06-18", "2025-03-26"]);
+export class Mcp {
+    token;
+    url;
+    auth;
+    fetchImpl;
+    sessionId;
+    protocol;
+    connected = false;
+    nextId = 1;
+    constructor(token, options = {}) {
+        if (token.trim() === "")
+            throw new CarrierError(400, "invalid_token", "An MCP token is required.");
+        const auth = options.auth ?? "token";
+        if (auth !== "token" && auth !== "bearer") {
+            throw new CarrierError(400, "invalid_auth", "MCP auth must be token or bearer.");
+        }
+        this.token = token;
+        this.url = options.url ?? DEFAULT_MCP_URL;
+        this.auth = auth;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    /** Initialize a session and send notifications/initialized. */
+    async connect() {
+        const result = await this.rpc("initialize", {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            clientInfo: { name: "@carrierllc/sdk", version: SDK_VERSION },
+        }, true);
+        if (!isRecord(result))
+            throw new CarrierError(200, "invalid_response", "MCP initialize did not return an object.");
+        const version = result.protocolVersion;
+        if (typeof version !== "string" || !ACCEPTED_PROTOCOL_VERSIONS.has(version)) {
+            throw new CarrierError(400, "unsupported_protocol", `MCP server negotiated ${String(version)}.`);
+        }
+        this.protocol = version;
+        await this.notify("notifications/initialized");
+        this.connected = true;
+        return result;
+    }
+    /** Return the tools advertised for this session. */
+    async listTools() {
+        await this.ensureConnected();
+        const result = await this.rpc("tools/list", {});
+        if (!isRecord(result) || !Array.isArray(result.tools)) {
+            throw new CarrierError(200, "invalid_response", "MCP tools/list did not return tools.");
+        }
+        return result.tools;
+    }
+    /** Call one MCP tool and return the tool result object. */
+    async callTool(name, args = {}) {
+        await this.ensureConnected();
+        if (name.trim() === "")
+            throw new CarrierError(400, "invalid_tool", "An MCP tool name is required.");
+        const result = await this.rpc("tools/call", { name, arguments: args });
+        if (!isRecord(result))
+            throw new CarrierError(200, "invalid_response", "MCP tools/call did not return an object.");
+        return result;
+    }
+    /** Call any MCP method. The session is opened on the first call. */
+    async request(method, params = {}) {
+        if (method !== "initialize")
+            await this.ensureConnected();
+        return this.rpc(method, params);
+    }
+    async ensureConnected() {
+        if (!this.connected)
+            await this.connect();
+    }
+    async notify(method) {
+        await this.send({ jsonrpc: "2.0", method }, true);
+    }
+    async rpc(method, params, handshake = false) {
+        const id = this.nextId;
+        this.nextId += 1;
+        return this.send({ jsonrpc: "2.0", id, method, params }, false, handshake);
+    }
+    async send(message, notify = false, handshake = false) {
+        let response;
+        try {
+            response = await this.fetchImpl(this.endpoint(), {
+                method: "POST",
+                headers: this.headers(),
+                body: JSON.stringify(message),
+            });
+        }
+        catch (error) {
+            const text = error instanceof Error ? error.message : "Network request failed.";
+            throw new CarrierError(0, "network_error", text, "api_error");
+        }
+        if (handshake)
+            this.sessionId = response.headers.get("mcp-session-id") ?? this.sessionId;
+        const raw = await response.text();
+        if (!response.ok) {
+            throw new CarrierError(response.status, "mcp_error", raw.trim() === "" ? "MCP request failed." : raw.slice(0, 300), "api_error");
+        }
+        if (notify && raw.trim() === "")
+            return undefined;
+        return decodeRpc(raw, response.headers.get("content-type") ?? "");
+    }
+    endpoint() {
+        if (this.auth !== "token")
+            return this.url;
+        const url = new URL(this.url);
+        url.searchParams.set("TOKEN", this.token);
+        return url.toString();
+    }
+    headers() {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            "User-Agent": USER_AGENT,
+        };
+        if (this.auth === "bearer")
+            headers.Authorization = `Bearer ${this.token}`;
+        if (this.sessionId)
+            headers["Mcp-Session-Id"] = this.sessionId;
+        if (this.protocol)
+            headers["MCP-Protocol-Version"] = this.protocol;
+        return headers;
+    }
+}
+function decodeRpc(raw, contentType) {
+    if (raw.trim() === "")
+        return undefined;
+    if (contentType.includes("text/event-stream"))
+        return decodeSse(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CarrierError(200, "invalid_response", "MCP returned a body that is not JSON.");
+    }
+    if (!isRecord(parsed))
+        throw new CarrierError(200, "invalid_response", "MCP returned a body that is not an object.");
+    return rpcPayload(parsed);
+}
+function decodeSse(raw) {
+    for (const block of raw.split("\n\n")) {
+        for (const line of block.split("\n")) {
+            if (!line.startsWith("data:"))
+                continue;
+            const data = line.slice(5).trim();
+            if (data === "" || data === "[DONE]")
+                continue;
+            const parsed = JSON.parse(data);
+            if (isRecord(parsed) && ("result" in parsed || "error" in parsed))
+                return rpcPayload(parsed);
+        }
+    }
+    throw new CarrierError(200, "invalid_response", "MCP event stream did not include a result.");
+}
+function rpcPayload(message) {
+    if (isRecord(message.error)) {
+        const text = message.error.message;
+        throw new CarrierError(200, "mcp_error", typeof text === "string" && text !== "" ? text : "MCP request failed.", "api_error");
+    }
+    return message.result;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/operation-ids.d.ts

@@ -0,0 +1,5 @@
+/** Operation ids from the public OpenAPI document.
+ *
+ * Generated by sdks/generate.py. Do not edit by hand.
+ */
+export type OperationId = "list_reseller_accounts" | "get_reseller_info" | "esim_status_per_account" | "list_sponsors" | "list_steering_lists" | "get_subscriber" | "list_subscribers" | "create_subscriber" | "get_sim_provider_status" | "change_sim_status" | "get_subscriber_location" | "hlr_get_bitrate" | "hlr_set_bitrate" | "list_subscriber_packages" | "assign_package" | "clean_all_packages" | "list_package_templates" | "create_package_template" | "list_location_zones" | "create_location_zone" | "list_detailed_location_zones" | "list_destination_prefixes" | "subscriber_usage" | "subscriber_network_events" | "subscriber_active_period" | "get_tariff" | "list_network_profiles" | "modify_subscriber_balance" | "modify_subscriber_status" | "modify_subscriber_contact_info" | "set_subscriber_traffic_restrictions" | "modify_subscriber_steering_list" | "move_subscriber_range_to_account" | "assign_recurring_package" | "modify_package_limits" | "modify_package_expiry" | "modify_package_status" | "stop_resume_recurring_package" | "modify_account_balance" | "delete_subscriber_package" | "modify_template_core" | "modify_template_recurring" | "modify_template_throttling" | "send_sms" | "fleet_health" | "churn_risk" | "audit_network_coverage" | "diagnose_subscriber" | "detect_usage_anomalies" | "optimize_package" | "marketing_intelligence" | "high_cost_subscribers" | "high_cost_subscribers_method_guard" | "detect_country_entry" | "list_intelligence_schedules" | "create_intelligence_schedule" | "delete_intelligence_schedule" | "run_intelligence_schedule" | "get_intelligence_schedule_report" | "get_intelligence_share" | "operator_billing_connect_begin" | "operator_billing_connect_oauth_begin" | "operator_billing_connect_oauth_complete" | "operator_billing_connect_status" | "operator_billing_connect_dashboard_link" | "operator_billing_list_payouts" | "operator_billing_create_manual_payout" | "operator_billing_get_payout_schedule" | "operator_billing_update_payout_schedule" | "operator_billing_list_fees" | "operator_billing_list_refunds" | "operator_billing_create_refund" | "operator_billing_list_disputes" | "operator_billing_submit_dispute_evidence" | "operator_billing_list_fraud_reviews" | "operator_billing_approve_fraud_review" | "operator_billing_decline_fraud_review" | "operator_billing_list_value_lists" | "operator_billing_add_value_list_item" | "operator_identity_status" | "operator_identity_create_session" | "operator_identity_update_session" | "operator_list_promotions" | "operator_create_promotion" | "signup_start" | "signup_verify" | "create_api_key" | "get_onboarding_state" | "onboarding_save_org" | "onboarding_connect_ocs_token" | "onboarding_start_managed_account" | "onboarding_save_plan" | "onboarding_skip_plan" | "onboarding_test_esim" | "onboarding_complete" | "operator_billing_stripe_webhook" | "receive_bridge4ip_webhook" | "affect_subscriber_phone_number" | "modify_subscriber_mobile_plan" | "modify_subscriber_voip_plan" | "push_steering_to_subscriber" | "modify_subscriber_package_active_period" | "get_subscriber_location_by_cell_id" | "reset_subscriber_gz_counter" | "list_destination_lists" | "list_subscriber_voip_tariff" | "list_voip_tariff_rule" | "change_network_profile_of_location_zone" | "carrier_webhook_config" | "ai_chat" | "ai_insights" | "ai_quota" | "list_invoice_periods" | "get_billing_config" | "update_billing_config" | "stripe_connect_begin" | "stripe_connect_status" | "list_invoices" | "create_invoice" | "get_invoice" | "update_invoice" | "void_invoice" | "get_invoice_document" | "list_connectivity_plans" | "list_connectivity_products" | "create_connectivity_product" | "get_connectivity_product" | "list_connectivity_intents" | "create_connectivity_intent" | "get_connectivity_intent" | "confirm_connectivity_intent" | "create_connectivity_webhook_endpoint" | "list_connectivity_webhook_endpoints" | "delete_connectivity_webhook_endpoint" | "list_connectivity_events" | "get_connectivity_event" | "create_connectivity_usage_record" | "list_connectivity_usage_records" | "retry_connectivity_event" | "issue_esim_from_inventory" | "rollback_esim_issuance" | "subscriber_country_history" | "get_subscriber_notes" | "add_subscriber_note" | "put_subscriber_notes" | "observe_connectivity_event" | "ingest_connectivity_usage" | "ingest_cdr_events" | "aggregate_cdr" | "list_storefront_templates" | "get_storefront_order" | "health_check";

package/dist/operation-ids.js

@@ -0,0 +1 @@
+export {};

package/dist/operations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Generic caller for every operation id in the public OpenAPI document.
+ */
+import { type Operation } from "./catalog.js";
+export interface CallParams {
+    path?: Record<string, string>;
+    query?: Record<string, string | number | boolean>;
+    headers?: Record<string, string>;
+    body?: unknown;
+    idempotencyKey?: string;
+}
+export interface PreparedCall {
+    method: string;
+    path: string;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    body?: unknown;
+    idempotencyKey?: string;
+}
+export declare function prepareCall(operationId: string, params?: CallParams): PreparedCall;
+export declare function inputSchema(spec: Operation): Record<string, unknown>;
+export declare function argumentsToCall(spec: Operation, args: Record<string, unknown>): CallParams;

package/dist/operations.js

@@ -0,0 +1,177 @@
+/**
+ * Generic caller for every operation id in the public OpenAPI document.
+ */
+import { CarrierError } from "./error.js";
+import { requireIdempotencyKey, requirePathId } from "./idempotency.js";
+import { HEADER_FIELDS, operation } from "./catalog.js";
+const IDEMPOTENCY_HEADERS = new Set(["Idempotency-Key", "X-Idempotency-Key"]);
+export function prepareCall(operationId, params = {}) {
+    const spec = operation(operationId);
+    const pathValues = params.path ?? {};
+    const queryValues = params.query ?? {};
+    const headerValues = { ...(params.headers ?? {}) };
+    rejectUnknown("path", pathValues, spec.pathParams);
+    rejectUnknown("query", queryValues, spec.queryParams);
+    rejectUnknown("header", headerValues, spec.headerParams);
+    requirePresent("Path", pathValues, spec.pathParams);
+    applyIdempotency(spec, headerValues, params.idempotencyKey);
+    requireHeaders(headerValues, spec);
+    for (const name of Object.keys(headerValues)) {
+        if (IDEMPOTENCY_HEADERS.has(name)) {
+            headerValues[name] = requireIdempotencyKey(headerValues[name]);
+        }
+    }
+    if (spec.bodyRequired && params.body === undefined) {
+        throw new CarrierError(400, "missing_body", "This operation requires a JSON body.");
+    }
+    if (params.body !== undefined && !spec.body) {
+        throw new CarrierError(400, "invalid_body", "This operation does not take a JSON body.");
+    }
+    const idempotencyKey = headerValues["Idempotency-Key"];
+    delete headerValues["Idempotency-Key"];
+    const query = {};
+    for (const [key, value] of Object.entries(queryValues)) {
+        query[key] = queryValue(value);
+    }
+    return {
+        method: spec.method,
+        path: fillPath(spec.path, pathValues),
+        query: Object.keys(query).length > 0 ? query : undefined,
+        headers: Object.keys(headerValues).length > 0 ? headerValues : undefined,
+        body: spec.body ? params.body : undefined,
+        idempotencyKey,
+    };
+}
+export function inputSchema(spec) {
+    const properties = {};
+    const required = [];
+    for (const param of spec.pathParams) {
+        properties[param.name] = { type: "string", description: `Path ${param.name}` };
+        if (param.required)
+            required.push(param.name);
+    }
+    for (const param of spec.queryParams) {
+        properties[param.name] = { type: "string", description: `Query ${param.name}` };
+        if (param.required)
+            required.push(param.name);
+    }
+    for (const param of spec.headerParams) {
+        const field = HEADER_FIELDS[param.name] ?? param.name;
+        properties[field] = { type: "string", description: param.name };
+        if (param.required)
+            required.push(field);
+    }
+    if (spec.body) {
+        properties.body = { type: "object", additionalProperties: true, description: "JSON request body" };
+        if (spec.bodyRequired)
+            required.push("body");
+    }
+    return { type: "object", properties, required, additionalProperties: false };
+}
+export function argumentsToCall(spec, args) {
+    const known = new Set();
+    for (const param of spec.pathParams)
+        known.add(param.name);
+    for (const param of spec.queryParams)
+        known.add(param.name);
+    const headerByField = new Map();
+    for (const param of spec.headerParams) {
+        const field = HEADER_FIELDS[param.name] ?? param.name;
+        headerByField.set(field, param.name);
+        known.add(field);
+    }
+    if (spec.body)
+        known.add("body");
+    for (const key of Object.keys(args)) {
+        if (!known.has(key))
+            throw new CarrierError(400, "unknown_parameter", `Unknown argument ${key}.`);
+    }
+    const path = {};
+    const query = {};
+    const headers = {};
+    for (const param of spec.pathParams) {
+        if (param.name in args)
+            path[param.name] = stringArg(args[param.name], param.name);
+    }
+    for (const param of spec.queryParams) {
+        if (param.name in args)
+            query[param.name] = stringArg(args[param.name], param.name);
+    }
+    let idempotencyKey;
+    for (const [field, header] of headerByField) {
+        if (!(field in args))
+            continue;
+        const value = stringArg(args[field], field);
+        if (field === "idempotency_key")
+            idempotencyKey = value;
+        else
+            headers[header] = value;
+    }
+    return {
+        path,
+        query,
+        headers,
+        body: "body" in args ? args.body : undefined,
+        idempotencyKey,
+    };
+}
+function rejectUnknown(label, values, params) {
+    const allowed = new Set(params.map((param) => param.name));
+    for (const name of Object.keys(values)) {
+        if (!allowed.has(name)) {
+            throw new CarrierError(400, "unknown_parameter", `Unknown ${label} parameter ${name}.`);
+        }
+    }
+}
+function requirePresent(label, values, params) {
+    for (const param of params) {
+        if (param.required && !(param.name in values)) {
+            throw new CarrierError(400, "missing_parameter", `${label} parameter ${param.name} is required.`);
+        }
+    }
+}
+function applyIdempotency(spec, headers, idempotencyKey) {
+    if (idempotencyKey === undefined)
+        return;
+    const names = new Set(spec.headerParams.map((param) => param.name));
+    if (names.has("Idempotency-Key")) {
+        headers["Idempotency-Key"] = idempotencyKey;
+        return;
+    }
+    if (names.has("X-Idempotency-Key")) {
+        headers["X-Idempotency-Key"] = idempotencyKey;
+        return;
+    }
+    throw new CarrierError(400, "unknown_parameter", "This operation does not take an idempotency key.");
+}
+function requireHeaders(headers, spec) {
+    for (const param of spec.headerParams) {
+        if (!param.required || param.name in headers)
+            continue;
+        const field = HEADER_FIELDS[param.name] ?? param.name;
+        throw new CarrierError(400, "missing_parameter", `${field} is required.`);
+    }
+}
+function fillPath(template, values) {
+    const filled = template.replace(/\{([^{}]+)\}/g, (_match, name) => {
+        if (!(name in values)) {
+            throw new CarrierError(400, "missing_parameter", `Path parameter ${name} is required.`);
+        }
+        return encodeURIComponent(requirePathId(values[name] ?? "", name));
+    });
+    if (filled.includes("{") || filled.includes("}")) {
+        throw new CarrierError(400, "invalid_path", "Operation path could not be filled.");
+    }
+    return filled;
+}
+function queryValue(value) {
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    return String(value);
+}
+function stringArg(value, label) {
+    if (typeof value !== "string") {
+        throw new CarrierError(400, "invalid_parameter", `${label} must be a string.`);
+    }
+    return value;
+}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** Published version. Keep this equal to package.json. */
+export declare const SDK_VERSION = "0.2.0";
+export declare const USER_AGENT = "@carrierllc/sdk/0.2.0";

package/dist/version.js

@@ -0,0 +1,3 @@
+/** Published version. Keep this equal to package.json. */
+export const SDK_VERSION = "0.2.0";
+export const USER_AGENT = `@carrierllc/sdk/${SDK_VERSION}`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@carrierllc/sdk",
-  "version": "0.1.0",
-  "description": "Typed client for Carrier connectivity intents and products.",
+  "version": "0.2.0",
+  "description": "TypeScript client for the Carrier API, MCP server, and CLI.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && rm -rf dist/data && cp -r src/data dist/data",
     "type-check": "tsc --noEmit",
     "lint": "eslint src tests",
     "test": "vitest run"