@carrierllc/sdk 0.2.2 → 0.2.4

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.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.
+`npm install @carrierllc/sdk@0.2.4` 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/data/cli.json

@@ -2,7 +2,7 @@
   {
     "invocation": "carrier subscribers list",
     "domain": "subscribers",
-    "summary": "List subscribers. OCS needs at least one of account/iccid/msisdn/imsi.",
+    "summary": "List subscribers. With no filter, uses your default account (lowest-id account under your reseller).",
     "write": false,
     "transport": "mcp",
     "tool": "list_subscribers",
@@ -1056,6 +1056,81 @@
       }
     ]
   },
+  {
+    "invocation": "carrier network-default show",
+    "domain": "network-default",
+    "summary": "Show the org network default (cheapest_available, all or custom) and what applies today. New assignments only.",
+    "write": false,
+    "transport": "mcp",
+    "tool": "get_network_default",
+    "restMethod": null,
+    "restPath": null,
+    "options": []
+  },
+  {
+    "invocation": "carrier network-default set",
+    "domain": "network-default",
+    "summary": "Store the org network default. Changes no SIM and writes nothing to OCS; applies to new assignments.",
+    "write": true,
+    "transport": "mcp",
+    "tool": "set_network_default",
+    "restMethod": null,
+    "restPath": null,
+    "options": [
+      {
+        "flags": "--mode <mode>",
+        "description": "cheapest_available | all | custom",
+        "required": true
+      },
+      {
+        "flags": "--list-id <id>",
+        "description": "Steering list ID from `carrier steering list`. Required when --mode is custom.",
+        "required": false
+      }
+    ]
+  },
+  {
+    "invocation": "carrier network-default plan",
+    "domain": "network-default",
+    "summary": "Show which networks a SIM would get in the given countries. Read only. Falls back to all networks with a loud warning when the tariff is missing.",
+    "write": false,
+    "transport": "mcp",
+    "tool": "plan_network_default",
+    "restMethod": null,
+    "restPath": null,
+    "options": [
+      {
+        "flags": "--countries <codes>",
+        "description": "Comma-separated ISO-3166 alpha-2 codes, e.g. CA,US",
+        "required": true
+      },
+      {
+        "flags": "--sim-mode <mode>",
+        "description": "Override for this SIM: cheapest_available | all | custom",
+        "required": false
+      },
+      {
+        "flags": "--sim-list-id <id>",
+        "description": "Steering list ID when --sim-mode is custom",
+        "required": false
+      },
+      {
+        "flags": "--package-mode <mode>",
+        "description": "Override for this package: cheapest_available | all | custom",
+        "required": false
+      },
+      {
+        "flags": "--package-list-id <id>",
+        "description": "Steering list ID when --package-mode is custom",
+        "required": false
+      },
+      {
+        "flags": "--reseller-id <id>",
+        "description": "Reseller ID (omit for the token owner's reseller)",
+        "required": false
+      }
+    ]
+  },
   {
     "invocation": "carrier accounts list",
     "domain": "accounts",

package/dist/data/operations.json

@@ -1795,6 +1795,45 @@
       }
     ]
   },
+  {
+    "id": "get_network_default",
+    "method": "GET",
+    "path": "/v1/network-default",
+    "tag": "Network",
+    "summary": "Read the org network default (cheapest_available, all or custom) and what applies today. New assignments only.",
+    "security": "bearer",
+    "body": false,
+    "bodyRequired": false,
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": []
+  },
+  {
+    "id": "set_network_default",
+    "method": "PUT",
+    "path": "/v1/network-default",
+    "tag": "Network",
+    "summary": "Set the org network default. Stored only; touches no SIM and writes nothing to OCS. Applies to new assignments.",
+    "security": "bearer",
+    "body": true,
+    "bodyRequired": true,
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": []
+  },
+  {
+    "id": "plan_network_default",
+    "method": "POST",
+    "path": "/v1/network-default/plan",
+    "tag": "Network",
+    "summary": "Plan which networks a SIM gets in given countries: the cheapest available by default, unless the org or this call overrides it. Read only; falls back to all networks with an explicit warning when the tariff is missing.",
+    "security": "bearer",
+    "body": true,
+    "bodyRequired": true,
+    "pathParams": [],
+    "queryParams": [],
+    "headerParams": []
+  },
   {
     "id": "carrier_webhook_config",
     "method": "GET",
@@ -2545,6 +2584,24 @@
     ],
     "headerParams": []
   },
+  {
+    "id": "rollback_storefront_order",
+    "method": "DELETE",
+    "path": "/api/orders/{orderId}",
+    "tag": "Storefront",
+    "summary": "Cancel one storefront order and release its eSIM (CAR-264 rollback)",
+    "security": "storefront",
+    "body": false,
+    "bodyRequired": false,
+    "pathParams": [
+      {
+        "name": "orderId",
+        "required": true
+      }
+    ],
+    "queryParams": [],
+    "headerParams": []
+  },
   {
     "id": "get_hosted_storefront",
     "method": "GET",

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" | "list_storefront_buyer_orders" | "get_storefront_order" | "get_hosted_storefront" | "list_storefronts" | "create_storefront" | "get_storefront" | "update_storefront" | "upsert_storefront_plan" | "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" | "get_network_default" | "set_network_default" | "plan_network_default" | "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" | "rollback_storefront_order" | "get_hosted_storefront" | "list_storefronts" | "create_storefront" | "get_storefront" | "update_storefront" | "upsert_storefront_plan" | "health_check";

package/dist/storefront-labels.d.ts

@@ -9,7 +9,21 @@ export type LabelResult = {
     ok: false;
     message: string;
 };
-export declare function parseDataGb(raw: string): LabelResult;
+/**
+ * `unlimited` is always explicit, never inferred later from a bare 0.
+ * A caller reading only `value` and forgetting to check `unlimited` gets a
+ * finite 0, which every downstream consumer treats as "no data" and rejects
+ * or hides, not as "unlimited" — the failure mode is loud, not silent.
+ */
+export type DataGbResult = {
+    ok: true;
+    value: number;
+    unlimited: boolean;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseDataGb(raw: string): DataGbResult;
 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): {

package/dist/storefront-labels.js

@@ -21,8 +21,11 @@ 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);
+        return { ok: true, value: 0, unlimited: true };
+    const parsed = parseAmount(raw, /gigabytes?|gbs?|gb/gi, "Enter data like 1, 1 GB, or Unlimited.", 10_000, false);
+    if (!parsed.ok)
+        return parsed;
+    return { ok: true, value: parsed.value, unlimited: false };
 }
 export function parseValidityDays(raw) {
     return parseAmount(raw, /days?/gi, "Enter validity like 7 or 7 days.", 3650, true);

package/dist/storefront-write.d.ts

@@ -23,6 +23,8 @@ export interface StorefrontPlanInput {
     currency?: string;
     templateId?: number;
     dataGb?: number;
+    /** The only way a plan becomes unlimited. A 0 or missing dataGb without this stays finite. */
+    unlimited?: boolean;
     validityDays?: number;
     regions?: string[];
     description?: string;
@@ -40,6 +42,7 @@ export interface StorefrontPlanBody {
     currency?: string;
     ocs_package_template_id?: number;
     data_gb?: number;
+    unlimited?: boolean;
     validity_days?: number;
     regions?: string[];
     description?: string;

package/dist/storefront-write.js

@@ -36,6 +36,7 @@ export function completePlanInput(input, plans) {
         input.currency,
         input.templateId,
         input.dataGb,
+        input.unlimited,
         input.validityDays,
         input.regions,
         input.description,
@@ -82,6 +83,7 @@ export function storefrontPlanBody(input) {
         input.currency,
         input.templateId,
         input.dataGb,
+        input.unlimited,
         input.validityDays,
         input.regions,
         input.description,
@@ -92,6 +94,13 @@ export function storefrontPlanBody(input) {
     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." };
     }
+    // A missing or zero dataGb never means unlimited on its own: that reading is
+    // exactly the bug a forgotten field falls into. `unlimited: true` is the
+    // only way in. A caller that means "unlimited" and sends 0 without the flag
+    // gets a loud rejection, not a silently unlimited plan.
+    if (input.dataGb !== undefined && input.dataGb <= 0 && input.unlimited !== true) {
+        return { error: "data_gb of 0 is refused. Send unlimited: true to sell an unlimited plan." };
+    }
     const body = {
         slug: input.slug,
         name: input.name,
@@ -101,6 +110,8 @@ export function storefrontPlanBody(input) {
     };
     if (input.dataGb !== undefined)
         body.data_gb = input.dataGb;
+    if (input.unlimited !== undefined)
+        body.unlimited = input.unlimited;
     if (input.validityDays !== undefined)
         body.validity_days = input.validityDays;
     if (input.regions !== undefined)

package/dist/types.d.ts

@@ -9,6 +9,8 @@ export interface ConnectivityPlan {
     object: "connectivity.plan";
     name: string;
     data_mb: number;
+    /** True only when the plan is explicitly unlimited. A 0 or missing data_mb never implies this. */
+    unlimited: boolean;
     validity_days: number;
     countries: string[];
     livemode: boolean;
@@ -78,6 +80,8 @@ export interface StorefrontPlanParams {
     product_id?: string;
     description?: string;
     data_gb?: number;
+    /** The only way to sell an unlimited plan. A 0 or missing data_gb without this is refused. */
+    unlimited?: boolean;
     validity_days?: number;
     regions?: string[];
     active?: boolean;

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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