@jskit-ai/payments-core 0.1.1

package/src/server/catalogue.js

@@ -0,0 +1,117 @@
+import { createHash, randomUUID } from "node:crypto";
+import { PaymentError } from "./service.js";
+
+const fingerprint = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+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.
+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);
+  }
+  async function preview() {
+    const state = await store.inspectCatalogue(merchant);
+    const changes = [];
+    const drift = [];
+    for (const [planId, plan] of Object.entries(plans)) {
+      const binding = state.plans[planId];
+      if (!binding) changes.push({ action: "create-product", planId, name: plan.name });
+      else {
+        const actualProduct = await adapter.readProduct(binding.productId);
+        if (actualProduct.name !== binding.name) drift.push({ planId, reason: "The product name changed in the provider dashboard." });
+        if (binding.name !== plan.name) changes.push({ action: "rename-product", planId, productId: binding.productId, name: plan.name });
+        if (binding.priceId) {
+          const actual = await adapter.readPrice(binding.priceId);
+          if (actual.productId !== binding.productId || !samePrice(actual, binding) || actual.active !== true) drift.push({ planId, reason: "The provider price differs from its saved binding." });
+        }
+      }
+      if (!binding?.priceId || !samePrice(binding, plan)) changes.push({ action: "create-price", planId, ...priceFields(plan) });
+    }
+    const removed = Object.keys(state.plans).filter((planId) => !Object.hasOwn(plans, planId));
+    const result = { environment: merchant.environment, providerAccountId: merchant.providerAccountId, changes, drift, removed, revision: state.revision || 0,
+      pending: state.pending || null };
+    return { ...result, reviewId: fingerprint(result) };
+  }
+  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);
+    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);
+        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);
+        const operation = { ...change, token, productId: current?.productId };
+        state.pending = operation;
+        return operation;
+      });
+      let result;
+      try {
+        if (pending.action === "create-product") result = await adapter.createProduct({ name: pending.name, requestId: token });
+        else if (pending.action === "rename-product") result = await adapter.renameProduct({ id: pending.productId, name: pending.name, requestId: token });
+        else result = await adapter.createPrice({ ...pending, requestId: token });
+      } catch {
+        throw new PaymentError("payment_catalogue_uncertain", "Catalogue publication stopped. Inspect the pending provider request before retrying; completed items are preserved.", 409);
+      }
+      await finish(pending, result);
+      expectedRevision++;
+      completed.push({ ...change, id: result.id });
+    }
+    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);
+    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);
+      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;
+      else {
+        if (current.priceId) state.history.push({ planId: pending.planId, ...current });
+        state.plans[pending.planId] = { ...current, priceId: result.id, ...priceFields(pending) };
+      }
+      state.revision = (state.revision || 0) + 1;
+      delete state.pending;
+    });
+  }
+  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);
+    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);
+        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.");
+    }
+    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);
+    }
+    await finish(pending, { id: providerId });
+    return { pending: false };
+  }
+  return Object.freeze({ preview, publish, recover });
+}
+
+export { createPaymentCatalogue };

package/src/server/checkout.js

@@ -0,0 +1,131 @@
+import { createHash, randomUUID } from "node:crypto";
+import { PaymentError } from "./service.js";
+
+// Application composition boundary: authorization is mandatory and supplied by
+// the app's framework. Actor and subject must come from its authenticated route.
+function createPaymentCheckoutService({ adapter, store, payments, merchantScope, returnUrl, authorize }) {
+  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) {
+    throw new TypeError("Configure an HTTPS application return/checkout URL (HTTP is allowed only for local development).");
+  }
+  const merchant = structuredClone(merchantScope);
+  async function allowed(actor, subjectId, action) {
+    if (typeof subjectId !== "string" || !subjectId || subjectId.length > 200 || await authorize(actor, { subjectId, action }) !== true) {
+      throw new PaymentError("payment_forbidden", "You cannot manage this billable account.", 403);
+    }
+    return { ...merchant, subjectId };
+  }
+  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);
+      const ready = await operation(tx);
+      if (ready.cached) return ready;
+      tx.state.pendingPaymentOperation = { token, ...ready };
+      return ready;
+    });
+    if (prepared.cached) return prepared.result;
+    // Intent commits BEFORE the network request. A killed process leaves an
+    // 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); }
+    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);
+      delete tx.state.pendingPaymentOperation;
+      return value;
+    });
+  }
+  async function checkout({ actor, subjectId, email, planId, requestId }) {
+    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.");
+    const identity = createHash("sha256").update(JSON.stringify(scope)).digest("hex");
+    const customerId = await perform(scope, async (tx) => tx.state.customerId
+      ? { cached: true, result: tx.state.customerId }
+      : { action: "customer", email },
+    () => adapter.createCustomer({ email, requestId: `customer-${identity}` }),
+    async (tx, value) => { tx.state.customerId = value; return value; });
+    await store.bindCustomer(merchant, customerId, subjectId);
+    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);
+        return { cached: true, result: saved.result };
+      }
+      if (Object.values(tx.state.subscriptions).some((subscription) =>
+        !["canceled", "incomplete_expired"].includes(subscription.status))) {
+        throw new PaymentError("payment_subscription_exists", "Manage the existing subscription through billing instead of starting another checkout.", 409);
+      }
+      return { action: "checkout", customerId, planId, requestId };
+    }, () => adapter.createCheckout({ customerId, planId, returnUrl: target.href,
+      requestId: `checkout-${createHash("sha256").update(JSON.stringify([scope, requestId])).digest("hex")}` }),
+    async (tx, result) => { await tx.record(`checkout:${requestId}`, { planId, result }); return result; });
+  }
+  async function account({ actor, subjectId }) {
+    const scope = await allowed(actor, subjectId, "account");
+    const state = await payments.inspect(scope);
+    const customer = await store.inspect(scope);
+    return { ...state, hasCustomer: Boolean(customer.customerId) };
+  }
+  async function history({ actor, subjectId, collection, after = null }) {
+    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.");
+    }
+    // Never accept a customer identifier from the browser or editor caller.
+    const { customerId } = await store.inspect(scope);
+    if (!customerId) return { collection, items: [], nextCursor: null };
+    try { return await adapter.readHistory({ customerId, collection, after }); }
+    catch { throw new PaymentError("payment_history_unavailable", "Billing history could not be loaded. Check provider access and retry.", 502); }
+  }
+  async function portal({ actor, subjectId }) {
+    const scope = await allowed(actor, subjectId, "portal");
+    return perform(scope, async (tx) => {
+      if (!tx.state.customerId) throw new PaymentError("payment_customer_missing", "Create a billing account first.", 404);
+      return { action: "portal", customerId: tx.state.customerId };
+    }, ({ customerId }) => adapter.createPortal({ customerId, returnUrl: target.href }), async (_tx, result) => result);
+  }
+  // Reconciliation is an app-server operation. The trusted callback inspects the
+  // provider dashboard/API and must return evidence, never browser-supplied data.
+  async function reconcilePending({ actor, subjectId, inspectProvider }) {
+    const scope = await allowed(actor, subjectId, "reconcile");
+    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;
+      if (!pending) return { pending: false };
+      const evidence = await inspectProvider(structuredClone(pending));
+      if (evidence?.confirmedNotCreated === true) {
+        delete tx.state.pendingPaymentOperation;
+        return { pending: false, retryAllowed: true };
+      }
+      const result = evidence?.result;
+      if (pending.action === "customer" && typeof result === "string" && result) tx.state.customerId = result;
+      else if (pending.action === "checkout" && typeof result?.id === "string" && typeof result.url === "string") {
+        await tx.record(`checkout:${pending.requestId}`, { planId: pending.planId, result });
+      } else if (!(pending.action === "portal" && typeof result?.url === "string")) {
+        throw new PaymentError("payment_reconciliation_required", "Provider inspection did not resolve this request.", 409);
+      }
+      delete tx.state.pendingPaymentOperation;
+      return { pending: false, result };
+    });
+  }
+  async function webhook({ rawBody, signature }) {
+    const event = await adapter.verifyEvent(rawBody, signature);
+    const identity = adapter.eventIdentity(event);
+    if (!identity) return { ignored: true };
+    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);
+      return facts;
+    } });
+  }
+  return Object.freeze({ account, history, checkout, portal, webhook, reconcilePending });
+}
+
+export { createPaymentCheckoutService };

package/src/server/knexStore.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const empty = () => ({ lots: [], subscriptions: {} });
+
+function merchant(scope) {
+  const fields = ["applicationId", "integrationId", "providerAccountId", "environment"];
+  for (const field of fields) {
+    if (typeof scope?.[field] !== "string" || !scope[field] || scope[field].length > 200) throw new TypeError(`Payment scope requires ${field}.`);
+  }
+  if (!["sandbox", "live"].includes(scope.environment)) throw new TypeError("Payment scope requires sandbox or live.");
+  return fields.map((field) => scope[field]);
+}
+function identifier(value) {
+  if (typeof value !== "string" || !value || value.length > 200) throw new TypeError("Payment identity is required (maximum 200 characters).");
+  return value;
+}
+const accountKey = (scope) => hash([...merchant(scope), identifier(scope.subjectId)]);
+
+function createKnexPaymentStore({ knex }) {
+  if (typeof knex !== "function" || typeof knex.transaction !== "function") throw new TypeError("Supply the application's transactional Knex client.");
+
+  async function inspect(scope) {
+    const row = await knex("payment_accounts").where({ account_key: accountKey(scope) }).first();
+    return row ? JSON.parse(row.payload) : empty();
+  }
+  async function withAccount(scope, work) {
+    const key = accountKey(scope);
+    return knex.transaction(async (trx) => {
+      // The retained account row serializes grants, usage, refunds and event handling.
+      await trx("payment_accounts").insert({ account_key: key, payload: JSON.stringify(empty()) })
+        .onConflict("account_key").merge({ account_key: key });
+      const row = await trx("payment_accounts").where({ account_key: key }).forUpdate().first();
+      const state = JSON.parse(row.payload);
+      const result = await work({
+        state,
+        async find(reference) {
+          const entry = await trx("payment_entries").where({ entry_key: hash([key, identifier(reference)]) }).first();
+          return entry ? JSON.parse(entry.payload) : null;
+        },
+        async record(reference, payload) {
+          await trx("payment_entries").insert({ entry_key: hash([key, identifier(reference)]), account_key: key, payload: JSON.stringify(payload) });
+        }
+      });
+      await trx("payment_accounts").where({ account_key: key }).update({ payload: JSON.stringify(state) });
+      return result;
+    });
+  }
+  async function bindCustomer(scope, customerId, subjectId) {
+    const key = hash([...merchant(scope), identifier(customerId)]);
+    identifier(subjectId);
+    await knex.transaction(async (trx) => {
+      await trx("payment_customers").insert({ customer_key: key, subject_id: subjectId })
+        .onConflict("customer_key").merge({ customer_key: key });
+      const row = await trx("payment_customers").where({ customer_key: key }).first();
+      if (row.subject_id !== subjectId) throw new Error("This provider customer is already bound to a different billable subject.");
+    });
+  }
+  async function resolveCustomer(scope, customerId) {
+    const row = await knex("payment_customers").where({ customer_key: hash([...merchant(scope), identifier(customerId)]) }).first();
+    return row?.subject_id ?? null;
+  }
+  async function inspectCatalogue(scope) {
+    const row = await knex("payment_catalogues").where({ catalogue_key: hash(merchant(scope)) }).first();
+    return row ? JSON.parse(row.payload) : { plans: {}, history: [] };
+  }
+  async function withCatalogue(scope, work) {
+    const key = hash(merchant(scope));
+    return knex.transaction(async (trx) => {
+      await trx("payment_catalogues").insert({ catalogue_key: key, payload: JSON.stringify({ plans: {}, history: [] }) })
+        .onConflict("catalogue_key").merge({ catalogue_key: key });
+      const row = await trx("payment_catalogues").where({ catalogue_key: key }).forUpdate().first();
+      const state = JSON.parse(row.payload);
+      const result = await work(state);
+      await trx("payment_catalogues").where({ catalogue_key: key }).update({ payload: JSON.stringify(state) });
+      return result;
+    });
+  }
+  return Object.freeze({ inspect, withAccount, bindCustomer, resolveCustomer, inspectCatalogue, withCatalogue });
+}
+
+export { createKnexPaymentStore };

package/src/server/paddle.js

@@ -0,0 +1,117 @@
+import { Paddle, Environment } from "@paddle/paddle-node-sdk";
+import { PaymentError } from "./service.js";
+
+const invalid = () => { throw new PaymentError("payment_provider_result_invalid", "Check the Paddle account, price mapping and subscription shape.", 502); };
+
+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 prices = structuredClone(priceBindings);
+  const planFor = (priceId) => {
+    const matches = Object.entries(prices).filter(([, value]) => value === priceId);
+    if (!matches.length && Object.hasOwn(historicalPriceBindings, priceId)) return historicalPriceBindings[priceId];
+    if (matches.length !== 1) invalid();
+    return matches[0][0];
+  };
+  function validatePlan(planId) {
+    if (!Object.hasOwn(prices, planId)) throw new PaymentError("payment_plan_unknown", "Select a published payment plan.");
+  }
+  async function verifyAccount() {
+    await client.products.list({ perPage: 1 }).next();
+    // A successful catalogue read cannot prove merchant verification or identify
+    // the legal account. Keep those readiness checks explicit in the UI.
+    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);
+    try { return await client.webhooks.unmarshal(rawBody.toString("utf8"), webhookSecret, signature); }
+    catch { throw new PaymentError("payment_signature_invalid", "Paddle webhook verification failed.", 400); }
+  }
+  function eventIdentity(event) {
+    if (event.eventType === "transaction.completed") {
+      if (event.data?.subscriptionId === null) return null;
+      if (!event.data?.subscriptionId) invalid();
+    } else if (!event.eventType?.startsWith("subscription.")) return null;
+    if (!event.eventId || !event.data?.customerId) invalid();
+    return { eventId: event.eventId, customerId: event.data.customerId };
+  }
+  async function loadEvent(event) {
+    let transaction = null;
+    let subscriptionId;
+    if (event.eventType === "transaction.completed") {
+      transaction = await client.transactions.get(event.data.id);
+      subscriptionId = transaction.subscriptionId;
+      if (!subscriptionId) return null;
+    } else if (event.eventType.startsWith("subscription.")) subscriptionId = event.data.id;
+    else return null;
+    const subscription = await client.subscriptions.get(subscriptionId);
+    if (subscription.items?.length !== 1 || subscription.items[0].quantity !== 1) invalid();
+    const result = { subscription: {
+      id: subscription.id, status: subscription.status, planId: planFor(subscription.items[0].price.id),
+      periodEnd: subscription.currentBillingPeriod ? Date.parse(subscription.currentBillingPeriod.endsAt) : 0
+    } };
+    if (transaction && transaction.customerId !== subscription.customerId) invalid();
+    if (transaction?.status === "completed" && ["api", "web", "subscription_recurring"].includes(transaction.origin)) {
+      if (transaction.items?.length !== 1 || transaction.items[0].quantity !== 1 || transaction.items[0].proration || !transaction.billingPeriod) invalid();
+      result.renewal = { id: transaction.id, planId: planFor(transaction.items[0].price?.id), periodEnd: Date.parse(transaction.billingPeriod.endsAt) };
+    }
+    return { customerId: subscription.customerId, ...result };
+  }
+  async function createCustomer({ email }) {
+    const customer = await client.customers.create({ email });
+    return customer.id;
+  }
+  async function createCheckout({ customerId, planId, returnUrl }) {
+    if (!Object.hasOwn(prices, planId)) throw new PaymentError("payment_plan_unknown", "Select a published payment plan.");
+    // This URL is an app-owned Paddle.js checkout page, approved in Paddle.
+    const result = await client.transactions.create({ customerId, collectionMode: "automatic",
+      items: [{ priceId: prices[planId], quantity: 1 }], checkout: { url: returnUrl } });
+    if (typeof result.checkout?.url !== "string") invalid();
+    return { id: result.id, url: result.checkout.url };
+  }
+  async function createPortal({ customerId }) {
+    const result = await client.customerPortalSessions.create(customerId, []);
+    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.");
+    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.
+    const data = await page.next();
+    if (!Array.isArray(data) || data.length > 20 || typeof page.hasMore !== "boolean" || (page.hasMore && !data.length)) invalid();
+    const items = data.map((value) => {
+      if (value.customerId !== customerId || typeof value.id !== "string" || typeof value.status !== "string" ||
+        typeof value.createdAt !== "string" || !Number.isFinite(Date.parse(value.createdAt))) invalid();
+      const base = { id: value.id, kind: collection === "subscriptions" ? "subscription" : "transaction",
+        status: value.status, createdAt: new Date(value.createdAt).toISOString() };
+      if (collection === "subscriptions") return base;
+      const total = value.details?.totals?.total ?? null;
+      if ((total !== null && (typeof total !== "string" || !/^-?[0-9]{1,30}$/.test(total))) || !/^[A-Z]{3}$/.test(value.currencyCode)) invalid();
+      // A transaction total is not proof it was paid. Preserve provider status.
+      return { ...base, currency: value.currencyCode, totalMinor: total, paidMinor: null };
+    });
+    return { collection, items, nextCursor: page.hasMore ? items.at(-1).id : null };
+  }
+  async function readProduct(productId) {
+    const value = await client.products.get(productId);
+    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.");
+    return client.products.create({ name, taxCategory });
+  }
+  async function renameProduct({ id, name }) {
+    return client.products.update(id, { name });
+  }
+  async function readPrice(priceId) {
+    const value = await client.prices.get(priceId);
+    if (value.billingCycle?.frequency !== 1) invalid();
+    return { id: value.id, productId: value.productId, amount: Number(value.unitPrice.amount), currency: value.unitPrice.currencyCode, interval: value.billingCycle.interval, active: value.status === "active" };
+  }
+  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 });
+}
+
+export { createPaddlePaymentAdapter };

package/src/server/readiness.js

@@ -0,0 +1,63 @@
+import { PaymentError } from "./service.js";
+
+// 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 }) {
+  const merchant = structuredClone(scope);
+  if (!["sandbox", "live"].includes(merchant?.environment) || !merchant.providerAccountId) throw new TypeError("Supply the configured payment merchant scope.");
+  async function inspect() {
+    const checks = [
+      { id: "credentials", status: "unknown", detail: "Check the provider credentials for this environment." },
+      { id: "account", status: "unknown", detail: "Confirm the configured merchant owns these credentials." },
+      { id: "charges", status: "manual", detail: "Confirm payment acceptance is enabled in the provider dashboard." },
+      { id: "payouts", status: "manual", detail: "Confirm payout eligibility in the provider dashboard." },
+      { id: "catalogue", status: "unknown", detail: "Inspect the saved products and prices." },
+      { id: "webhook", status: "unknown", detail: "Verify the deployed webhook route, signing secret and subscribed events." },
+      { id: "checkout", status: "unknown", detail: "Verify app checkout and portal routes, authorization and return handling." },
+      { id: "site", status: "manual", detail: "Review required site content and provider domain or website approval." },
+      { id: "deployment", status: "unknown", detail: "Verify the intended release uses this configuration and environment." }
+    ];
+    let provider;
+    try { provider = await adapter.verifyAccount(); }
+    catch { checks[0] = { id: "credentials", status: "failed", detail: "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);
+      }
+      const verified = provider.credentialsVerified === true || provider.accountId === merchant.providerAccountId;
+      checks[0] = { id: "credentials", status: verified ? "passed" : "unknown", detail: verified
+        ? "The provider accepted credential verification for this environment." : "The provider returned no affirmative credential verification." };
+      checks[1] = { id: "account", status: provider.accountId === merchant.providerAccountId ? "passed" : "manual",
+        detail: provider.accountId === merchant.providerAccountId ? "The provider account matches the saved merchant identity." : "This provider check does not establish merchant identity. Confirm it in the provider dashboard." };
+      for (const [index, property] of [[2, "chargesEnabled"], [3, "payoutsEnabled"]]) {
+        if (typeof provider[property] === "boolean") checks[index] = { id: checks[index].id, status: provider[property] ? "passed" : "failed",
+          detail: `The provider reports ${checks[index].id} ${provider[property] ? "enabled" : "not enabled"}.` };
+      }
+      try {
+        const review = await catalogue.preview();
+        if (review.environment !== merchant.environment || review.providerAccountId !== merchant.providerAccountId) throw new Error("scope");
+        const unresolved = Boolean(review.pending || review.changes.length || review.drift.length || review.removed.length);
+        checks[4] = { id: "catalogue", status: unresolved ? "failed" : "passed",
+          detail: unresolved ? "Catalogue changes, drift, removed plans or an unresolved write need review." : "Saved plans match their published provider products and prices." };
+      } catch { checks[4] = { id: "catalogue", status: "failed", detail: "Catalogue inspection failed. Review the application's catalogue command and provider access." }; }
+    }
+    if (inspectApplication) {
+      let evidence;
+      try { evidence = await inspectApplication(); } catch { evidence = {}; }
+      for (const check of checks.slice(5)) {
+        const value = evidence?.[check.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.");
+        }
+        check.status = value.status;
+        check.detail = value.detail;
+      }
+    }
+    return { paymentEnvironment: merchant.environment, providerAccountId: merchant.providerAccountId, checks };
+  }
+  return Object.freeze({ inspect });
+}
+
+export { createPaymentReadiness };