@volter/twin-stripe 2.0.38 → 3.0.0

package/src/semantics/payment_intents.ts

@@ -0,0 +1,83 @@
+// Stripe's payment_intents operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import type { Row } from '../engine/common.ts';
+import { PI, TYPES_GIVEN } from '../engine/payment-intents.ts';
+import { asBool, mintClientSecret, nowUnix, validateMoney, verifyMicrodeposits } from '../engine/stripe.ts';
+import { afterCharge, beginBankDebit, cancelAuthorization, captureAuthorization, confirmIntent, confirmOnly, fundFromCashBalance, incrementTooSmall, methodFromData, mintCharge, mintMandate, payInvoiceOf, paymentIntentsLoad, paymentIntentsSend, search } from './shared.ts';
+
+export async function PostPaymentIntents(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  const bad = validateMoney(params);
+  if (bad) return paymentIntentsSend(ctx, bad);
+  // what describes a confirmation needs one: error_on_requires_action, mandate, mandate_data, off_session and return_url
+  // are each, in the served spec, a parameter that "can only be used with `confirm=true`" (shared.ts confirmOnly)
+  const unconfirmed = confirmOnly(ctx, ['error_on_requires_action', 'mandate', 'mandate_data', 'off_session', 'return_url'], asBool(params.confirm));
+  if (unconfirmed) return unconfirmed;
+  // automatic_payment_methods: when enabled, Stripe selects eligible methods and answers the
+  // normalized { enabled, allow_redirects } object
+  const apmIn = params.automatic_payment_methods;
+  const apmEnabled = apmIn && typeof apmIn === 'object' ? asBool((apmIn as Record<string, unknown>).enabled) : false;
+  const automatic_payment_methods = apmEnabled ? { enabled: true, allow_redirects: ((apmIn as Record<string, unknown>).allow_redirects as string) ?? 'always' } : null;
+  // the methods it may be paid with: allowed_payment_method_types in the served version, payment_method_types for a
+  // caller pinned to an earlier one (docs.stripe.com/api/payment_intents/create)
+  const given = Array.isArray(params.allowed_payment_method_types) ? params.allowed_payment_method_types : params.payment_method_types;
+  const payment_method_types = Array.isArray(given) ? given.map(String) : ['card'];
+  // `confirm` is an instruction, not a field: `confirm=true` attempts to confirm the intent at once
+  // (https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm)
+  const { automatic_payment_methods: _a, payment_method_types: _p, allowed_payment_method_types: _ap, id: provided, expand: _e, confirm: confirmNow, payment_method_data: data, mandate_data: _mandate, ...rest } = params;
+  // a create's payment_method_data makes its method, as a confirm's does (payment-methods.ts methodFromData)
+  const made = await methodFromData(ctx, data);
+  if (made) rest.payment_method = made;
+  // the id is minted first so the client secret can carry it: Stripe.js parses the id back out
+  const id = typeof provided === 'string' && provided ? provided : ctx.mint(PI);
+  // it waits for a payment method until it has one, then for its confirmation (manifest.ts)
+  const hasMethod = typeof rest.payment_method === 'string' && rest.payment_method !== '';
+  if (hasMethod) ctx.legal(PI, 'status', 'PostPaymentIntents', 'requires_payment_method', 'requires_confirmation', id);
+  const body = await ctx.write(
+    PI,
+    id,
+    {
+      object: 'payment_intent',
+      created: nowUnix(ctx.occurredAt),
+      status: hasMethod ? 'requires_confirmation' : 'requires_payment_method',
+      client_secret: mintClientSecret(id, await ctx.secret(`client-secret:${id}`)),
+      livemode: false,
+      capture_method: 'automatic',
+      amount_capturable: 0,
+      amount_received: 0,
+      next_action: null,
+      automatic_payment_methods,
+      payment_method_types,
+      ...(Array.isArray(params.allowed_payment_method_types) ? { allowed_payment_method_types: payment_method_types } : {}),
+      payment_method_options: (params.payment_method_options as object) ?? {},
+      ...rest,
+    },
+    'payment_intent.create',
+  );
+  if (Array.isArray(given)) await ctx.record(TYPES_GIVEN, { payment_intent: id }, id);
+  if (asBool(confirmNow)) return confirmIntent(ctx, body, {});
+  return ctx.reply(ctx.expand(PI, body));
+}
+
+export async function PostPaymentIntentsIntentCancel(ctx: HandlerContext): Promise<Response> {
+  const loaded = paymentIntentsLoad(ctx, 'PostPaymentIntentsIntentCancel');
+  if ('answer' in loaded) return loaded.answer;
+  const cancellation_reason = typeof ctx.params.cancellation_reason === 'string' ? ctx.params.cancellation_reason : 'requested_by_customer';
+  // "For PaymentIntents with a `status` of `requires_capture`, the remaining `amount_capturable` is automatically
+  // refunded" (docs.stripe.com/api/payment_intents/cancel): the authorization is released (charges.ts)
+  const held = loaded.pi.status === 'requires_capture' && typeof loaded.pi.latest_charge === 'string' ? ctx.get('charge', loaded.pi.latest_charge) : undefined;
+  if (held && held.captured === false && held.refunded !== true) await cancelAuthorization(ctx, held);
+  return ctx.reply(ctx.expand(PI, await ctx.write(PI, String(loaded.pi.id), { status: 'canceled', cancellation_reason, amount_capturable: 0 }, 'payment_intent.canceled')));
+}
+
+export async function PostPaymentIntentsIntentConfirm(ctx: HandlerContext): Promise<Response> {
+  const loaded = paymentIntentsLoad(ctx, 'PostPaymentIntentsIntentConfirm');
+  if ('answer' in loaded) return loaded.answer;
+  const given = ctx.params;
+  const { expand: _e, payment_method_data: data, mandate_data: _mandate, ...params } = given;
+  // a confirm's payment_method_data makes the method it pays with; neither it nor mandate_data is a field of the intent
+  const made = await methodFromData(ctx, data);
+  return confirmIntent(ctx, loaded.pi, made ? { ...params, payment_method: made } : params);
+}
+

package/src/semantics/payment_methods.ts

@@ -0,0 +1,43 @@
+// Stripe's payment_methods operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import type { Row } from '../engine/common.ts';
+import { noBilling, PM } from '../engine/payment-methods.ts';
+import { declineFor, paymentMethodSubObject } from '../engine/stripe.ts';
+import { afterSuccessOf, at, attachable, attachPaymentMethod, created, fail, pmMissing } from './shared.ts';
+
+export async function GetPaymentMethodsPaymentMethod(ctx: HandlerContext): Promise<Response> {
+  const m = ctx.get(PM, at(ctx, 'payment_method'));
+  return m ? ctx.reply(m) : pmMissing(ctx, at(ctx, 'payment_method'));
+}
+
+// the raw card number, cvc and bank account number are never echoed: the modeled sub-object is
+// what the PaymentMethod carries, with the decline outcome its card implies, so a later charge
+// naming it only by id declines the same way
+export async function PostPaymentMethods(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  const pmType = typeof params.type === 'string' ? params.type : 'card';
+  const { card: _card, sepa_debit: _sepa, us_bank_account: _ach, type: _t, ...rest } = params;
+  const sub = paymentMethodSubObject(pmType, params);
+  const declineOutcome = pmType === 'card' ? (declineFor(() => undefined, params) ?? null) : null;
+  // and what Stripe does after its card succeeds (a dispute, a review), which a later charge naming it by id brings
+  const afterSuccess = pmType === 'card' ? afterSuccessOf(ctx, params.card) : undefined;
+  // the billing details the create gives are the method's (docs.stripe.com/api/payment_methods/create#create_payment_method-billing_details)
+  const given = rest.billing_details && typeof rest.billing_details === 'object' ? (rest.billing_details as Row) : {};
+  return ctx.reply(await created(ctx, PM, { ...rest, type: pmType, customer: null, livemode: false, billing_details: { ...noBilling, ...given }, ...sub, _declineOutcome: declineOutcome, ...(afterSuccess ? { _afterSuccess: afterSuccess } : {}) }, {}));
+}
+
+export async function PostPaymentMethodsPaymentMethodAttach(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'payment_method');
+  const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
+  if (!customer) return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
+  if (!ctx.get('customer', customer)) return fail(ctx, `No such customer: '${customer}'`, 400, 'resource_missing');
+  if (!attachable(ctx, id)) return pmMissing(ctx, id);
+  return ctx.reply(await attachPaymentMethod(ctx, id, customer));
+}
+
+export async function PostPaymentMethodsPaymentMethodDetach(ctx: HandlerContext): Promise<Response> {
+  const id = at(ctx, 'payment_method');
+  if (!ctx.get(PM, id)) return pmMissing(ctx, id);
+  return ctx.reply(await ctx.write(PM, id, { customer: null }, 'payment_method.detach'));
+}

package/src/semantics/payouts.ts

@@ -0,0 +1,23 @@
+// Stripe's payouts operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { inRange } from '../engine/common.ts';
+import { validateMoney } from '../engine/stripe.ts';
+import { account, asOf, at, created, fail, kept, list, newest, noExternalAccount, payoutBank, payoutDefaults, payoutMissing, refusePayout, send, settlePayout, where } from './shared.ts';
+
+export async function PostPayouts(ctx: HandlerContext): Promise<Response> {
+  const bad = validateMoney(ctx.params);
+  if (bad) return send(ctx, bad);
+  const acct = account(ctx);
+  if (acct && !ctx.get('account', acct)) return fail(ctx, `No such account: '${acct}'`, 400, 'account_invalid');
+  const amount = Math.trunc(Number(ctx.params.amount) || 0);
+  const currency = String(ctx.params.currency ?? 'usd');
+  // a connected account is paid out to its own bank account
+  if (acct && !ctx.rows('external_account').some((e) => e.account === acct && (e.currency ?? currency) === currency)) return noExternalAccount(ctx, currency);
+  const refused = refusePayout(ctx, amount, currency);
+  if (refused) return refused;
+  const id = ctx.mint('payout');
+  const bt = await settlePayout(ctx, id, -amount, currency);
+  return ctx.reply(await created(ctx, 'payout', { ...ctx.params, id }, { status: 'pending', ...payoutDefaults(ctx), balance_transaction: bt, destination: acct ? payoutBank(ctx, acct, currency) : null, ...(acct ? { _account: acct } : {}) }));
+}
+

package/src/semantics/prices.ts

@@ -0,0 +1,42 @@
+// Stripe's prices operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import type { Row } from '../engine/common.ts';
+import { asBool } from '../engine/stripe.ts';
+import { at, created, fail, list, newest, tieredPrice, where } from './shared.ts';
+
+// `type` is not stored (it collides with the tree's discriminator), so `recurring` stands for it
+export async function GetPrices(ctx: HandlerContext): Promise<Response> {
+  return list(ctx, 'price', where(ctx, newest(ctx, 'price'), {
+    active: (p, v) => asBool(p.active) === asBool(v),
+    product: (p, v) => p.product === v,
+    currency: (p, v) => p.currency === v,
+    type: (p, v) => (v === 'recurring' ? !!p.recurring : !p.recurring),
+    lookup_keys: (p, v) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String(p.lookup_key)),
+  }));
+}
+
+export async function GetPricesPrice(ctx: HandlerContext): Promise<Response> {
+  const p = ctx.get('price', at(ctx, 'price'));
+  return p ? ctx.reply(p) : fail(ctx, `No such price: '${at(ctx, 'price')}'`, 404, 'resource_missing');
+}
+
+export async function PostPrices(ctx: HandlerContext): Promise<Response> {
+  const params = ctx.params;
+  // the product must exist
+  const product = typeof params.product === 'string' ? params.product : '';
+  if (!product || !ctx.get('product', product)) return fail(ctx, `No such product: '${product}'`, 400, 'resource_missing');
+  // a tiered price needs tiers_mode and tiers, each tier with up_to and a unit or flat amount; it
+  // has no single unit_amount, and its last tier's up_to is null (∞)
+  const scheme = typeof params.billing_scheme === 'string' ? params.billing_scheme : 'per_unit';
+  if (scheme === 'tiered') return tieredPrice(ctx, params);
+  // a price that recurs is billed by subscriptions; any other is paid once. Its recurring block answers what the create
+  // left out as Stripe does: `usage_type` "Defaults to `licensed`", and the create example's answer
+  // (docs.stripe.com/api/prices/create) carries `"interval_count": 1, "trial_period_days": null`; a meter only a metered
+  // price names
+  if (params.recurring && typeof params.recurring === 'object') {
+    const r = params.recurring as Row;
+    params.recurring = { ...r, interval_count: r.interval_count !== undefined ? Math.trunc(Number(r.interval_count)) : 1, usage_type: r.usage_type ?? 'licensed', trial_period_days: r.trial_period_days !== undefined ? Math.trunc(Number(r.trial_period_days)) : null, meter: r.meter ?? null };
+  }
+  return ctx.reply(await created(ctx, 'price', params, { active: true, livemode: false, billing_scheme: 'per_unit', type: params.recurring ? 'recurring' : 'one_time', metadata: {} }));
+}

package/src/semantics/products.ts

@@ -1,154 +1,30 @@
-// Product and Price semantics, with the entitlement features granted to a product. Retrieve of a
-// product and the product and price updates (archiving and restoring by `active`, the machines in
-// ../manifest.ts) are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { asBool } from '../stripe-twin.ts';
-import { at, created, fail, kept, list, newest, where, type Row } from './shared.ts';
+// Stripe's products operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { asBool, nowUnix } from '../engine/stripe.ts';
+import { alreadyAttached, at, created, fail, search, featureMissing, kept, list, newest, pricedProductRefused, productFeature, productMissing, where } from './shared.ts';
 
-const productMissing = (ctx: SemanticsContext, id: string): Response => fail(ctx, `No such product: '${id}'`, 404, 'resource_missing');
-
-const createProduct: Semantics = async (ctx) =>
-  ctx.reply(await created(ctx, 'product', ctx.params, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: ctx.now() }));
-
-const listProducts: Semantics = async (ctx) =>
-  list(ctx, 'product', where(ctx, newest(ctx, 'product'), {
-    active: (p, v) => asBool(p.active) === asBool(v),
-    ids: (p, v) => (Array.isArray(v) ? v.map(String).includes(String(p.id)) : String(p.id) === String(v)),
-  }));
-
-// a product with prices cannot be deleted; Stripe says to deactivate it instead
-/** A product deleted while it has prices: "Deleting a product is only possible if it has no prices associated with it"
- *  (docs.stripe.com/api/products/delete). */
-function pricedProductRefused(ctx: SemanticsContext): Response {
-  return fail(ctx, 'You cannot delete the product because it has one or more prices. Deactivate the product instead.', 400, 'resource_already_exists');
-}
-
-const deleteProduct: Semantics = async (ctx) => {
+export async function DeleteProductsId(ctx: HandlerContext): Promise<Response> {
   const id = at(ctx, 'id');
   if (!ctx.get('product', id)) return productMissing(ctx, id);
   if (ctx.rows('price').some((p) => p.product === id)) return pricedProductRefused(ctx);
   await ctx.write('product', id, { deleted: true }, 'product.delete');
   return ctx.reply({ id, object: 'product', deleted: true });
-};
-
-// ── features: an entitlements feature granted to a product, at most once ──
-
-/** A feature attached to a product that already has it. */
-function alreadyAttached(ctx: SemanticsContext): Response {
-  return fail(ctx, 'This feature is already attached to the product.', 400, 'resource_already_exists');
-}
-
-const attachFeature: Semantics = async (ctx) => {
-  const product = at(ctx, 'product');
-  if (!ctx.get('product', product)) return productMissing(ctx, product);
-  const feature = typeof ctx.params.entitlement_feature === 'string' ? ctx.params.entitlement_feature : '';
-  if (!feature) return fail(ctx, 'Missing required param: entitlement_feature.', 400, 'parameter_missing');
-  const feat = ctx.get('entitlements_feature', feature);
-  if (!feat) return fail(ctx, `No such feature: '${feature}'`, 400, 'resource_missing');
-  if (ctx.rowsRaw('product_feature').some((pf) => pf._product === product && pf._feature === feature)) return alreadyAttached(ctx);
-  // Stripe answers the feature itself as the product feature's entitlement_feature (docs.stripe.com/api/product-feature/object)
-  return ctx.reply(
-    await created(ctx, 'product_feature', { _product: product, _feature: feature }, {
-      livemode: false,
-      entitlement_feature: { id: feature, object: 'entitlements.feature', name: feat.name, lookup_key: feat.lookup_key, active: feat.active, metadata: feat.metadata ?? {}, livemode: false },
-    }),
-  );
-};
-
-const features: Semantics = async (ctx) => {
-  const product = at(ctx, 'product');
-  if (!ctx.get('product', product)) return productMissing(ctx, product);
-  return list(ctx, 'product_feature', newest(ctx, 'product_feature').filter((pf) => kept(ctx, 'product_feature', pf, '_product') === product));
-};
-
-const productFeature = (ctx: SemanticsContext): Row | undefined => {
-  const pf = ctx.get('product_feature', at(ctx, 'id'));
-  // the product a feature is attached to is its address, not a field Stripe answers
-  return pf && kept(ctx, 'product_feature', pf, '_product') === at(ctx, 'product') ? pf : undefined;
-};
-const featureMissing = (ctx: SemanticsContext): Response => fail(ctx, `No such product feature: '${at(ctx, 'id')}'`, 404, 'resource_missing');
-
-const feature: Semantics = async (ctx) => {
-  const pf = productFeature(ctx);
-  return pf ? ctx.reply(pf) : featureMissing(ctx);
-};
-
-const detachFeature: Semantics = async (ctx) => {
-  if (!productFeature(ctx)) return featureMissing(ctx);
-  const id = at(ctx, 'id');
-  // when it came off the product: a subscription keeps it until its next period (semantics/entitlements.ts)
-  await ctx.write('product_feature', id, { deleted: true, _removed_at: Number(ctx.now()) }, 'product_feature.delete');
-  return ctx.reply({ id, object: 'product_feature', deleted: true });
-};
-
-// ── prices ──
-
-/** A tiered price: tiers_mode and tiers, each tier with up_to and a unit or flat amount; no single unit_amount, and
- *  the last tier's up_to null (∞) (docs.stripe.com/products-prices/pricing-models#tiered-pricing). */
-async function tieredPrice(ctx: SemanticsContext, params: Row): Promise<Response> {
-  const mode = typeof params.tiers_mode === 'string' ? params.tiers_mode : '';
-  if (mode !== 'graduated' && mode !== 'volume') return fail(ctx, 'Missing required param: tiers_mode (graduated or volume).', 400, 'parameter_missing');
-  const rawTiers = Array.isArray(params.tiers) ? (params.tiers as Row[]) : [];
-  if (rawTiers.length === 0) return fail(ctx, 'Missing required param: tiers.', 400, 'parameter_missing');
-  const tiers = rawTiers.map((t) => {
-    const upToRaw = t.up_to;
-    return {
-      up_to: upToRaw === 'inf' || upToRaw === undefined || upToRaw === null ? null : Math.trunc(Number(upToRaw)),
-      unit_amount: t.unit_amount !== undefined ? Math.trunc(Number(t.unit_amount)) : null,
-      unit_amount_decimal: t.unit_amount !== undefined ? String(Math.trunc(Number(t.unit_amount))) : null,
-      flat_amount: t.flat_amount !== undefined ? Math.trunc(Number(t.flat_amount)) : null,
-      flat_amount_decimal: t.flat_amount !== undefined ? String(Math.trunc(Number(t.flat_amount))) : null,
-    };
-  });
-  if (tiers.some((t) => t.unit_amount === null && t.flat_amount === null)) return fail(ctx, 'Each tier must specify a unit_amount or flat_amount.', 400, 'parameter_invalid_empty');
-  const { tiers: _t, ...rest } = params;
-  return ctx.reply(await created(ctx, 'price', { ...rest, billing_scheme: 'tiered', tiers_mode: mode, tiers, unit_amount: null }, { active: true, livemode: false, type: rest.recurring ? 'recurring' : 'one_time', metadata: {} }));
 }
 
-const createPrice: Semantics = async (ctx) => {
-  const params = ctx.params;
-  // the product must exist
-  const product = typeof params.product === 'string' ? params.product : '';
-  if (!product || !ctx.get('product', product)) return fail(ctx, `No such product: '${product}'`, 400, 'resource_missing');
-  // a tiered price needs tiers_mode and tiers, each tier with up_to and a unit or flat amount; it
-  // has no single unit_amount, and its last tier's up_to is null (∞)
-  const scheme = typeof params.billing_scheme === 'string' ? params.billing_scheme : 'per_unit';
-  if (scheme === 'tiered') return tieredPrice(ctx, params);
-  // a price that recurs is billed by subscriptions; any other is paid once. Its recurring block answers what the create
-  // left out as Stripe does: `usage_type` "Defaults to `licensed`", and the create example's answer
-  // (docs.stripe.com/api/prices/create) carries `"interval_count": 1, "trial_period_days": null`; a meter only a metered
-  // price names
-  if (params.recurring && typeof params.recurring === 'object') {
-    const r = params.recurring as Row;
-    params.recurring = { ...r, interval_count: r.interval_count !== undefined ? Math.trunc(Number(r.interval_count)) : 1, usage_type: r.usage_type ?? 'licensed', trial_period_days: r.trial_period_days !== undefined ? Math.trunc(Number(r.trial_period_days)) : null, meter: r.meter ?? null };
-  }
-  return ctx.reply(await created(ctx, 'price', params, { active: true, livemode: false, billing_scheme: 'per_unit', type: params.recurring ? 'recurring' : 'one_time', metadata: {} }));
-};
-
-// `type` is not stored (it collides with the tree's discriminator), so `recurring` stands for it
-const listPrices: Semantics = async (ctx) =>
-  list(ctx, 'price', where(ctx, newest(ctx, 'price'), {
+export async function GetProducts(ctx: HandlerContext): Promise<Response> {
+  return list(ctx, 'product', where(ctx, newest(ctx, 'product'), {
     active: (p, v) => asBool(p.active) === asBool(v),
-    product: (p, v) => p.product === v,
-    currency: (p, v) => p.currency === v,
-    type: (p, v) => (v === 'recurring' ? !!p.recurring : !p.recurring),
-    lookup_keys: (p, v) => (Array.isArray(v) ? v.map(String) : [String(v)]).includes(String(p.lookup_key)),
+    ids: (p, v) => (Array.isArray(v) ? v.map(String).includes(String(p.id)) : String(p.id) === String(v)),
   }));
+}
 
-const retrievePrice: Semantics = async (ctx) => {
-  const p = ctx.get('price', at(ctx, 'price'));
-  return p ? ctx.reply(p) : fail(ctx, `No such price: '${at(ctx, 'price')}'`, 404, 'resource_missing');
-};
+export async function PostProducts(ctx: HandlerContext): Promise<Response> {
+  return ctx.reply(await created(ctx, 'product', ctx.params, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: nowUnix(ctx.occurredAt) }));
+}
 
-export const products: Record<string, Semantics> = {
-  PostProducts: createProduct,
-  GetProducts: listProducts,
-  DeleteProductsId: deleteProduct,
-  PostProductsProductFeatures: attachFeature,
-  GetProductsProductFeatures: features,
-  GetProductsProductFeaturesId: feature,
-  DeleteProductsProductFeaturesId: detachFeature,
-  PostPrices: createPrice,
-  GetPrices: listPrices,
-  GetPricesPrice: retrievePrice,
-};
+/** `GET /v1/products/search?query=`: the products Stripe's search language selects (Ponder's catalog probes). */
+// source: spec:GetProductsSearch "Search for products you’ve previously created using Stripe’s"
+export async function GetProductsSearch(ctx: HandlerContext): Promise<Response> {
+  return search(ctx, 'product');
+}

package/src/semantics/promotion_codes.ts

@@ -0,0 +1,39 @@
+// Stripe's promotion_codes operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { asBool } from '../engine/stripe.ts';
+import { created, fail, list, newest, where } from './shared.ts';
+
+export async function GetPromotionCodes(ctx: HandlerContext): Promise<Response> {
+  return list(ctx, 'promotion_code', where(ctx, newest(ctx, 'promotion_code'), {
+    code: (p, v) => p.code === v,
+    active: (p, v) => asBool(p.active) === asBool(v),
+    coupon: (p, v) => p.coupon === v,
+    customer: (p, v) => p.customer === v,
+  }));
+}
+
+// a code the caller does not give is derived from the promotion code's id
+export async function PostPromotionCodes(ctx: HandlerContext): Promise<Response> {
+  // what it promotes: promotion[type]=coupon and promotion[coupon] (2025-09-30.clover,
+  // docs.stripe.com/changelog/clover/2025-09-30/polymorphic-coupon), or the top-level coupon a caller pinned to an
+  // earlier version sends; the twin keeps the coupon's id on the code for its rules
+  const given = ctx.params;
+  const { promotion, coupon: legacy, ...params } = given;
+  const promo = promotion && typeof promotion === 'object' ? (promotion as Record<string, unknown>) : undefined;
+  if (promo && promo.type !== 'coupon') return fail(ctx, 'Invalid promotion[type]: must be coupon.', 400, 'parameter_invalid_string_enum');
+  const coupon = typeof promo?.coupon === 'string' ? promo.coupon : typeof legacy === 'string' ? legacy : '';
+  if (!coupon) return fail(ctx, promo ? 'Missing required param: promotion[coupon].' : 'Missing required param: promotion.', 400, 'parameter_missing');
+  if (!ctx.get('coupon', coupon)) return fail(ctx, `No such coupon: '${coupon}'`, 400, 'resource_missing');
+  const id = ctx.mint('promotion_code');
+  const code = typeof params.code === 'string' && params.code ? params.code : `TWIN${id.toUpperCase().replace(/[^A-Z0-9]/g, '')}`;
+  return ctx.reply(
+    await created(ctx, 'promotion_code', { ...params, coupon, promotion: { type: 'coupon', coupon }, id, code }, {
+      active: params.active !== undefined ? asBool(params.active) : true,
+      customer: typeof params.customer === 'string' ? params.customer : null,
+      expires_at: params.expires_at !== undefined ? Number(params.expires_at) : null,
+      max_redemptions: params.max_redemptions !== undefined ? Number(params.max_redemptions) : null,
+      times_redeemed: 0, livemode: false, metadata: {}, restrictions: { first_time_transaction: false, minimum_amount: null, minimum_amount_currency: null },
+    }),
+  );
+}

package/src/semantics/radar.ts

@@ -1,85 +1,16 @@
-// Radar semantics: reviews of payments Radar held (approving closes one, the machine in
-// ../manifest.ts) and the value lists custom rules reference, with their items. Review list and
-// retrieve, value-list list and retrieve, and value-list-item retrieve are the derived core's.
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { at, created, fail, list, newest } from './shared.ts';
+// Stripe's radar operations (docs/contributing/architecture.md, "What an author writes"): each handler over the
+// handler contract's context, computing with the engine (../engine/).
+import type { HandlerContext } from '@volter/world-core';
+import { VL, VLI } from '../engine/radar.ts';
+import { at, created, fail, list, listMissing, newest, radarSyncItems } from './shared.ts';
 
-const approve: Semantics = async (ctx) => {
-  const id = at(ctx, 'review');
-  const r = ctx.get('review', id);
-  if (!r) return fail(ctx, `No such review: '${id}'`, 404, 'resource_missing');
-  const refused = ctx.legal('review', 'open', 'PostReviewsReviewApprove', r.open === true, undefined, id);
-  if (refused) return ctx.refuse(refused);
-  return ctx.reply(await ctx.write('review', id, { open: false, closed_reason: 'approved', reason: 'approved' }, 'review.closed'));
-};
-
-const VL = 'radar.value_list';
-const VLI = 'radar.value_list_item';
-const listMissing = (ctx: SemanticsContext, id: string, status = 404): Response => fail(ctx, `No such radar value list: '${id}'`, status, 'resource_missing');
-
-const createList: Semantics = async (ctx) => {
-  const params = ctx.params;
-  if (params.alias === undefined || params.alias === '') return fail(ctx, 'Missing required param: alias.', 400, 'parameter_missing');
-  if (params.name === undefined || params.name === '') return fail(ctx, 'Missing required param: name.', 400, 'parameter_missing');
-  const made = await created(ctx, VL, params, {
-    item_type: typeof params.item_type === 'string' ? params.item_type : 'string', livemode: false, metadata: {},
-    created_by: 'twin', list_items: { object: 'list', data: [], has_more: false, url: '' },
-  });
-  await syncItems(ctx, String(made.id));
-  return ctx.reply(ctx.get(VL, String(made.id))!);
-};
-
-/** A value list's list_items, "List of items contained within this value list" (the served spec), kept in step with
- *  its items, at the address the fixture names (/v1/radar/value_list_items?value_list=…). */
-async function syncItems(ctx: SemanticsContext, listId: string): Promise<void> {
-  const data = newest(ctx, VLI).filter((i) => i.value_list === listId);
-  await ctx.write(VL, listId, { list_items: { object: 'list', data, has_more: false, url: `/v1/radar/value_list_items?value_list=${listId}` } }, 'radar.value_list.items_synced');
-}
-
-const updateList: Semantics = async (ctx) => {
-  const id = at(ctx, 'value_list');
-  if (!ctx.row(VL, id, { withDeleted: true })) return listMissing(ctx, id);
-  return ctx.reply(await ctx.write(VL, id, ctx.params, 'radar.value_list.updated'));
-};
-
-const deleteList: Semantics = async (ctx) => {
-  const id = at(ctx, 'value_list');
-  if (!ctx.row(VL, id, { withDeleted: true })) return listMissing(ctx, id);
-  await ctx.write(VL, id, { deleted: true }, 'radar.value_list.deleted');
-  return ctx.reply({ id, object: 'radar.value_list', deleted: true });
-};
-
-const addItem: Semantics = async (ctx) => {
+export async function PostRadarValueListItems(ctx: HandlerContext): Promise<Response> {
   const listId = typeof ctx.params.value_list === 'string' ? ctx.params.value_list : '';
   if (!listId) return fail(ctx, 'Missing required param: value_list.', 400, 'parameter_missing');
   if (!ctx.row(VL, listId, { withDeleted: true })) return listMissing(ctx, listId, 400);
   if (ctx.params.value === undefined || ctx.params.value === '') return fail(ctx, 'Missing required param: value.', 400, 'parameter_missing');
   const item = await created(ctx, VLI, { value_list: listId, value: ctx.params.value }, { livemode: false, created_by: 'twin' });
-  await syncItems(ctx, listId);
+  await radarSyncItems(ctx, listId);
   return ctx.reply(item);
-};
-
-const items: Semantics = async (ctx) => {
-  const listId = typeof ctx.params.value_list === 'string' ? ctx.params.value_list : '';
-  if (!listId) return fail(ctx, 'Missing required param: value_list.', 400, 'parameter_missing');
-  return list(ctx, VLI, newest(ctx, VLI).filter((i) => i.value_list === listId));
-};
-
-const removeItem: Semantics = async (ctx) => {
-  const id = at(ctx, 'item');
-  const was = ctx.row(VLI, id, { withDeleted: true });
-  if (!was) return fail(ctx, `No such radar value list item: '${id}'`, 404, 'resource_missing');
-  await ctx.write(VLI, id, { deleted: true }, 'radar.value_list_item.deleted');
-  if (typeof was.value_list === 'string' && ctx.get(VL, was.value_list)) await syncItems(ctx, was.value_list);
-  return ctx.reply({ id, object: 'radar.value_list_item', deleted: true });
-};
+}
 
-export const radar: Record<string, Semantics> = {
-  PostReviewsReviewApprove: approve,
-  PostRadarValueLists: createList,
-  PostRadarValueListsValueList: updateList,
-  DeleteRadarValueListsValueList: deleteList,
-  PostRadarValueListItems: addItem,
-  GetRadarValueListItems: items,
-  DeleteRadarValueListItemsItem: removeItem,
-};