@volter/twin-stripe 2.0.38 → 3.0.0

package/dist/src/semantics/payment_intents.js

@@ -0,0 +1,79 @@
+import { PI, TYPES_GIVEN } from "../engine/payment-intents.js";
+import { asBool, mintClientSecret, nowUnix, validateMoney } from "../engine/stripe.js";
+import { cancelAuthorization, confirmIntent, confirmOnly, methodFromData, paymentIntentsLoad, paymentIntentsSend } from "./shared.js";
+export async function PostPaymentIntents(ctx) {
+    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.enabled) : false;
+    const automatic_payment_methods = apmEnabled ? { enabled: true, allow_redirects: apmIn.allow_redirects ?? '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 ?? {},
+        ...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) {
+    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) {
+    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/dist/src/semantics/payment_methods.d.ts

@@ -0,0 +1,5 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetPaymentMethodsPaymentMethod(ctx: HandlerContext): Promise<Response>;
+export declare function PostPaymentMethods(ctx: HandlerContext): Promise<Response>;
+export declare function PostPaymentMethodsPaymentMethodAttach(ctx: HandlerContext): Promise<Response>;
+export declare function PostPaymentMethodsPaymentMethodDetach(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/payment_methods.js

@@ -0,0 +1,39 @@
+import { noBilling, PM } from "../engine/payment-methods.js";
+import { declineFor, paymentMethodSubObject } from "../engine/stripe.js";
+import { afterSuccessOf, at, attachable, attachPaymentMethod, created, fail, pmMissing } from "./shared.js";
+export async function GetPaymentMethodsPaymentMethod(ctx) {
+    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) {
+    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 : {};
+    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) {
+    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) {
+    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/dist/src/semantics/payouts.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function PostPayouts(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/payouts.js

@@ -0,0 +1,21 @@
+import { validateMoney } from "../engine/stripe.js";
+import { account, created, fail, noExternalAccount, payoutBank, payoutDefaults, refusePayout, send, settlePayout } from "./shared.js";
+export async function PostPayouts(ctx) {
+    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/dist/src/semantics/prices.d.ts

@@ -0,0 +1,4 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetPrices(ctx: HandlerContext): Promise<Response>;
+export declare function GetPricesPrice(ctx: HandlerContext): Promise<Response>;
+export declare function PostPrices(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/prices.js

@@ -0,0 +1,37 @@
+import { asBool } from "../engine/stripe.js";
+import { at, created, fail, list, newest, tieredPrice, where } from "./shared.js";
+// `type` is not stored (it collides with the tree's discriminator), so `recurring` stands for it
+export async function GetPrices(ctx) {
+    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) {
+    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) {
+    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;
+        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/dist/src/semantics/products.d.ts

@@ -1,2 +1,6 @@
-import type { Semantics } from '@volter/world-core';
-export declare const products: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function DeleteProductsId(ctx: HandlerContext): Promise<Response>;
+export declare function GetProducts(ctx: HandlerContext): Promise<Response>;
+export declare function PostProducts(ctx: HandlerContext): Promise<Response>;
+/** `GET /v1/products/search?query=`: the products Stripe's search language selects (Ponder's catalog probes). */
+export declare function GetProductsSearch(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/products.js

@@ -1,18 +1,6 @@
-import { asBool } from "../stripe-twin.js";
-import { at, created, fail, kept, list, newest, where } from "./shared.js";
-const productMissing = (ctx, id) => fail(ctx, `No such product: '${id}'`, 404, 'resource_missing');
-const createProduct = async (ctx) => ctx.reply(await created(ctx, 'product', ctx.params, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: ctx.now() }));
-const listProducts = 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) {
-    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 = async (ctx) => {
+import { asBool, nowUnix } from "../engine/stripe.js";
+import { at, created, search, list, newest, pricedProductRefused, productMissing, where } from "./shared.js";
+export async function DeleteProductsId(ctx) {
     const id = at(ctx, 'id');
     if (!ctx.get('product', id))
         return productMissing(ctx, id);
@@ -20,121 +8,18 @@ const deleteProduct = async (ctx) => {
         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) {
-    return fail(ctx, 'This feature is already attached to the product.', 400, 'resource_already_exists');
 }
-const attachFeature = 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 },
+export async function GetProducts(ctx) {
+    return 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)),
     }));
-};
-const features = 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) => {
-    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) => fail(ctx, `No such product feature: '${at(ctx, 'id')}'`, 404, 'resource_missing');
-const feature = async (ctx) => {
-    const pf = productFeature(ctx);
-    return pf ? ctx.reply(pf) : featureMissing(ctx);
-};
-const detachFeature = 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, params) {
-    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 : [];
-    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 = 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;
-        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 = async (ctx) => 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)),
-}));
-const retrievePrice = 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 const products = {
-    PostProducts: createProduct,
-    GetProducts: listProducts,
-    DeleteProductsId: deleteProduct,
-    PostProductsProductFeatures: attachFeature,
-    GetProductsProductFeatures: features,
-    GetProductsProductFeaturesId: feature,
-    DeleteProductsProductFeaturesId: detachFeature,
-    PostPrices: createPrice,
-    GetPrices: listPrices,
-    GetPricesPrice: retrievePrice,
-};
+export async function PostProducts(ctx) {
+    return ctx.reply(await created(ctx, 'product', ctx.params, { active: true, livemode: false, images: [], marketing_features: [], metadata: {}, updated: nowUnix(ctx.occurredAt) }));
+}
+/** `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) {
+    return search(ctx, 'product');
+}

package/dist/src/semantics/promotion_codes.d.ts

@@ -0,0 +1,3 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetPromotionCodes(ctx: HandlerContext): Promise<Response>;
+export declare function PostPromotionCodes(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/promotion_codes.js

@@ -0,0 +1,35 @@
+import { asBool } from "../engine/stripe.js";
+import { created, fail, list, newest, where } from "./shared.js";
+export async function GetPromotionCodes(ctx) {
+    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) {
+    // 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 : 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/dist/src/semantics/radar.d.ts

@@ -1,2 +1,2 @@
-import type { Semantics } from '@volter/world-core';
-export declare const radar: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function PostRadarValueListItems(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/radar.js

@@ -1,50 +1,6 @@
-import { at, created, fail, list, newest } from "./shared.js";
-const approve = 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, id, status = 404) => fail(ctx, `No such radar value list: '${id}'`, status, 'resource_missing');
-const createList = 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, listId) {
-    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 = 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 = 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 = async (ctx) => {
+import { VL, VLI } from "../engine/radar.js";
+import { created, fail, listMissing, radarSyncItems } from "./shared.js";
+export async function PostRadarValueListItems(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');
@@ -53,31 +9,6 @@ const addItem = async (ctx) => {
     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 = 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 = 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 = {
-    PostReviewsReviewApprove: approve,
-    PostRadarValueLists: createList,
-    PostRadarValueListsValueList: updateList,
-    DeleteRadarValueListsValueList: deleteList,
-    PostRadarValueListItems: addItem,
-    GetRadarValueListItems: items,
-    DeleteRadarValueListItemsItem: removeItem,
-};
+}

package/dist/src/semantics/refunds.d.ts

@@ -1,9 +1,3 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-export declare function refundCharge(ctx: SemanticsContext, charge: Row, params: Row): Promise<Response>;
-/** Time's settling of held refunds, caught up to the World's clock: each refund held for want of balance, oldest first,
- *  is made at the first moment the account's available balance covers it (the funds that come due then), its debit
- *  written then, as `refund.updated`. Where the documentation stops and the twin decides: a held refund is made the
- *  moment the balance covers it. */
-export declare function settleHeldRefunds(ctx: SemanticsContext): Promise<void>;
-export declare const refunds: Record<string, Semantics>;
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetRefundsRefund(ctx: HandlerContext): Promise<Response>;
+export declare function PostRefunds(ctx: HandlerContext): Promise<Response>;