@carrierllc/sdk 0.2.1 → 0.2.2

package/README.md

@@ -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.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.
+`npm install @carrierllc/sdk@0.2.2` 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.d.ts

@@ -7,7 +7,7 @@
  */
 import type { OperationId } from "./operation-ids.js";
 import { type CallParams } from "./operations.js";
-import type { ConnectivityIntent, ConnectivityPlan, IdempotentRequest, IntentCreateParams, ProductCreateParams } from "./types.js";
+import type { ConnectivityIntent, ConnectivityPlan, HostedStorefront, IdempotentRequest, IntentCreateParams, ProductCreateParams, StorefrontCreateParams, StorefrontPlanParams, StorefrontUpdateParams } from "./types.js";
 export interface CarrierOptions {
     /** Defaults to https://api.carrier.llc. No trailing slash required. */
     baseUrl?: string;
@@ -24,6 +24,16 @@ export declare class Carrier {
     readonly products: {
         create: (body: ProductCreateParams, options: IdempotentRequest) => Promise<ConnectivityPlan>;
     };
+    readonly storefronts: {
+        list: () => Promise<{
+            data: HostedStorefront[];
+        }>;
+        create: (body: StorefrontCreateParams, options: IdempotentRequest) => Promise<HostedStorefront>;
+        update: (id: string, body: StorefrontUpdateParams) => Promise<HostedStorefront>;
+        upsertPlan: (id: string, body: StorefrontPlanParams) => Promise<{
+            slug: string;
+        }>;
+    };
     constructor(apiKey: string, options?: CarrierOptions);
     /** Call any operation id from the public OpenAPI document. */
     call(operationId: OperationId, params?: CallParams): Promise<unknown>;

package/dist/client.js

@@ -15,6 +15,7 @@ export class Carrier {
     fetchImpl;
     intents;
     products;
+    storefronts;
     constructor(apiKey, options = {}) {
         if (apiKey.trim() === "") {
             throw new CarrierError(400, "invalid_api_key", "A Carrier API key is required.");
@@ -28,6 +29,12 @@ export class Carrier {
         this.products = {
             create: (body, request) => this.post("/v1/connectivity/products", body, request.idempotencyKey),
         };
+        this.storefronts = {
+            list: () => this.request("GET", "/v1/storefronts", {}),
+            create: (body, request) => this.post("/v1/storefronts", body, request.idempotencyKey),
+            update: (id, body) => this.request("PATCH", `/v1/storefronts/${encodeURIComponent(id)}`, { body }),
+            upsertPlan: (id, body) => this.request("POST", `/v1/storefronts/${encodeURIComponent(id)}/plans`, { body }),
+        };
     }
     /** Call any operation id from the public OpenAPI document. */
     async call(operationId, params = {}) {

package/dist/data/operations.json

@@ -2500,6 +2500,28 @@
     "queryParams": [],
     "headerParams": []
   },
+  {
+    "id": "list_storefront_buyer_orders",
+    "method": "GET",
+    "path": "/api/orders",
+    "tag": "Storefront",
+    "summary": "List eSIMs one buyer paid for on one shop",
+    "security": "storefront",
+    "body": false,
+    "bodyRequired": false,
+    "pathParams": [],
+    "queryParams": [
+      {
+        "name": "storefront",
+        "required": true
+      },
+      {
+        "name": "email",
+        "required": true
+      }
+    ],
+    "headerParams": []
+  },
   {
     "id": "get_storefront_order",
     "method": "GET",
@@ -2515,6 +2537,114 @@
         "required": true
       }
     ],
+    "queryParams": [
+      {
+        "name": "storefront",
+        "required": false
+      }
+    ],
+    "headerParams": []
+  },
+  {
+    "id": "get_hosted_storefront",
+    "method": "GET",
+    "path": "/api/hosted/{slug}",
+    "tag": "Storefront",
+    "summary": "Published hosted storefront, including its sellable plans",
+    "security": "public",
+    "body": false,
+    "bodyRequired": false,
+    "pathParams": [
+      {
+        "name": "slug",
+        "required": true
+      }
+    ],
+    "queryParams": [],
+    "headerParams": []
+  },
+  {
+    "id": "list_storefronts",
+    "method": "GET",
+    "path": "/v1/storefronts",
+    "tag": "Storefront",
+    "summary": "List hosted storefronts for the caller's organization",
+    "security": "bearer",
+    "body": false,
+    "bodyRequired": false,
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": []
+  },
+  {
+    "id": "create_storefront",
+    "method": "POST",
+    "path": "/v1/storefronts",
+    "tag": "Storefront",
+    "summary": "Create a hosted storefront",
+    "security": "bearer",
+    "body": true,
+    "bodyRequired": true,
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": [
+      {
+        "name": "Idempotency-Key",
+        "required": true
+      }
+    ]
+  },
+  {
+    "id": "get_storefront",
+    "method": "GET",
+    "path": "/v1/storefronts/{id}",
+    "tag": "Storefront",
+    "summary": "Read one hosted storefront owned by the caller",
+    "security": "bearer",
+    "body": false,
+    "bodyRequired": false,
+    "pathParams": [
+      {
+        "name": "id",
+        "required": true
+      }
+    ],
+    "queryParams": [],
+    "headerParams": []
+  },
+  {
+    "id": "update_storefront",
+    "method": "PATCH",
+    "path": "/v1/storefronts/{id}",
+    "tag": "Storefront",
+    "summary": "Update a hosted storefront. Omitted fields are left as they are.",
+    "security": "bearer",
+    "body": true,
+    "bodyRequired": true,
+    "pathParams": [
+      {
+        "name": "id",
+        "required": true
+      }
+    ],
+    "queryParams": [],
+    "headerParams": []
+  },
+  {
+    "id": "upsert_storefront_plan",
+    "method": "POST",
+    "path": "/v1/storefronts/{id}/plans",
+    "tag": "Storefront",
+    "summary": "Create or replace a plan on a hosted storefront. product_id copies a connectivity plan owned by the caller.",
+    "security": "bearer",
+    "body": true,
+    "bodyRequired": true,
+    "pathParams": [
+      {
+        "name": "id",
+        "required": true
+      }
+    ],
     "queryParams": [],
     "headerParams": []
   },

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export { DEFAULT_MCP_URL, Mcp, PROTOCOL_VERSION, type McpOptions } from "./mcp.j
 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";
+export { isStorefrontPlanError, logoFileDataUrl, logoReference, majorToCents, parseCountryInput, parseDataGb, parseValidityDays, parseWholeNumber, completePlanInput, storefrontBrandPatch, storefrontPlanBody, hostedStorefrontUrl, storefrontSlugFrom, type ExistingStorefrontBrand, type StorefrontBrandInput, type StorefrontPlanBody, type StorefrontPlanInput, type StoredPlanIdentity, } from "./storefront-write.js";
+export type { ConnectivityEsim, ConnectivityIntent, ConnectivityPlan, HostedStorefront, IdempotentRequest, IntentCreateParams, IntentStatus, PlanPrice, ProductCreateParams, StorefrontCreateParams, StorefrontPlanParams, StorefrontUpdateParams, } from "./types.js";

package/dist/index.js

@@ -5,3 +5,4 @@ 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";
+export { isStorefrontPlanError, logoFileDataUrl, logoReference, majorToCents, parseCountryInput, parseDataGb, parseValidityDays, parseWholeNumber, completePlanInput, storefrontBrandPatch, storefrontPlanBody, hostedStorefrontUrl, storefrontSlugFrom, } from "./storefront-write.js";

package/dist/operation-ids.d.ts

@@ -2,4 +2,4 @@
  *
  * 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";
+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" | "list_storefront_buyer_orders" | "get_storefront_order" | "get_hosted_storefront" | "list_storefronts" | "create_storefront" | "get_storefront" | "update_storefront" | "upsert_storefront_plan" | "health_check";

package/dist/storefront-labels.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Labels a brand can type. The API still stores gigabytes, whole days,
+ * minor currency units, and two-letter country codes.
+ */
+export type LabelResult = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseDataGb(raw: string): LabelResult;
+export declare function parseValidityDays(raw: string): LabelResult;
+/** Stripe minor units. Yen is already the minor unit, so 1000 JPY stays 1000. */
+export declare function majorToCents(input: string, currency?: string): {
+    ok: true;
+    cents: number;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseCountryInput(raw: string): {
+    ok: true;
+    regions: string[];
+} | {
+    ok: false;
+    message: string;
+};
+/** Turns a small picture file into the data URL the shop stores. */
+export declare function logoFileDataUrl(bytes: Uint8Array): {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** Keeps an https address or a picture data URL. Drops SVG and script addresses. */
+export declare function logoReference(value: string): {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/storefront-labels.js

@@ -0,0 +1,168 @@
+/**
+ * Labels a brand can type. The API still stores gigabytes, whole days,
+ * minor currency units, and two-letter country codes.
+ */
+const regionNames = new Intl.DisplayNames(["en"], { type: "region" });
+const PREFERRED = new Set(["CW", "BF", "BJ", "MM", "CD", "RS", "DE", "FR", "GB", "VU", "ZW", "RU", "TL", "VN", "YE"]);
+const NAME_TO_CODE = new Map();
+for (let first = 65; first <= 90; first += 1) {
+    for (let second = 65; second <= 90; second += 1) {
+        const code = String.fromCharCode(first, second);
+        const label = regionLabel(code);
+        if (!label)
+            continue;
+        const key = label.toLowerCase();
+        const current = NAME_TO_CODE.get(key);
+        if (!current || PREFERRED.has(code))
+            NAME_TO_CODE.set(key, code);
+    }
+}
+NAME_TO_CODE.set("uk", "GB");
+const CODE_ALIASES = { UK: "GB" };
+export function parseDataGb(raw) {
+    if (raw.trim().toLowerCase() === "unlimited")
+        return { ok: true, value: 0 };
+    return parseAmount(raw, /gigabytes?|gbs?|gb/gi, "Enter data like 1, 1 GB, or Unlimited.", 10_000, false);
+}
+export function parseValidityDays(raw) {
+    return parseAmount(raw, /days?/gi, "Enter validity like 7 or 7 days.", 3650, true);
+}
+const ZERO_DECIMAL = new Set([
+    "BIF", "CLP", "DJF", "GNF", "JPY", "KMF", "KRW", "MGA", "PYG", "RWF",
+    "UGX", "VND", "VUV", "XAF", "XOF", "XPF",
+]);
+/** Stripe minor units. Yen is already the minor unit, so 1000 JPY stays 1000. */
+export function majorToCents(input, currency = "EUR") {
+    const text = input.trim();
+    if (ZERO_DECIMAL.has(currency.trim().toUpperCase())) {
+        if (!/^\d+$/.test(text))
+            return { ok: false, message: "Enter a whole number, such as 1000." };
+        const cents = Number(text);
+        if (!Number.isSafeInteger(cents) || cents <= 0)
+            return { ok: false, message: "Enter a price above zero." };
+        return { ok: true, cents };
+    }
+    const match = /^(\d+)(?:\.(\d{1,2}))?$/.exec(text);
+    if (!match)
+        return { ok: false, message: "Enter a price like 9.00." };
+    const major = Number(match[1]);
+    const fraction = (match[2] ?? "").padEnd(2, "0");
+    const cents = major * 100 + Number(fraction);
+    if (!Number.isSafeInteger(cents) || cents <= 0)
+        return { ok: false, message: "Enter a price above zero." };
+    return { ok: true, cents };
+}
+export function parseCountryInput(raw) {
+    const regions = [];
+    const parts = raw.split(",").map((part) => part.trim()).filter((part) => part !== "");
+    for (const part of parts) {
+        const added = codesFor(part);
+        if (!added)
+            return { ok: false, message: "Countries are names, such as France, or codes such as FR." };
+        for (const code of added) {
+            if (regions.length >= 40)
+                break;
+            if (!regions.includes(code))
+                regions.push(code);
+        }
+    }
+    return { ok: true, regions };
+}
+function parseAmount(raw, unit, message, max, whole) {
+    const text = raw.trim().replace(unit, "").trim();
+    if (text === "" || !/^\d+(\.\d+)?$/.test(text))
+        return { ok: false, message };
+    const value = Number(text);
+    if (!Number.isFinite(value) || value < 0 || value > max)
+        return { ok: false, message };
+    if (whole && !Number.isInteger(value))
+        return { ok: false, message };
+    return { ok: true, value };
+}
+function codesFor(part) {
+    const tokens = part.split(/\s+/).filter((token) => token !== "");
+    if (tokens.length > 1 && tokens.every((token) => /^[A-Za-z]{2}$/.test(token))) {
+        return tokens.map((token) => canonical(token));
+    }
+    if (/^[A-Za-z]{2}$/.test(part))
+        return [canonical(part)];
+    const code = NAME_TO_CODE.get(part.toLowerCase());
+    return code ? [code] : null;
+}
+function canonical(code) {
+    const upper = code.toUpperCase();
+    return CODE_ALIASES[upper] ?? upper;
+}
+const LOGO_DATA = /^data:image\/(png|jpeg|webp|gif);base64,[A-Za-z0-9+/]+={0,2}$/;
+const LOGO_MAX_CHARS = 100_000;
+const LOGO_MAX_BYTES = 70 * 1024;
+/** Turns a small picture file into the data URL the shop stores. */
+export function logoFileDataUrl(bytes) {
+    const mime = logoMime(bytes);
+    if (!mime || bytes.byteLength < 1 || bytes.byteLength > LOGO_MAX_BYTES) {
+        return { ok: false, message: "Use a PNG, JPEG, WebP, or GIF under 70 KB, or an https address." };
+    }
+    const url = `data:${mime};base64,${toBase64(bytes)}`;
+    if (url.length > LOGO_MAX_CHARS || !LOGO_DATA.test(url)) {
+        return { ok: false, message: "Use a PNG, JPEG, WebP, or GIF under 70 KB, or an https address." };
+    }
+    return { ok: true, url };
+}
+/** Keeps an https address or a picture data URL. Drops SVG and script addresses. */
+export function logoReference(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("data:")) {
+        if (trimmed.length <= LOGO_MAX_CHARS && LOGO_DATA.test(trimmed))
+            return { ok: true, url: trimmed };
+        return { ok: false, message: "Use a PNG, JPEG, WebP, or GIF under 70 KB, or an https address." };
+    }
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol === "https:")
+            return { ok: true, url: url.toString() };
+    }
+    catch {
+        return { ok: false, message: "Use a PNG, JPEG, WebP, or GIF under 70 KB, or an https address." };
+    }
+    return { ok: false, message: "Use a PNG, JPEG, WebP, or GIF under 70 KB, or an https address." };
+}
+function toBase64(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function logoMime(bytes) {
+    if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+        return "image/png";
+    }
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff)
+        return "image/jpeg";
+    if (bytes.length >= 6 && bytes[0] === 0x47 && bytes[1] === 0x49 && bytes[2] === 0x46)
+        return "image/gif";
+    if (bytes.length >= 12 &&
+        bytes[0] === 0x52 &&
+        bytes[1] === 0x49 &&
+        bytes[2] === 0x46 &&
+        bytes[3] === 0x46 &&
+        bytes[8] === 0x57 &&
+        bytes[9] === 0x45 &&
+        bytes[10] === 0x42 &&
+        bytes[11] === 0x50) {
+        return "image/webp";
+    }
+    return null;
+}
+function regionLabel(code) {
+    if (!/^[A-Z]{2}$/.test(code))
+        return undefined;
+    try {
+        const label = regionNames.of(code);
+        if (!label || label.toUpperCase() === code)
+            return undefined;
+        return label;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/storefront-write.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Bodies for the hosted storefront write API.
+ * A theme or copy object replaces that object, so a color change is merged
+ * onto the store already saved before it is sent.
+ */
+export { logoFileDataUrl, logoReference, majorToCents, parseCountryInput, parseDataGb, parseValidityDays, } from "./storefront-labels.js";
+export interface StorefrontBrandInput {
+    accent?: string;
+    accentDark?: string;
+    bg?: string;
+    text?: string;
+    logoUrl?: string;
+    hero?: string;
+    tagline?: string;
+    supportEmail?: string;
+    legalName?: string;
+}
+export interface StorefrontPlanInput {
+    productId?: string;
+    slug?: string;
+    name?: string;
+    priceCents?: number;
+    currency?: string;
+    templateId?: number;
+    dataGb?: number;
+    validityDays?: number;
+    regions?: string[];
+    description?: string;
+    active?: boolean;
+}
+export interface ExistingStorefrontBrand {
+    theme?: Record<string, unknown>;
+    copy?: Record<string, unknown>;
+}
+export interface StorefrontPlanBody {
+    product_id?: string;
+    slug?: string;
+    name?: string;
+    price_cents?: number;
+    currency?: string;
+    ocs_package_template_id?: number;
+    data_gb?: number;
+    validity_days?: number;
+    regions?: string[];
+    description?: string;
+    active?: boolean;
+}
+export declare function storefrontBrandPatch(input: StorefrontBrandInput, existing?: ExistingStorefrontBrand): {
+    theme?: Record<string, unknown>;
+    copy?: Record<string, unknown>;
+};
+export interface StoredPlanIdentity {
+    slug: string;
+    name: string;
+    currency: string;
+    ocs_package_template_id: number;
+}
+/** Fill slug, name, currency, and template id from a saved plan so a price change can omit them. */
+export declare function completePlanInput(input: StorefrontPlanInput, plans: StoredPlanIdentity[]): StorefrontPlanInput;
+export declare function storefrontPlanBody(input: StorefrontPlanInput): StorefrontPlanBody | {
+    error: string;
+} | null;
+export declare function isStorefrontPlanError(value: StorefrontPlanBody | {
+    error: string;
+} | null): value is {
+    error: string;
+};
+/** Whole numbers from CLI flags. An omitted flag stays omitted. */
+export declare function parseWholeNumber(value: string | undefined, label: string): {
+    ok: true;
+    value: number | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+/** "Acme Mobile" becomes acme-mobile. Reserved or empty input returns "". */
+/** Public shop address for a hosted slug. Custom domains are not part of this address. */
+export declare function hostedStorefrontUrl(slug: string): string;
+export declare function storefrontSlugFrom(raw: string): string;

package/dist/storefront-write.js

@@ -0,0 +1,157 @@
+/**
+ * Bodies for the hosted storefront write API.
+ * A theme or copy object replaces that object, so a color change is merged
+ * onto the store already saved before it is sent.
+ */
+export { logoFileDataUrl, logoReference, majorToCents, parseCountryInput, parseDataGb, parseValidityDays, } from "./storefront-labels.js";
+const THEME_FIELDS = [
+    ["accent", "accent"],
+    ["accentDark", "accentDark"],
+    ["bg", "bg"],
+    ["text", "text"],
+    ["logoUrl", "logoUrl"],
+];
+const COPY_FIELDS = [
+    ["hero", "hero"],
+    ["tagline", "tagline"],
+    ["supportEmail", "supportEmail"],
+    ["legalName", "legalName"],
+];
+export function storefrontBrandPatch(input, existing) {
+    const theme = overlay(existing?.theme, input, THEME_FIELDS);
+    const copy = overlay(existing?.copy, input, COPY_FIELDS);
+    return {
+        ...(theme ? { theme } : {}),
+        ...(copy ? { copy } : {}),
+    };
+}
+/** Fill slug, name, currency, and template id from a saved plan so a price change can omit them. */
+export function completePlanInput(input, plans) {
+    if ((input.productId?.trim() ?? "") !== "")
+        return input;
+    const touched = [
+        input.slug,
+        input.name,
+        input.priceCents,
+        input.currency,
+        input.templateId,
+        input.dataGb,
+        input.validityDays,
+        input.regions,
+        input.description,
+        input.active,
+    ].some((value) => value !== undefined);
+    if (!touched)
+        return input;
+    const slug = input.slug?.trim();
+    const match = slug ? plans.find((plan) => plan.slug === slug) : plans.length === 1 ? plans[0] : undefined;
+    if (!match) {
+        const currency = sharedCurrency(plans);
+        if (!input.currency && currency)
+            return { ...input, currency };
+        return input;
+    }
+    return {
+        ...input,
+        slug: input.slug ?? match.slug,
+        name: input.name ?? match.name,
+        currency: input.currency ?? match.currency,
+        templateId: input.templateId ?? match.ocs_package_template_id,
+    };
+}
+function sharedCurrency(plans) {
+    const codes = new Set(plans.map((plan) => plan.currency.trim().toUpperCase()).filter((code) => code !== ""));
+    if (codes.size !== 1)
+        return undefined;
+    return [...codes][0];
+}
+export function storefrontPlanBody(input) {
+    const productId = input.productId?.trim() ?? "";
+    if (productId !== "") {
+        const body = { product_id: productId };
+        if (input.priceCents !== undefined)
+            body.price_cents = input.priceCents;
+        if (input.active !== undefined)
+            body.active = input.active;
+        return body;
+    }
+    const touched = [
+        input.slug,
+        input.name,
+        input.priceCents,
+        input.currency,
+        input.templateId,
+        input.dataGb,
+        input.validityDays,
+        input.regions,
+        input.description,
+        input.active,
+    ].some((value) => value !== undefined);
+    if (!touched)
+        return null;
+    if (!input.slug || !input.name || input.priceCents === undefined || !input.currency || input.templateId === undefined) {
+        return { error: "A plan needs a slug, name, price in minor units, currency, and OCS template id." };
+    }
+    const body = {
+        slug: input.slug,
+        name: input.name,
+        price_cents: input.priceCents,
+        currency: input.currency,
+        ocs_package_template_id: input.templateId,
+    };
+    if (input.dataGb !== undefined)
+        body.data_gb = input.dataGb;
+    if (input.validityDays !== undefined)
+        body.validity_days = input.validityDays;
+    if (input.regions !== undefined)
+        body.regions = input.regions;
+    if (input.description !== undefined)
+        body.description = input.description;
+    if (input.active !== undefined)
+        body.active = input.active;
+    return body;
+}
+export function isStorefrontPlanError(value) {
+    return value !== null && "error" in value;
+}
+/** Whole numbers from CLI flags. An omitted flag stays omitted. */
+export function parseWholeNumber(value, label) {
+    if (value === undefined)
+        return { ok: true, value: undefined };
+    if (!/^\d+$/.test(value))
+        return { ok: false, message: `${label} must be a whole number.` };
+    return { ok: true, value: Number(value) };
+}
+function overlay(base, input, fields) {
+    const patch = {};
+    let touched = false;
+    for (const [field, jsonKey] of fields) {
+        const value = input[field];
+        if (typeof value !== "string" || value.trim() === "")
+            continue;
+        patch[jsonKey] = value.trim();
+        touched = true;
+    }
+    if (!touched)
+        return undefined;
+    return { ...(base ?? {}), ...patch };
+}
+const RESERVED_SLUGS = new Set(["www", "app", "api", "stores", "checkout", "dashboard", "admin", "mail"]);
+/** "Acme Mobile" becomes acme-mobile. Reserved or empty input returns "". */
+/** Public shop address for a hosted slug. Custom domains are not part of this address. */
+export function hostedStorefrontUrl(slug) {
+    return `https://${slug}.stores.carrier.llc`;
+}
+export function storefrontSlugFrom(raw) {
+    const folded = raw
+        .trim()
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    const clipped = folded.slice(0, 40).replace(/-+$/g, "");
+    if (RESERVED_SLUGS.has(clipped))
+        return "";
+    return /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/.test(clipped) ? clipped : "";
+}

package/dist/types.d.ts

@@ -52,3 +52,47 @@ export interface ProductCreateParams {
 export interface IdempotentRequest {
     idempotencyKey: string;
 }
+export interface HostedStorefront {
+    id: string;
+    object: "storefront";
+    slug: string;
+    name: string;
+    status: "draft" | "published";
+    url: string;
+    updated_at: number;
+    theme?: Record<string, unknown>;
+    copy?: Record<string, unknown>;
+    plans?: Array<{
+        slug: string;
+        name: string;
+        currency: string;
+        ocs_package_template_id: number;
+    }>;
+}
+export interface StorefrontPlanParams {
+    slug?: string;
+    name?: string;
+    price_cents?: number;
+    currency?: string;
+    ocs_package_template_id?: number;
+    product_id?: string;
+    description?: string;
+    data_gb?: number;
+    validity_days?: number;
+    regions?: string[];
+    active?: boolean;
+}
+export interface StorefrontCreateParams {
+    slug: string;
+    name: string;
+    status?: "draft" | "published";
+    theme?: Record<string, unknown>;
+    copy?: Record<string, unknown>;
+}
+export interface StorefrontUpdateParams {
+    slug?: string;
+    name?: string;
+    status?: "draft" | "published";
+    theme?: Record<string, unknown>;
+    copy?: Record<string, unknown>;
+}

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrierllc/sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "TypeScript client for the Carrier API, MCP server, and CLI.",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./storefront-write": {
+      "types": "./dist/storefront-write.d.ts",
+      "import": "./dist/storefront-write.js"
     }
   },
   "files": [