@volter/twin-stripe 3.0.0 → 3.0.1

package/dist/src/semantics/invoices.js

@@ -1,29 +1,75 @@
-import { collectsThroughIntent, draft, INV, linesOf, prorationLines, sumLines, transitions } from "../engine/invoices.js";
-import { addBillingInterval, applyCouponDiscount, asBool, cardError, declineFor, nowUnix, paginate, priceAmount, subscriptionItemPairs } from "../engine/stripe.js";
-import { activatedByPayment, at, created, expanded, fail, finalizedFields, finder, invoiceMissing, invoicesLoad, mintCharge, newest, nothingToPayWith, openPaymentIntent, path, pullPendingItem, send, spendOnceCoupon } from "./shared.js";
-// only a draft is deleted; a finalized invoice is voided instead
-export async function DeleteInvoicesInvoice(ctx) {
-    const loaded = invoicesLoad(ctx, 'DeleteInvoicesInvoice');
-    if ('answer' in loaded)
-        return loaded.answer;
-    const id = String(loaded.inv.id);
-    await ctx.write(INV, id, { deleted: true }, 'invoice.deleted');
-    return ctx.reply({ id, object: 'invoice', deleted: true });
-}
+import { INV, transitions } from "../engine/invoices.js";
+import { asBool, cardError, declineFor, nowUnix } from "../engine/stripe.js";
+import { resourceView, activatedByPayment, at, expanded, finalizeForPayment, finder, invoiceMissing, invoicesLoad, mintCharge, nothingToPayWith, send } from "./shared.js";
+import { draft, prorationLines, sumLines } from "../engine/invoices.js";
+import { addBillingInterval, applyCouponDiscount, priceAmount } from "../engine/stripe.js";
+import { created, fail, newest, pendingPreviewLines, pullPendingItem } from "./shared.js";
 export async function GetInvoicesInvoice(ctx) {
     const id = at(ctx, 'invoice');
     const inv = ctx.get(INV, id);
     return inv ? ctx.reply(expanded(ctx, INV, inv)) : invoiceMissing(ctx, id);
 }
-// the invoice's lines, a page at a time
-export async function GetInvoicesInvoiceLines(ctx) {
+// paying charges a payment method (the one passed, the invoice's default, or the customer's) unless
+// the payment is recorded out of band; a declining card answers 402 and leaves the invoice open. A
+// paid invoice settles the PaymentIntent finalize opened, and names the charge that took the money.
+export async function PostInvoicesInvoicePay(ctx) {
     const id = at(ctx, 'invoice');
-    const inv = ctx.get(INV, id);
-    if (!inv)
+    const found = ctx.get(INV, id);
+    if (!found)
         return invoiceMissing(ctx, id);
-    const { page, hasMore } = paginate(linesOf(inv), ctx.params);
-    return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page.map((l) => ({ invoice: id, ...l })) });
+    const refused = ctx.legal(INV, 'status', 'PostInvoicesInvoicePay', found.status, undefined, id);
+    if (refused)
+        return ctx.refuse(refused);
+    // paying a draft finalizes it first, as its finalize does (its number, and the PaymentIntent it collects through)
+    // source: https://docs.stripe.com/invoicing/integration "To finalize a draft invoice, use the Dashboard, send it to the customer, or pay it."
+    const inv = found.status === 'draft' ? await finalizeForPayment(ctx, found, id) : found;
+    const params = ctx.params;
+    const paidOutOfBand = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
+    const payer = ctx.get('customer', String(inv.customer ?? ''));
+    const customerDefault = payer?.invoice_settings?.default_payment_method || payer?.default_source;
+    if (!paidOutOfBand && !params.payment_method && !params.source && !inv.default_payment_method && !inv.default_source && !customerDefault)
+        return nothingToPayWith(ctx);
+    // what it charges: the method passed, else the invoice's default, its subscription's, then its customer's
+    // (docs.stripe.com/api/invoices/pay#pay_invoice-payment_method)
+    const subscription = typeof inv.subscription === 'string' ? resourceView(ctx, 'subscription', inv.subscription) : undefined;
+    const decline = declineFor(finder(ctx), params, { payment_method: inv.default_payment_method ?? subscription?.default_payment_method ?? customerDefault });
+    const intent = typeof inv.payment_intent === 'string' ? ctx.get('payment_intent', inv.payment_intent) : undefined;
+    if (decline)
+        return send(ctx, cardError(decline, intent ? { payment_intent: intent } : {}));
+    const amountPaid = Number(inv.total ?? inv.amount_due) || 0;
+    let body = await ctx.write(INV, id, {
+        // paid outside Stripe, the invoice counts it as such: `amount_paid_off_stripe`, "Amount, in cents (or local
+        // equivalent), that was paid on the invoice outside of Stripe" (served spec, invoice), the only place the served
+        // version shows it now that basil renders no `paid_out_of_band` (../engine/version.ts)
+        status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
+        ...(paidOutOfBand ? { amount_paid_off_stripe: amountPaid } : {}),
+        status_transitions: { ...transitions(inv), paid_at: nowUnix(ctx.occurredAt) },
+    }, 'invoice.pay');
+    if (!paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {
+        const pi = ctx.get('payment_intent', inv.payment_intent);
+        if (pi && pi.status !== 'succeeded' && !ctx.legal('payment_intent', 'status', 'PostInvoicesInvoicePay', pi.status)) {
+            const chargeId = await mintCharge(ctx, inv.payment_intent, { ...pi, invoice: id, ...(typeof params.payment_method === 'string' ? { payment_method: params.payment_method } : {}) }, amountPaid);
+            await ctx.write('payment_intent', inv.payment_intent, { status: 'succeeded', amount_received: amountPaid, amount_capturable: 0, next_action: null, latest_charge: chargeId }, 'payment_intent.succeeded');
+            body = await ctx.write(INV, id, { charge: chargeId }, 'invoice.update');
+        }
+    }
+    // a subscription waiting on this invoice (incomplete on its first, past_due on a failed renewal) is active once it is paid
+    const subId = typeof inv.subscription === 'string' ? inv.subscription : undefined;
+    const sub = subId ? resourceView(ctx, 'subscription', subId) : undefined;
+    if (subId && sub && (sub.status === 'incomplete' || sub.status === 'past_due') && !ctx.legal('subscription', 'status', 'PostInvoicesInvoicePay', sub.status, 'active', subId))
+        await activatedByPayment(ctx, subId);
+    return ctx.reply(expanded(ctx, INV, ctx.get(INV, id) ?? body));
 }
+// sending a draft finalizes it; any other invoice keeps its status and records the send
+export async function PostInvoicesInvoiceVoid(ctx) {
+    const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceVoid');
+    if ('answer' in loaded)
+        return loaded.answer;
+    const inv = loaded.inv;
+    const body = await ctx.write(INV, String(inv.id), { status: 'void', status_transitions: { ...transitions(inv), voided_at: nowUnix(ctx.occurredAt) } }, 'invoice.void');
+    return ctx.reply(expanded(ctx, INV, body));
+}
+// the invoice's lines, a page at a time
 // a new invoice pulls in the customer's pending items only when asked: pending_invoice_items_behavior "Defaults to
 // `exclude` if the parameter is omitted" (docs.stripe.com/api/invoices/create)
 export async function PostInvoices(ctx) {
@@ -51,18 +97,16 @@ export async function PostInvoices(ctx) {
 /**
  * A preview of the next invoice for a customer or subscription (create_preview), computed and never
  * stored: the subscription's items at their prices, the customer's pending items, the subscription's
- * discount, and with `subscription_details.proration_date` a credit for the unused period against a
- * charge for the new one (split evenly: there is no clock here to measure the remaining fraction).
+ * discount, and an update's unused-time credit and remaining-time charge at the old and new prices.
  */
 export async function PostInvoicesCreatePreview(ctx) {
     const params = ctx.params;
-    const prorationDate = params.subscription_details?.proration_date;
     const now = Number(nowUnix(ctx.occurredAt));
     let subId = typeof params.subscription === 'string' ? params.subscription : '';
     let customer = typeof params.customer === 'string' ? params.customer : '';
     let sub;
     if (subId) {
-        sub = ctx.get('subscription', subId);
+        sub = resourceView(ctx, 'subscription', subId);
         if (!sub)
             return fail(ctx, `No such subscription: '${subId}'`, 404, 'resource_missing');
         customer = customer || String(sub.customer ?? '');
@@ -80,17 +124,58 @@ export async function PostInvoicesCreatePreview(ctx) {
     // the upcoming invoice bills the subscription's next period, its "subscription renewal charges"
     // (docs.stripe.com/api/invoices/create_preview): from the current period's end, one billing interval long
     const renewsAt = sub && Number(sub.current_period_end) > 0 ? Number(sub.current_period_end) : now;
-    const itemRows = sub ? ctx.rows('subscription_item').filter((r) => r.subscription === subId) : [];
+    let itemRows = sub ? ctx.rows('subscription_item').filter((r) => r.subscription === subId) : [];
+    const details = params.subscription_details;
+    const previousItems = itemRows;
+    // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "The default value is"
+    const behavior = details?.proration_behavior ?? 'create_prorations';
+    // source: https://docs.stripe.com/billing/subscriptions/prorations "The prorated amount is calculated as soon as the API updates the subscription."
+    // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "forces the proration to be calculated as though the update was done at the specified time."
+    const prorationTime = details?.proration_date === undefined ? now : Number(details.proration_date);
+    const periodStart = Number(sub?.current_period_start ?? now);
+    const periodEnd = Number(sub?.current_period_end ?? now);
+    // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "The time given must be within the current subscription period"
+    // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "cannot be set to"
+    if (details?.proration_date !== undefined && (behavior === 'none' || !sub || !Array.isArray(details.items) || prorationTime < periodStart || prorationTime > periodEnd))
+        return fail(ctx, 'Invalid subscription_details[proration_date] for this subscription preview.', 400, 'parameter_invalid_integer');
+    // source: spec:/paths/~1v1~1invoices~1create_preview/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/subscription_details/description "The subscription creation or modification params to apply as a preview."
+    // Preview changes are local to this calculation: the subscription and its stored items are never changed.
+    if (Array.isArray(details?.items)) {
+        itemRows = itemRows.map(item => ({ ...item }));
+        for (const change of details.items) {
+            const index = change.id ? itemRows.findIndex(item => item.id === change.id) : -1;
+            if (change.id && index < 0)
+                return fail(ctx, `No such subscription_item: '${change.id}'`, 400, 'resource_missing');
+            if (asBool(change.deleted)) {
+                if (index >= 0)
+                    itemRows.splice(index, 1);
+                continue;
+            }
+            const previous = index >= 0 ? itemRows[index] : {};
+            const priceId = typeof change.price === 'string' ? change.price : typeof previous.price === 'string' ? previous.price : previous.price?.id;
+            const price = typeof priceId === 'string' ? ctx.get('price', priceId) : undefined;
+            if (!price)
+                return fail(ctx, `No such price: '${priceId ?? ''}'`, 400, 'resource_missing');
+            const quantity = change.quantity === undefined ? Number(previous.quantity ?? 1) : Number(change.quantity);
+            const previewItem = { ...previous, price, quantity };
+            if (index >= 0)
+                itemRows[index] = previewItem;
+            else
+                itemRows.push(previewItem);
+        }
+    }
     const out = [];
     let subtotal = 0;
     let period = now + 30 * 24 * 3600;
     if (sub) {
-        for (const { price: priceId, quantity } of subscriptionItemPairs(sub)) {
+        for (const previewItem of itemRows) {
+            const priceId = typeof previewItem.price === 'string' ? previewItem.price : String(previewItem.price?.id ?? '');
+            const quantity = Number(previewItem.quantity) || 0;
             const price = ctx.get('price', priceId);
             const amount = priceAmount(price, quantity);
             const recurring = price?.recurring ?? {};
             period = recurring.interval ? addBillingInterval(renewsAt, recurring.interval, Number(recurring.interval_count) || 1) : period;
-            const item = itemRows.find((r) => (typeof r.price === 'string' ? r.price : r.price?.id) === priceId);
+            const item = previewItem;
             subtotal += amount;
             out.push({
                 id: `il_twin_${priceId}`, object: 'line_item', type: 'subscription', amount, currency,
@@ -98,19 +183,32 @@ export async function PostInvoicesCreatePreview(ctx) {
                 period: { start: renewsAt, end: period }, description: `${quantity} × ${price?.nickname ?? priceId}`,
             });
         }
-        if (prorationDate !== undefined && subtotal > 0)
-            prorationLines(out, subtotal, currency, now, period);
-    }
-    for (const ii of newest(ctx, 'invoiceitem', 'date')) {
-        if (ii.customer !== customer || ii.invoice)
-            continue;
-        out.push({ id: `il_${String(ii.id)}`, object: 'line_item', type: 'invoiceitem', amount: Number(ii.amount) || 0, currency, quantity: Number(ii.quantity) || 1, proration: false, invoice_item: ii.id, period: ii.period ?? { start: now, end: now }, description: ii.description ?? null });
     }
-    subtotal = sumLines(out);
     const subDiscount = Array.isArray(sub?.discounts) && sub.discounts.length ? sub.discounts[0] : undefined;
     const coupon = subDiscount && typeof subDiscount.coupon === 'object' ? subDiscount.coupon : undefined;
-    const discountAmount = applyCouponDiscount(Math.max(0, subtotal), coupon);
-    const total = Math.max(0, subtotal - discountAmount);
+    // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "Disable creating prorations in this request."
+    // source: https://docs.stripe.com/billing/subscriptions/prorations "creates a non-proration debit, even when the debit covers a partial billing period."
+    if (sub && Array.isArray(details?.items) && behavior !== 'none' && sub.status !== 'trialing') {
+        const before = previousItems.map(item => {
+            const priceId = typeof item.price === 'string' ? item.price : String(item.price.id);
+            const price = ctx.get('price', priceId);
+            return { id: `il_twin_${priceId}`, object: 'line_item', type: 'subscription', amount: priceAmount(price, Number(item.quantity ?? 1)), currency,
+                price: price ?? priceId, quantity: Number(item.quantity ?? 1), subscription: subId, subscription_item: item.id,
+                period: { start: item.current_period_start ?? periodStart, end: item.current_period_end ?? periodEnd } };
+        });
+        const after = out.map(line => ({ ...line, period: { start: periodStart, end: periodEnd } }));
+        const prorations = prorationLines(before, after, prorationTime, periodStart, periodEnd, coupon);
+        // source: https://docs.stripe.com/api/invoices/create_preview.md?query=subscription_details "Always invoice immediately for prorations."
+        if (behavior === 'always_invoice' && prorations.length)
+            out.splice(0, out.length, ...prorations);
+        else
+            out.unshift(...prorations);
+    }
+    out.push(...pendingPreviewLines(ctx, customer, currency, now));
+    subtotal = sumLines(out);
+    // source: https://docs.stripe.com/billing/subscriptions/prorations "no additional discounts are applied to the proration line items themselves"
+    const discountAmount = applyCouponDiscount(Math.max(0, sumLines(out.filter(line => !line.proration))), coupon);
+    const total = subtotal - discountAmount;
     return ctx.reply({
         ...draft(now),
         // "For preview invoices created using the create preview endpoint, this id will be prefixed with `upcoming_in`"
@@ -119,101 +217,10 @@ export async function PostInvoicesCreatePreview(ctx) {
         object: 'invoice', id: `upcoming_${ctx.mint(INV)}`, customer, subscription: subId || null, currency,
         billing_reason: subId ? 'upcoming' : 'manual',
         created: now, period_start: now, period_end: period,
-        subtotal, total, amount_due: total, amount_paid: 0, amount_remaining: total,
+        subtotal, total, amount_due: Math.max(0, total), amount_paid: 0, amount_remaining: Math.max(0, total),
         starting_balance: 0, ending_balance: null,
         discounts: discountAmount > 0 && subDiscount ? [subDiscount] : [],
         total_discount_amounts: discountAmount > 0 ? [{ amount: discountAmount, discount: subDiscount?.id ?? null }] : [],
         lines: { object: 'list', url: '/v1/invoices/create_preview/lines', has_more: false, total_count: out.length, data: out },
     });
 }
-export async function PostInvoicesInvoiceFinalize(ctx) {
-    const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceFinalize');
-    if ('answer' in loaded)
-        return loaded.answer;
-    const inv = loaded.inv;
-    const id = String(inv.id);
-    const piId = collectsThroughIntent(inv) ? ctx.mint('payment_intent') : null;
-    const body = await ctx.write(INV, id, { ...finalizedFields(ctx, inv, Number(nowUnix(ctx.occurredAt))), status: 'open', status_transitions: { ...transitions(inv), finalized_at: nowUnix(ctx.occurredAt) }, payment_intent: piId }, 'invoice.finalize');
-    if (piId)
-        await openPaymentIntent(ctx, piId, inv, id);
-    // a subscription's invoice finalized spends the once coupon it took (renewals.ts spendOnceCoupon)
-    await spendOnceCoupon(ctx, inv);
-    return ctx.reply(expanded(ctx, INV, body));
-}
-// paying charges a payment method (the one passed, the invoice's default, or the customer's) unless
-// the payment is recorded out of band; a declining card answers 402 and leaves the invoice open. A
-// paid invoice settles the PaymentIntent finalize opened, and names the charge that took the money.
-export async function PostInvoicesInvoicePay(ctx) {
-    const id = at(ctx, 'invoice');
-    const inv = ctx.get(INV, id);
-    if (!inv)
-        return invoiceMissing(ctx, id);
-    const refused = ctx.legal(INV, 'status', 'PostInvoicesInvoicePay', inv.status, undefined, id);
-    if (refused)
-        return ctx.refuse(refused);
-    const params = ctx.params;
-    const paidOutOfBand = params.paid_out_of_band !== undefined && asBool(params.paid_out_of_band);
-    const payer = ctx.get('customer', String(inv.customer ?? ''));
-    const customerDefault = payer?.invoice_settings?.default_payment_method || payer?.default_source;
-    if (!paidOutOfBand && !params.payment_method && !params.source && !inv.default_payment_method && !inv.default_source && !customerDefault)
-        return nothingToPayWith(ctx);
-    // what it charges: the method passed, else the invoice's default, its subscription's, then its customer's
-    // (docs.stripe.com/api/invoices/pay#pay_invoice-payment_method)
-    const subscription = typeof inv.subscription === 'string' ? ctx.get('subscription', inv.subscription) : undefined;
-    const decline = declineFor(finder(ctx), params, { payment_method: inv.default_payment_method ?? subscription?.default_payment_method ?? customerDefault });
-    const intent = typeof inv.payment_intent === 'string' ? ctx.get('payment_intent', inv.payment_intent) : undefined;
-    if (decline)
-        return send(ctx, cardError(decline, intent ? { payment_intent: intent } : {}));
-    const amountPaid = Number(inv.total ?? inv.amount_due) || 0;
-    let body = await ctx.write(INV, id, {
-        // paid outside Stripe, the invoice counts it as such: `amount_paid_off_stripe`, "Amount, in cents (or local
-        // equivalent), that was paid on the invoice outside of Stripe" (served spec, invoice), the only place the served
-        // version shows it now that basil renders no `paid_out_of_band` (../engine/version.ts)
-        status: 'paid', paid: true, paid_out_of_band: paidOutOfBand, amount_paid: amountPaid, amount_remaining: 0,
-        ...(paidOutOfBand ? { amount_paid_off_stripe: amountPaid } : {}),
-        status_transitions: { ...transitions(inv), paid_at: nowUnix(ctx.occurredAt) },
-    }, 'invoice.pay');
-    if (!paidOutOfBand && typeof inv.payment_intent === 'string' && inv.payment_intent) {
-        const pi = ctx.get('payment_intent', inv.payment_intent);
-        if (pi && pi.status !== 'succeeded' && !ctx.legal('payment_intent', 'status', 'PostInvoicesInvoicePay', pi.status)) {
-            const chargeId = await mintCharge(ctx, inv.payment_intent, { ...pi, invoice: id, ...(typeof params.payment_method === 'string' ? { payment_method: params.payment_method } : {}) }, amountPaid);
-            await ctx.write('payment_intent', inv.payment_intent, { status: 'succeeded', amount_received: amountPaid, amount_capturable: 0, next_action: null, latest_charge: chargeId }, 'payment_intent.succeeded');
-            body = await ctx.write(INV, id, { charge: chargeId }, 'invoice.update');
-        }
-    }
-    // a subscription waiting on this invoice (incomplete on its first, past_due on a failed renewal) is active once it is paid
-    const subId = typeof inv.subscription === 'string' ? inv.subscription : undefined;
-    const sub = subId ? ctx.get('subscription', subId) : undefined;
-    if (subId && sub && (sub.status === 'incomplete' || sub.status === 'past_due') && !ctx.legal('subscription', 'status', 'PostInvoicesInvoicePay', sub.status, 'active', subId))
-        await activatedByPayment(ctx, subId);
-    return ctx.reply(expanded(ctx, INV, body));
-}
-// sending a draft finalizes it; any other invoice keeps its status and records the send
-export async function PostInvoicesInvoiceSend(ctx) {
-    const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceSend');
-    if ('answer' in loaded)
-        return loaded.answer;
-    const inv = loaded.inv;
-    const id = String(inv.id);
-    const becameOpen = inv.status === 'draft';
-    const piId = collectsThroughIntent(inv) ? ctx.mint('payment_intent') : null;
-    const now = nowUnix(ctx.occurredAt);
-    const body = await ctx.write(INV, id, {
-        status: becameOpen ? 'open' : inv.status, _sent: true, _sent_at: now,
-        status_transitions: { ...transitions(inv), ...(becameOpen ? { finalized_at: now } : {}) },
-        ...(becameOpen ? { payment_intent: piId } : {}),
-    }, 'invoice.sent');
-    if (piId)
-        await openPaymentIntent(ctx, piId, inv, id);
-    if (becameOpen)
-        await spendOnceCoupon(ctx, inv);
-    return ctx.reply(expanded(ctx, INV, body));
-}
-export async function PostInvoicesInvoiceVoid(ctx) {
-    const loaded = invoicesLoad(ctx, 'PostInvoicesInvoiceVoid');
-    if ('answer' in loaded)
-        return loaded.answer;
-    const inv = loaded.inv;
-    const body = await ctx.write(INV, String(inv.id), { status: 'void', status_transitions: { ...transitions(inv), voided_at: nowUnix(ctx.occurredAt) } }, 'invoice.void');
-    return ctx.reply(expanded(ctx, INV, body));
-}

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

@@ -0,0 +1,6 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function GetIssuingCardsCard(ctx: HandlerContext): Promise<Response>;
+export declare function PostIssuingAuthorizationsAuthorizationApprove(ctx: HandlerContext): Promise<Response>;
+export declare function PostIssuingAuthorizationsAuthorizationDecline(ctx: HandlerContext): Promise<Response>;
+export declare function PostIssuingCards(ctx: HandlerContext): Promise<Response>;
+export declare function PostIssuingCardsCard(ctx: HandlerContext): Promise<Response>;

package/dist/src/semantics/issuing.js

@@ -0,0 +1,77 @@
+import { CARD, CH, cardNumberOf, cvcOf } from "../engine/issuing.js";
+import { emptySpendingControls, normalizeSpendingControls, nowUnix } from "../engine/stripe.js";
+import { at, created, fail, issuingDecide, issuingRefusal, send } from "./shared.js";
+export async function GetIssuingCardsCard(ctx) {
+    const id = at(ctx, 'card');
+    const card = ctx.get(CARD, id);
+    if (!card)
+        return fail(ctx, `No such card: '${id}'`, 404, 'resource_missing');
+    const expand = Array.isArray(ctx.params.expand) ? ctx.params.expand.map(String) : [];
+    // source: spec:/components/schemas/issuing.card/properties/number/description "For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with"
+    const virtual = card.type === 'virtual';
+    const shown = { ...card };
+    if (virtual && expand.includes('number'))
+        shown.number = cardNumberOf(await ctx.secret(`issuing-card-number:${id}`));
+    // source: spec:/components/schemas/issuing.card/properties/cvc/description "The card's CVC. For security reasons, this is only available for virtual cards"
+    if (virtual && expand.includes('cvc'))
+        shown.cvc = cvcOf(await ctx.secret(`issuing-card-cvc:${id}`));
+    return ctx.reply(ctx.expand(CARD, shown));
+}
+export async function PostIssuingAuthorizationsAuthorizationApprove(ctx) {
+    return issuingDecide(true)(ctx);
+}
+export async function PostIssuingAuthorizationsAuthorizationDecline(ctx) {
+    return issuingDecide(false)(ctx);
+}
+export async function PostIssuingCards(ctx) {
+    const params = ctx.params;
+    // source: spec:PostIssuingCards "The currency for the card."
+    if (params.currency === undefined || params.currency === '')
+        return fail(ctx, 'Missing required param: currency.', 400, 'parameter_missing');
+    const cardType = typeof params.type === 'string' ? params.type : '';
+    if (!cardType)
+        return fail(ctx, 'Missing required param: type.', 400, 'parameter_missing');
+    // source: spec:PostIssuingCards "The type of card to issue."
+    if (cardType !== 'virtual' && cardType !== 'physical')
+        return fail(ctx, "Invalid type: must be one of 'virtual' or 'physical'.", 400, 'parameter_invalid_string_enum');
+    // the card answers its cardholder in full (the served spec's issuing.card.cardholder is the Cardholder object)
+    const holder = typeof params.cardholder === 'string' ? params.cardholder : '';
+    const cardholder = holder ? ctx.get(CH, holder) : undefined;
+    if (holder && !cardholder)
+        return fail(ctx, `No such cardholder: '${holder}'`, 400, 'resource_missing');
+    const controls = normalizeSpendingControls(params.spending_controls, typeof params.currency === 'string' ? params.currency : null);
+    if (controls.error)
+        return send(ctx, controls.error);
+    const id = ctx.mint(CARD);
+    const number = cardNumberOf(await ctx.secret(`issuing-card-number:${id}`));
+    // Where the documentation stops and the twin decides: a card expires three years after it is issued, at the end of
+    // the month it was issued in.
+    const issued = new Date(Number(nowUnix(ctx.occurredAt)) * 1000);
+    return ctx.reply(ctx.expand(CARD, await created(ctx, CARD, { ...params, id, cardholder: holder || null, spending_controls: controls.controls ?? emptySpendingControls() }, {
+        // source: https://docs.stripe.com/api/issuing/cards/create "Whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to inactive."
+        status: typeof params.status === 'string' ? params.status : 'inactive',
+        livemode: false, metadata: {}, brand: 'Visa', last4: number.slice(-4),
+        exp_month: issued.getUTCMonth() + 1, exp_year: issued.getUTCFullYear() + 3,
+        cancellation_reason: null, replacement_for: null, replacement_reason: null, shipping: null, wallets: null,
+    })));
+}
+// source: spec:PostIssuingCardsCard "Any parameters not provided will be left unchanged."
+export async function PostIssuingCardsCard(ctx) {
+    const id = at(ctx, 'card');
+    const card = ctx.get(CARD, id);
+    if (!card)
+        return fail(ctx, `No such card: '${id}'`, 404, 'resource_missing');
+    const { expand: _expand, ...fields } = ctx.params;
+    // source: spec:/paths/~1v1~1issuing~1cards~1{card}/post/requestBody/content/application~1x-www-form-urlencoded/schema/properties/status "Dictates whether authorizations can be approved on this card."
+    if (fields.status !== undefined && !['active', 'inactive', 'canceled'].includes(String(fields.status)))
+        return issuingRefusal(ctx, 'card_status');
+    if (fields.status !== undefined) {
+        const refused = ctx.legal(CARD, 'status', 'PostIssuingCardsCard', card.status, String(fields.status), id);
+        if (refused)
+            return ctx.refuse(refused);
+    }
+    const controls = normalizeSpendingControls(fields.spending_controls, String(card.currency), card.spending_controls);
+    if (controls.error)
+        return send(ctx, controls.error);
+    return ctx.reply(ctx.expand(CARD, await ctx.write(CARD, id, { ...fields, ...(controls.controls ? { spending_controls: controls.controls } : {}) }, 'issuing.card.update')));
+}

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

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

package/dist/src/semantics/payment_intents.js

@@ -1,6 +1,7 @@
 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";
+import { confirmIntent, intentFields, confirmOnly, methodFromData, paymentIntentsSend } from "./shared.js";
+import { cancelAuthorization, paymentIntentsLoad } from "./shared.js";
 export async function PostPaymentIntents(ctx) {
     const params = ctx.params;
     const bad = validateMoney(params);
@@ -47,14 +48,15 @@ export async function PostPaymentIntents(ctx) {
         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,
+        ...intentFields(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 confirmIntent(ctx, body, { ...params, payment_method: rest.payment_method });
     return ctx.reply(ctx.expand(PI, body));
 }
+// source: spec:GetPaymentIntentsSearch "Search for PaymentIntents"
 export async function PostPaymentIntentsIntentCancel(ctx) {
     const loaded = paymentIntentsLoad(ctx, 'PostPaymentIntentsIntentCancel');
     if ('answer' in loaded)
@@ -67,13 +69,3 @@ export async function PostPaymentIntentsIntentCancel(ctx) {
         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

@@ -1,5 +1,3 @@
 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

@@ -1,6 +1,5 @@
-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";
+import { PM } from "../engine/payment-methods.js";
+import { at, 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'));
@@ -8,29 +7,6 @@ export async function GetPaymentMethodsPaymentMethod(ctx) {
 // 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))

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

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

package/dist/src/semantics/payouts.js

@@ -1,5 +1,5 @@
 import { validateMoney } from "../engine/stripe.js";
-import { account, created, fail, noExternalAccount, payoutBank, payoutDefaults, refusePayout, send, settlePayout } from "./shared.js";
+import { account, asOf, created, kept, list, newest, fail, noExternalAccount, payoutBank, payoutDefaults, refusePayout, send, settlePayout } from "./shared.js";
 export async function PostPayouts(ctx) {
     const bad = validateMoney(ctx.params);
     if (bad)
@@ -19,3 +19,10 @@ export async function PostPayouts(ctx) {
     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 } : {}) }));
 }
+// source: https://docs.stripe.com/connect/authentication "Stripe-Account header"
+// source: https://docs.stripe.com/payouts "paid"
+export async function GetPayouts(ctx) {
+    const acct = account(ctx);
+    const payouts = newest(ctx, 'payout').filter((p) => (kept(ctx, 'payout', p, '_account') ?? null) === (acct ?? null));
+    return list(ctx, 'payout', payouts.map((p) => asOf(ctx, p)));
+}

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

@@ -1,6 +1,4 @@
 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>;
+/** `GET /v1/products/search?query=`: the products Stripe's search language selects. */

package/dist/src/semantics/products.js

@@ -1,14 +1,5 @@
 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);
-    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 });
-}
+import { created, list, newest, where } from "./shared.js";
 export async function GetProducts(ctx) {
     return list(ctx, 'product', where(ctx, newest(ctx, 'product'), {
         active: (p, v) => asBool(p.active) === asBool(v),
@@ -18,8 +9,6 @@ export async function GetProducts(ctx) {
 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). */
+/** `GET /v1/products/search?query=`: the products Stripe's search language selects. */
 // source: spec:GetProductsSearch "Search for products you’ve previously created using Stripe’s"
-export async function GetProductsSearch(ctx) {
-    return search(ctx, 'product');
-}
+// source: spec:PostProductsProductFeatures "Creates a product_feature"

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

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

package/dist/src/semantics/refunds.js

@@ -1,8 +1,4 @@
-import { at, refundCharge, refundMissing, target } from "./shared.js";
-export async function GetRefundsRefund(ctx) {
-    const r = ctx.get('refund', at(ctx, 'refund'));
-    return r ? ctx.reply(r) : refundMissing(ctx, at(ctx, 'refund'));
-}
+import { refundCharge, target } from "./shared.js";
 export async function PostRefunds(ctx) {
     const ch = target(ctx);
     return ch instanceof Response ? ch : refundCharge(ctx, ch, ctx.params);