@volter/twin-stripe 2.0.37 → 3.0.0

package/dist/src/semantics/credit-notes.js

@@ -1,172 +0,0 @@
-import { paginate } from "../stripe-twin.js";
-import { refundCharge } from "./refunds.js";
-import { at, created, fail, path } from "./shared.js";
-const CN = 'credit_note';
-const noteMissing = (ctx, id) => fail(ctx, `No such credit note: '${id}'`, 404, 'resource_missing');
-/** The credit note the request describes (the `amount` form: one custom line), or Stripe's refusal. */
-function build(ctx, id) {
-    const params = ctx.params;
-    const invoiceId = typeof params.invoice === 'string' ? params.invoice : '';
-    if (!invoiceId)
-        return fail(ctx, 'Missing required param: invoice.', 400, 'parameter_missing');
-    const invoice = ctx.get('invoice', invoiceId);
-    if (!invoice)
-        return fail(ctx, `No such invoice: '${invoiceId}'`, 404, 'resource_missing');
-    if (params.amount === undefined)
-        return fail(ctx, 'Missing required param: amount.', 400, 'parameter_missing');
-    const amount = Number(params.amount);
-    if (!Number.isInteger(amount) || amount <= 0)
-        return fail(ctx, 'Invalid integer: amount must be a positive integer.', 400, 'parameter_invalid_integer');
-    const vendorType = invoice.status === 'paid' ? 'post_payment' : 'pre_payment';
-    const outOfBand = Number(params.out_of_band_amount) || 0;
-    // a paid invoice's credit is paid back: "The sum of refunds, customer balance credits, and outside of Stripe credits
-    // must equal the post_payment_amount" (docs.stripe.com/api/credit_notes/create); the message's wording is the twin's
-    if (vendorType === 'post_payment') {
-        const split = (Number(params.refund_amount) || 0) + (Number(params.credit_amount) || 0) + outOfBand;
-        if (split !== amount)
-            return fail(ctx, `The sum of refund_amount, credit_amount and out_of_band_amount (${split}) must equal the credit note's post_payment_amount (${amount}).`, 400, 'parameter_invalid_integer');
-    }
-    const line = {
-        object: 'credit_note_line_item', id: `cnli_${id}_1`, type: 'custom_line_item',
-        amount, description: typeof params.memo === 'string' ? params.memo : null,
-        // a custom line credits no invoice line: invoice_line_item ("ID of the invoice line item being credited") is left
-        // out, the served spec not letting it be null
-        discount_amount: 0, discount_amounts: [], livemode: false,
-        pretax_credit_amounts: [], quantity: null, tax_rates: [], taxes: [],
-        unit_amount: null, unit_amount_decimal: null,
-    };
-    return {
-        amount, amount_shipping: 0, created: ctx.now(), currency: typeof invoice.currency === 'string' ? invoice.currency : 'usd', customer: typeof invoice.customer === 'string' ? invoice.customer : null,
-        customer_balance_transaction: null,
-        // "The date when this credit note is in effect. Same as `created` unless overwritten" (the served spec)
-        discount_amount: 0, discount_amounts: [], effective_at: params.effective_at !== undefined ? Number(params.effective_at) : ctx.now(), invoice: invoiceId,
-        lines: { object: 'list', data: [line], has_more: false, total_count: 1, url: `/v1/credit_notes/${id}/lines` },
-        livemode: false, memo: params.memo ?? null, metadata: params.metadata && typeof params.metadata === 'object' ? params.metadata : {},
-        number: `${invoiceId}-CN-01`, out_of_band_amount: outOfBand || null,
-        pdf: `https://files.twin.local/credit_notes/${id}.pdf`,
-        post_payment_amount: vendorType === 'post_payment' ? amount : 0,
-        pre_payment_amount: vendorType === 'pre_payment' ? amount : 0,
-        pretax_credit_amounts: [],
-        reason: typeof params.reason === 'string' ? params.reason : null,
-        refunds: [], shipping_cost: null, status: 'issued',
-        subtotal: amount, subtotal_excluding_tax: amount,
-        type: vendorType, total: amount, total_excluding_tax: amount, total_taxes: [],
-        voided_at: null,
-    };
-}
-/** The invoice's credit-note sums, from its issued credit notes; a pre-payment credit lowers what is owed. */
-async function syncInvoice(ctx, invoiceId) {
-    const inv = ctx.get('invoice', invoiceId);
-    if (!inv)
-        return;
-    let pre = 0;
-    let post = 0;
-    for (const cn of ctx.rows(CN)) {
-        if (cn.invoice !== invoiceId || cn.status === 'void')
-            continue;
-        if (cn.type === 'post_payment')
-            post += Number(cn.amount) || 0;
-        else
-            pre += Number(cn.amount) || 0;
-    }
-    const total = Number(inv.total ?? inv.amount_due) || 0;
-    const paid = Number(inv.amount_paid) || 0;
-    await ctx.write('invoice', invoiceId, { pre_payment_credit_notes_amount: pre, post_payment_credit_notes_amount: post, amount_remaining: Math.max(0, total - paid - pre) }, 'invoice.update');
-}
-// the preview computes the credit note without keeping it
-const preview = async (ctx) => {
-    const id = 'cn_preview';
-    const cn = build(ctx, id);
-    return cn instanceof Response ? cn : ctx.reply({ object: CN, ...cn, id });
-};
-/** What a post-payment credit pays back: "Refunds: create a new refund (using refund_amount)"; "Customer balance credit:
- *  credit the customer's balance (using credit_amount) which will be automatically applied to their next invoice when
- *  it's finalized" (docs.stripe.com/api/credit_notes/create). The refund is made on the invoice's charge as a refund
- *  call makes it (refunds.ts); the credit is a customer balance transaction of type credit_note. Where the documentation
- *  stops and the twin decides: the refund carries no reason of its own. */
-async function payBack(ctx, id, cn) {
-    const params = ctx.params;
-    const out = {};
-    const refundAmount = Number(params.refund_amount) || 0;
-    if (refundAmount > 0) {
-        const invoice = ctx.get('invoice', String(cn.invoice));
-        const pi = typeof invoice?.payment_intent === 'string' ? ctx.get('payment_intent', invoice.payment_intent) : undefined;
-        const chargeId = typeof invoice?.charge === 'string' ? invoice.charge : typeof pi?.latest_charge === 'string' ? pi.latest_charge : undefined;
-        const charge = chargeId ? ctx.get('charge', chargeId) : undefined;
-        if (!charge)
-            return fail(ctx, 'This invoice was not paid with a charge that can be refunded.', 400, 'invoice_no_charge_to_refund');
-        const answer = await refundCharge(ctx, charge, { amount: refundAmount });
-        if (answer.status >= 400)
-            return answer;
-        const refund = (await answer.json());
-        out.refunds = [{ amount_refunded: refundAmount, refund: refund.id, type: 'refund', payment_record_refund: null }];
-    }
-    const creditAmount = Number(params.credit_amount) || 0;
-    const customer = typeof cn.customer === 'string' ? cn.customer : undefined;
-    if (creditAmount > 0 && customer) {
-        const ending = (Number(ctx.get('customer', customer)?.balance) || 0) - creditAmount;
-        const txn = await created(ctx, 'customer_balance_transaction', { customer, amount: -creditAmount, currency: cn.currency, credit_note: id, invoice: cn.invoice }, {
-            ending_balance: ending, type: 'credit_note', livemode: false, metadata: {}, description: null, checkout_session: null,
-        });
-        await ctx.write('customer', customer, { balance: ending }, `customer.balance_adjusted:${String(txn.id)}`);
-        out.customer_balance_transaction = txn.id;
-    }
-    return out;
-}
-const create = async (ctx) => {
-    const id = ctx.mint(CN);
-    const cn = build(ctx, id);
-    if (cn instanceof Response)
-        return cn;
-    const paid = cn.type === 'post_payment' ? await payBack(ctx, id, cn) : {};
-    if (paid instanceof Response)
-        return paid;
-    const body = await created(ctx, CN, { id, ...cn, ...paid }, {});
-    await syncInvoice(ctx, String(cn.invoice));
-    return ctx.reply(body);
-};
-const retrieve = async (ctx) => {
-    const c = ctx.get(CN, at(ctx, 'id'));
-    return c ? ctx.reply(c) : noteMissing(ctx, at(ctx, 'id'));
-};
-const lines = async (ctx) => {
-    const c = ctx.get(CN, at(ctx, 'credit_note'));
-    if (!c)
-        return noteMissing(ctx, at(ctx, 'credit_note'));
-    const l = c.lines;
-    const { page, hasMore } = paginate(Array.isArray(l?.data) ? l.data : [], ctx.params);
-    return ctx.reply({ object: 'list', url: path(ctx), has_more: hasMore, data: page });
-};
-const voidNote = async (ctx) => {
-    const id = at(ctx, 'id');
-    const c = ctx.get(CN, id);
-    if (!c)
-        return noteMissing(ctx, id);
-    const refused = ctx.legal(CN, 'status', 'PostCreditNotesIdVoid', c.status, undefined, id);
-    if (refused)
-        return ctx.refuse(refused);
-    const voided = await ctx.write(CN, id, { status: 'void', voided_at: ctx.now() }, 'credit_note.void');
-    if (typeof c.invoice === 'string')
-        await syncInvoice(ctx, c.invoice);
-    return ctx.reply(voided);
-};
-// only the memo and metadata change
-const update = async (ctx) => {
-    const id = at(ctx, 'id');
-    if (!ctx.get(CN, id))
-        return noteMissing(ctx, id);
-    const patch = {};
-    if (ctx.params.memo !== undefined)
-        patch.memo = ctx.params.memo;
-    if (ctx.params.metadata !== undefined)
-        patch.metadata = ctx.params.metadata;
-    return ctx.reply(await ctx.write(CN, id, patch, 'credit_note.update'));
-};
-export const creditNotes = {
-    GetCreditNotesPreview: preview,
-    PostCreditNotes: create,
-    GetCreditNotesId: retrieve,
-    GetCreditNotesCreditNoteLines: lines,
-    PostCreditNotesIdVoid: voidNote,
-    PostCreditNotesId: update,
-};

package/dist/src/semantics/ephemeral-keys.d.ts

@@ -1,2 +0,0 @@
-import type { Semantics } from '@volter/world-core';
-export declare const ephemeralKeys: Record<string, Semantics>;

package/dist/src/semantics/ephemeral-keys.js

@@ -1,34 +0,0 @@
-import { at, fail } from "./shared.js";
-const create = async (ctx) => {
-    const version = ctx.call.request.headers.get('stripe-version');
-    if (!version)
-        return fail(ctx, 'You must pass the `Stripe-Version` header (e.g. via the apiVersion option) when creating an ephemeral key.', 400, 'parameter_missing');
-    const params = ctx.params;
-    const scopes = [];
-    if (typeof params.customer === 'string' && params.customer)
-        scopes.push(['customer', params.customer]);
-    if (typeof params.issuing_card === 'string' && params.issuing_card)
-        scopes.push(['issuing.card', params.issuing_card]);
-    if (typeof params.verification_session === 'string' && params.verification_session)
-        scopes.push(['identity.verification_session', params.verification_session]);
-    if (scopes.length !== 1)
-        return fail(ctx, 'You must pass exactly one of `customer`, `issuing_card`, or `verification_session`.', 400, 'parameter_missing');
-    const [scope, scopedId] = scopes[0];
-    if (scope === 'customer' && !ctx.get('customer', scopedId))
-        return fail(ctx, `No such customer: '${scopedId}'`, 400, 'resource_missing');
-    const id = ctx.mint('ephemeral_key');
-    const now = Number(ctx.now());
-    const associated_objects = [{ type: scope, id: scopedId }];
-    await ctx.write('ephemeral_key', id, { object: 'ephemeral_key', created: now, expires: now + 3600, livemode: false, associated_objects }, 'ephemeral_key.create');
-    return ctx.reply({ id, object: 'ephemeral_key', created: now, expires: now + 3600, livemode: false, secret: `ek_test_twin_${id}`, associated_objects });
-};
-const expire = async (ctx) => {
-    const id = at(ctx, 'key');
-    if (!ctx.get('ephemeral_key', id))
-        return fail(ctx, `No such ephemeral key: '${id}'`, 404, 'resource_missing');
-    return ctx.reply(await ctx.write('ephemeral_key', id, { expires: ctx.now() }, 'ephemeral_key.delete'));
-};
-export const ephemeralKeys = {
-    PostEphemeralKeys: create,
-    DeleteEphemeralKeysKey: expire,
-};

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

@@ -1,2 +0,0 @@
-import type { Semantics } from '@volter/world-core';
-export declare const files: Record<string, Semantics>;

package/dist/src/semantics/files.js

@@ -1,125 +0,0 @@
-import { asBool } from "../stripe-twin.js";
-import { actingAccount } from "./ledger.js";
-import { at, created, fail, filePurposeRefused, list, mergeUpdate, newest, where } from "./shared.js";
-/** The type Stripe answers for an uploaded file: "The returned file type (for example, csv, pdf, jpg, or png)"
- *  (docs.stripe.com/api/files/object). Where the documentation stops and the twin decides: read from the name's
- *  extension (jpeg as jpg), and null for a name without one. */
-function fileType(name) {
-    const ext = /\.([a-z0-9]+)$/i.exec(name)?.[1]?.toLowerCase();
-    return ext ? (ext === 'jpeg' ? 'jpg' : ext) : null;
-}
-// multipart on Stripe; the file is described by the part uploaded: its name, its size in bytes and its type
-const createFile = async (ctx) => {
-    const purpose = typeof ctx.params.purpose === 'string' ? ctx.params.purpose : '';
-    if (!purpose)
-        return fail(ctx, 'Missing required param: purpose.', 400, 'parameter_missing');
-    const part = ctx.params.file && typeof ctx.params.file === 'object' ? ctx.params.file : undefined;
-    const filename = typeof ctx.params.file === 'string' ? ctx.params.file : typeof part?.name === 'string' ? part.name : 'twin_upload';
-    const made = await created(ctx, 'file', { purpose }, {
-        filename, size: typeof part?.size === 'number' ? part.size : 0,
-        type: fileType(filename), title: null, expires_at: null, url: null,
-        links: { object: 'list', data: [], has_more: false, total_count: 0, url: '' },
-    });
-    await syncLinks(ctx, String(made.id));
-    return ctx.reply(ctx.get('file', String(made.id)));
-};
-/** A file's links, kept in step with the links made to it, at the address Stripe lists them
- *  (/v1/file_links?file=…, the File object's example). */
-async function syncLinks(ctx, fileId) {
-    const data = newest(ctx, 'file_link').filter((l) => l.file === fileId);
-    await ctx.write('file', fileId, { links: { object: 'list', data, has_more: false, url: `/v1/file_links?file=${fileId}` } }, 'file.links_synced');
-}
-/** The purposes a file link may be made to: "The file's `purpose` must be one of the following: …" (the served
- *  spec, POST /v1/file_links `file`). */
-const LINKABLE = ['business_icon', 'business_logo', 'customer_signature', 'dispute_evidence', 'finance_report_run', 'financial_account_statement', 'identity_document_downloadable', 'issuing_regulatory_reporting', 'pci_document', 'selfie', 'sigma_scheduled_query', 'tax_document_user_upload', 'terminal_android_apk', 'terminal_reader_splashscreen'];
-// `file` is required; a link is kept, has its own public url, and is listed on its file
-const createFileLink = async (ctx) => {
-    if (ctx.params.file === undefined || ctx.params.file === '')
-        return fail(ctx, 'Missing required param: file.', 400, 'parameter_missing');
-    const fileId = String(ctx.params.file);
-    const refused = filePurposeRefused(ctx, 'file', LINKABLE);
-    if (refused)
-        return refused;
-    const id = ctx.mint('file_link');
-    const link = await created(ctx, 'file_link', { ...ctx.params, id, file: fileId }, {
-        url: `https://files.twin.local/links/${id}`, expired: false, livemode: false, metadata: {},
-        expires_at: ctx.params.expires_at !== undefined ? Number(ctx.params.expires_at) : null,
-    });
-    await syncLinks(ctx, fileId);
-    return ctx.reply(link);
-};
-// the person verifies at the session's url, Stripe Identity's hosted page (../screens/identity.tsx)
-const createVerificationSession = async (ctx) => {
-    const id = ctx.mint('identity.verification_session');
-    return ctx.reply(await created(ctx, 'identity.verification_session', { ...ctx.params, id }, {
-        status: 'requires_input', livemode: false, client_secret: `${id}_secret_twin`, url: `https://verify.stripe.com/start/${id}`,
-        last_error: null, last_verification_report: null, verified_outputs: null, return_url: ctx.params.return_url ?? null,
-    }));
-};
-// ── the customer portal ──
-// the configuration defaults to the account's default one
-const createPortalSession = async (ctx) => {
-    const customer = typeof ctx.params.customer === 'string' ? ctx.params.customer : '';
-    if (!customer)
-        return fail(ctx, 'Missing required param: customer.', 400, 'parameter_missing');
-    if (!ctx.row('customer', customer, { withDeleted: true }))
-        return fail(ctx, `No such customer: '${customer}'`, 404, 'resource_missing');
-    const configuration = typeof ctx.params.configuration === 'string' && ctx.params.configuration
-        ? ctx.params.configuration
-        : (ctx.rowsRaw('billing_portal.configuration', { withDeleted: true }).find((c) => c.is_default)?.id ?? 'bpc_twin_default');
-    const id = ctx.mint('billing_portal.session');
-    return ctx.reply(await created(ctx, 'billing_portal.session', {
-        id, customer, configuration, return_url: ctx.params.return_url ?? null, url: `https://billing.stripe.com/p/session/${id}`,
-        locale: ctx.params.locale ?? null, on_behalf_of: ctx.params.on_behalf_of ?? null, livemode: false,
-        // the account the session was made on (Stripe-Account), whose name the portal shows (screens/portal.tsx)
-        ...(actingAccount(ctx) ? { _brand_account: actingAccount(ctx) } : {}),
-    }, {}));
-};
-const PBC = 'billing_portal.configuration';
-/** A portal configuration's features, each filled where the request leaves it: every feature is answered (the served
- *  spec requires all five), as the create page's example answers a request that sets only customer_update and
- *  invoice_history: payment_method_update disabled, subscription_cancel disabled at_period_end with proration_behavior
- *  none and its five default reasons, subscription_update disabled with no allowed updates and proration_behavior none
- *  (docs.stripe.com/api/customer_portal/configurations/create); trial_update_behavior "Defaults to a value of
- *  `end_trial` if you don't set it during creation" (the served spec). Where the documentation stops and the twin
- *  decides: a feature the request leaves out is disabled, and schedule_at_period_end has no conditions. */
-const PORTAL_FEATURES = {
-    customer_update: { allowed_updates: [], enabled: false },
-    invoice_history: { enabled: false },
-    payment_method_update: { enabled: false, payment_method_configuration: null },
-    subscription_cancel: { cancellation_reason: { enabled: false, options: ['too_expensive', 'missing_features', 'switched_service', 'unused', 'other'] }, enabled: false, mode: 'at_period_end', proration_behavior: 'none' },
-    subscription_update: { default_allowed_updates: [], enabled: false, proration_behavior: 'none', schedule_at_period_end: { conditions: [] }, trial_update_behavior: 'end_trial' },
-};
-const filled = (base, given) => {
-    if (!given || typeof given !== 'object' || Array.isArray(given) || !base || typeof base !== 'object' || Array.isArray(base))
-        return given === undefined ? base : given;
-    const out = { ...base };
-    for (const [k, v] of Object.entries(given))
-        out[k] = filled(base[k], v);
-    return out;
-};
-const createPortalConfiguration = async (ctx) => ctx.reply(await created(ctx, PBC, { ...ctx.params, business_profile: filled({ headline: null, privacy_policy_url: null, terms_of_service_url: null }, ctx.params.business_profile), features: filled(PORTAL_FEATURES, ctx.params.features) }, {
-    active: true, is_default: false, livemode: false,
-    login_page: { enabled: false, url: null },
-    metadata: {}, default_return_url: ctx.params.default_return_url ?? null,
-    updated: ctx.now(),
-}));
-const listPortalConfigurations = async (ctx) => list(ctx, PBC, where(ctx, newest(ctx, PBC), {
-    active: (c, v) => asBool(c.active) === asBool(v),
-    is_default: (c, v) => asBool(c.is_default) === asBool(v),
-}));
-const updatePortalConfiguration = async (ctx) => {
-    const id = at(ctx, 'configuration');
-    if (!ctx.get(PBC, id))
-        return ctx.notFound(PBC, id);
-    return ctx.reply(await ctx.write(PBC, id, mergeUpdate(ctx, PBC, id, { ...ctx.params, updated: ctx.now() }), 'billing_portal.configuration.update'));
-};
-export const files = {
-    PostFiles: createFile,
-    PostFileLinks: createFileLink,
-    PostIdentityVerificationSessions: createVerificationSession,
-    PostBillingPortalSessions: createPortalSession,
-    PostBillingPortalConfigurations: createPortalConfiguration,
-    GetBillingPortalConfigurations: listPortalConfigurations,
-    PostBillingPortalConfigurationsConfiguration: updatePortalConfiguration,
-};

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

@@ -1,13 +0,0 @@
-import type { Semantics, SemanticsContext } from '@volter/world-core';
-import { type Row } from './shared.js';
-/** The id of a card's cardholder: the card answers the cardholder in full (the served spec's issuing.card.cardholder is
- *  the Cardholder object, not an id); its id is read from it for filtering and for the objects that name it by id. */
-export declare const holderId: (c: Row) => string;
-/** Time's decision on a real-time request no one answered, caught up to the World's clock: once its window has ended,
- *  a pending authorization whose issuing_authorization.request went unanswered, and that no approve or decline decided,
- *  is decided automatically, its request_history reason webhook_timeout ("webhook_timeout for all other failure modes",
- *  the same page, beside webhook_error for a response Stripe cannot process).
- *  Where the documentation stops and the twin decides: the timeout setting is the Dashboard's, which the API does not
- *  answer, and the twin's is to decline; the window is measured in World time from the authorization's created. */
-export declare function lapseRealtimeRequests(ctx: SemanticsContext): Promise<void>;
-export declare const issuing: Record<string, Semantics>;