← Stripe Pin Desk
API
Tokens

Run Stripe Pin Desk from your own code

Both metered lanes are available over HTTP and each returns one JSON object. The division of labour: the page masks the comments, finds the API version pins in the file, compares each with the target, bumps the safe ones itself and lists what needs a decision, then hands it all to the run as facts. The run writes the review or the rewrite; the page then holds it to its own facts and re-scans the upgraded file with the same scanner (pinreply.js).

Base URL and the response shape

Every endpoint lives under https://api.skillsafe.ai/v1/app-api, and every response has one shape:

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

The token is minted for this app (the guest call takes {"slug":"stripe-pin-desk"}), so no slug header is needed afterwards. Send it as Authorization: Bearer YOUR_TOKEN. The run body is the input object, sent bare.

StatusCodeMeaning
400validation_errorThe body is not a JSON object, or a required key (task, unit, code, facts) is missing. The page always sends all six of task, unit, code, manifest, carry, facts; carry is an empty string for review and manifest may be empty.
401unauthorizedNo token, or a stale one. Mint a guest token or sign in again.
402insufficient_creditsThe balance is under min_credits. Price with /estimate first.
403forbiddenA guest token tried to run: both lanes are metered and need a personal sign-in.
404not_foundUnknown job id.
429rate_limitedBack off and retry.
5xxserver_errorTransient. Retry with the same Idempotency-Key so a retry never double-bills.

The task field comes first

Two lanes, chosen by task, in the order the work runs - inspect, then produce:

A missing or unknown task is answered as review. Both lanes send the same six fields. The facts are the page's scan, one finding per line with its id, and a line starting "must:" is a rule the reply has to hold. The page's handoff carries the review's decisions into carry for the rewrite lane. The review sends at most 24,000 characters of code (the middle of a longer file is cut on whole lines and marked; every finding is still in the facts); the rewrite lane takes at most 16,000.

The input

FieldRequiredWhat
taskyesreview or rewrite (the page calls it Upgrade). If it is missing or neither, do review and set "task": "review".
unityesthe file's path, the language and the target with its source.
codeyesthe file as pasted (before the page's changes). A line starting "// [... N lines cut by the page" (or "# [..." or "<!-- [...") marks code the page scanned but did not send.
manifestsend it (may be empty)the package manifest as pasted; may be empty.
carrysend it (empty for review)rewrite task only: the review's decisions, one per line as id | confirmed or cleared or extra | where | fix or reason; may be empty.
factsyesthe page's scan: the language, the target and its source, every pin (line, kind, where, value, the page's action), thin event handling, then one finding per line as id | area | severity | line | where | evidence | source | what the page did (changed or left). "changed" means the page made the change the finding's fix names in its own copy, which the person already has; the code field is still the original paste, so judge it as written. Lines starting "must:" apply to your reply.
retry_notenooptional; if present, your previous reply was unusable - follow it.

The rules the model applies

From the source skill, @stripe/upgrade-stripe - the only standard the run applies:

House rules

The replies

review

Decide each finding, state the target, add what a scan cannot see, put the steps in order and write the tests.

  1. summary - one sentence, at most 40 words: which pins are off the target today, what the page already changed, and the first step.
  2. target - one sentence: the target version, its source (entered by the person, or the bundled fallback - unverified), and whether it crosses a major release from the oldest pin.
  3. findings - one object per page finding you confirm, in id order: id, widget (where it sits, e.g. "createCheckout"), issue (one sentence), fix (one sentence, one decision), code (the lines for that piece only, at most 8; "" when fix says it all).
  4. cleared - one object per page finding that is not a problem here, with id and why (one sentence tied to the code). Every page id appears exactly once, in findings or in cleared.
  5. extra - at most 5 issues the scan cannot see, each tied to a line of the code: id (X1, X2, ...), area (pins, client, typed, changelog, tests, webhooks, events, stripejs, sdk or storage), line (a number), widget, issue, fix. Examples: a response field the code reads that a major release may rename (name the call, the changelog decides), a pin passed through a helper, a handler that verifies with one signing secret where cutover needs two, an object id cached in a fixed-width field, a retry that replays a request on the old version. [] when there are none.
  6. plan - 2 to 10 short strings, the steps in order following the skill's checklist (the changelog, the SDK package, the client pin and overrides, the tests with the Stripe-Version header, webhook endpoints, Stripe.js and mobile, id storage), each naming the ids it covers (e.g. "Pin the reporting client to the target (P3)"). Every confirmed id appears in a step. [] only when nothing is confirmed.
  7. tests - 3 to 12 strings, each one command or one check: curl calls to the Stripe API for the resources this file uses, each with -u "$STRIPE_SECRET_KEY:" and -H "Stripe-Version: <the target>"; the webhook check (stripe trigger or a test event to the replacement endpoint); one check per changed call path.
  8. caveats - at most 4 short strings; [] when there is nothing to say.
{
  "task": "review",
  "summary": "one sentence",
  "target": "one sentence",
  "findings": [ { "id": "P1", "widget": "the file", "issue": "one sentence", "fix": "one sentence", "code": "" } ],
  "cleared": [ { "id": "P2", "why": "one sentence" } ],
  "extra": [ { "id": "X1", "area": "changelog", "line": 52, "widget": "syncSubscription", "issue": "one sentence", "fix": "one sentence" } ],
  "plan": [ "Pin the reporting client to the target (P3)" ],
  "tests": [ "curl https://api.stripe.com/v1/customers -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\"" ],
  "caveats": [ ]
}

The page holds it to its own facts (check() in pinreply.js; any warning makes the reply flagged): the reply answers the task it was sent; every page finding id appears exactly once across findings and cleared, and no id the page never found; a cleared id has a reason; a confirmed id has an issue and a fix; the target is stated and is the page's, and the bundled fallback is never called the latest without saying it is unverified; at most five extra issues, each on a line inside the paste; a fix order of 2 to 10 steps that names every confirmed id; 3 to 12 tests, every API call among them sending Stripe-Version with the target and the key from STRIPE_SECRET_KEY; a summary; no web link in the prose and no key in any field.

rewrite

Rewrite the whole file on the target.

  1. summary - one sentence, at most 40 words: what the upgrade changed and what it left for the person.
  2. code - the complete file. Keep every function, export, class, import still used and every call; change what the findings and the carried decisions name, plus every carried extra whose edit is made in this file (list it in changes; one that needs another file or the Dashboard goes in a caveat). Every pin the file keeps is the target, or the pasted value of a pin whose finding is in kept (a newer pin, a preview pin, a typed SDK the person upgrades). Never write a secret. Never shorten the file with "..." or "unchanged" - write every line. If the code holds a line marking a cut by the page, keep that line exactly where it is.
  3. changes - one object per page finding you acted on (including the ones the page already changed, which the upgrade keeps), in id order: id, change (one sentence naming where). Carried extra ids (X1, ...) go after the page's ids.
  4. kept - one object per page finding you did not change: id, why (one sentence - the review cleared it, it needs the changelog or the Dashboard, or the manifest the person edits). A confirmed finding whose fix is a check rather than a line in this file (the changelog, a replacement endpoint made in the Dashboard, the manifest) belongs in kept; a carried extra with no edit in this file goes in a caveat. The page's re-scan still lists what stays true after a correct upgrade (a snapshot handler, a pin kept on purpose). Every page id appears exactly once, in changes or in kept; an id the carried review cleared belongs in kept.
  5. caveats - at most 4 short strings; [] when there is nothing to say.
{
  "task": "rewrite",
  "summary": "one sentence",
  "code": "the complete file",
  "changes": [ { "id": "P1", "change": "one sentence" } ],
  "kept": [ { "id": "P2", "why": "one sentence" } ],
  "caveats": [ ]
}

The page requires: the reply answers the task it was sent; every page finding id appears exactly once across changes and kept; every function survives; the file is not shortened and elides nothing; no key in the code; and the upgraded code is scanned again against the same target - a rule the changes claim fixed that still fires, or a rule the paste never had, is flagged; so is a pin on a version neither pasted nor the target, and a pin newer than the target that the upgrade moved down.

Worked examples

Three runs from the page's free samples (invented apps): the review of a Node.js billing service on 2024-06-20, the upgrade of the same file carrying that review, and the review of a checkout page on Stripe.js basil. Each input is exactly what the page sends; each reply is the saved reply the sample replays, shipped unedited - but the code, the facts and long strings are shortened in this display only, and every cut is listed under the example. The last line is the page's own check of the full reply.

review - A Node.js billing service on 2024-06-20

The page read it as: Needs decisions - 0 blocker, 1 major, 1 minor; findings P1 major-jump, P2 stale-pin, P3 no-pin, P4 id-length, P5 major-jump, P6 stale-pin, P7 webhook-version, P8 snapshot-handler, P9 unknown-event.

Input (code is 2151 characters; the first 1380 are shown; facts is 3192 characters; the first 1395 are shown):

{
 "task": "review",
 "unit": "File: src/billing.ts\nLanguage: Node.js / TypeScript (stripe-node)\nTarget: 2026-10-28.endive (bundled fallback, unverified)",
 "code": "import Stripe from \"stripe\";\nimport express from \"express\";\nimport knex from \"knex\";\nimport { config } from \"./config\";\n\n// One client for the app, one for the nightly reports job.\nconst stripe = new Stripe(config.stripeSecretKey, {\n  apiVersion: \"2024-06-20\",\n  maxNetworkRetries: 2,\n});\nconst reporting = new Stripe(config.reportingKey);\n\nexport async function migrate(db: knex.Knex) {\n  await db.schema.createTable(\"accounts\", (table) => {\n    table.increments(\"id\");\n    table.string(\"email\").notNullable();\n    table.string(\"stripe_customer_id\", 32);\n    table.string(\"stripe_subscription_id\", 255);\n  });\n}\n\nexport async function createCheckout(priceId: string, customer: string) {\n  return stripe.checkout.sessions.create(\n    { mode: \"subscription\", customer, line_items: [{ price: priceId, quantity: 1 }], success_url: config.appUrl + \"/thanks\" },\n    { apiVersion: \"2025-03-31.basil\" }\n  );\n}\n\nexport async function monthlyRevenue() {\n  const charges = await reporting.charges.list({ limit: 100, created: { gte: config.monthStart } });\n  return charges.data.reduce((sum, c) => sum + c.amount, 0);\n}\n\nexport async function registerWebhook(url: string) {\n  return stripe.webhookEndpoints.create({\n    url,\n    api_version: \"2024-06-20\",\n    enabled_events: [\"invoice.paid\", \"customer.subscription.updated\", \"customer.subscription.deleted\"],\n  });\n}\n\nconst app = express();\n\n[... 771 more characters cut from this display ...]",
 "manifest": "",
 "carry": "",
 "facts": "The page's scan of 66 lines (Node.js / TypeScript (stripe-node), detected) - 3 version pins (1 client, 1 per-request, 1 webhook endpoint); 4 of 9 findings changed by the page; verdict: Needs decisions.\nTarget: 2026-10-28.endive - the skill's bundled fallback, a snapshot from 2026-11-03; not verified against the live docs, so never call it the latest; the endive release, stable.\nPins (line | kind | where | pinned | the page's action):\n- line 8 | client | the file | 2024-06-20 | bumped to 2026-10-28.endive\n- line 25 | per-request | createCheckout | 2025-03-31.basil | bumped to 2026-10-28.endive\n- line 37 | webhook endpoint | registerWebhook | 2024-06-20 | left\nThin event handling: none seen. Manifest: none pasted.\nFindings (id | area | severity | line | where | evidence | source | what the page did):\n- P1 | changelog | major | line 8 | the file | From 2024-06-20 to 2026-10-28.endive the integration crosses 5 major releases (acacia, basil, clover, dahlia, endive), each starting with breaking changes: field renames or removals, behaviour changes, removed endpoints or parameters. | source: apiVersion: \"2024-06-20\", | left\n- P2 | pins | major | line 8 | the file | A client pin on 2024-06-20, older than the target 2026-10-28.endive. | source: apiVersion: \"2024-06-20\", | changed\n- P3 | client | major | line 11 | the file | The client is created without an explicit API version - it\n\n[... 1797 more characters cut from this display ...]"
}

Reply:

{
 "task": "review",
 "summary": "The client, reporting client and createCheckout pins sit off 2026-10-28.endive and the webhook endpoint stays on 2024-06-20; the page bumped the pins and widened stripe_customer_id, so the first step is reading the changelog from 2024-06-20.",
 "target": "The target is 2026-10-28.endive, the skill's bundled fallback and unverified against the live docs, and from the oldest pin 2024-06-20 it crosses five major releases (acacia, basil, clover, dahlia, endive).",
 "findings": [
  {
   "id": "P1",
   "widget": "the file",
   "issue": "The client moves from 2024-06-20 to 2026-10-28.endive across five major releases, so calls such as stripe.checkout.sessions.create, reporting.charges.list and stripe.webhookEndpoints.create may meet breaking changes.",
   "fix": "Read the changelog from 2024-06-20 to 2026-10-28.endive and adjust each call and field this file reads where the changelog says so.",
   "code": ""
  },
  {
   "id": "P2",
   "widget": "the file",
   "issue": "The main client is pinned to 2024-06-20, older than the target.",
   "fix": "Keep the page's change, which sets apiVersion to 2026-10-28.endive in the main client configuration.",
   "code": "const stripe = new Stripe(config.stripeSecretKey, {\n  apiVersion: \"2026-10-28.endive\",\n  maxNetworkRetries: 2,\n});"
  },
  {
   "id": "P3",
   "widget": "the file",
   "issue": "The reporting client is created without an API version, so it follows the account's default and shifts when the account is upgraded.",
   "fix": "Keep the page's change, which pins the reporting client explicitly to 2026-10-28.endive.",
   "code": "const reporting = new Stripe(config.reportingKey, { apiVersion: \"2026-10-28.endive\" });"
  },
  {
   "id": "P4",
   "widget": "migrate",
   "issue": "The stripe_customer_id column is capped at 32 characters while Stripe object ids can reach 255.",
   "fix": "Keep the page's change, which widens stripe_customer_id to 255 characters.",
   "code": "table.string(\"stripe_customer_id\", 255);"
  },
  {
   "id": "P5",
   "widget": "createCheckout",
   "issue": "The per-request override moves from 2025-03-31.basil to the target across clover, dahlia and endive, so stripe.checkout.sessions.create and its parameters may meet breaking changes.",
   "fix": "Check stripe.checkout.sessions.create and its parameters (mode, customer, line_items, success_url) against the changelog from basil to endive before shipping the bump.",
   "code": ""
  },
  {
   "id": "P6",
   "widget": "createCheckout",
   "issue": "The per-request override on stripe.checkout.sessions.create is pinned to 2025-03-31.basil, older than the target.",
   "fix": "Keep the page's change, which sets the per-request apiVersion to 2026-10-28.endive.",
   "code": "{ apiVersion: \"2026-10-28.endive\" }"
  },
  {
   "id": "P7",
   "widget": "registerWebhook",
   "issue": "The webhook endpoint is created on 2024-06-20, so its snapshot payloads keep that version until the endpoint is replaced.",
   "fix": "Set api_version to 2026-10-28.endive in registerWebhook and create a replacement endpoint with it, saving its new signing secret, then disable the old endpoint after cutover.",
   "code": "api_version: \"2026-10-28.endive\","
  },
  {
   "id": "P8",
   "widget": "the file",
   "issue": "The handler casts snapshot payloads to Stripe.Invoice and Stripe.Subscription, which follow the endpoint's version rather than the client's pin, so they stay on 2024-06-20 until the endpoint moves.",
   "fix": "Test markPaid and syncSubscription with snapshot events from the replacement endpoint on 2026-10-28.endive before cutover.",
   "code": ""
  },
  {
   "id": "P9",
   "widget": "the file",
   "issue": "The switch over event.type has no default branch, so an unfamiliar event type passes without any handling.",
   "fix": "Add a default branch that logs the unfamiliar event type and still answers with received true.",
   "code": "    default:\n      console.log(\"unhandled event\", event.type);\n      break;"
  }
 ],
 "cleared": [],
 "extra": [
  {
   "id": "X1",
   "area": "webhooks",
   "line": 44,
   "widget": "the file",
   "issue": "stripe.webhooks.constructEvent verifies with the single config.webhookSecret, but the cutover to a replacement endpoint needs the old and new signing secrets accepted together.",
   "fix": "Try the new signing secret first and fall back to the old one, both read from env vars, until the old endpoint is disabled."
  },
  {
   "id": "X2",
   "area": "changelog",
   "line": 63,
   "widget": "syncSubscription",
   "issue": "syncSubscription reads sub.current_period_end from the subscription payload, a field a major release may rename or move.",
   "fix": "Check the customer.subscription events and the Subscription object in the changelog and change the field read only if the changelog says so."
  },
  {
   "id": "X3",
   "area": "changelog",
   "line": 59,
   "widget": "markPaid",
   "issue": "markPaid reads invoice.amount_paid from the invoice.paid payload, a field a major release may change.",
   "fix": "Check the Invoice object in the changelog from 2024-06-20 to endive and adjust the field read only if the changelog says so."
  }
 ],
 "plan": [
  "Read the changelog from 2024-06-20 to 2026-10-28.endive for every call this file makes (P1, P5)",
  "Pin the main client and the reporting client to the target (P2, P3)",
  "Move the createCheckout per-request override to the target (P6)",
  "Widen stripe_customer_id to 255 characters with a migration (P4)",
  "Run the tests with the Stripe-Version header on the target before changing the default",
  "Create a replacement webhook endpoint on the target in registerWebhook and save its signing secret (P7)",
  "Accept both signing secrets during cutover and test the handlers with target snapshot events (P8)",
  "Add a default branch for unfamiliar event types, then disable the old endpoint (P9)"
 ],
 "tests": [
  "curl https://api.stripe.com/v1/customers?limit=1 -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\"",
  "curl https://api.stripe.com/v1/checkout/sessions?limit=1 -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\"",
  "curl \"https://api.stripe.com/v1/charges?limit=100\" -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\"",
  "curl https://api.stripe.com/v1/webhook_endpoints -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\"",
  "curl https://api.stripe.com/v1/webhook_endpoints -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\" -d url=\"$WEBHOOK_URL\" -d api_version=2026-10-28.endive -d \"enabled_events[]=invoice.paid\"",
  "curl https://api.stripe.com/v1/subscriptions?limit=1 -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\"",
  "stripe trigger invoice.paid against the replacement endpoint and check markPaid logs the invoice id and amount",
  "stripe trigger customer.subscription.updated and check syncSubscription logs the id, status and period end",
  "Call createCheckout with a test price and customer and check the session is created on 2026-10-28.endive",
  "Run monthlyRevenue against test-mode charges and check the sum matches"
 ],
 "caveats": [
  "The account upgrade itself happens in Workbench, and a rollback stays open for 72 hours after it.",
  "Endpoints registered outside this file need a replacement on the target in the Dashboard.",
  "The second signing secret has to be added to the environment alongside STRIPE_WEBHOOK_SECRET during cutover."
 ]
}

What step 5 prints for it: P1: Read the changelog from 2024-06-20 to 2026-10-28.endive and adjust each call and field this file reads where the changelog says so. | P2: Keep the page's change, which sets apiVersion to 2026-10-28.endive in the main client configuration. | P3: Keep the page's change, which pins the reporting client explicitly to 2026-10-28.endive. | P4: Keep the page's change, which widens stripe_customer_id to 255 characters. | P5: Check stripe.checkout.sessions.create and its parameters (mode, customer, line_items, success_url) against the changelog from basil to endive before shipping the bump. | P6: Keep the page's change, which sets the per-request apiVersion to 2026-10-28.endive. | P7: Set api_version to 2026-10-28.endive in registerWebhook and create a replacement endpoint with it, saving its new signing secret, then disable the old endpoint after cutover. | P8: Test markPaid and syncSubscription with snapshot events from the replacement endpoint on 2026-10-28.endive before cutover. | P9: Add a default branch that logs the unfamiliar event type and still answers with received true.

The page's check: kept - X1 repeats what the page already found on line 44.

rewrite - A Node.js billing service on 2024-06-20

The input carries the saved review (R.laneForm fills carry from the review reply), as the page's handoff does. The page re-scanned the upgraded code: 9 findings before, 1 after.

Input (code is 2151 characters; the first 1380 are shown; facts is 3192 characters; the first 1395 are shown; carry is 1811 characters; the first 1399 are shown):

{
 "task": "rewrite",
 "unit": "File: src/billing.ts\nLanguage: Node.js / TypeScript (stripe-node)\nTarget: 2026-10-28.endive (bundled fallback, unverified)",
 "code": "import Stripe from \"stripe\";\nimport express from \"express\";\nimport knex from \"knex\";\nimport { config } from \"./config\";\n\n// One client for the app, one for the nightly reports job.\nconst stripe = new Stripe(config.stripeSecretKey, {\n  apiVersion: \"2024-06-20\",\n  maxNetworkRetries: 2,\n});\nconst reporting = new Stripe(config.reportingKey);\n\nexport async function migrate(db: knex.Knex) {\n  await db.schema.createTable(\"accounts\", (table) => {\n    table.increments(\"id\");\n    table.string(\"email\").notNullable();\n    table.string(\"stripe_customer_id\", 32);\n    table.string(\"stripe_subscription_id\", 255);\n  });\n}\n\nexport async function createCheckout(priceId: string, customer: string) {\n  return stripe.checkout.sessions.create(\n    { mode: \"subscription\", customer, line_items: [{ price: priceId, quantity: 1 }], success_url: config.appUrl + \"/thanks\" },\n    { apiVersion: \"2025-03-31.basil\" }\n  );\n}\n\nexport async function monthlyRevenue() {\n  const charges = await reporting.charges.list({ limit: 100, created: { gte: config.monthStart } });\n  return charges.data.reduce((sum, c) => sum + c.amount, 0);\n}\n\nexport async function registerWebhook(url: string) {\n  return stripe.webhookEndpoints.create({\n    url,\n    api_version: \"2024-06-20\",\n    enabled_events: [\"invoice.paid\", \"customer.subscription.updated\", \"customer.subscription.deleted\"],\n  });\n}\n\nconst app = express();\n\n[... 771 more characters cut from this display ...]",
 "manifest": "",
 "carry": "P1 | confirmed | the file | Read the changelog from 2024-06-20 to 2026-10-28.endive and adjust each call and field this file reads where the changelog says so.\nP2 | confirmed | the file | Keep the page's change, which sets apiVersion to 2026-10-28.endive in the main client configuration.\nP3 | confirmed | the file | Keep the page's change, which pins the reporting client explicitly to 2026-10-28.endive.\nP4 | confirmed | migrate | Keep the page's change, which widens stripe_customer_id to 255 characters.\nP5 | confirmed | createCheckout | Check stripe.checkout.sessions.create and its parameters (mode, customer, line_items, success_url) against the changelog from basil to endive before shipping the bump.\nP6 | confirmed | createCheckout | Keep the page's change, which sets the per-request apiVersion to 2026-10-28.endive.\nP7 | confirmed | registerWebhook | Set api_version to 2026-10-28.endive in registerWebhook and create a replacement endpoint with it, saving its new signing secret, then disable the old endpoint after cutover.\nP8 | confirmed | the file | Test markPaid and syncSubscription with snapshot events from the replacement endpoint on 2026-10-28.endive before cutover.\nP9 | confirmed | the file | Add a default branch that logs the unfamiliar event type and still answers with received true.\nX1 | extra | the file (line 44) | Try the new signing secret first and fall back to the\n\n[... 412 more characters cut from this display ...]",
 "facts": "The page's scan of 66 lines (Node.js / TypeScript (stripe-node), detected) - 3 version pins (1 client, 1 per-request, 1 webhook endpoint); 4 of 9 findings changed by the page; verdict: Needs decisions.\nTarget: 2026-10-28.endive - the skill's bundled fallback, a snapshot from 2026-11-03; not verified against the live docs, so never call it the latest; the endive release, stable.\nPins (line | kind | where | pinned | the page's action):\n- line 8 | client | the file | 2024-06-20 | bumped to 2026-10-28.endive\n- line 25 | per-request | createCheckout | 2025-03-31.basil | bumped to 2026-10-28.endive\n- line 37 | webhook endpoint | registerWebhook | 2024-06-20 | left\nThin event handling: none seen. Manifest: none pasted.\nFindings (id | area | severity | line | where | evidence | source | what the page did):\n- P1 | changelog | major | line 8 | the file | From 2024-06-20 to 2026-10-28.endive the integration crosses 5 major releases (acacia, basil, clover, dahlia, endive), each starting with breaking changes: field renames or removals, behaviour changes, removed endpoints or parameters. | source: apiVersion: \"2024-06-20\", | left\n- P2 | pins | major | line 8 | the file | A client pin on 2024-06-20, older than the target 2026-10-28.endive. | source: apiVersion: \"2024-06-20\", | changed\n- P3 | client | major | line 11 | the file | The client is created without an explicit API version - it\n\n[... 1797 more characters cut from this display ...]"
}

Reply (long strings shortened for display - see the cuts below):

{
 "task": "rewrite",
 "summary": "Every pin in src/billing.ts now sits on 2026-10-28.endive, stripe_customer_id is 255 wide and the webhook accepts two secrets with a default branch; the changelog review and the replacement endpoint cutover stay with the person.",
 "code": "import Stripe from \"stripe\";\nimport express from \"express\";\nimport knex from \"knex\";\nimport { config } from \"./config\";\n\n// One client for the app, one for the nightly reports job.\nconst stripe = new Stripe(config.stripeSecretKey, {\n  apiVersion: \"2026-10-28.endive\",\n  maxNetworkRetries: 2,\n});\nconst reporting = new [... 2487 more characters cut from this display]",
 "changes": [
  {
   "id": "P2",
   "change": "The main client configuration keeps the page's apiVersion of 2026-10-28.endive."
  },
  {
   "id": "P3",
   "change": "The reporting client is now created with an explicit apiVersion of 2026-10-28.endive."
  },
  {
   "id": "P4",
   "change": "migrate keeps the page's widening of stripe_customer_id to 255 characters."
  },
  {
   "id": "P6",
   "change": "The createCheckout per-request override keeps the page's bump to 2026-10-28.endive."
  },
  {
   "id": "P7",
   "change": "registerWebhook now creates endpoints with api_version 2026-10-28.endive."
  },
  {
   "id": "P9",
   "change": "The switch in the webhook route gains a default branch that logs the unfamiliar event type."
  },
  {
   "id": "X1",
   "change": "The webhook route verifies through verifyEvent, which falls back to STRIPE_WEBHOOK_SECRET_PREVIOUS during cutover."
  }
 ],
 "kept": [
  {
   "id": "P1",
   "why": "The breaking changes from 2024-06-20 to endive need the changelog, which this rewrite cannot read."
  },
  {
   "id": "P5",
   "why": "Whether stripe.checkout.sessions.create needs other edits is for the changelog from basil to endive to decide."
  },
  {
   "id": "P8",
   "why": "Testing markPaid and syncSubscription against snapshot events needs the replacement endpoint, which is created outside this file."
  }
 ],
 "caveats": [
  "The fields read in markPaid and syncSubscription (X3, X2) stay as written until the changelog says otherwise.",
  "Register the replacement endpoint, set STRIPE_WEBHOOK_SECRET_PREVIOUS to the old secret during cutover, then disable the old endpoint.",
  "The account upgrade happens in Workbench, and a rollback stays open for 72 hours."
 ]
}

Cut from this display only (the saved reply and the check use the full text): code (2804 characters, 317 shown).

What step 5 prints for it: P2: The main client configuration keeps the page's apiVersion of 2026-10-28.endive. | P3: The reporting client is now created with an explicit apiVersion of 2026-10-28.endive. | P4: migrate keeps the page's widening of stripe_customer_id to 255 characters. | P6: The createCheckout per-request override keeps the page's bump to 2026-10-28.endive. | P7: registerWebhook now creates endpoints with api_version 2026-10-28.endive. | P9: The switch in the webhook route gains a default branch that logs the unfamiliar event type. | X1: The webhook route verifies through verifyEvent, which falls back to STRIPE_WEBHOOK_SECRET_PREVIOUS during cutover.

The page's check: kept - nothing to flag

review - A checkout page on Stripe.js basil

The page read it as: Needs decisions - 0 blocker, 1 major, 0 minor; findings P1 stripejs-old, P2 stripejs-override.

Input (facts is 1529 characters; the first 1395 are shown):

{
 "task": "review",
 "unit": "File: public/checkout.html\nLanguage: HTML page (Stripe.js)\nTarget: 2026-10-28.endive (bundled fallback, unverified)",
 "code": "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\" />\n  <title>Checkout</title>\n  <script src=\"https://js.stripe.com/basil/stripe.js\"></script>\n  <link rel=\"stylesheet\" href=\"/checkout.css\" />\n</head>\n<body>\n  <form id=\"payment-form\">\n    <div id=\"payment-element\"></div>\n    <button id=\"submit\">Pay now</button>\n    <p id=\"error\" role=\"alert\"></p>\n  </form>\n  <script>\n    const stripe = Stripe(window.STRIPE_PUBLISHABLE_KEY, { apiVersion: \"2025-03-31.basil\" });\n    let elements;\n\n    async function initialize() {\n      const res = await fetch(\"/create-payment-intent\", { method: \"POST\" });\n      const { clientSecret } = await res.json();\n      elements = stripe.elements({ clientSecret, appearance: { theme: \"stripe\" } });\n      elements.create(\"payment\").mount(\"#payment-element\");\n    }\n\n    async function handleSubmit(e) {\n      e.preventDefault();\n      const { error } = await stripe.confirmPayment({\n        elements,\n        confirmParams: { return_url: window.location.origin + \"/complete\" },\n      });\n      document.getElementById(\"error\").textContent = error ? error.message : \"\";\n    }\n\n    document.getElementById(\"payment-form\").addEventListener(\"submit\", handleSubmit);\n    initialize();\n  </script>\n</body>\n</html>\n",
 "manifest": "",
 "carry": "",
 "facts": "The page's scan of 40 lines (HTML page (Stripe.js), detected) - 2 version pins (1 Stripe.js option, 1 Stripe.js script); 1 of 2 findings changed by the page; verdict: Needs decisions.\nTarget: 2026-10-28.endive - the skill's bundled fallback, a snapshot from 2026-11-03; not verified against the live docs, so never call it the latest; the endive release, stable.\nPins (line | kind | where | pinned | the page's action):\n- line 16 | Stripe.js option | the file | 2025-03-31.basil | left\n- line 6 | Stripe.js script | the file | basil | bumped to endive\nThin event handling: none seen. Manifest: none pasted.\nFindings (id | area | severity | line | where | evidence | source | what the page did):\n- P1 | stripejs | major | line 6 | the file | The script loads the basil release; Stripe.js pairs each release with its own API version, so the page keeps the basil API until the script moves. | source: <script src=\"https://js.stripe.com/basil/stripe.js\"></script> | changed\n- P2 | stripejs | major | line 16 | the file | An apiVersion option (2025-03-31.basil) on a versioned Stripe.js release (basil): each release pairs with its own API version and the association cannot be overridden. | source: const stripe = Stripe(window.STRIPE_PUBLISHABLE_KEY, { apiVersion: \"2025-03-31.basil\" }); | left\nmust: account for every finding id above exactly once - in findings (confirmed) or in cleared (with the\n\n[... 134 more characters cut from this display ...]"
}

Reply:

{
 "task": "review",
 "summary": "The Stripe.js script loads basil and the Stripe() call passes apiVersion 2025-03-31.basil; the page moved the script to endive, and the first step is moving the server's API version to the target.",
 "target": "The target is 2026-10-28.endive, the skill's bundled fallback and unverified against the live docs, and from the oldest pin 2025-03-31.basil it crosses three major releases (clover, dahlia, endive).",
 "findings": [
  {
   "id": "P1",
   "widget": "the file",
   "issue": "The script loads the basil release of Stripe.js, which pairs with the basil API version.",
   "fix": "Keep the page's change, which loads the endive release of Stripe.js in place of basil.",
   "code": ""
  },
  {
   "id": "P2",
   "widget": "the file",
   "issue": "The Stripe() call passes apiVersion 2025-03-31.basil on a versioned release, where the pairing cannot be overridden.",
   "fix": "Remove the apiVersion option from the Stripe() call and let the endive release set the version.",
   "code": "const stripe = Stripe(window.STRIPE_PUBLISHABLE_KEY);"
  }
 ],
 "cleared": [],
 "extra": [
  {
   "id": "X1",
   "area": "pins",
   "line": 20,
   "widget": "initialize",
   "issue": "The PaymentIntent behind clientSecret is created by the server route /create-payment-intent, whose pin this file cannot show.",
   "fix": "Pin the server code behind /create-payment-intent to 2026-10-28.endive before the Stripe.js switch ships."
  }
 ],
 "plan": [
  "Read the changelog from 2025-03-31.basil to 2026-10-28.endive for PaymentIntents, Elements and stripe.confirmPayment (P1, P2)",
  "Move the server behind /create-payment-intent to the target first",
  "Run the tests with the Stripe-Version header on the target",
  "Switch the script to the endive release of Stripe.js (P1)",
  "Drop the apiVersion option from the Stripe() call (P2)"
 ],
 "tests": [
  "curl https://api.stripe.com/v1/payment_intents -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\" -d amount=1000 -d currency=usd -d \"automatic_payment_methods[enabled]=true\"",
  "curl https://api.stripe.com/v1/payment_intents?limit=1 -u \"$STRIPE_SECRET_KEY:\" -H \"Stripe-Version: 2026-10-28.endive\"",
  "Load the checkout page and check the browser console shows no error from the Stripe() call",
  "Check the Payment Element mounts in payment-element with a clientSecret from /create-payment-intent",
  "Submit a test card through handleSubmit and check stripe.confirmPayment returns to the complete page",
  "stripe trigger payment_intent.succeeded and check the server's handler receives it"
 ],
 "caveats": [
  "The server route /create-payment-intent lives outside this file and has to move to the target before the script changes.",
  "The account upgrade happens in Workbench, and a rollback stays open for 72 hours."
 ]
}

What step 5 prints for it: P1: Keep the page's change, which loads the endive release of Stripe.js in place of basil. | P2: Remove the apiVersion option from the Stripe() call and let the endive release set the version.

The page's check: kept - nothing to flag

Build the input yourself

Load the engine in node (global.window = global; require("./pinkit.js"); require("./pinreply.js")), then:

const K = PinKit, R = PinReply;
const f = K.form({ name: "src/pay.ts", lang: "auto", target: "2026-10-28.endive", manifest: "", carry: "",
  code: "import Stripe from \"stripe\";\nconst stripe = new Stripe(key, { apiVersion: \"2025-09-30.clover\" });\nexport const list = () => stripe.customers.list();" });
// f.scan.pins (each with its kind and the page's action), f.findings (each with .auto when the page changed it), f.scan.migrated (the upgraded copy), f.steps
// K.findingsCsv(f), K.itemsCsv(f), K.checklistMd(f) - the free exports
const b = K.buildInput(f, "review");                         // or "rewrite" (R.laneForm(form, "rewrite", review) fills carry)
const wire = K.toWire(b.input);                              // POST this to /estimate and /run
// then: const reply = R.normalize(R.parseReply(job.output.output), "review");
// R.check(reply, b)                                         // {status: kept or flags, notes}

Get a token for the steps below from /tokens.html.

Step 1 — a tiny client helper

One function that sends JSON and unwraps the response. Paste a personal token from /tokens.html, or leave it empty and mint a guest token in step 2.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="YOUR_TOKEN"   # from https://stripe-pin-desk.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

Step 2 — a token

A guest token is enough for /me and /estimate. A run is metered, so it needs a personal token: sign in on /tokens.html and copy it from there.

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"stripe-pin-desk"}' | jq -r '.data.token')

Step 3 — GET /me

Who the token is (subject_type: user or guest) and the credit balance.

api GET /me | jq '.data | {subject_type, credits}'

Step 4 — POST /estimate

Free. The body is the run input itself, the bare object (never wrapped in {"input": ...}). hold_credits is a reservation, not the price; min_credits is what the balance must cover; model_alias reads gpt-terra.

# input.json: the run input object - {"task": "review", "unit": "File: src/billing.ts\nLanguage: Node.js / TypeScript (stripe-node)\nTarget: 2026-10-28.endive (bundled fallback, unverified)", "code": "import Stripe from \"stripe\";\n...", "manifest": "", "carry": "", "facts": "The page's scan of 66 lines ...\nFindings (id | area | severity | line | where | evidence | source | what the page did):\n- P1 | changelog | major | line 8 | ..."}
# - see the input table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}'

Step 5 — POST /run, then poll the job

Send an Idempotency-Key built from the lane and the input: a retry with the same key never bills twice. The page uses stripe-pin-desk:<task>:<inputHash>:a<attempt> - the lane is part of the key, retry_note is left out of the hash - and its one automatic reformat retry is a new attempt number, named in the page as one extra run. A review reply carries summary, target, findings, cleared, extra, plan, tests and caveats; a rewrite reply carries summary, code, changes, kept and caveats. The code below prints the gist of either: each confirmed finding and its fix, or each change.

KEY="stripe-pin-desk:$(jq -r .task input.json):$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}'
jq -r 'if .task == "rewrite" then (.changes[] | "\(.id): \(.change)") 
       else (.findings[] | "\(.id): \(.fix)") end' reply.json

Step 6 — POST /run-stream

The same run as Server-Sent Events, with the same input.json. Browsers receive progress ticks rather than text deltas; the final done event carries the reply.

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: stripe-pin-desk:$(jq -r .task input.json):$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json