@carrierllc/mcp 0.13.14 → 0.13.16

package/dist/cli.js

@@ -39,7 +39,7 @@ import {
   verifyStorefront,
   walletScreen,
   which
-} from "./chunk-DIHA6TVT.js";
+} from "./chunk-D6VGTHND.js";
 import {
   copyTree,
   exists,

package/dist/index.js

@@ -80,7 +80,7 @@ import {
   verifyStorefront,
   withOcsListSummary,
   withTemplateResellerId
-} from "./chunk-DIHA6TVT.js";
+} from "./chunk-D6VGTHND.js";
 import "./chunk-SHKKVIIA.js";
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrierllc/mcp",
-  "version": "0.13.14",
+  "version": "0.13.16",
   "description": "Carrier MCP \u2014 natural-language control of MVNO/eSIM fleets via eSIMVault OCS. Stdio mode for direct integration with Claude Desktop, Cursor, Windsurf, and MCP-compatible clients. Ships the `carrier` CLI (plugin install + white-label eSIM storefront scaffold).",
   "license": "MIT",
   "author": "Carrier (Lifecycle Innovations Limited)",

package/plugin/carrier/skills/issue-esim/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: issue-esim
-description: Issue one Carrier eSIM with POST /v1/connectivity/intents. Use when someone wants global connectivity, a test eSIM, or test_global_1gb. Do not use the operator OCS catalog for this.
+description: Issue one Carrier eSIM with POST /v1/connectivity/intents. Use when a developer with no eSIMVault OCS reseller account wants global connectivity, a test eSIM, or test_global_1gb. Do not use for an existing OCS reseller, and do not use the operator OCS catalog for this.
 argument-hint: "[test_global_1gb|test_eu_1gb|live plan slug] [idempotency key]"
 ---
 
@@ -8,7 +8,7 @@ argument-hint: "[test_global_1gb|test_eu_1gb|live plan slug] [idempotency key]"
 
 This is the developer path. It is one object, `connectivity.intent`, not the OCS method list.
 
-The description above is the trigger. Load this skill when the task is connectivity. Do not load the operator MCP catalog first: clients inject every tool on that server before a skill can hide them.
+The description above is the trigger. Load this skill when the task is connectivity for a developer who has no OCS reseller account. An existing OCS reseller already has an eSIMVault account and its own inventory tooling; do not steer that caller here. Do not load the operator MCP catalog first: clients inject every tool on that server before a skill can hide them.
 
 ## Install, if this skill is not already available
 
@@ -24,16 +24,59 @@ The same note, as a direct link:
 npx skills add https://carrier.llc/.well-known/agent-skills/issue-esim -g -a cursor -a claude-code -y
 ```
 
+`skills` 1.7.0 requires Node 22.20 or newer (`styleText` in a Node 20 runtime throws a SyntaxError before this even installs). On Node 20, run either command through `npx -p node@22` instead:
+
+```bash
+npx -y -p node@22 -p skills -- skills add https://carrier.llc -g -a cursor -a claude-code -y
+npx -y -p node@22 -p skills -- skills add https://carrier.llc/.well-known/agent-skills/issue-esim -g -a cursor -a claude-code -y
+```
+
 ## Issue
 
 `POST https://api.carrier.llc/v1/connectivity/intents`
 
 Required header: `Idempotency-Key` (stable per order, max 255 characters).
 
-Auth: `Authorization: Bearer` with an `ak_` key from the console. Do not put the key in the repo.
+Auth: `Authorization: Bearer $CARRIER_API_KEY` with an `ak_` key. Mint one with `POST /v1/api-keys` (needs the write scope, so do this once from the console after upgrading — see Auth errors below), or from the console under Settings → API Keys. Do not put the key in the repo.
+
+```bash
+curl -sS https://api.carrier.llc/v1/connectivity/intents \
+  -X POST \
+  -H "Authorization: Bearer $CARRIER_API_KEY" \
+  -H "Idempotency-Key: order_123" \
+  -H "Content-Type: application/json" \
+  -d '{ "plan": "test_global_1gb" }'
+```
+
+Response, `201 Created` on the first call (`200` on a replay of the same key and body):
 
 ```json
-{ "plan": "test_global_1gb" }
+{
+  "id": "cni_5f9b1c2d3e4a4b6c8d7e9f0a1b2c3d4e",
+  "object": "connectivity.intent",
+  "status": "succeeded",
+  "livemode": false,
+  "plan": {
+    "id": "test_global_1gb",
+    "object": "connectivity.plan",
+    "name": "Test Global 1 GB",
+    "data_mb": 1024,
+    "validity_days": 7,
+    "countries": ["US", "GB", "DE", "FR", "JP", "SG", "BR", "AU"],
+    "livemode": false,
+    "price": null
+  },
+  "esim": {
+    "iccid": "8900000000000000001",
+    "activation_code": "LPA:1$test.smdp.carrier.llc$TEST",
+    "qr_code": null,
+    "smdp_address": "test.smdp.carrier.llc",
+    "matching_id": "TEST"
+  },
+  "metadata": {},
+  "error": null,
+  "created": 1798761600
+}
 ```
 
 Plans:
@@ -41,13 +84,28 @@ Plans:
 - `test_global_1gb` and `test_eu_1gb` succeed immediately, set `livemode` false, and never call the network. They work on the free tier. The ICCID `8900000000000000001` and SM-DP+ `test.smdp.carrier.llc` are fixtures.
 - Any other slug is a live catalogue plan. It draws one eSIM from the caller's own account and needs the write scope. Do not fall back to a platform stock account.
 
-The same key and body return the original intent. Do not issue a second SIM to "make sure".
+The same key and body return the original intent (`200`, same `id`). The same key with a different `plan` or `metadata` is refused with `409 idempotency_mismatch` and does not touch the first intent — retry with a new key instead of reusing one across two different orders:
+
+```json
+{ "error": { "type": "invalid_request_error", "code": "idempotency_mismatch", "message": "This Idempotency-Key was already used with a different request." } }
+```
 
 Confirm a plan later with `POST /v1/connectivity/intents/:id/confirm` when the first call omitted `plan`.
 
+### Auth errors
+
+| Cause | Status | Body |
+| --- | --- | --- |
+| No `Authorization` header, or not `Bearer ...` | 401 | `{ "error": "Missing or invalid Authorization header" }` |
+| Bearer token invalid or expired | 401 | `{ "error": "Unauthorized" }` |
+| Live plan (anything but `test_global_1gb`/`test_eu_1gb`) on the free tier | 402 | `{ "error": { "type": "invalid_request_error", "code": "write_required", "message": "Live plans require the write scope. Test plans such as test_global_1gb work on the free tier." } }` |
+| Monthly quota exceeded (free: 1,000 calls/mo, pro: 50,000) | 429 | `{ "error": "Monthly quota exceeded", "limit": 1000, "used": 1000, "reset_at": "...", "upgrade_url": "https://mcp.carrier.llc/upgrade" }` |
+
+The write scope (needed for any live, non-`test_` plan and for minting `ak_` keys) comes from the **Pro** or **Enterprise** subscription tier; the free tier only has the read scope. Test plans work on free with no subscription and no eSIMVault account. Get an `ak_` key from Console → Settings → API Keys after upgrading, or headlessly via `POST /v1/api-keys` once you already have write-scoped access from the console session.
+
 ## One-tool MCP
 
-`carrier-intent` is a separate process with one tool, `create_connectivity_intent`. It posts the intent above. It is not registered on `https://mcp.carrier.llc/mcp`.
+`carrier-intent` is a separate process with two tools: `create_connectivity_intent` and `publish_storefront`. This skill uses `create_connectivity_intent`, which posts the intent above. `publish_storefront` belongs to the publish-storefront skill. It is not registered on `https://mcp.carrier.llc/mcp`.
 
 ```json
 {
@@ -66,8 +124,13 @@ Put the `ak_` key in that env block on the machine. Call the tool with `plan` an
 ## After it succeeds
 
 - Read `esim.iccid` and `esim.smdp_address` back to the user.
-- Webhooks: `POST /v1/connectivity/webhook_endpoints` with an https URL. The secret is shown once. Deliveries use `Carrier-Signature`.
-- Test usage: `POST /v1/connectivity/usage_records` with the intent id and `quantity_mb`. A live intent refuses a self-reported quantity (`network_metered`) because the wallet meter already debits those bytes.
+- Webhooks: `POST /v1/connectivity/webhook_endpoints` with an https URL. The secret (`whsec_...`) is shown once, on create only. Events fire for `esim.issued` (a succeeded intent, including test plans), `esim.first_attach`, and `usage.threshold_reached`; a redelivery is `POST /v1/connectivity/events/:id/retry`, not a new event. Test-plan intents do fire `esim.issued` — it is not gated on `livemode`.
+- Verify `Carrier-Signature`: HMAC-SHA256 over `${timestamp}.${body}` with the endpoint secret, header shaped `t=<unix>,v1=<hex>`. Recompute the hex over the raw body and compare to `v1`. Carrier does not currently enforce a delivery time margin on the send side, so an integration that wants replay protection should reject a `t` more than a few minutes from its own clock.
+- Test usage: `POST /v1/connectivity/usage_records` with the intent id and `quantity_mb`. A live intent refuses a self-reported quantity with `400 network_metered` because the wallet meter already debits those bytes.
+
+## Shared inventory with OCS resellers
+
+A live (non-`test_`) plan draws its eSIM from the same eSIMVault account number as everything else on that account — the connectivity intent, the storefront checkout webhook, and a direct OCS `affectPackageToSubscriber` call all pull from one pool. Issuing through this skill does not create separate stock. Each draw is idempotency-locked per channel (`intent:<id>` for this path) so retries cannot double-issue, but two different channels against the same low-stock template can still race each other for the last unit — whichever wins the OCS call gets it, and the other side sees `NO_INVENTORY`/503, not a queued retry. If you also run OCS writes directly, keep template-level headroom rather than assuming this skill's calls are invisible to your other tooling.
 
 ## If the person is new, use these sentences
 
@@ -84,6 +147,8 @@ A country list is the countries someone typed on an offer. Carrier stores that l
 Steering is which mobile networks a SIM is told to join. Changing it is a job for the person who runs the SIMs.
 A green zone is a short list of sites that can stay reachable after the data is used up, so someone can get help, pay, or download the SIM again.
 
+Longer explanations, plus when to use each tool and when to skip it: [references/glossary.md](references/glossary.md).
+
 ## Do not
 
 - Do not register `https://mcp.carrier.llc/mcp` to issue this SIM. That server is the operator fleet.

package/plugin/carrier/skills/issue-esim/references/glossary.md

@@ -0,0 +1,14 @@
+# Glossary, for someone new to this
+
+A skill is a note your AI reads so it follows the same steps every time.
+A plug lets an AI app press a button. This plug has one button: give this order a SIM.
+This other plug opens every button a phone company uses to run many SIMs.
+These are the same switchboard buttons, typed into a terminal instead of clicked. People call that a CLI.
+An intent is your ask: please attach a SIM to this order. The same ask twice does not make two SIMs.
+A product is the offer you sell: how much data, how many days, which countries, and the price. Saving it does not charge anyone.
+A package is the data sitting on one SIM after it is issued. A code package, such as the library named @carrierllc/sdk, is a different thing.
+A subscriber is one SIM line, and the person or device that line belongs to.
+On this page a client is the small code library your app uses to ask for a SIM. A customer is the person who buys that SIM.
+A country list is the countries someone typed on an offer. Carrier stores that list. It does not look up a live coverage map.
+Steering is which mobile networks a SIM is told to join. Changing it is a job for the person who runs the SIMs.
+A green zone is a short list of sites that can stay reachable after the data is used up, so someone can get help, pay, or download the SIM again.

package/plugin/carrier/skills/publish-storefront/SKILL.md

@@ -18,10 +18,10 @@ Once per user, so every project sees it:
 npx skills add https://carrier.llc -g -a cursor -a claude-code -y
 ```
 
-If that host is not published yet, install this directory:
+`skills` 1.7.0 requires Node 22.20 or newer (`styleText` in a Node 20 runtime throws a SyntaxError before this even installs). On Node 20, run that command through `npx -p node@22` instead:
 
 ```bash
-npx skills add https://github.com/Lifecycle-Innovations-Limited/carrier.llc/tree/main/apps/mcp-stdio/plugin/carrier/skills/publish-storefront -g -a cursor -a claude-code -y
+npx -y -p node@22 -p skills -- skills add https://carrier.llc -g -a cursor -a claude-code -y
 ```
 
 ## Publish
@@ -70,9 +70,9 @@ A replay of the same key returns the original store. Send theme and copy again o
 }
 ```
 
-`price_cents` is the Stripe minor-unit amount. For EUR, 900 is 9.00. For JPY, 1000 is 1000 yen, not 100000. The OCS template id is the package that gets issued. Changing this price does not change another slug. Leave out data, validity, countries, buyer text, or whether the plan is for sale, and those stored values stay. When the shop has one plan, a price alone is enough: the CLI and the intent tool reuse that plan's slug, name, currency, and template id. A new plan can omit currency when every saved plan uses the same code.
+`price_cents` is the Stripe minor-unit amount. For EUR, 900 is 9.00. For JPY, 1000 is 1000 yen, not 100000. `ocs_package_template_id` is the OCS package template that gets issued. Do not look it up in the operator OCS catalog. The default route is `product_id` (below): the connectivity plan already carries its template id, so you never type it. That id was supplied once, when the org created the plan with `POST /v1/connectivity/products` (`package_template_id`) or in the console under Connectivity products. Send `ocs_package_template_id` yourself only when you already hold a template id from your own OCS account. Changing this price does not change another slug. Leave out data, validity, countries, buyer text, or whether the plan is for sale, and those stored values stay. When the shop has one plan, a price alone is enough: the CLI and the intent tool reuse that plan's slug, name, currency, and template id. A new plan can omit currency when every saved plan uses the same code.
 
-To copy a connectivity plan the org already created, send its id instead of the template fields. Optional `price_cents` overrides the retail price. The shop address is derived from the plan name.
+This is the standard route: to copy a connectivity plan the org already created, send its id instead of the template fields. Optional `price_cents` overrides the retail price. The shop address is derived from the plan name.
 
 ```json
 { "product_id": "cnp_abcdef0123456789abcdef0123456789", "price_cents": 1200 }
@@ -111,4 +111,12 @@ The CLI reads the existing store and merges color and copy before the PATCH. A s
 
 `description` is the sentence buyers read under the plan name. Leave it out to keep the saved sentence. The intent tool field is `plan_description`. The CLI flag is `--plan-text`.
 
-The developer MCP tool is `publish_storefront` on the intent server. It accepts `accent`, `hero`, `product_id`, `plan_slug`, `plan_name`, `price` (`9.00`, or `1000` with currency JPY) or `price_cents`, `currency`, `ocs_package_template_id`, `data_gb` (`1 GB`, or the text `Unlimited`), `unlimited` (boolean; the only way to sell an unlimited plan — a bare `data_gb: 0` without it is refused), `validity_days` (`7 days`), `regions` (France or DE), and `plan_description`. `product_id` copies a connectivity plan and does not need a template id. It is not an operator OCS tool.
+The intent server (`carrier-intent`, package `@carrierllc/mcp-intent`) has two tools: `create_connectivity_intent`, which the issue-esim skill covers, and `publish_storefront`, which this skill covers. Neither is an operator OCS tool. `publish_storefront` accepts `accent`, `hero`, `product_id`, `plan_slug`, `plan_name`, `price` (`9.00`, or `1000` with currency JPY) or `price_cents`, `currency`, `ocs_package_template_id`, `data_gb` (`1 GB`, or the text `Unlimited`), `unlimited` (boolean; the only way to sell an unlimited plan — a bare `data_gb: 0` without it is refused), `validity_days` (`7 days`), `regions` (France or DE), and `plan_description`. `product_id` copies a connectivity plan and does not need a template id.
+
+## Who is paid
+
+State of the code today, not a commercial agreement:
+
+- A hosted shop sells through Stripe Checkout created by Carrier's checkout service with Carrier's own Stripe key. The session sets no connected account, application fee, or transfer, so the payment is collected on Carrier's Stripe account.
+- Nothing in this API pays the buyer's money out to the brand, and it does not define a fee, a tax or VAT setting, or terms of sale. The `legalName` you send is printed in the shop footer. It is display text, not a merchant registration.
+- Settlement, fees, VAT, and terms between the brand and Carrier are not set by this API. Confirm them with Carrier before you take live orders.

package/templates/storefront/src/vendor/carrier/client.ts

@@ -72,6 +72,18 @@ const MOCK_TEMPLATES: SkuTemplate[] = [
   },
 ];
 
+/**
+ * How long the storefront may keep serving a catalog it already fetched.
+ *
+ * A price or bundle change made in Carrier must be visible within the agreed
+ * ceiling (CAR-281: 3600s ISR). The unscoped `/api/templates` answer also
+ * carries `public, max-age=60` upstream, so revalidate + 60s is the real
+ * worst case. It used to be 3600 for the unscoped read, which put the worst
+ * case at 3660s. Keep one value for both reads and keep it well under the
+ * ceiling; the scoped read is also busted by tag on save.
+ */
+export const CATALOG_REVALIDATE_SECONDS = 60;
+
 /** Why the catalog is not live. Absent when `source` is "live". */
 export type CatalogDegradedReason = "unconfigured" | "upstream-error" | "network-error";
 
@@ -109,8 +121,8 @@ export async function fetchTemplateCatalog(): Promise<TemplateCatalog> {
       : "/api/templates";
     const res = await fetch(`${base}${templatesPath}`, {
       next: slug
-        ? { revalidate: 60, tags: [`storefront:${slug}`] }
-        : { revalidate: 3600 },
+        ? { revalidate: CATALOG_REVALIDATE_SECONDS, tags: [`storefront:${slug}`] }
+        : { revalidate: CATALOG_REVALIDATE_SECONDS },
     });
     if (!res.ok) return sampleCatalog("upstream-error");
     const templates = (await res.json()) as SkuTemplate[];