@peable.to/contracts 0.4.0 → 1.0.0

package/dist/cjs/resources/billingEngine/params.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emptyBody = exports.httpUrlParam = exports.automaticTaxParam = exports.discountsParam = exports.discountParams = exports.signedAmountParam = exports.amountParam = exports.currencyParam = exports.daysUntilDueParam = exports.shortText = exports.quantityParam = void 0;
+const zod_1 = require("zod");
+const params_1 = require("../../common/params");
+const money_1 = require("../../vocabulary/money");
+/**
+ * Request (and response) pieces the billing engine's resources share (ADR
+ * 0018). Internal to this group: not re-exported from its `index.ts`, so no
+ * name here can collide with another group's at the package root.
+ */
+/** A quantity: a whole number of units, 0 to a billion. */
+exports.quantityParam = zod_1.z.number().int().min(0).max(1000000000);
+/** Non-empty bounded text. */
+const shortText = (max) => zod_1.z.string().min(1).max(max);
+exports.shortText = shortText;
+/** `send_invoice` only: days from finalization to the due date. */
+exports.daysUntilDueParam = zod_1.z.number().int().min(0).max(365);
+/** A currency a request names. */
+exports.currencyParam = zod_1.z.enum(money_1.CURRENCY_CODES);
+/** A canonical base-unit integer string: `"1999"`, never `"19.99"` or `1999`. */
+exports.amountParam = zod_1.z
+    .string()
+    .refine(money_1.isBaseUnitString, 'must be a non-negative integer string in the smallest currency unit');
+/** A signed base-unit integer string (a balance adjustment). */
+exports.signedAmountParam = zod_1.z
+    .string()
+    .regex(/^(0|-?[1-9][0-9]{0,30})$/, 'must be an integer string in the smallest currency unit, optionally negative');
+/** One entry of `discounts[]`: a coupon or a promotion code. */
+exports.discountParams = zod_1.z
+    .object({ coupon: params_1.idParam.optional(), promotion_code: params_1.idParam.optional() })
+    .strict();
+/** `discounts[]`, at most twenty. */
+exports.discountsParam = zod_1.z.array(exports.discountParams).max(20);
+/** `automatic_tax[enabled]`: compute Peable Tax (ADR 0011) before the invoice finalizes. */
+exports.automaticTaxParam = zod_1.z.object({ enabled: zod_1.z.boolean() }).strict();
+/** An http(s) URL a request names (a return URL, a policy link). */
+exports.httpUrlParam = zod_1.z
+    .string()
+    .regex(/^https?:\/\//)
+    .max(2048);
+/** A request with no parameters at all. */
+exports.emptyBody = zod_1.z.object({}).strict();

package/dist/cjs/resources/billingEngine/public.js

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publicBillingRoutes = exports.completePortalPaymentMethodUpdateParams = exports.startPortalPaymentMethodUpdateParams = exports.portalCustomerParams = exports.portalChangePlanParams = exports.portalSubscriptionParams = exports.payPublicInvoiceParams = exports.portalPaymentMethodUpdateResultSchema = exports.portalPaymentMethodUpdateSchema = exports.publicPortalSessionSchema = exports.publicPortalSubscriptionSchema = exports.publicInvoicePaymentSchema = exports.publicInvoiceSchema = void 0;
+const zod_1 = require("zod");
+const address_1 = require("../../common/address");
+const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+const billingPortal_1 = require("../../vocabulary/billingPortal");
+const invoices_1 = require("../../vocabulary/invoices");
+const subscriptions_1 = require("../../vocabulary/subscriptions");
+const billingPortal_2 = require("./billingPortal");
+const params_2 = require("./params");
+/**
+ * The payer-facing billing routes (ADR 0018) — anonymous, authorized by an
+ * unguessable bearer token in the path, like a payment link: a finalized
+ * invoice as its payer sees it, and the customer portal. Nothing here reveals
+ * anything but the one invoice or the one customer the token names. Called by
+ * the hosted checkout (`checkout.peable.to`), never by the server SDK.
+ */
+/** The merchant as a payer sees it. */
+const publicMerchantSchema = zod_1.z
+    .object({ name: zod_1.z.string().nullable(), avatar_url: zod_1.z.string().nullable() })
+    .strict();
+/** A finalized invoice as its payer sees it. */
+exports.publicInvoiceSchema = (0, objects_1.defineObject)('public_invoice', 'PublicInvoice', zod_1.z
+    .object({
+    object: zod_1.z.literal('public_invoice'),
+    livemode: primitives_1.livemode,
+    number: zod_1.z.string().nullable(),
+    status: zod_1.z.enum(invoices_1.INVOICE_STATUSES),
+    currency: primitives_1.currency,
+    merchant: publicMerchantSchema,
+    customer_name: zod_1.z.string().nullable(),
+    customer_email: zod_1.z.string().nullable(),
+    description: zod_1.z.string().nullable(),
+    lines: zod_1.z.array(zod_1.z
+        .object({
+        description: zod_1.z.string().nullable(),
+        quantity: zod_1.z.number().int().nullable(),
+        amount: primitives_1.signedAmount,
+        period: zod_1.z.object({ start: primitives_1.unixSeconds, end: primitives_1.unixSeconds }).strict(),
+        proration: zod_1.z.boolean(),
+    })
+        .strict()),
+    subtotal: primitives_1.signedAmount,
+    total_discount: primitives_1.signedAmount,
+    tax: primitives_1.signedAmount.nullable(),
+    total: primitives_1.signedAmount,
+    amount_due: primitives_1.amount,
+    amount_paid: primitives_1.amount,
+    amount_remaining: primitives_1.amount,
+    due_date: primitives_1.unixSeconds.nullable(),
+    created: primitives_1.unixSeconds,
+    finalized_at: primitives_1.unixSeconds.nullable(),
+    paid_at: primitives_1.unixSeconds.nullable(),
+    payment_method_types: zod_1.z
+        .array(zod_1.z.enum(invoices_1.PUBLIC_INVOICE_PAYMENT_METHOD_TYPES))
+        .describe("Which rail pays it: a card through the provider's fields, FairCoin from the payer's wallet."),
+    invoice_pdf: zod_1.z.string(),
+})
+    .strict());
+/**
+ * The PaymentIntent the payer completes on the hosted checkout
+ * (`/i/:id#client_secret=…`). The same invoice always answers the same intent
+ * while it can still be paid.
+ */
+exports.publicInvoicePaymentSchema = (0, objects_1.defineObject)('public_invoice_payment', 'PublicInvoicePayment', zod_1.z
+    .object({
+    object: zod_1.z.literal('public_invoice_payment'),
+    payment_intent: zod_1.z.string().describe('The PaymentIntent (`pi_…`) that pays the invoice.'),
+    client_secret: zod_1.z
+        .string()
+        .describe("The intent's payer credential (`pi_…_secret_…`), as a payment link hands out."),
+})
+    .strict());
+/** One subscription as the hosted portal shows it. */
+exports.publicPortalSubscriptionSchema = (0, objects_1.defineComponent)('PublicPortalSubscription', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    status: zod_1.z.enum(subscriptions_1.SUBSCRIPTION_STATUSES),
+    currency: primitives_1.currency,
+    current_period_end: primitives_1.unixSeconds,
+    cancel_at_period_end: zod_1.z.boolean(),
+    cancel_at: primitives_1.unixSeconds.nullable(),
+    trial_end: primitives_1.unixSeconds.nullable(),
+    collection_method: zod_1.z.enum(subscriptions_1.COLLECTION_METHODS),
+    items: zod_1.z.array(zod_1.z
+        .object({
+        id: zod_1.z.string(),
+        price: zod_1.z.string(),
+        product: zod_1.z.string(),
+        product_name: zod_1.z.string(),
+        quantity: zod_1.z.number().int().nonnegative(),
+        unit_amount: primitives_1.amount.nullable(),
+        interval: zod_1.z.string().nullable(),
+    })
+        .strict()),
+})
+    .strict());
+/** The hosted portal's view of its customer. */
+exports.publicPortalSessionSchema = (0, objects_1.defineObject)('billing_portal.public_session', 'PublicPortalSession', zod_1.z
+    .object({
+    object: zod_1.z.literal('billing_portal.public_session'),
+    livemode: primitives_1.livemode,
+    merchant: publicMerchantSchema,
+    business_profile: billingPortal_2.billingPortalBusinessProfileSchema,
+    features: billingPortal_2.billingPortalFeaturesSchema,
+    return_url: zod_1.z.string().nullable(),
+    expires_at: primitives_1.unixSeconds,
+    customer: zod_1.z
+        .object({
+        id: zod_1.z.string(),
+        email: zod_1.z.string().nullable(),
+        name: zod_1.z.string().nullable(),
+        phone: zod_1.z.string().nullable(),
+        address: address_1.addressSchema.nullable(),
+        default_payment_method: zod_1.z
+            .object({
+            id: zod_1.z.string(),
+            card: zod_1.z
+                .object({
+                brand: zod_1.z.string(),
+                last4: zod_1.z.string(),
+                exp_month: zod_1.z.number().int(),
+                exp_year: zod_1.z.number().int(),
+            })
+                .strict()
+                .nullable(),
+        })
+            .strict()
+            .nullable(),
+    })
+        .strict(),
+    subscriptions: zod_1.z.array(exports.publicPortalSubscriptionSchema),
+    invoices: zod_1.z.array(zod_1.z
+        .object({
+        id: zod_1.z.string(),
+        number: zod_1.z.string().nullable(),
+        status: zod_1.z.enum(invoices_1.INVOICE_STATUSES),
+        currency: primitives_1.currency,
+        total: primitives_1.signedAmount,
+        amount_due: primitives_1.amount,
+        created: primitives_1.unixSeconds,
+        hosted_invoice_url: zod_1.z.string().nullable(),
+        invoice_pdf: zod_1.z.string().nullable(),
+    })
+        .strict()),
+    plans: zod_1.z
+        .array(zod_1.z
+        .object({
+        product: zod_1.z.string(),
+        product_name: zod_1.z.string(),
+        prices: zod_1.z.array(zod_1.z
+            .object({
+            id: zod_1.z.string(),
+            unit_amount: primitives_1.amount.nullable(),
+            currency: primitives_1.currency,
+            interval: zod_1.z.string().nullable(),
+            interval_count: zod_1.z.number().int().nullable(),
+        })
+            .strict()),
+    })
+        .strict())
+        .describe('The plans `subscription_update` allows, priced.'),
+})
+    .strict());
+/** A card update begun: the SetupIntent the portal page confirms with the provider's own fields. */
+exports.portalPaymentMethodUpdateSchema = (0, objects_1.defineComponent)('PortalPaymentMethodUpdate', zod_1.z
+    .object({
+    setup_intent: zod_1.z.string().describe('The SetupIntent (`seti_…`) to confirm.'),
+    client_secret: zod_1.z.string().describe('Its payer credential.'),
+})
+    .strict());
+/** A card update finished: `pending` until the SetupIntent succeeded. */
+exports.portalPaymentMethodUpdateResultSchema = (0, objects_1.defineComponent)('PortalPaymentMethodUpdateResult', zod_1.z
+    .object({
+    status: zod_1.z.enum(billingPortal_1.PORTAL_PAYMENT_METHOD_UPDATE_STATUSES),
+    session: exports.publicPortalSessionSchema,
+})
+    .strict());
+// ---- Requests ------------------------------------------------------------------------
+exports.payPublicInvoiceParams = params_2.emptyBody;
+/** A portal action on one of the customer's subscriptions. */
+exports.portalSubscriptionParams = zod_1.z.object({ subscription: params_1.idParam }).strict();
+/** Switch a (single-item) subscription to one of the configuration's plans, or change its quantity. */
+exports.portalChangePlanParams = zod_1.z
+    .object({
+    subscription: params_1.idParam,
+    price: params_1.idParam.optional(),
+    quantity: params_2.quantityParam.optional(),
+})
+    .strict();
+/** The fields the configuration's `customer_update.allowed_updates` names. */
+exports.portalCustomerParams = zod_1.z
+    .object({
+    email: address_1.emailParam.optional(),
+    name: (0, params_2.shortText)(500).optional(),
+    phone: (0, params_2.shortText)(40).optional(),
+    address: address_1.addressParams.optional(),
+})
+    .strict();
+exports.startPortalPaymentMethodUpdateParams = params_2.emptyBody;
+exports.completePortalPaymentMethodUpdateParams = zod_1.z.object({ setup_intent: params_1.idParam }).strict();
+// ---- Routes --------------------------------------------------------------------------
+const invoiceToken = { token: 'The hosted invoice token (from `hosted_invoice_url`).' };
+const portalToken = { token: 'The portal session token (from the session `url`).' };
+exports.publicBillingRoutes = [
+    (0, route_1.defineRoute)({
+        operationId: 'retrievePublicInvoice',
+        method: 'get',
+        path: '/v1/invoices/public/{token}',
+        tag: 'Hosted invoices',
+        summary: 'Retrieve a hosted invoice',
+        description: 'A finalized invoice as its payer sees it.',
+        auth: 'public',
+        params: invoiceToken,
+        response: exports.publicInvoiceSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'payPublicInvoice',
+        method: 'post',
+        path: '/v1/invoices/public/{token}/pay',
+        tag: 'Hosted invoices',
+        summary: 'Pay a hosted invoice',
+        description: 'The PaymentIntent the payer completes — a card through the provider’s own fields, FairCoin from the payer’s wallet. The same invoice answers the same intent while it can still be paid.',
+        auth: 'public',
+        params: invoiceToken,
+        body: exports.payPublicInvoiceParams,
+        response: exports.publicInvoicePaymentSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrievePublicInvoicePdf',
+        method: 'get',
+        path: '/v1/invoices/public/{token}/pdf',
+        tag: 'Hosted invoices',
+        summary: "Download a hosted invoice's PDF",
+        auth: 'public',
+        params: invoiceToken,
+        response: { kind: 'binary', contentType: 'application/pdf' },
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrievePublicPortalSession',
+        method: 'get',
+        path: '/v1/billing_portal/public/{token}',
+        tag: 'Hosted portal',
+        summary: 'Retrieve the hosted portal',
+        description: 'The customer, their subscriptions, invoices and the plans they may switch to.',
+        auth: 'public',
+        params: portalToken,
+        response: exports.publicPortalSessionSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'cancelPortalSubscription',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/cancel',
+        tag: 'Hosted portal',
+        summary: 'Cancel a subscription from the portal',
+        description: 'At period end or now, as the configuration says. Answers the portal as it now is.',
+        auth: 'public',
+        params: portalToken,
+        body: exports.portalSubscriptionParams,
+        response: exports.publicPortalSessionSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'renewPortalSubscription',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/renew',
+        tag: 'Hosted portal',
+        summary: 'Undo a cancellation at period end',
+        description: 'Answers the portal as it now is.',
+        auth: 'public',
+        params: portalToken,
+        body: exports.portalSubscriptionParams,
+        response: exports.publicPortalSessionSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'changePortalSubscriptionPlan',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/change_plan',
+        tag: 'Hosted portal',
+        summary: 'Change plan from the portal',
+        description: 'Answers the portal as it now is.',
+        auth: 'public',
+        params: portalToken,
+        body: exports.portalChangePlanParams,
+        response: exports.publicPortalSessionSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'updatePortalCustomer',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/customer',
+        tag: 'Hosted portal',
+        summary: 'Update billing details from the portal',
+        description: 'Answers the portal as it now is.',
+        auth: 'public',
+        params: portalToken,
+        body: exports.portalCustomerParams,
+        response: exports.publicPortalSessionSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'startPortalPaymentMethodUpdate',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/payment_method_update',
+        tag: 'Hosted portal',
+        summary: 'Begin a card update from the portal',
+        description: 'A SetupIntent for the customer; card customers only.',
+        auth: 'public',
+        params: portalToken,
+        body: exports.startPortalPaymentMethodUpdateParams,
+        response: exports.portalPaymentMethodUpdateSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'completePortalPaymentMethodUpdate',
+        method: 'post',
+        path: '/v1/billing_portal/public/{token}/payment_method_update/complete',
+        tag: 'Hosted portal',
+        summary: 'Finish a card update from the portal',
+        description: "Once the SetupIntent succeeded, its method becomes the customer's default and every live subscription's.",
+        auth: 'public',
+        params: portalToken,
+        body: exports.completePortalPaymentMethodUpdateParams,
+        response: exports.portalPaymentMethodUpdateResultSchema,
+    }),
+];