@carrierllc/sdk 0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @carrierllc/sdk
+
+Typed client for one connectivity intent, and for the product an operator defines.
+
+```ts
+import { Carrier } from "@carrierllc/sdk"
+
+const carrier = new Carrier(process.env.CARRIER_API_KEY ?? "")
+
+const intent = await carrier.intents.create(
+  { plan: "test_global_1gb", metadata: { order: "123" } },
+  { idempotencyKey: "order_123" },
+)
+```
+
+`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.

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+import type { ConnectivityIntent, ConnectivityPlan, IdempotentRequest, IntentCreateParams, ProductCreateParams } from "./types.js";
+export interface CarrierOptions {
+    /** Defaults to https://api.carrier.llc. No trailing slash required. */
+    baseUrl?: string;
+    /** Override fetch in tests. */
+    fetch?: typeof fetch;
+}
+export declare class Carrier {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    readonly intents: {
+        create: (body: IntentCreateParams, options: IdempotentRequest) => Promise<ConnectivityIntent>;
+    };
+    readonly products: {
+        create: (body: ProductCreateParams, options: IdempotentRequest) => Promise<ConnectivityPlan>;
+    };
+    constructor(apiKey: string, options?: CarrierOptions);
+    private post;
+}

package/dist/client.js

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+import { CarrierError, errorFromBody } from "./error.js";
+import { requireIdempotencyKey } from "./idempotency.js";
+export class Carrier {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    intents;
+    products;
+    constructor(apiKey, options = {}) {
+        if (apiKey.trim() === "") {
+            throw new CarrierError(400, "invalid_api_key", "A Carrier API key is required.");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://api.carrier.llc").replace(/\/$/, "");
+        this.fetchImpl = options.fetch ?? fetch;
+        this.intents = {
+            create: (body, request) => this.post("/v1/connectivity/intents", body, request.idempotencyKey),
+        };
+        this.products = {
+            create: (body, request) => this.post("/v1/connectivity/products", body, request.idempotencyKey),
+        };
+    }
+    async post(path, body, idempotencyKey) {
+        const key = requireIdempotencyKey(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),
+            });
+        }
+        catch (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);
+        return parsed;
+    }
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new CarrierError(response.status, "invalid_response", "Carrier returned a body that is not JSON.");
+    }
+}

package/dist/error.d.ts

@@ -0,0 +1,8 @@
+/** Error returned by the Carrier API, or raised before a request is sent. */
+export declare class CarrierError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly type: string;
+    constructor(status: number, code: string, message: string, type?: string);
+}
+export declare function errorFromBody(status: number, body: unknown): CarrierError;

package/dist/error.js

@@ -0,0 +1,26 @@
+/** Error returned by the Carrier API, or raised before a request is sent. */
+export class CarrierError extends Error {
+    status;
+    code;
+    type;
+    constructor(status, code, message, type = "invalid_request_error") {
+        super(message);
+        this.name = "CarrierError";
+        this.status = status;
+        this.code = code;
+        this.type = type;
+    }
+}
+export function errorFromBody(status, body) {
+    if (body && typeof body === "object" && "error" in body) {
+        const error = body.error;
+        if (error && typeof error === "object") {
+            const record = error;
+            const code = typeof record.code === "string" ? record.code : "api_error";
+            const message = typeof record.message === "string" ? record.message : "Carrier request failed.";
+            const type = typeof record.type === "string" ? record.type : "api_error";
+            return new CarrierError(status, code, message, type);
+        }
+    }
+    return new CarrierError(status, "api_error", "Carrier request failed.", "api_error");
+}

package/dist/idempotency.d.ts

@@ -0,0 +1,2 @@
+/** Same limits as the API, so a bad key fails before a request is sent. */
+export declare function requireIdempotencyKey(key: string | undefined): string;

package/dist/idempotency.js

@@ -0,0 +1,17 @@
+import { CarrierError } from "./error.js";
+/** Same limits as the API, so a bad key fails before a request is sent. */
+export function requireIdempotencyKey(key) {
+    if (key === undefined || key.trim() === "") {
+        throw new CarrierError(400, "invalid_idempotency_key", "Idempotency-Key is required.");
+    }
+    if (key.length > 255) {
+        throw new CarrierError(400, "invalid_idempotency_key", "Idempotency-Key must be 255 characters or fewer.");
+    }
+    for (let index = 0; index < key.length; index++) {
+        const code = key.charCodeAt(index);
+        if (code <= 31 || code === 127) {
+            throw new CarrierError(400, "invalid_idempotency_key", "Idempotency-Key must not contain control characters.");
+        }
+    }
+    return key;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Carrier, type CarrierOptions } from "./client.js";
+export { CarrierError } from "./error.js";
+export type { ConnectivityEsim, ConnectivityIntent, ConnectivityPlan, IdempotentRequest, IntentCreateParams, IntentStatus, PlanPrice, ProductCreateParams, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Carrier } from "./client.js";
+export { CarrierError } from "./error.js";

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+/** Public objects returned by the connectivity API. */
+export type IntentStatus = "requires_plan" | "processing" | "succeeded" | "failed";
+export interface PlanPrice {
+    amount: number;
+    currency: string;
+}
+export interface ConnectivityPlan {
+    id: string;
+    object: "connectivity.plan";
+    name: string;
+    data_mb: number;
+    validity_days: number;
+    countries: string[];
+    livemode: boolean;
+    price: PlanPrice | null;
+}
+export interface ConnectivityEsim {
+    iccid: string;
+    activation_code: string | null;
+    qr_code: string | null;
+    smdp_address: string | null;
+    matching_id: string | null;
+}
+export interface ConnectivityIntent {
+    id: string;
+    object: "connectivity.intent";
+    status: IntentStatus;
+    livemode: boolean;
+    plan: ConnectivityPlan | null;
+    esim: ConnectivityEsim | null;
+    metadata: Record<string, string>;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    created: number;
+}
+export interface IntentCreateParams {
+    plan?: string | null;
+    metadata?: Record<string, string>;
+}
+export interface ProductCreateParams {
+    name: string;
+    data_mb: number;
+    validity_days: number;
+    countries: string[];
+    price_cents: number;
+    currency: "USD" | "EUR" | "GBP" | "CHF";
+    package_template_id: number;
+    account_id?: number;
+}
+export interface IdempotentRequest {
+    idempotencyKey: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+/** Public objects returned by the connectivity API. */
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@carrierllc/sdk",
+  "version": "0.1.0",
+  "description": "Typed client for Carrier connectivity intents and products.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "eslint": "^10.9.1",
+    "@typescript-eslint/eslint-plugin": "^8.59.4",
+    "@typescript-eslint/parser": "^8.69.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "test": "vitest run"
+  }
+}