@jskit-ai/payments-core 0.2.0 → 0.2.2

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/payments-core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Application-owned payment configuration, subscription access and transactional usage credits.",
   "exports": {
@@ -16,10 +16,11 @@
     "./server/paddle": "./src/server/paddle.js",
     "./server/catalogue": "./src/server/catalogue.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"
+    "test": "jskit test"
   },
   "dependencies": {
     "@paddle/paddle-node-sdk": "3.10.0",

package/src/server/catalogue.js

@@ -4,8 +4,15 @@ 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);
@@ -112,7 +119,11 @@ function createPaymentCatalogue({ store, adapter, scope, configuration }) {
     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) {
@@ -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;
@@ -125,7 +136,14 @@ function createPaymentCheckoutService({ adapter, store, payments, merchantScope,
       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/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

@@ -8,6 +8,17 @@ const invalid = () => {
   });
 };
 
+/**
+ * @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 });
@@ -111,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() {
@@ -50,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

@@ -39,10 +39,19 @@ 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) {
@@ -122,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);
@@ -148,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

@@ -9,6 +9,17 @@ const invalid = () => {
   });
 };
 
+/**
+ * @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";
@@ -126,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,17 +3,31 @@ import schema from "../../contracts/configuration.schema.json" with { type: "jso
 
 const validate = new Ajv({ allErrors: true, strict: true }).compile(schema);
 
-// Each JSKIT field error also has a code and params; the error's messageCode names its sentence.
-function configurationError(message, fieldErrors, { messageCode, messageParams = {} }) {
-  return Object.assign(new Error(message), {
-    code: "payment_configuration_invalid", statusCode: 422, fieldErrors, messageCode, messageParams
-  });
+/**
+ * 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.",
+    throw new PaymentConfigurationError("Check the application's payment configuration.",
       validate.errors.map(({ instancePath, message }) => ({ path: `extensions.payments${instancePath}`, message })),
       { messageCode: "payments.configuration.invalid" });
   }
@@ -42,7 +56,7 @@ function validatePaymentConfiguration(document) {
       }
     }
   }
-  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.

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');