@carrierllc/sdk 0.2.12 → 0.2.13

package/README.md

@@ -13,7 +13,7 @@ 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.
+`intents.create` posts to `/v1/connectivity/intents`. Issuance requires a stable caller key matching `[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}` (1–200 ASCII characters). The same key and body identify the original operation; they do not prove provider exactly-once completion. After transport/body loss, `CarrierError` has `code: "outcome_unknown"`, the original `idempotencyKey`, and `retryable: false`. The SDK sends once, disables redirects, and never generates a replacement key. Preserve the key and reconcile; do not automatically retry or reissue. `products.create` posts to `/v1/connectivity/products`. The price on a product is catalogue data. Neither call debits a wallet.
 
 ```ts
 import { Cli, Mcp, restTools } from "@carrierllc/sdk"
@@ -35,4 +35,4 @@ 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.6` 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.
+`npm install @carrierllc/sdk@0.2.11` 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/client.js

@@ -6,7 +6,7 @@
  * debits a wallet.
  */
 import { CarrierError, errorFromBody } from "./error.js";
-import { requireIdempotencyKey } from "./idempotency.js";
+import { isIssuance, requireIssuanceKey, requireIdempotencyKey } from "./idempotency.js";
 import { prepareCall } from "./operations.js";
 import { USER_AGENT } from "./version.js";
 export class Carrier {
@@ -67,17 +67,37 @@ export class Carrier {
         }
         if (options.idempotencyKey !== undefined)
             headers["Idempotency-Key"] = requireIdempotencyKey(options.idempotencyKey);
+        const issuance = isIssuance(method, path);
+        const issuanceKey = issuance ? requireIssuanceKey(options.idempotencyKey ?? headers["X-Idempotency-Key"]) : undefined;
+        const unknownOutcome = (status, cause) => new CarrierError(status, "outcome_unknown", "Issuance may have been dispatched. Do not retry or change the key; reconcile the original operation.", "api_error", { idempotencyKey: issuanceKey, retryable: false, cause });
         let response;
         try {
-            response = await this.fetchImpl(url.toString(), { method, headers, body: payload });
+            response = await this.fetchImpl(url.toString(), { method, headers, body: payload, ...(issuance ? { redirect: "error" } : {}) });
         }
         catch (error) {
+            if (issuance)
+                throw unknownOutcome(0, error);
             const message = error instanceof Error ? error.message : "Network request failed.";
             throw new CarrierError(0, "network_error", message, "api_error");
         }
-        const parsed = await readJson(response);
-        if (!response.ok)
-            throw errorFromBody(response.status, parsed);
+        let parsed;
+        try {
+            parsed = issuance ? JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(await response.arrayBuffer())) : await readJson(response);
+        }
+        catch (error) {
+            if (issuance)
+                throw unknownOutcome(response.status, error);
+            throw error;
+        }
+        if (issuance && response.status >= 300 && response.status < 400)
+            throw unknownOutcome(response.status);
+        if (!response.ok) {
+            const error = errorFromBody(response.status, parsed);
+            if (issuance && ["outcome_unknown", "manual_reconciliation_required"].includes(error.code.toLowerCase())) {
+                throw new CarrierError(error.status, error.code, error.message, error.type, { idempotencyKey: issuanceKey, retryable: false });
+            }
+            throw error;
+        }
         return parsed;
     }
 }

package/dist/data/cli.json

@@ -568,7 +568,47 @@
       },
       {
         "flags": "--account-id <id>",
-        "description": "Auto-pick a free eSIM from this account instead of using --iccid",
+        "description": "Issue from inventory through the authenticated Carrier API; requires --request-key; preserve it after unknown outcomes",
+        "required": false
+      },
+      {
+        "flags": "--request-key <key>",
+        "description": "Required stable inventory key (1–200 safe characters); preserved after unknown outcomes",
+        "required": false
+      },
+      {
+        "flags": "--start-date <date>",
+        "description": "Inventory package start date",
+        "required": false
+      },
+      {
+        "flags": "--end-date <date>",
+        "description": "Inventory package end date",
+        "required": false
+      },
+      {
+        "flags": "--validity-period <days>",
+        "description": "Inventory package validity period",
+        "required": false
+      },
+      {
+        "flags": "--business-kind <kind>",
+        "description": "Authorized reference kind: storefront_order",
+        "required": false
+      },
+      {
+        "flags": "--business-id <id>",
+        "description": "Existing API-authorized order ID",
+        "required": false
+      },
+      {
+        "flags": "--business-line <line>",
+        "description": "Authorized reference line: esim",
+        "required": false
+      },
+      {
+        "flags": "--business-verb <verb>",
+        "description": "Authorized reference verb: issue",
         "required": false
       }
     ]

package/dist/data/operations.json

@@ -2453,7 +2453,7 @@
     "headerParams": [
       {
         "name": "X-Idempotency-Key",
-        "required": false
+        "required": true
       }
     ]
   },

package/dist/error.d.ts

@@ -3,6 +3,13 @@ export declare class CarrierError extends Error {
     readonly status: number;
     readonly code: string;
     readonly type: string;
-    constructor(status: number, code: string, message: string, type?: string);
+    /** Present for a possibly dispatched issuance; keep this key for reconciliation. */
+    readonly idempotencyKey?: string;
+    readonly retryable?: boolean;
+    constructor(status: number, code: string, message: string, type?: string, details?: {
+        idempotencyKey?: string;
+        retryable?: boolean;
+        cause?: unknown;
+    });
 }
 export declare function errorFromBody(status: number, body: unknown): CarrierError;

package/dist/error.js

@@ -3,17 +3,26 @@ export class CarrierError extends Error {
     status;
     code;
     type;
-    constructor(status, code, message, type = "invalid_request_error") {
-        super(message);
+    /** Present for a possibly dispatched issuance; keep this key for reconciliation. */
+    idempotencyKey;
+    retryable;
+    constructor(status, code, message, type = "invalid_request_error", details = {}) {
+        super(message, { cause: details.cause });
         this.name = "CarrierError";
         this.status = status;
         this.code = code;
         this.type = type;
+        this.idempotencyKey = details.idempotencyKey;
+        this.retryable = details.retryable;
     }
 }
 export function errorFromBody(status, body) {
     if (body && typeof body === "object" && "error" in body) {
         const error = body.error;
+        if (typeof error === "string") {
+            const code = body.code;
+            return new CarrierError(status, typeof code === "string" ? code : "api_error", error, "api_error");
+        }
         if (error && typeof error === "object") {
             const record = error;
             const code = typeof record.code === "string" ? record.code : "api_error";

package/dist/idempotency.d.ts

@@ -1,4 +1,7 @@
-/** Same limits as the API, so a bad key fails before a request is sent. */
+/** Issuance keys are the verbatim stable operation identity, never normalized. */
+export declare function requireIssuanceKey(key: string | undefined): string;
+export declare function isIssuance(method: string, path: string): boolean;
+/** Nonissuance operations retain their existing API limits. */
 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

@@ -1,5 +1,15 @@
 import { CarrierError } from "./error.js";
-/** Same limits as the API, so a bad key fails before a request is sent. */
+/** Issuance keys are the verbatim stable operation identity, never normalized. */
+export function requireIssuanceKey(key) {
+    if (typeof key !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(key) || /[\r\n]/.test(key)) {
+        throw new CarrierError(400, "invalid_idempotency_key", "Issuance requires a 1–200 character ASCII key starting with a letter or digit and containing only letters, digits, _, ., :, or -.");
+    }
+    return key;
+}
+export function isIssuance(method, path) {
+    return method === "POST" && ["/v1/connectivity/intents", "/v1/subscribers/issue-from-inventory"].includes(path);
+}
+/** Nonissuance operations retain their existing API limits. */
 export function requireIdempotencyKey(key) {
     if (key === undefined || key.trim() === "") {
         throw new CarrierError(400, "invalid_idempotency_key", "Idempotency-Key is required.");

package/dist/operations.js

@@ -2,7 +2,7 @@
  * Generic caller for every operation id in the public OpenAPI document.
  */
 import { CarrierError } from "./error.js";
-import { requireIdempotencyKey, requirePathId } from "./idempotency.js";
+import { isIssuance, requireIssuanceKey, 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 = {}) {
@@ -18,7 +18,7 @@ export function prepareCall(operationId, params = {}) {
     requireHeaders(headerValues, spec);
     for (const name of Object.keys(headerValues)) {
         if (IDEMPOTENCY_HEADERS.has(name)) {
-            headerValues[name] = requireIdempotencyKey(headerValues[name]);
+            headerValues[name] = isIssuance(spec.method, spec.path) ? requireIssuanceKey(headerValues[name]) : requireIdempotencyKey(headerValues[name]);
         }
     }
     if (spec.bodyRequired && params.body === undefined) {
@@ -57,7 +57,9 @@ export function inputSchema(spec) {
     }
     for (const param of spec.headerParams) {
         const field = HEADER_FIELDS[param.name] ?? param.name;
-        properties[field] = { type: "string", description: param.name };
+        properties[field] = { type: "string", description: param.name,
+            ...(isIssuance(spec.method, spec.path) && IDEMPOTENCY_HEADERS.has(param.name) ? { minLength: 1, maxLength: 200, pattern: "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$" } : {}),
+        };
         if (param.required)
             required.push(field);
     }

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrierllc/sdk",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "description": "TypeScript client for the Carrier API, MCP server, and CLI.",
   "license": "MIT",
   "type": "module",