@jskit-ai/payments-core 0.1.62 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+## 0.2.0 - 2026-10-29
+
+- Translation ready: every user-visible text is a message key with its English in `locales/en.json`, so an app translates it by supplying translation files only. With no translations, texts and behaviour are unchanged. See the guide "Translating a JSKIT app".
+- `PaymentError` takes `{ messageCode, messageParams }` as its fourth argument; existing `payment_*` codes keep their values.
+
+### New message keys (53)
+
+All keys in `locales/en.json` (exported as `./locales/en.json`) are new in this version.
+
+<details><summary>Key list</summary>
+
+- `jskit.errors.payment_plan_unknown`
+- `jskit.errors.payment_readiness_invalid`
+- `jskit.errors.payment_forbidden`
+- `jskit.errors.payment_operation_conflict`
+- `jskit.errors.payment_request_invalid`
+- `jskit.errors.payment_subscription_exists`
+- `jskit.errors.payment_history_unavailable`
+- `jskit.errors.payment_customer_missing`
+- `jskit.errors.payment_reconciliation_required`
+- `jskit.errors.payment_customer_conflict`
+- `jskit.errors.payment_catalogue_pending`
+- `jskit.errors.payment_catalogue_uncertain`
+- `jskit.errors.payment_balance_limit`
+- `jskit.errors.payment_feature_required`
+- `jskit.errors.payment_insufficient_credits`
+- `jskit.errors.payment_debit_missing`
+- `jskit.errors.payment_customer_unbound`
+- `jskit.payments.scope.readinessMismatch`
+- `jskit.payments.scope.catalogueMismatch`
+- `jskit.payments.scope.merchantMismatch`
+- `jskit.payments.operation.unfinished`
+- `jskit.payments.operation.mayHaveSucceeded`
+- `jskit.payments.input.billingEmail`
+- `jskit.payments.input.historyPage`
+- `jskit.payments.input.historyCollection`
+- `jskit.payments.input.recoveryObjectId`
+- `jskit.payments.input.reference`
+- `jskit.payments.input.creditQuantity`
+- `jskit.payments.input.timestamp`
+- `jskit.payments.reference.otherPlan`
+- `jskit.payments.reference.differentInputs`
+- `jskit.payments.provider.checkAccount`
+- `jskit.payments.provider.unsupportedEvent`
+- `jskit.payments.provider.objectIdMissing`
+- `jskit.payments.provider.subscriptionBinding`
+- `jskit.payments.provider.renewalBinding`
+- `jskit.payments.webhook.rawBodyRequired`
+- `jskit.payments.webhook.verificationFailed`
+- `jskit.payments.configuration.invalid`
+- `jskit.payments.configuration.taxCategoryUnpublishable`
+- `jskit.payments.configuration.sharedConnectionRequired`
+- `jskit.payments.configuration.paddleEnvironment`
+- `jskit.payments.configuration.paddleTaxCategory`
+- `jskit.payments.configuration.paddleClientToken`
+- `jskit.payments.catalogue.reviewFirst`
+- `jskit.payments.catalogue.publicationChanged`
+- `jskit.payments.catalogue.planChanged`
+- `jskit.payments.catalogue.productChanged`
+- `jskit.payments.catalogue.priceChanged`
+- `jskit.payments.catalogue.pendingCatalogueRequestChanged`
+- `jskit.payments.catalogue.recoveryReviewChanged`
+- `jskit.payments.catalogue.pendingRequestChanged`
+- `jskit.payments.catalogue.objectMismatch`
+
+</details>
+
+### Codes (53)
+
+Error, field-error and message codes this package sends, with their English. Undotted codes kept their existing values and render from `jskit.errors.<code>`.
+
+| Code | English |
+| --- | --- |
+| `payment_plan_unknown` | Select a published payment plan. |
+| `payment_readiness_invalid` | App readiness checks must return bounded status and safe explanatory text. |
+| `payment_forbidden` | You cannot manage this billable account. |
+| `payment_operation_conflict` | The pending payment operation changed. |
+| `payment_request_invalid` | Supply a stable checkout request identifier. |
+| `payment_subscription_exists` | Manage the existing subscription through billing instead of starting another checkout. |
+| `payment_history_unavailable` | Billing history could not be loaded. Check provider access and retry. |
+| `payment_customer_missing` | Create a billing account first. |
+| `payment_reconciliation_required` | Provider inspection did not resolve this request. |
+| `payment_customer_conflict` | This provider customer is already bound to a different billable subject. |
+| `payment_catalogue_pending` | Another catalogue request needs resolution. |
+| `payment_catalogue_uncertain` | Catalogue publication stopped. Inspect the pending provider request before retrying; completed items are preserved. |
+| `payment_balance_limit` | Credit balance exceeds the supported integer range. |
+| `payment_feature_required` | Your subscription does not include this feature. |
+| `payment_insufficient_credits` | Not enough credits for this action. |
+| `payment_debit_missing` | No debit exists for this reference. |
+| `payment_customer_unbound` | Bind this provider customer before processing its events. |
+| `payments.scope.readinessMismatch` | Readiness returned a different payment account or environment. |
+| `payments.scope.catalogueMismatch` | Catalogue scope does not match its configured environment. |
+| `payments.scope.merchantMismatch` | The payment scope does not match this environment's merchant configuration. |
+| `payments.operation.unfinished` | Inspect the unfinished provider request before retrying. |
+| `payments.operation.mayHaveSucceeded` | Inspect this account's provider activity before retrying; the request may have succeeded. |
+| `payments.input.billingEmail` | Supply the authenticated billing contact's email. |
+| `payments.input.historyPage` | Select billing subscriptions or transactions and a valid page cursor. |
+| `payments.input.historyCollection` | Select a billing history collection. |
+| `payments.input.recoveryObjectId` | Supply the exact provider object ID to recover. |
+| `payments.input.reference` | Use a nonempty business reference of at most 150 characters. |
+| `payments.input.creditQuantity` | Use a positive integer credit quantity, at most one billion. |
+| `payments.input.timestamp` | Use an integer UTC timestamp in milliseconds. |
+| `payments.reference.otherPlan` | The checkout request already selected another plan. |
+| `payments.reference.differentInputs` | This business reference was already used with different inputs. |
+| `payments.provider.checkAccount` | Check the {provider} account, price mapping and subscription shape. |
+| `payments.provider.unsupportedEvent` | The event is not a supported subscription payment for this customer. |
+| `payments.provider.objectIdMissing` | The provider did not return an object ID. |
+| `payments.provider.subscriptionBinding` | Check the provider subscription and logical price binding. |
+| `payments.provider.renewalBinding` | Check the renewal's logical price binding. |
+| `payments.webhook.rawBodyRequired` | Supply the unmodified webhook request bytes. |
+| `payments.webhook.verificationFailed` | {provider} webhook verification failed. |
+| `payments.configuration.invalid` | Check the application's payment configuration. |
+| `payments.configuration.taxCategoryUnpublishable` | Set the application's Paddle product tax category before publishing. |
+| `payments.configuration.sharedConnectionRequired` | Select a shared Stripe or Paddle connection with a backend API-key Env reference for {environment}. |
+| `payments.configuration.paddleEnvironment` | Select a Paddle connection configured for {environment}. |
+| `payments.configuration.paddleTaxCategory` | Choose the Paddle tax category for the products this app sells. |
+| `payments.configuration.paddleClientToken` | Set the Env reference for this environment's Paddle public client token. |
+| `payments.catalogue.reviewFirst` | Review the current catalogue and resolve provider drift or unfinished requests first. |
+| `payments.catalogue.publicationChanged` | Another publication changed the catalogue; review again. |
+| `payments.catalogue.planChanged` | This plan changed; review again. |
+| `payments.catalogue.productChanged` | This product changed; review again. |
+| `payments.catalogue.priceChanged` | This price changed; review again. |
+| `payments.catalogue.pendingCatalogueRequestChanged` | The pending catalogue request changed. |
+| `payments.catalogue.recoveryReviewChanged` | The recovery review changed. Inspect the current pending operation first. |
+| `payments.catalogue.pendingRequestChanged` | The pending request changed. |
+| `payments.catalogue.objectMismatch` | The provider object does not match the pending operation. |

package/docs/conformance.md

@@ -2,7 +2,7 @@
 
 `contracts/conformance.json` is ordinary JSON, also exported as
 `@jskit-ai/payments-core/conformance.json`. Read the file as data; no Node process,
-JSKIT import, editor service or Genesis command is necessary to interpret it.
+JSKIT import, editor service or project tool is necessary to interpret it.
 It accompanies the draft-07 configuration schema and the semantic contract.
 These are test examples, not a production workflow interpreter.
 
@@ -72,9 +72,9 @@ runtime. The application selects its billable model and schema; the fixture does
 not prescribe table names or copy JSKIT's storage internals into another framework.
 
 A Node CLI consumer can run the same semantic calls against its installed JSKIT
-services. Genesis may describe the project's test command, but these fixtures do
-not require Genesis to execute it. Vibe64 configuration must preserve these same
-values rather than inventing a different hosted payment format.
+services. Project tooling may describe the project's test command, but these
+fixtures do not require it to execute. A hosted editor's configuration must
+preserve these same values rather than inventing a different hosted payment format.
 
 ## Evidence boundaries
 

package/docs/contract.md

@@ -124,3 +124,11 @@ Configuration failures use `payment_configuration_invalid` (422). Field errors
 identify `extensions.payments/...` paths, including cross-reference failures at
 `environments/<environment>/integrationId` and missing Paddle token/tax-category
 fields. Messages explain the repair without echoing credential values.
+
+Every error keeps its English `message` and its stable `payment_*` `code`. The
+English of a code used for one sentence lives under `jskit.errors.<code>` in
+`locales/en.json`. Where one code covers several sentences, the error also
+carries `messageCode` and `messageParams` naming a `jskit.payments.*` message,
+and binding field errors carry `code` and `params`, so a JSKIT application can
+show them in the user's language. Other implementations may ignore these
+fields.

package/docs/standalone.md

@@ -249,7 +249,7 @@ An optional app-owned `inspectApplication` callback may supply `webhook`,
 `passed`, `failed`, `unknown` or `manual` and a safe explanation of at most 500
 characters. Record only observed checks. Never turn an unavailable check into
 success or claim provider approval from a fixture. This callback is a normal app
-function, not a Vibe64 API. Authorize any route/CLI wrapper exposing the service.
+function, not a hosted API. Authorize any route/CLI wrapper exposing the service.
 
 Catalogue recovery requires a fresh `catalogue.preview()` and its `reviewId`:
 `catalogue.recover({reviewId, providerId})`. The adapter reads the candidate object;

package/locales/en.json

@@ -0,0 +1,77 @@
+{
+  "jskit": {
+    "errors": {
+      "payment_plan_unknown": "Select a published payment plan.",
+      "payment_readiness_invalid": "App readiness checks must return bounded status and safe explanatory text.",
+      "payment_forbidden": "You cannot manage this billable account.",
+      "payment_operation_conflict": "The pending payment operation changed.",
+      "payment_request_invalid": "Supply a stable checkout request identifier.",
+      "payment_subscription_exists": "Manage the existing subscription through billing instead of starting another checkout.",
+      "payment_history_unavailable": "Billing history could not be loaded. Check provider access and retry.",
+      "payment_customer_missing": "Create a billing account first.",
+      "payment_reconciliation_required": "Provider inspection did not resolve this request.",
+      "payment_customer_conflict": "This provider customer is already bound to a different billable subject.",
+      "payment_catalogue_pending": "Another catalogue request needs resolution.",
+      "payment_catalogue_uncertain": "Catalogue publication stopped. Inspect the pending provider request before retrying; completed items are preserved.",
+      "payment_balance_limit": "Credit balance exceeds the supported integer range.",
+      "payment_feature_required": "Your subscription does not include this feature.",
+      "payment_insufficient_credits": "Not enough credits for this action.",
+      "payment_debit_missing": "No debit exists for this reference.",
+      "payment_customer_unbound": "Bind this provider customer before processing its events."
+    },
+    "payments": {
+      "scope": {
+        "readinessMismatch": "Readiness returned a different payment account or environment.",
+        "catalogueMismatch": "Catalogue scope does not match its configured environment.",
+        "merchantMismatch": "The payment scope does not match this environment's merchant configuration."
+      },
+      "operation": {
+        "unfinished": "Inspect the unfinished provider request before retrying.",
+        "mayHaveSucceeded": "Inspect this account's provider activity before retrying; the request may have succeeded."
+      },
+      "input": {
+        "billingEmail": "Supply the authenticated billing contact's email.",
+        "historyPage": "Select billing subscriptions or transactions and a valid page cursor.",
+        "historyCollection": "Select a billing history collection.",
+        "recoveryObjectId": "Supply the exact provider object ID to recover.",
+        "reference": "Use a nonempty business reference of at most 150 characters.",
+        "creditQuantity": "Use a positive integer credit quantity, at most one billion.",
+        "timestamp": "Use an integer UTC timestamp in milliseconds."
+      },
+      "reference": {
+        "otherPlan": "The checkout request already selected another plan.",
+        "differentInputs": "This business reference was already used with different inputs."
+      },
+      "provider": {
+        "checkAccount": "Check the {provider} account, price mapping and subscription shape.",
+        "unsupportedEvent": "The event is not a supported subscription payment for this customer.",
+        "objectIdMissing": "The provider did not return an object ID.",
+        "subscriptionBinding": "Check the provider subscription and logical price binding.",
+        "renewalBinding": "Check the renewal's logical price binding."
+      },
+      "webhook": {
+        "rawBodyRequired": "Supply the unmodified webhook request bytes.",
+        "verificationFailed": "{provider} webhook verification failed."
+      },
+      "configuration": {
+        "invalid": "Check the application's payment configuration.",
+        "taxCategoryUnpublishable": "Set the application's Paddle product tax category before publishing.",
+        "sharedConnectionRequired": "Select a shared Stripe or Paddle connection with a backend API-key Env reference for {environment}.",
+        "paddleEnvironment": "Select a Paddle connection configured for {environment}.",
+        "paddleTaxCategory": "Choose the Paddle tax category for the products this app sells.",
+        "paddleClientToken": "Set the Env reference for this environment's Paddle public client token."
+      },
+      "catalogue": {
+        "reviewFirst": "Review the current catalogue and resolve provider drift or unfinished requests first.",
+        "publicationChanged": "Another publication changed the catalogue; review again.",
+        "planChanged": "This plan changed; review again.",
+        "productChanged": "This product changed; review again.",
+        "priceChanged": "This price changed; review again.",
+        "pendingCatalogueRequestChanged": "The pending catalogue request changed.",
+        "recoveryReviewChanged": "The recovery review changed. Inspect the current pending operation first.",
+        "pendingRequestChanged": "The pending request changed.",
+        "objectMismatch": "The provider object does not match the pending operation."
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/payments-core",
-  "version": "0.1.62",
+  "version": "0.2.1",
   "type": "module",
   "description": "Application-owned payment configuration, subscription access and transactional usage credits.",
   "exports": {
@@ -15,7 +15,9 @@
     "./server/stripe": "./src/server/stripe.js",
     "./server/paddle": "./src/server/paddle.js",
     "./server/catalogue": "./src/server/catalogue.js",
-    "./server/readiness": "./src/server/readiness.js"
+    "./server/readiness": "./src/server/readiness.js",
+    "./server/types": "./src/server/types.js",
+    "./locales/en.json": "./locales/en.json"
   },
   "scripts": {
     "test": "node --test --test-concurrency=1"

package/src/server/catalogue.js

@@ -4,14 +4,23 @@ import { PaymentError, fingerprint } from "./errors.js";
 const priceFields = (plan) => ({ amount: plan.amount, currency: plan.currency, interval: plan.interval });
 const samePrice = (a, b) => fingerprint(priceFields(a)) === fingerprint(priceFields(b));
 
-// Trusted application service. Hosts must authorize catalogue management before
-// invoking it. No provider mutation happens while merely reading configuration.
+/**
+ * Trusted application service. Hosts must authorize catalogue management before
+ * invoking it. No provider mutation happens while merely reading configuration.
+ * @param {object} dependencies
+ * @param {import("./types.js").PaymentStore} dependencies.store
+ * @param {import("./types.js").PaymentProviderAdapter} dependencies.adapter
+ * @param {import("./types.js").PaymentMerchantScope} dependencies.scope The merchant scope the catalogue belongs to.
+ * @param {import("./types.js").PaymentConfiguration} dependencies.configuration
+ */
 function createPaymentCatalogue({ store, adapter, scope, configuration }) {
   const plans = structuredClone(configuration.plans);
   const merchant = structuredClone(scope);
   const environment = configuration.environments[merchant.environment];
   if (!environment || environment.integrationId !== merchant.integrationId || environment.providerAccountId !== merchant.providerAccountId) {
-    throw new PaymentError("payment_scope_invalid", "Catalogue scope does not match its configured environment.", 403);
+    throw new PaymentError("payment_scope_invalid", "Catalogue scope does not match its configured environment.", 403, {
+      messageCode: "payments.scope.catalogueMismatch"
+    });
   }
   async function preview() {
     const state = await store.inspectCatalogue(merchant);
@@ -38,19 +47,19 @@ function createPaymentCatalogue({ store, adapter, scope, configuration }) {
   }
   async function publish({ reviewId }) {
     const review = await preview();
-    if (review.reviewId !== reviewId || review.drift.length || review.pending) throw new PaymentError("payment_catalogue_review_required", "Review the current catalogue and resolve provider drift or unfinished requests first.", 409);
+    if (review.reviewId !== reviewId || review.drift.length || review.pending) throw new PaymentError("payment_catalogue_review_required", "Review the current catalogue and resolve provider drift or unfinished requests first.", 409, { messageCode: "payments.catalogue.reviewFirst" });
     const completed = [];
     let expectedRevision = review.revision;
     for (const change of review.changes) {
       const token = randomUUID();
       const pending = await store.withCatalogue(merchant, async (state) => {
         if (state.pending) throw new PaymentError("payment_catalogue_pending", "Another catalogue request needs resolution.", 409);
-        if ((state.revision || 0) !== expectedRevision) throw new PaymentError("payment_catalogue_review_required", "Another publication changed the catalogue; review again.", 409);
+        if ((state.revision || 0) !== expectedRevision) throw new PaymentError("payment_catalogue_review_required", "Another publication changed the catalogue; review again.", 409, { messageCode: "payments.catalogue.publicationChanged" });
         const current = state.plans[change.planId];
         // Reject another publisher changing this plan after the reviewed read.
-        if (change.action === "create-product" && current) throw new PaymentError("payment_catalogue_review_required", "This plan changed; review again.", 409);
-        if (change.action === "rename-product" && current?.productId !== change.productId) throw new PaymentError("payment_catalogue_review_required", "This product changed; review again.", 409);
-        if (change.action === "create-price" && (!current?.productId || (current.priceId && samePrice(current, change)))) throw new PaymentError("payment_catalogue_review_required", "This price changed; review again.", 409);
+        if (change.action === "create-product" && current) throw new PaymentError("payment_catalogue_review_required", "This plan changed; review again.", 409, { messageCode: "payments.catalogue.planChanged" });
+        if (change.action === "rename-product" && current?.productId !== change.productId) throw new PaymentError("payment_catalogue_review_required", "This product changed; review again.", 409, { messageCode: "payments.catalogue.productChanged" });
+        if (change.action === "create-price" && (!current?.productId || (current.priceId && samePrice(current, change)))) throw new PaymentError("payment_catalogue_review_required", "This price changed; review again.", 409, { messageCode: "payments.catalogue.priceChanged" });
         const operation = { ...change, token, productId: current?.productId };
         state.pending = operation;
         return operation;
@@ -70,9 +79,9 @@ function createPaymentCatalogue({ store, adapter, scope, configuration }) {
     return { completed, removed: review.removed };
   }
   async function finish(pending, result) {
-    if (typeof result?.id !== "string" || !result.id) throw new PaymentError("payment_provider_result_invalid", "The provider did not return an object ID.", 502);
+    if (typeof result?.id !== "string" || !result.id) throw new PaymentError("payment_provider_result_invalid", "The provider did not return an object ID.", 502, { messageCode: "payments.provider.objectIdMissing" });
     await store.withCatalogue(merchant, async (state) => {
-      if (state.pending?.token !== pending.token) throw new PaymentError("payment_catalogue_review_required", "The pending catalogue request changed.", 409);
+      if (state.pending?.token !== pending.token) throw new PaymentError("payment_catalogue_review_required", "The pending catalogue request changed.", 409, { messageCode: "payments.catalogue.pendingCatalogueRequestChanged" });
       const current = state.plans[pending.planId];
       if (pending.action === "create-product") state.plans[pending.planId] = { productId: result.id, name: pending.name };
       else if (pending.action === "rename-product") current.name = pending.name;
@@ -86,31 +95,35 @@ function createPaymentCatalogue({ store, adapter, scope, configuration }) {
   }
   async function recover({ reviewId, providerId, confirmedNotCreated = false }) {
     const review = await preview();
-    if (review.reviewId !== reviewId) throw new PaymentError("payment_catalogue_review_required", "The recovery review changed. Inspect the current pending operation first.", 409);
+    if (review.reviewId !== reviewId) throw new PaymentError("payment_catalogue_review_required", "The recovery review changed. Inspect the current pending operation first.", 409, { messageCode: "payments.catalogue.recoveryReviewChanged" });
     const pending = review.pending;
     if (!pending) return { pending: false };
     if (confirmedNotCreated) {
       // Trusted app administrator must supply actual provider inspection evidence.
       // This parameter must not be exposed as an unauthenticated browser command.
       await store.withCatalogue(merchant, async (current) => {
-        if (current.pending?.token !== pending.token) throw new PaymentError("payment_catalogue_review_required", "The pending request changed.", 409);
+        if (current.pending?.token !== pending.token) throw new PaymentError("payment_catalogue_review_required", "The pending request changed.", 409, { messageCode: "payments.catalogue.pendingRequestChanged" });
         delete current.pending;
       });
       return { pending: false, retryAllowed: true };
     }
     if (typeof providerId !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(providerId)) {
-      throw new PaymentError("payment_input_invalid", "Supply the exact provider object ID to recover.");
+      throw new PaymentError("payment_input_invalid", "Supply the exact provider object ID to recover.", 422, { messageCode: "payments.input.recoveryObjectId" });
     }
     const result = pending.action === "create-price" ? await adapter.readPrice(providerId) : await adapter.readProduct(providerId);
     if (!result || result.id !== providerId || (pending.action === "create-price" && (result.active !== true || result.productId !== pending.productId || !samePrice(result, pending))) ||
         (pending.action !== "create-price" && result.name !== pending.name) ||
         (pending.action === "rename-product" && providerId !== pending.productId)) {
-      throw new PaymentError("payment_catalogue_review_required", "The provider object does not match the pending operation.", 409);
+      throw new PaymentError("payment_catalogue_review_required", "The provider object does not match the pending operation.", 409, { messageCode: "payments.catalogue.objectMismatch" });
     }
     await finish(pending, { id: providerId });
     return { pending: false };
   }
-  return Object.freeze({ preview, publish, recover });
+  return Object.freeze({
+    preview,
+    publish,
+    recover
+  });
 }
 
 export { createPaymentCatalogue };

package/src/server/checkout.js

@@ -1,9 +1,19 @@
 import { randomUUID } from "node:crypto";
 import { PaymentError, fingerprint } from "./errors.js";
 
-// Application composition boundary: authorization is mandatory and supplied by
-// the app's framework. Actor and subject must come from its authenticated route.
+/**
+ * Application composition boundary: authorization is mandatory and supplied by
+ * the app's framework. Actor and subject must come from its authenticated route.
+ * @param {object} dependencies
+ * @param {import("./types.js").PaymentProviderAdapter} dependencies.adapter
+ * @param {import("./types.js").PaymentStore} dependencies.store
+ * @param {import("./types.js").PaymentService} dependencies.payments
+ * @param {import("./types.js").PaymentMerchantScope} dependencies.merchantScope
+ * @param {string} dependencies.returnUrl
+ * @param {(actor: unknown, request: { subjectId: string, action: string }) => boolean | Promise<boolean>} dependencies.authorize
+ */
 function createPaymentCheckoutService({ adapter, store, payments, merchantScope, returnUrl, authorize }) {
+  // readable-check: allow method-probe - input validation: the application passes its billable-subject authorization
   if (typeof authorize !== "function") throw new TypeError("Supply the application's billable-subject authorization function.");
   const target = new URL(returnUrl);
   if ((target.protocol !== "https:" && !(target.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(target.hostname))) || target.username || target.password || target.hash) {
@@ -19,7 +29,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
   async function perform(scope, operation, remote, complete) {
     const token = randomUUID();
     const prepared = await store.withAccount(scope, async (tx) => {
-      if (tx.state.pendingPaymentOperation) throw new PaymentError("payment_operation_uncertain", "Inspect the unfinished provider request before retrying.", 409);
+      if (tx.state.pendingPaymentOperation) throw new PaymentError("payment_operation_uncertain", "Inspect the unfinished provider request before retrying.", 409, { messageCode: "payments.operation.unfinished" });
       const ready = await operation(tx);
       if (ready.cached) return ready;
       tx.state.pendingPaymentOperation = { token, ...ready };
@@ -30,7 +40,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     // unresolved operation, rather than permitting a duplicate provider write.
     let result;
     try { result = await remote(prepared); }
-    catch { throw new PaymentError("payment_operation_uncertain", "Inspect this account's provider activity before retrying; the request may have succeeded.", 409); }
+    catch { throw new PaymentError("payment_operation_uncertain", "Inspect this account's provider activity before retrying; the request may have succeeded.", 409, { messageCode: "payments.operation.mayHaveSucceeded" }); }
     return store.withAccount(scope, async (tx) => {
       if (tx.state.pendingPaymentOperation?.token !== token) throw new PaymentError("payment_operation_conflict", "The pending payment operation changed.", 409);
       const value = await complete(tx, result, prepared);
@@ -42,7 +52,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     const scope = await allowed(actor, subjectId, "checkout");
     adapter.validatePlan(planId);
     if (typeof requestId !== "string" || !/^[A-Za-z0-9_-]{1,100}$/.test(requestId)) throw new PaymentError("payment_request_invalid", "Supply a stable checkout request identifier.");
-    if (typeof email !== "string" || email.length > 320 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) throw new PaymentError("payment_input_invalid", "Supply the authenticated billing contact's email.");
+    if (typeof email !== "string" || email.length > 320 || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) throw new PaymentError("payment_input_invalid", "Supply the authenticated billing contact's email.", 422, { messageCode: "payments.input.billingEmail" });
     const identity = fingerprint(scope);
     const customerId = await perform(scope, async (tx) => tx.state.customerId
       ? { cached: true, result: tx.state.customerId }
@@ -53,7 +63,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     return perform(scope, async (tx) => {
       const saved = await tx.find(`checkout:${requestId}`);
       if (saved) {
-        if (saved.planId !== planId) throw new PaymentError("payment_reference_conflict", "The checkout request already selected another plan.", 409);
+        if (saved.planId !== planId) throw new PaymentError("payment_reference_conflict", "The checkout request already selected another plan.", 409, { messageCode: "payments.reference.otherPlan" });
         return { cached: true, result: saved.result };
       }
       if (Object.values(tx.state.subscriptions).some((subscription) =>
@@ -75,7 +85,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     const scope = await allowed(actor, subjectId, "history");
     if (!["subscriptions", "transactions"].includes(collection) ||
       (after !== null && (typeof after !== "string" || !/^[A-Za-z0-9_-]{1,200}$/.test(after)))) {
-      throw new PaymentError("payment_input_invalid", "Select billing subscriptions or transactions and a valid page cursor.");
+      throw new PaymentError("payment_input_invalid", "Select billing subscriptions or transactions and a valid page cursor.", 422, { messageCode: "payments.input.historyPage" });
     }
     // Never accept a customer identifier from the browser or editor caller.
     const { customerId } = await store.inspect(scope);
@@ -94,6 +104,7 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
   // provider dashboard/API and must return evidence, never browser-supplied data.
   async function reconcilePending({ actor, subjectId, inspectProvider }) {
     const scope = await allowed(actor, subjectId, "reconcile");
+    // readable-check: allow method-probe - input validation: the caller passes its server-side provider inspection
     if (typeof inspectProvider !== "function") throw new TypeError("Supply the server's provider inspection function.");
     return store.withAccount(scope, async (tx) => {
       const pending = tx.state.pendingPaymentOperation;
@@ -121,11 +132,18 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
     const { eventId, customerId } = identity;
     return payments.reconcileEvent(merchant, { eventId, customerId, load: async () => {
       const facts = await adapter.loadEvent(event);
-      if (!facts || facts.customerId !== customerId) throw new PaymentError("payment_provider_result_invalid", "The event is not a supported subscription payment for this customer.", 422);
+      if (!facts || facts.customerId !== customerId) throw new PaymentError("payment_provider_result_invalid", "The event is not a supported subscription payment for this customer.", 422, { messageCode: "payments.provider.unsupportedEvent" });
       return facts;
     } });
   }
-  return Object.freeze({ account, history, checkout, portal, webhook, reconcilePending });
+  return Object.freeze({
+    account,
+    history,
+    checkout,
+    portal,
+    webhook,
+    reconcilePending
+  });
 }
 
 export { createPaymentCheckoutService };

package/src/server/errors.js

@@ -1,11 +1,17 @@
 import { createHash } from "node:crypto";
 
+// code is the stable payment_* code callers branch on; a code shared by several
+// sentences adds a messageCode (and messageParams) naming this sentence.
 class PaymentError extends Error {
-  constructor(code, message, statusCode = 422) {
+  constructor(code, message, statusCode = 422, { messageCode = "", messageParams = {} } = {}) {
     super(message);
     this.name = "PaymentError";
     this.code = code;
     this.statusCode = statusCode;
+    if (messageCode) {
+      this.messageCode = messageCode;
+      this.messageParams = { ...messageParams };
+    }
   }
 }
 

package/src/server/knexStore.js

@@ -16,8 +16,12 @@ function identifier(value) {
 }
 const accountKey = (scope) => fingerprint([...merchant(scope), identifier(scope.subjectId)]);
 
+/** @param {{ knex: import("@jskit-ai/database-runtime/server/types").RuntimeKnex }} dependencies */
 function createKnexPaymentStore({ knex }) {
-  if (typeof knex !== "function" || typeof knex.transaction !== "function") throw new TypeError("Supply the application's transactional Knex client.");
+  // readable-check: allow method-probe - input validation: the application passes its own Knex instance
+  if (typeof knex !== "function" || typeof knex.transaction !== "function") {
+    throw new TypeError("createKnexPaymentStore requires the application's Knex instance.");
+  }
 
   async function inspect(scope) {
     const row = await knex("payment_accounts").where({ account_key: accountKey(scope) }).first();
@@ -75,7 +79,14 @@ function createKnexPaymentStore({ knex }) {
       return result;
     });
   }
-  return Object.freeze({ inspect, withAccount, bindCustomer, resolveCustomer, inspectCatalogue, withCatalogue });
+  return Object.freeze({
+    inspect,
+    withAccount,
+    bindCustomer,
+    resolveCustomer,
+    inspectCatalogue,
+    withCatalogue
+  });
 }
 
 export { createKnexPaymentStore };

package/src/server/paddle.js

@@ -2,8 +2,23 @@ import { Paddle, Environment } from "@paddle/paddle-node-sdk";
 import { PaymentError } from "./errors.js";
 import { createPriceBindings } from "./priceBindings.js";
 
-const invalid = () => { throw new PaymentError("payment_provider_result_invalid", "Check the Paddle account, price mapping and subscription shape.", 502); };
+const invalid = () => {
+  throw new PaymentError("payment_provider_result_invalid", "Check the Paddle account, price mapping and subscription shape.", 502, {
+    messageCode: "payments.provider.checkAccount", messageParams: { provider: "Paddle" }
+  });
+};
 
+/**
+ * @param {object} options
+ * @param {string} [options.apiKey]
+ * @param {string} options.webhookSecret
+ * @param {"sandbox" | "live"} options.environment
+ * @param {Record<string, string>} options.priceBindings Each plan's current price id.
+ * @param {Record<string, string>} [options.historicalPriceBindings] The plan of each retired price id.
+ * @param {import("@paddle/paddle-node-sdk").TaxCategory} [options.taxCategory] The tax category of the products it publishes.
+ * @param {import("@paddle/paddle-node-sdk").Paddle} [options.client]
+ */
+// readable-check: allow dependency-default - data: historicalPriceBindings maps retired price ids to plans, not a collaborator
 function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceBindings, taxCategory, historicalPriceBindings = {}, client = new Paddle(apiKey, { environment: environment === "live" ? Environment.production : Environment.sandbox }) }) {
   if (!["sandbox", "live"].includes(environment) || typeof webhookSecret !== "string" || !webhookSecret) throw new TypeError("Supply Paddle credentials and environment.");
   const { validatePlan, priceFor, planFor } = createPriceBindings({ priceBindings, historicalPriceBindings, invalid });
@@ -14,9 +29,11 @@ function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceB
     return { environment, credentialsVerified: true, accountIdentityVerified: false, merchantApproval: "manual-check-required" };
   }
   async function verifyEvent(rawBody, signature) {
-    if (!Buffer.isBuffer(rawBody)) throw new PaymentError("payment_signature_invalid", "Supply the unmodified webhook request bytes.", 400);
+    if (!Buffer.isBuffer(rawBody)) throw new PaymentError("payment_signature_invalid", "Supply the unmodified webhook request bytes.", 400, { messageCode: "payments.webhook.rawBodyRequired" });
     try { return await client.webhooks.unmarshal(rawBody.toString("utf8"), webhookSecret, signature); }
-    catch { throw new PaymentError("payment_signature_invalid", "Paddle webhook verification failed.", 400); }
+    catch { throw new PaymentError("payment_signature_invalid", "Paddle webhook verification failed.", 400, {
+      messageCode: "payments.webhook.verificationFailed", messageParams: { provider: "Paddle" }
+    }); }
   }
   function eventIdentity(event) {
     if (event.eventType === "transaction.completed") {
@@ -65,7 +82,7 @@ function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceB
     return { id: result.id, url: result.urls.general.overview };
   }
   async function readHistory({ customerId, collection, after = null }) {
-    if (!["subscriptions", "transactions"].includes(collection)) throw new PaymentError("payment_input_invalid", "Select a billing history collection.");
+    if (!["subscriptions", "transactions"].includes(collection)) throw new PaymentError("payment_input_invalid", "Select a billing history collection.", 422, { messageCode: "payments.input.historyCollection" });
     const query = { customerId: [customerId], perPage: 20, ...(after ? { after } : {}) };
     const page = collection === "subscriptions" ? client.subscriptions.list(query) : client.transactions.list(query);
     // Fetch one page only; never iterate the SDK collection over the account.
@@ -89,7 +106,9 @@ function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceB
     return { id: value.id, name: value.name };
   }
   async function createProduct({ name }) {
-    if (!taxCategory) throw new PaymentError("payment_configuration_invalid", "Set the application's Paddle product tax category before publishing.");
+    if (!taxCategory) throw new PaymentError("payment_configuration_invalid", "Set the application's Paddle product tax category before publishing.", 422, {
+      messageCode: "payments.configuration.taxCategoryUnpublishable"
+    });
     return client.products.create({ name, taxCategory });
   }
   async function renameProduct({ id, name }) {
@@ -103,7 +122,22 @@ function createPaddlePaymentAdapter({ apiKey, webhookSecret, environment, priceB
   async function createPrice({ productId, amount, currency, interval }) {
     return client.prices.create({ productId, description: `${currency} ${amount} per ${interval}`, unitPrice: { amount: String(amount), currencyCode: currency }, billingCycle: { interval, frequency: 1 } });
   }
-  return Object.freeze({ validatePlan, verifyAccount, verifyEvent, eventIdentity, loadEvent, createCustomer, createCheckout, createPortal, readHistory, readProduct, createProduct, renameProduct, readPrice, createPrice });
+  return Object.freeze({
+    validatePlan,
+    verifyAccount,
+    verifyEvent,
+    eventIdentity,
+    loadEvent,
+    createCustomer,
+    createCheckout,
+    createPortal,
+    readHistory,
+    readProduct,
+    createProduct,
+    renameProduct,
+    readPrice,
+    createPrice
+  });
 }
 
 export { createPaddlePaymentAdapter };

package/src/server/priceBindings.js

@@ -1,7 +1,13 @@
 import { PaymentError } from "./errors.js";
 
-// Plan-to-price bindings shared by the provider adapters. `invalid` throws the
-// adapter's own provider-result error for an unknown or ambiguous price.
+/**
+ * Plan-to-price bindings shared by the provider adapters. `invalid` throws the
+ * adapter's own provider-result error for an unknown or ambiguous price.
+ * @param {object} bindings
+ * @param {Record<string, string>} bindings.priceBindings Each plan's current price id.
+ * @param {Record<string, string>} [bindings.historicalPriceBindings] The plan of each retired price id.
+ * @param {() => never} bindings.invalid
+ */
 function createPriceBindings({ priceBindings, historicalPriceBindings = {}, invalid }) {
   const prices = structuredClone(priceBindings);
   function validatePlan(planId) {
@@ -17,7 +23,11 @@ function createPriceBindings({ priceBindings, historicalPriceBindings = {}, inva
     if (matches.length !== 1) invalid();
     return matches[0][0];
   }
-  return { validatePlan, priceFor, planFor };
+  return Object.freeze({
+    validatePlan,
+    priceFor,
+    planFor
+  });
 }
 
 export { createPriceBindings };

package/src/server/readiness.js

@@ -13,10 +13,19 @@ const DEFAULT_CHECKS = Object.freeze([
 ]);
 // Only these checks take their result from the application's own evidence.
 const APPLICATION_CHECKS = ["webhook", "checkout", "site", "deployment"];
+// No application evidence: every application check keeps its default.
+const inspectNoApplicationEvidence = async () => ({});
 
-// App-server inspection, invoked only after the host authorizes management.
-// Missing app evidence stays unknown; provider errors never become display text.
-function createPaymentReadiness({ adapter, catalogue, scope, inspectApplication }) {
+/**
+ * App-server inspection, invoked only after the host authorizes management.
+ * Missing app evidence stays unknown; provider errors never become display text.
+ * @param {object} dependencies
+ * @param {import("./types.js").PaymentProviderAdapter} dependencies.adapter
+ * @param {import("./types.js").PaymentCatalogue} dependencies.catalogue
+ * @param {import("./types.js").PaymentMerchantScope} dependencies.scope The merchant scope the readiness checks belong to.
+ * @param {() => unknown} [dependencies.inspectApplication] The application's own evidence, by check id.
+ */
+function createPaymentReadiness({ adapter, catalogue, scope, inspectApplication = inspectNoApplicationEvidence }) {
   const merchant = structuredClone(scope);
   if (!["sandbox", "live"].includes(merchant?.environment) || !merchant.providerAccountId) throw new TypeError("Supply the configured payment merchant scope.");
   async function inspect() {
@@ -27,7 +36,9 @@ function createPaymentReadiness({ adapter, catalogue, scope, inspectApplication
     catch { set("credentials", "failed", "Provider verification failed. Check the account, credentials and environment."); }
     if (provider) {
       if (provider.environment !== merchant.environment || (provider.accountId && provider.accountId !== merchant.providerAccountId)) {
-        throw new PaymentError("payment_scope_invalid", "Readiness returned a different payment account or environment.", 403);
+        throw new PaymentError("payment_scope_invalid", "Readiness returned a different payment account or environment.", 403, {
+          messageCode: "payments.scope.readinessMismatch"
+        });
       }
       const verified = provider.credentialsVerified === true || provider.accountId === merchant.providerAccountId;
       set("credentials", verified ? "passed" : "unknown", verified
@@ -48,18 +59,16 @@ function createPaymentReadiness({ adapter, catalogue, scope, inspectApplication
           unresolved ? "Catalogue changes, drift, removed plans or an unresolved write need review." : "Saved plans match their published provider products and prices.");
       } catch { set("catalogue", "failed", "Catalogue inspection failed. Review the application's catalogue command and provider access."); }
     }
-    if (inspectApplication) {
-      let evidence;
-      try { evidence = await inspectApplication(); } catch { evidence = {}; }
-      for (const id of APPLICATION_CHECKS) {
-        const value = evidence?.[id];
-        if (value === undefined) continue;
-        if (!value || !["passed", "failed", "unknown", "manual"].includes(value.status) || typeof value.detail !== "string" ||
-          !value.detail.trim() || value.detail.length > 500 || /[\p{Cc}\p{Cf}]/u.test(value.detail)) {
-          throw new PaymentError("payment_readiness_invalid", "App readiness checks must return bounded status and safe explanatory text.");
-        }
-        set(id, value.status, value.detail);
+    let evidence;
+    try { evidence = await inspectApplication(); } catch { evidence = {}; }
+    for (const id of APPLICATION_CHECKS) {
+      const value = evidence?.[id];
+      if (value === undefined) continue;
+      if (!value || !["passed", "failed", "unknown", "manual"].includes(value.status) || typeof value.detail !== "string" ||
+        !value.detail.trim() || value.detail.length > 500 || /[\p{Cc}\p{Cf}]/u.test(value.detail)) {
+        throw new PaymentError("payment_readiness_invalid", "App readiness checks must return bounded status and safe explanatory text.");
       }
+      set(id, value.status, value.detail);
     }
     return { paymentEnvironment: merchant.environment, providerAccountId: merchant.providerAccountId, checks: [...checks.values()] };
   }

package/src/server/service.js

@@ -1,16 +1,16 @@
 import { PaymentError, fingerprint } from "./errors.js";
 
-const fail = (code, message, status) => { throw new PaymentError(code, message, status); };
+const fail = (code, message, status, options) => { throw new PaymentError(code, message, status, options); };
 function reference(value) {
-  if (typeof value !== "string" || !value || value.length > 150 || ["__proto__", "constructor", "prototype"].includes(value)) fail("payment_input_invalid", "Use a nonempty business reference of at most 150 characters.");
+  if (typeof value !== "string" || !value || value.length > 150 || ["__proto__", "constructor", "prototype"].includes(value)) fail("payment_input_invalid", "Use a nonempty business reference of at most 150 characters.", 422, { messageCode: "payments.input.reference" });
   return value;
 }
 function units(value) {
-  if (!Number.isSafeInteger(value) || value < 1 || value > 1e9) fail("payment_input_invalid", "Use a positive integer credit quantity, at most one billion.");
+  if (!Number.isSafeInteger(value) || value < 1 || value > 1e9) fail("payment_input_invalid", "Use a positive integer credit quantity, at most one billion.", 422, { messageCode: "payments.input.creditQuantity" });
   return value;
 }
 function timestamp(value) {
-  if (!Number.isSafeInteger(value) || value < 0) fail("payment_input_invalid", "Use an integer UTC timestamp in milliseconds.");
+  if (!Number.isSafeInteger(value) || value < 0) fail("payment_input_invalid", "Use an integer UTC timestamp in milliseconds.", 422, { messageCode: "payments.input.timestamp" });
   return value;
 }
 const unexpired = (lot, now) => lot.expiresAt === null || lot.expiresAt > now;
@@ -20,7 +20,7 @@ async function once(tx, key, input, work) {
   const digest = fingerprint(input);
   const previous = await tx.find(key);
   if (previous) {
-    if (previous.digest !== digest) fail("payment_reference_conflict", "This business reference was already used with different inputs.", 409);
+    if (previous.digest !== digest) fail("payment_reference_conflict", "This business reference was already used with different inputs.", 409, { messageCode: "payments.reference.differentInputs" });
     return { ...previous.result, duplicate: true };
   }
   const result = await work();
@@ -39,16 +39,27 @@ async function grant(tx, { reference: id, units: quantity, expiresAt }, now) {
   });
 }
 
-// Server-side domain API. The application authorizes the billable subject before
-// invoking it; none of these methods is an HTTP endpoint or a browser authority.
+/**
+ * Server-side domain API. The application authorizes the billable subject before
+ * invoking it; none of these methods is an HTTP endpoint or a browser authority.
+ * @param {object} dependencies
+ * @param {import("./types.js").PaymentStore} dependencies.store
+ * @param {import("./types.js").PaymentConfiguration} dependencies.configuration
+ * @param {() => number} [dependencies.clock]
+ */
 function createPaymentService({ store, configuration, clock = Date.now }) {
-  if (!store?.withAccount || !store?.inspect || !configuration?.plans) throw new TypeError("Supply payment storage and validated payment configuration.");
+  // readable-check: allow method-probe - input validation: the application passes its own payment store and validated configuration
+  if (typeof store?.withAccount !== "function" || typeof store?.inspect !== "function" || !configuration?.plans) {
+    throw new TypeError("Supply payment storage and validated payment configuration.");
+  }
   const plans = structuredClone(configuration.plans);
   const environments = structuredClone(configuration.environments);
   function checkScope(scope) {
     const expected = environments[scope?.environment];
     if (!expected || expected.integrationId !== scope.integrationId || expected.providerAccountId !== scope.providerAccountId) {
-      fail("payment_scope_invalid", "The payment scope does not match this environment's merchant configuration.", 403);
+      fail("payment_scope_invalid", "The payment scope does not match this environment's merchant configuration.", 403, {
+        messageCode: "payments.scope.merchantMismatch"
+      });
     }
   }
 
@@ -120,6 +131,7 @@ function createPaymentService({ store, configuration, clock = Date.now }) {
   async function reconcileEvent(merchantScope, { eventId, customerId, load }) {
     checkScope(merchantScope);
     reference(eventId); reference(customerId);
+    // readable-check: allow method-probe - input validation: the caller passes its authenticated provider reconciliation
     if (typeof load !== "function") throw new TypeError("Supply an authenticated provider reconciliation function.");
     const subjectId = await store.resolveCustomer(merchantScope, customerId);
     if (!subjectId) fail("payment_customer_unbound", "Bind this provider customer before processing its events.", 409);
@@ -128,7 +140,7 @@ function createPaymentService({ store, configuration, clock = Date.now }) {
       const { subscription, renewal } = await load();
       reference(subscription?.id);
       if (!["active", "trialing", "past_due", "paused", "canceled", "unpaid", "incomplete", "incomplete_expired"].includes(subscription.status) ||
-          !Object.hasOwn(plans, subscription.planId)) fail("payment_provider_result_invalid", "Check the provider subscription and logical price binding.", 502);
+          !Object.hasOwn(plans, subscription.planId)) fail("payment_provider_result_invalid", "Check the provider subscription and logical price binding.", 502, { messageCode: "payments.provider.subscriptionBinding" });
       timestamp(subscription.periodEnd);
       tx.state.subscriptions[subscription.id] = {
         id: subscription.id, status: subscription.status, planId: subscription.planId, periodEnd: subscription.periodEnd
@@ -137,7 +149,7 @@ function createPaymentService({ store, configuration, clock = Date.now }) {
       if (renewal) {
         reference(renewal.id);
         timestamp(renewal.periodEnd);
-        if (!Object.hasOwn(plans, renewal.planId)) fail("payment_provider_result_invalid", "Check the renewal's logical price binding.", 502);
+        if (!Object.hasOwn(plans, renewal.planId)) fail("payment_provider_result_invalid", "Check the renewal's logical price binding.", 502, { messageCode: "payments.provider.renewalBinding" });
         const quantity = plans[renewal.planId].renewalCredits;
         // A provider invoice/transaction is the business key, not its delivery ID.
         if (quantity) creditGrant = await grant(tx, { reference: `renewal:${renewal.id}`, units: quantity, expiresAt: renewal.periodEnd }, timestamp(clock()));
@@ -146,7 +158,14 @@ function createPaymentService({ store, configuration, clock = Date.now }) {
     }));
   }
 
-  return Object.freeze({ inspect, requireFeature, grantCredits, debitCredits, refundDebit, reconcileEvent });
+  return Object.freeze({
+    inspect,
+    requireFeature,
+    grantCredits,
+    debitCredits,
+    refundDebit,
+    reconcileEvent
+  });
 }
 
 export { createPaymentService, PaymentError };

package/src/server/stripe.js

@@ -3,8 +3,23 @@ import { PaymentError } from "./errors.js";
 import { createPriceBindings } from "./priceBindings.js";
 
 const id = (value) => typeof value === "string" ? value : value?.id;
-const invalid = () => { throw new PaymentError("payment_provider_result_invalid", "Check the Stripe account, price mapping and subscription shape.", 502); };
+const invalid = () => {
+  throw new PaymentError("payment_provider_result_invalid", "Check the Stripe account, price mapping and subscription shape.", 502, {
+    messageCode: "payments.provider.checkAccount", messageParams: { provider: "Stripe" }
+  });
+};
 
+/**
+ * @param {object} options
+ * @param {string} [options.apiKey]
+ * @param {string} options.webhookSecret
+ * @param {"sandbox" | "live"} options.environment
+ * @param {string} options.providerAccountId
+ * @param {Record<string, string>} options.priceBindings Each plan's current price id.
+ * @param {Record<string, string>} [options.historicalPriceBindings] The plan of each retired price id.
+ * @param {import("stripe").Stripe} [options.client]
+ */
+// readable-check: allow dependency-default - data: historicalPriceBindings maps retired price ids to plans, not a collaborator
 function createStripePaymentAdapter({ apiKey, webhookSecret, environment, providerAccountId, priceBindings, historicalPriceBindings = {}, client = new Stripe(apiKey, { maxNetworkRetries: 0 }) }) {
   if (!["sandbox", "live"].includes(environment) || typeof webhookSecret !== "string" || !webhookSecret || !providerAccountId) throw new TypeError("Supply Stripe credentials, environment and account identity.");
   const live = environment === "live";
@@ -16,10 +31,12 @@ function createStripePaymentAdapter({ apiKey, webhookSecret, environment, provid
     return { accountId: account.id, environment, chargesEnabled: account.charges_enabled === true, payoutsEnabled: account.payouts_enabled === true };
   }
   async function verifyEvent(rawBody, signature) {
-    if (!Buffer.isBuffer(rawBody)) throw new PaymentError("payment_signature_invalid", "Supply the unmodified webhook request bytes.", 400);
+    if (!Buffer.isBuffer(rawBody)) throw new PaymentError("payment_signature_invalid", "Supply the unmodified webhook request bytes.", 400, { messageCode: "payments.webhook.rawBodyRequired" });
     let event;
     try { event = client.webhooks.constructEvent(rawBody, signature, webhookSecret); }
-    catch { throw new PaymentError("payment_signature_invalid", "Stripe webhook verification failed.", 400); }
+    catch { throw new PaymentError("payment_signature_invalid", "Stripe webhook verification failed.", 400, {
+      messageCode: "payments.webhook.verificationFailed", messageParams: { provider: "Stripe" }
+    }); }
     if (event.livemode !== live || (event.account && event.account !== providerAccountId)) invalid();
     return event;
   }
@@ -82,7 +99,7 @@ function createStripePaymentAdapter({ apiKey, webhookSecret, environment, provid
     return { id: result.id, url: result.url };
   }
   async function readHistory({ customerId, collection, after = null }) {
-    if (!["subscriptions", "transactions"].includes(collection)) throw new PaymentError("payment_input_invalid", "Select a billing history collection.");
+    if (!["subscriptions", "transactions"].includes(collection)) throw new PaymentError("payment_input_invalid", "Select a billing history collection.", 422, { messageCode: "payments.input.historyCollection" });
     await verifyAccount();
     const query = { customer: customerId, limit: 20, ...(after ? { starting_after: after } : {}) };
     const page = collection === "subscriptions"
@@ -120,11 +137,27 @@ function createStripePaymentAdapter({ apiKey, webhookSecret, environment, provid
     if (value.recurring?.interval_count !== 1 || value.billing_scheme !== "per_unit") invalid();
     return { id: value.id, productId: id(value.product), amount: value.unit_amount, currency: value.currency.toUpperCase(), interval: value.recurring.interval, active: value.active };
   }
+  /** @param {{ productId: string, amount: number, currency: string, interval: string, requestId: string }} price */
   async function createPrice({ productId, amount, currency, interval, requestId }) {
     await verifyAccount();
     return client.prices.create({ product: productId, unit_amount: amount, currency: currency.toLowerCase(), recurring: { interval } }, { idempotencyKey: requestId });
   }
-  return Object.freeze({ validatePlan, verifyAccount, verifyEvent, eventIdentity, loadEvent, createCustomer, createCheckout, createPortal, readHistory, readProduct, createProduct, renameProduct, readPrice, createPrice });
+  return Object.freeze({
+    validatePlan,
+    verifyAccount,
+    verifyEvent,
+    eventIdentity,
+    loadEvent,
+    createCustomer,
+    createCheckout,
+    createPortal,
+    readHistory,
+    readProduct,
+    createProduct,
+    renameProduct,
+    readPrice,
+    createPrice
+  });
 }
 
 export { createStripePaymentAdapter };

package/src/server/types.js

@@ -0,0 +1,105 @@
+// The types of the payment objects an application composes, for code that receives them,
+// and the contracts of the store and provider adapter it chooses.
+
+/** @typedef {ReturnType<typeof import("./catalogue.js").createPaymentCatalogue>} PaymentCatalogue */
+/** @typedef {ReturnType<typeof import("./checkout.js").createPaymentCheckoutService>} PaymentCheckoutService */
+/** @typedef {ReturnType<typeof import("./readiness.js").createPaymentReadiness>} PaymentReadiness */
+/** @typedef {ReturnType<typeof import("./service.js").createPaymentService>} PaymentService */
+/** @typedef {ReturnType<typeof import("../shared/configuration.js").validatePaymentConfiguration>} PaymentConfiguration */
+
+/**
+ * The merchant a payment record belongs to: one application's provider account
+ * in one environment.
+ * @typedef {object} PaymentMerchantScope
+ * @property {string} applicationId
+ * @property {string} integrationId
+ * @property {string} providerAccountId
+ * @property {"sandbox" | "live"} environment
+ */
+
+/**
+ * One billable subject of a merchant.
+ * @typedef {PaymentMerchantScope & { subjectId: string }} PaymentAccountScope
+ */
+
+/**
+ * One billable account's stored state.
+ * @typedef {object} PaymentAccountState
+ * @property {Array<{ id: string, remaining: number, expiresAt: number | null }>} lots The credit grants and what remains of each.
+ * @property {Record<string, { id: string, status: string, planId: string, periodEnd: number }>} subscriptions
+ * @property {string} [customerId] The provider customer bound to the account.
+ * @property {Record<string, any>} [pendingPaymentOperation] A provider request whose outcome is not recorded yet.
+ */
+
+/**
+ * An account held under the store's lock while work runs: its state, which the
+ * work changes in place, and the entries recorded under business references.
+ * @typedef {object} PaymentAccountTransaction
+ * @property {PaymentAccountState} state
+ * @property {(reference: string) => Promise<any>} find The entry recorded under a reference, or null.
+ * @property {(reference: string, entry: any) => Promise<void>} record Records an entry under a new reference.
+ */
+
+/**
+ * One merchant's published catalogue: each plan's provider product and price.
+ * @typedef {object} PaymentCatalogueState
+ * @property {Record<string, Record<string, any>>} plans
+ * @property {Array<Record<string, any>>} history The price bindings each plan had before its current one.
+ * @property {number} [revision]
+ * @property {Record<string, any>} [pending] A provider write whose outcome is not recorded yet.
+ */
+
+/**
+ * Where payment accounts and catalogues are kept: createKnexPaymentStore() or
+ * the application's own store. Each `with*` call runs its work under the
+ * record's lock and saves the state the work leaves.
+ * @typedef {object} PaymentStore
+ * @property {(scope: PaymentAccountScope) => Promise<PaymentAccountState>} inspect
+ * @property {<T>(scope: PaymentAccountScope, work: (account: PaymentAccountTransaction) => Promise<T>) => Promise<T>} withAccount
+ * @property {(scope: PaymentMerchantScope, customerId: string, subjectId: string) => Promise<void>} bindCustomer
+ *   Binds a provider customer to one billable subject, refusing a customer bound to another.
+ * @property {(scope: PaymentMerchantScope, customerId: string) => Promise<string | null>} resolveCustomer The subject a provider customer is bound to.
+ * @property {(scope: PaymentMerchantScope) => Promise<PaymentCatalogueState>} inspectCatalogue
+ * @property {<T>(scope: PaymentMerchantScope, work: (state: PaymentCatalogueState) => Promise<T>) => Promise<T>} withCatalogue
+ */
+
+/**
+ * A provider's billing page: its id and the URL the customer opens.
+ * @typedef {{ id: string, url: string }} PaymentProviderPage
+ */
+
+/**
+ * A price as the provider holds it.
+ * @typedef {object} PaymentProviderPrice
+ * @property {string} id
+ * @property {string} productId
+ * @property {number} amount In the currency's minor unit.
+ * @property {string} currency
+ * @property {string} interval
+ * @property {boolean} active
+ */
+
+/**
+ * A payment provider's operations: createStripePaymentAdapter() or
+ * createPaddlePaymentAdapter().
+ * @typedef {object} PaymentProviderAdapter
+ * @property {(planId: string) => void} validatePlan Throws for a plan with no current price binding.
+ * @property {() => Promise<{ environment: string, accountId?: string, credentialsVerified?: boolean, chargesEnabled?: boolean, payoutsEnabled?: boolean }>} verifyAccount
+ *   What the provider confirms about the configured account.
+ * @property {(rawBody: Buffer, signature: string) => Promise<any>} verifyEvent The webhook event, once its signature is verified.
+ * @property {(event: any) => { eventId: string, customerId: string } | null} eventIdentity The event and customer of a billing event, or null for an event to ignore.
+ * @property {(event: any) => Promise<{ customerId: string, subscription: Record<string, any>, renewal?: Record<string, any> } | null>} loadEvent
+ *   The provider's current subscription facts for the event.
+ * @property {(request: { email: string, requestId: string }) => Promise<string>} createCustomer The new customer's id.
+ * @property {(request: { customerId: string, planId: string, returnUrl: string, requestId: string }) => Promise<PaymentProviderPage>} createCheckout
+ * @property {(request: { customerId: string, returnUrl: string }) => Promise<PaymentProviderPage>} createPortal
+ * @property {(request: { customerId: string, collection: string, after?: string | null }) => Promise<{ collection: string, items: Array<Record<string, any>>, nextCursor: string | null }>} readHistory
+ *   One page of the customer's subscriptions or transactions.
+ * @property {(productId: string) => Promise<{ id: string, name: string }>} readProduct
+ * @property {(request: { name: string, requestId: string }) => Promise<{ id: string }>} createProduct
+ * @property {(request: { id: string, name: string, requestId: string }) => Promise<{ id: string }>} renameProduct
+ * @property {(priceId: string) => Promise<PaymentProviderPrice>} readPrice
+ * @property {(request: { productId: string, amount: number, currency: string, interval: string, requestId: string }) => Promise<{ id: string }>} createPrice
+ */
+
+export {};

package/src/shared/configuration.js

@@ -3,15 +3,33 @@ import schema from "../../contracts/configuration.schema.json" with { type: "jso
 
 const validate = new Ajv({ allErrors: true, strict: true }).compile(schema);
 
-function configurationError(message, fieldErrors) {
-  return Object.assign(new Error(message), { code: "payment_configuration_invalid", statusCode: 422, fieldErrors });
+/**
+ * A refused payment configuration: every field error has its path, English
+ * message, code and params, and the error's messageCode names its own sentence.
+ */
+class PaymentConfigurationError extends Error {
+  /**
+   * @param {string} message
+   * @param {Array<{ path: string, message: string, code?: string, params?: Record<string, unknown> }>} fieldErrors
+   * @param {{ messageCode: string, messageParams?: Record<string, unknown> }} translation
+   */
+  constructor(message, fieldErrors, { messageCode, messageParams = {} }) {
+    super(message);
+    this.name = "PaymentConfigurationError";
+    this.code = "payment_configuration_invalid";
+    this.statusCode = 422;
+    this.fieldErrors = fieldErrors;
+    this.messageCode = messageCode;
+    this.messageParams = messageParams;
+  }
 }
 
 function validatePaymentConfiguration(document) {
   const value = document?.extensions?.payments;
   if (!validate(value)) {
-    throw configurationError("Check the application's payment configuration.",
-      validate.errors.map(({ instancePath, message }) => ({ path: `extensions.payments${instancePath}`, message })));
+    throw new PaymentConfigurationError("Check the application's payment configuration.",
+      validate.errors.map(({ instancePath, message }) => ({ path: `extensions.payments${instancePath}`, message })),
+      { messageCode: "payments.configuration.invalid" });
   }
   // Report every environment's binding problems at once, like the schema stage.
   const fieldErrors = [];
@@ -20,15 +38,27 @@ function validatePaymentConfiguration(document) {
     const path = `extensions.payments/environments/${environment}`;
     if (!slot || !["stripe", "paddle"].includes(slot.provider) || slot.accountMode !== "shared" ||
         slot.authentication?.method !== "api-key" || !/^env:[A-Z_][A-Z0-9_]*$/.test(slot.authentication.secretRef || "")) {
-      fieldErrors.push({ path: `${path}/integrationId`, message: `Select a shared Stripe or Paddle connection with a backend API-key Env reference for ${environment}.` });
+      fieldErrors.push({ path: `${path}/integrationId`, message: `Select a shared Stripe or Paddle connection with a backend API-key Env reference for ${environment}.`,
+        code: "payments.configuration.sharedConnectionRequired", params: { environment } });
     }
     if (slot?.provider === "paddle") {
-      if (slot.settings?.environment !== environment) fieldErrors.push({ path: `${path}/integrationId`, message: `Select a Paddle connection configured for ${environment}.` });
-      if (!binding.taxCategory) fieldErrors.push({ path: `${path}/taxCategory`, message: "Choose the Paddle tax category for the products this app sells." });
-      if (!binding.publicClientTokenRef) fieldErrors.push({ path: `${path}/publicClientTokenRef`, message: "Set the Env reference for this environment's Paddle public client token." });
+      if (slot.settings?.environment !== environment) {
+        fieldErrors.push({ path: `${path}/integrationId`, message: `Select a Paddle connection configured for ${environment}.`,
+          code: "payments.configuration.paddleEnvironment", params: { environment } });
+      }
+      if (!binding.taxCategory) {
+        fieldErrors.push({ path: `${path}/taxCategory`, message: "Choose the Paddle tax category for the products this app sells.",
+          code: "payments.configuration.paddleTaxCategory", params: {} });
+      }
+      if (!binding.publicClientTokenRef) {
+        fieldErrors.push({ path: `${path}/publicClientTokenRef`, message: "Set the Env reference for this environment's Paddle public client token.",
+          code: "payments.configuration.paddleClientToken", params: {} });
+      }
     }
   }
-  if (fieldErrors.length) throw configurationError(fieldErrors[0].message, fieldErrors);
+  if (fieldErrors.length) throw new PaymentConfigurationError(fieldErrors[0].message, fieldErrors, {
+    messageCode: fieldErrors[0].code, messageParams: fieldErrors[0].params
+  });
   // The validated declaration is JSON data; callers may supply reactive proxies.
   return JSON.parse(JSON.stringify(value));
 }

package/test/i18nCatalog.test.js

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { catalogMessage, formatMessage, messageKeyForCode } from "@jskit-ai/kernel/shared/i18n";
+import { evaluateI18nCatalogContract } from "../../../tooling/test-support/i18nCatalogContract.mjs";
+import { validatePaymentConfiguration } from "../src/shared/configuration.js";
+import conformance from "../contracts/conformance.json" with { type: "json" };
+import en from "../locales/en.json" with { type: "json" };
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+const PACKAGE_DIR = path.join(REPO_ROOT, "packages", "payments-core");
+
+function english(code, params) {
+  const template = catalogMessage(en, messageKeyForCode(code));
+  return template === undefined ? undefined : formatMessage(template, params);
+}
+
+test("payments-core English catalog matches its source", () => {
+  const { problems } = evaluateI18nCatalogContract({
+    repoRoot: REPO_ROOT,
+    packageDir: PACKAGE_DIR
+  });
+  assert.deepEqual(problems, []);
+});
+
+test("every payment error's catalog English equals the English it throws", () => {
+  const site = /(?:PaymentError|fail)\(\s*"(payment_[a-z_]+)",\s*"((?:[^"\\]|\\.)*)"(?:,\s*\d+)?(?:,\s*\{\s*messageCode:\s*"([^"]+)"(?:,\s*messageParams:\s*\{\s*provider:\s*"([^"]+)"\s*\})?\s*\})?/gu;
+  const sources = fs.readdirSync(path.join(PACKAGE_DIR, "src", "server"))
+    .map((file) => fs.readFileSync(path.join(PACKAGE_DIR, "src", "server", file), "utf8"));
+  const sites = sources.join("\n").match(/(?:PaymentError|fail)\("payment_/gu).length;
+  let checked = 0;
+  for (const source of sources) {
+    for (const [, code, message, messageCode, provider] of source.matchAll(site)) {
+      const expected = JSON.parse(`"${message}"`);
+      if (messageCode) {
+        assert.equal(english(messageCode, provider ? { provider } : {}), expected, messageCode);
+      } else {
+        assert.equal(english(code), expected, code);
+      }
+      checked += 1;
+    }
+  }
+  assert.equal(checked, sites);
+});
+
+test("configuration errors carry codes whose English matches each field error", () => {
+  const coded = new Set();
+  for (const item of conformance.configurationCases) {
+    const documents = [item.document];
+    if (item.id === "paddle-sandbox") {
+      const document = structuredClone(item.document);
+      delete document.extensions.payments.environments.sandbox.taxCategory;
+      documents.push(document);
+    }
+    for (const document of documents) {
+      let error = null;
+      try {
+        validatePaymentConfiguration(document);
+      } catch (caught) {
+        error = caught;
+      }
+      if (!error) continue;
+      assert.equal(english(error.messageCode, error.messageParams), error.message, item.id);
+      for (const entry of error.fieldErrors.filter(({ code }) => code)) {
+        assert.equal(english(entry.code, entry.params), entry.message, entry.code);
+        coded.add(entry.code);
+      }
+    }
+  }
+  assert.deepEqual([...coded].sort(), [
+    "payments.configuration.paddleClientToken",
+    "payments.configuration.paddleEnvironment",
+    "payments.configuration.paddleTaxCategory",
+    "payments.configuration.sharedConnectionRequired"
+  ]);
+});

package/test/standalone.test.js

@@ -9,7 +9,7 @@ import { createPaymentService } from '@jskit-ai/payments-core/server';
 import { createKnexPaymentStore } from '@jskit-ai/payments-core/server/storage';
 import migration from '../migrations/payments_core_initial.cjs';
 
-// No editor, Genesis project, network or generated application is involved.
+// No editor, project tooling, network or generated application is involved.
 test('a hand-written app reloads payment policy from disk while retaining its own billing state', async () => {
   const directory = await mkdtemp(join(tmpdir(), 'standalone-payments-'));
   const path = join(directory, 'integrations.json');