@peable.to/contracts 0.4.0 → 1.1.0

package/dist/esm/resources/billingEngine/creditNotes.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, expandParam, idParam, listQuery, metadataCreateParam, queryInteger, } from '../../common/params.js';
+import { amount, currency, livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { CREDIT_NOTE_LINE_TYPES, CREDIT_NOTE_REASONS, CREDIT_NOTE_STATUSES, CREDIT_NOTE_TYPES, } from '../../vocabulary/invoices.js';
+import { invoiceActionParams } from './invoices.js';
+import { amountParam, quantityParam, shortText } from './params.js';
+/**
+ * Credit notes (`cn_…`, ADR 0018 §4): a finalized invoice credited — on an
+ * `open` one it reduces what is due; on a `paid` one it is given back
+ * (refunded through the invoice's payment, credited to the customer balance,
+ * or recorded as returned outside Orbit).
+ */
+export const creditNoteLineItemSchema = defineComponent('CreditNoteLineItem', z
+    .object({
+    id: z.string(),
+    object: z.literal('credit_note_line_item'),
+    type: z.enum(CREDIT_NOTE_LINE_TYPES),
+    invoice_line_item: z.string().nullable().describe('The invoice line (`il_…`) it credits.'),
+    description: z.string().nullable(),
+    quantity: z.number().int().nullable(),
+    amount: amount.describe('Before tax; tax-inclusive when the invoice line is.'),
+    tax_amount: amount,
+})
+    .strict());
+export const creditNoteSchema = defineObject('credit_note', 'CreditNote', z
+    .object({
+    id: z.string(),
+    object: z.literal('credit_note'),
+    livemode,
+    number: z.string().describe('`<invoice number>-CN-<nn>`.'),
+    invoice: expandable('invoice', '`in_…`, or the Invoice with `expand[]=invoice`.'),
+    customer: expandable('customer', '`cus_…`, or the Customer with `expand[]=customer`.'),
+    status: z.enum(CREDIT_NOTE_STATUSES),
+    type: z.enum(CREDIT_NOTE_TYPES),
+    reason: z.enum(CREDIT_NOTE_REASONS).nullable(),
+    currency,
+    lines: listOf(creditNoteLineItemSchema),
+    subtotal: amount,
+    tax: amount,
+    total: amount.describe('What is credited, tax included.'),
+    refund_amount: amount.describe("Of `total`: refunded through the invoice's payment."),
+    credit_amount: amount.describe('Of `total`: credited to the customer balance.'),
+    out_of_band_amount: amount.describe('Of `total`: recorded as returned outside Orbit.'),
+    refund: z.string().nullable().describe('The Refund (`re_…`) when part of it was refunded.'),
+    customer_balance_transaction: z
+        .string()
+        .nullable()
+        .describe('The customer balance transaction (`cbtxn_…`) of `credit_amount`.'),
+    memo: z.string().nullable(),
+    metadata,
+    voided_at: unixSeconds.nullable(),
+    created: unixSeconds,
+})
+    .strict());
+const creditNoteFields = {
+    invoice: idParam,
+    amount: amountParam
+        .optional()
+        .describe('Credit this much of the invoice, tax included, spread over its lines.'),
+    reason: z.enum(CREDIT_NOTE_REASONS).optional(),
+    memo: shortText(5000).optional(),
+    refund_amount: amountParam.optional(),
+    credit_amount: amountParam.optional(),
+    out_of_band_amount: amountParam.optional(),
+};
+const creditNoteLineFields = {
+    type: z.enum(CREDIT_NOTE_LINE_TYPES),
+    invoice_line_item: idParam.optional(),
+    amount: amountParam
+        .optional()
+        .describe('For an invoice line: the amount of it to credit (default all of it).'),
+    description: shortText(500).optional(),
+};
+/**
+ * Credit `lines`, or a whole `amount` (custom).
+ *
+ * On a `paid` invoice the credit must be distributed: `refund_amount` (through
+ * the invoice's payment; card only), `credit_amount` (to the customer balance)
+ * and `out_of_band_amount` must add up to the total. Omitted, all of it is
+ * refunded on a card invoice and credited to the balance otherwise. On an
+ * `open` invoice it reduces `amount_due` and none of the three apply.
+ */
+export const createCreditNoteParams = z
+    .object({
+    ...creditNoteFields,
+    lines: z
+        .array(z.object({ ...creditNoteLineFields, quantity: quantityParam.optional() }).strict())
+        .min(1)
+        .max(100)
+        .optional(),
+    metadata: metadataCreateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+/** The create's fields as a query (`lines[0][type]=…`). */
+export const previewCreditNoteQuery = z
+    .object({
+    ...creditNoteFields,
+    lines: z
+        .array(z
+        .object({ ...creditNoteLineFields, quantity: queryInteger({ min: 0 }).optional() })
+        .strict())
+        .max(100)
+        .optional(),
+})
+    .strict();
+export const voidCreditNoteParams = invoiceActionParams;
+export const listCreditNotesQuery = listQuery({
+    invoice: idParam.optional(),
+    customer: idParam.optional(),
+});
+const creditNoteId = { id: 'The credit note (`cn_…`).' };
+export const creditNoteRoutes = [
+    defineRoute({
+        operationId: 'createCreditNote',
+        method: 'post',
+        path: '/v1/credit_notes',
+        tag: 'Credit notes',
+        summary: 'Issue a credit note',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createCreditNoteParams,
+        response: creditNoteSchema,
+        sdk: 'creditNotes.create',
+        expandable: 'credit_note',
+    }),
+    defineRoute({
+        operationId: 'listCreditNotes',
+        method: 'get',
+        path: '/v1/credit_notes',
+        tag: 'Credit notes',
+        summary: 'List credit notes',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listCreditNotesQuery,
+        response: listOf(creditNoteSchema),
+        sdk: 'creditNotes.list',
+        expandable: 'credit_note',
+    }),
+    defineRoute({
+        operationId: 'previewCreditNote',
+        method: 'get',
+        path: '/v1/credit_notes/preview',
+        tag: 'Credit notes',
+        summary: 'Preview a credit note',
+        description: 'The note `POST /v1/credit_notes` would issue with the same fields, computed and never stored (its `id` and `number` are empty).',
+        auth: 'service',
+        scope: 'payments:read',
+        query: previewCreditNoteQuery,
+        response: creditNoteSchema,
+        sdk: 'creditNotes.preview',
+    }),
+    defineRoute({
+        operationId: 'retrieveCreditNote',
+        method: 'get',
+        path: '/v1/credit_notes/{id}',
+        tag: 'Credit notes',
+        summary: 'Retrieve a credit note',
+        auth: 'service',
+        scope: 'payments:read',
+        params: creditNoteId,
+        query: expandOnlyQuery,
+        response: creditNoteSchema,
+        sdk: 'creditNotes.retrieve',
+        expandable: 'credit_note',
+    }),
+    defineRoute({
+        operationId: 'voidCreditNote',
+        method: 'post',
+        path: '/v1/credit_notes/{id}/void',
+        tag: 'Credit notes',
+        summary: 'Void a credit note',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: creditNoteId,
+        body: voidCreditNoteParams,
+        response: creditNoteSchema,
+        sdk: 'creditNotes.voidCreditNote',
+        expandable: 'credit_note',
+    }),
+];

package/dist/esm/resources/billingEngine/customerBalanceTransactions.js

@@ -0,0 +1,87 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, expandParam, listQuery, metadataCreateParam } from '../../common/params.js';
+import { currency, livemode, metadata, signedAmount, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { CUSTOMER_BALANCE_TRANSACTION_TYPES } from '../../vocabulary/invoices.js';
+import { currencyParam, shortText, signedAmountParam } from './params.js';
+/**
+ * The customer balance ledger (`cbtxn_…`, ADR 0018 §3): every movement of a
+ * customer's balance. Negative is credit the customer holds (Stripe's
+ * convention), applied to their next invoice when it finalizes.
+ */
+export const customerBalanceTransactionSchema = defineObject('customer_balance_transaction', 'CustomerBalanceTransaction', z
+    .object({
+    id: z.string(),
+    object: z.literal('customer_balance_transaction'),
+    livemode,
+    customer: expandable('customer', '`cus_…`, or the Customer with `expand[]=customer`.'),
+    type: z.enum(CUSTOMER_BALANCE_TRANSACTION_TYPES),
+    amount: signedAmount.describe('SIGNED: negative credits the customer, positive debits.'),
+    currency,
+    ending_balance: signedAmount.describe('SIGNED: the balance after this transaction.'),
+    description: z.string().nullable(),
+    invoice: expandable('invoice', 'The invoice it moved with (`in_…`, or the Invoice with `expand[]=invoice`).').nullable(),
+    credit_note: z.string().nullable().describe('The credit note (`cn_…`) it came from.'),
+    metadata,
+    created: unixSeconds,
+})
+    .strict());
+/** An adjustment: a negative `amount` credits the customer, a positive one adds to what they owe. */
+export const createCustomerBalanceTransactionParams = z
+    .object({
+    amount: signedAmountParam.describe('SIGNED: negative credits the customer, positive debits.'),
+    currency: currencyParam,
+    description: shortText(350).optional(),
+    metadata: metadataCreateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const listCustomerBalanceTransactionsQuery = listQuery({});
+const customerId = 'The customer (`cus_…`).';
+export const customerBalanceTransactionRoutes = [
+    defineRoute({
+        operationId: 'createCustomerBalanceTransaction',
+        method: 'post',
+        path: '/v1/customers/{id}/balance_transactions',
+        tag: 'Customer balance',
+        summary: "Adjust a customer's balance",
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: customerId },
+        body: createCustomerBalanceTransactionParams,
+        response: customerBalanceTransactionSchema,
+        sdk: 'customerBalanceTransactions.create',
+        expandable: 'customer_balance_transaction',
+    }),
+    defineRoute({
+        operationId: 'listCustomerBalanceTransactions',
+        method: 'get',
+        path: '/v1/customers/{id}/balance_transactions',
+        tag: 'Customer balance',
+        summary: "List a customer's balance transactions",
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: customerId },
+        query: listCustomerBalanceTransactionsQuery,
+        response: listOf(customerBalanceTransactionSchema),
+        sdk: 'customerBalanceTransactions.list',
+        expandable: 'customer_balance_transaction',
+    }),
+    defineRoute({
+        operationId: 'retrieveCustomerBalanceTransaction',
+        method: 'get',
+        path: '/v1/customers/{id}/balance_transactions/{transaction}',
+        tag: 'Customer balance',
+        summary: 'Retrieve a customer balance transaction',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: customerId, transaction: 'The balance transaction (`cbtxn_…`).' },
+        query: expandOnlyQuery,
+        response: customerBalanceTransactionSchema,
+        sdk: 'customerBalanceTransactions.retrieve',
+        expandable: 'customer_balance_transaction',
+    }),
+];

package/dist/esm/resources/billingEngine/index.js

@@ -0,0 +1,26 @@
+// Contracts of this group: one module per resource, re-exported here, and
+// their routes concatenated into `billingEngineRoutes`.
+import { billingPortalRoutes } from './billingPortal.js';
+import { creditNoteRoutes } from './creditNotes.js';
+import { customerBalanceTransactionRoutes } from './customerBalanceTransactions.js';
+import { invoiceItemRoutes } from './invoiceItems.js';
+import { invoiceRoutes } from './invoices.js';
+import { publicBillingRoutes } from './public.js';
+import { subscriptionRoutes } from './subscriptions.js';
+export * from './billingPortal.js';
+export * from './creditNotes.js';
+export * from './customerBalanceTransactions.js';
+export * from './invoiceItems.js';
+export * from './invoices.js';
+export * from './public.js';
+export * from './subscriptions.js';
+/** Orbit's native billing engine (ADR 0018): subscriptions, invoices, credit notes, the balance ledger and the customer portal. */
+export const billingEngineRoutes = [
+    ...subscriptionRoutes,
+    ...invoiceRoutes,
+    ...invoiceItemRoutes,
+    ...creditNoteRoutes,
+    ...customerBalanceTransactionRoutes,
+    ...billingPortalRoutes,
+    ...publicBillingRoutes,
+];

package/dist/esm/resources/billingEngine/invoiceItems.js

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+import { embedded } from '../../common/objects.js';
+import { priceDataParams } from '../catalog/prices.js';
+import { deletedOf, listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, expandParam, idParam, listQuery, metadataCreateParam, metadataUpdateParam, queryBoolean, unixSecondsParam, } from '../../common/params.js';
+import { amount, currency, livemode, metadata, signedAmount, unixSeconds, } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { amountParam, currencyParam, quantityParam, shortText } from './params.js';
+/**
+ * Invoice items (`ii_…`, ADR 0018 §2): a charge waiting for an invoice — a
+ * pending item is pulled into the customer's next invoice (a subscription's
+ * renewal, or a manual invoice with `pending_invoice_items_behavior=include`),
+ * or it is created directly on a draft.
+ */
+export const invoiceItemSchema = defineObject('invoiceitem', 'InvoiceItem', z
+    .object({
+    id: z.string(),
+    object: z.literal('invoiceitem'),
+    livemode,
+    customer: expandable('customer', '`cus_…`, or the Customer with `expand[]=customer`.'),
+    invoice: expandable('invoice', 'The draft it is on (`in_…`, or the Invoice with `expand[]=invoice`); `null` while pending.').nullable(),
+    subscription: expandable('subscription', '`sub_…`, or the Subscription with `expand[]=subscription`.').nullable(),
+    subscription_item: z.string().nullable(),
+    price: embedded('price', 'The Price, embedded; `null` for a fixed amount.').nullable(),
+    quantity: z.number().int().nonnegative(),
+    unit_amount: amount
+        .nullable()
+        .describe('Base units per unit; `null` for a proration (an amount for a period, not per unit).'),
+    amount: signedAmount.describe('SIGNED (an engine-made proration credit is negative).'),
+    currency,
+    description: z.string().nullable(),
+    discountable: z.boolean(),
+    period: z.object({ start: unixSeconds, end: unixSeconds }).strict(),
+    proration: z.boolean(),
+    metadata,
+    date: unixSeconds,
+})
+    .strict());
+export const deletedInvoiceItemSchema = defineComponent('DeletedInvoiceItem', deletedOf('invoiceitem'));
+/**
+ * A price (`price` or `price_data`) times `quantity`, or a fixed `amount` +
+ * `currency`. Never negative — a credit is a credit note or a customer balance
+ * transaction.
+ */
+export const createInvoiceItemParams = z
+    .object({
+    customer: idParam,
+    invoice: idParam.optional().describe('A draft to put it on; absent, it is pending.'),
+    subscription: idParam.optional(),
+    price: idParam.optional(),
+    price_data: priceDataParams
+        .optional()
+        .describe('A one-off per-unit price of an existing product, for an item that names no stored price.'),
+    quantity: quantityParam.optional(),
+    amount: amountParam.optional(),
+    currency: currencyParam.optional(),
+    description: shortText(500).optional(),
+    discountable: z.boolean().optional(),
+    period: z.object({ start: unixSecondsParam, end: unixSecondsParam }).strict().optional(),
+    metadata: metadataCreateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+/** Pending items, or items on a draft. A field sent as `""` is cleared; `metadata` is a patch. */
+export const updateInvoiceItemParams = z
+    .object({
+    description: z.union([shortText(500), z.literal('')]).optional(),
+    quantity: quantityParam.optional(),
+    discountable: z.boolean().optional(),
+    metadata: metadataUpdateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const listInvoiceItemsQuery = listQuery({
+    customer: idParam.optional(),
+    invoice: idParam.optional(),
+    pending: queryBoolean.optional().describe('Only items not on any invoice yet.'),
+});
+const invoiceItemId = { id: 'The invoice item (`ii_…`).' };
+export const invoiceItemRoutes = [
+    defineRoute({
+        operationId: 'createInvoiceItem',
+        method: 'post',
+        path: '/v1/invoiceitems',
+        tag: 'Invoice items',
+        summary: 'Create an invoice item',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createInvoiceItemParams,
+        response: invoiceItemSchema,
+        sdk: 'invoiceItems.create',
+        expandable: 'invoiceitem',
+    }),
+    defineRoute({
+        operationId: 'listInvoiceItems',
+        method: 'get',
+        path: '/v1/invoiceitems',
+        tag: 'Invoice items',
+        summary: 'List invoice items',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listInvoiceItemsQuery,
+        response: listOf(invoiceItemSchema),
+        sdk: 'invoiceItems.list',
+        expandable: 'invoiceitem',
+    }),
+    defineRoute({
+        operationId: 'retrieveInvoiceItem',
+        method: 'get',
+        path: '/v1/invoiceitems/{id}',
+        tag: 'Invoice items',
+        summary: 'Retrieve an invoice item',
+        auth: 'service',
+        scope: 'payments:read',
+        params: invoiceItemId,
+        query: expandOnlyQuery,
+        response: invoiceItemSchema,
+        sdk: 'invoiceItems.retrieve',
+        expandable: 'invoiceitem',
+    }),
+    defineRoute({
+        operationId: 'updateInvoiceItem',
+        method: 'post',
+        path: '/v1/invoiceitems/{id}',
+        tag: 'Invoice items',
+        summary: 'Update an invoice item',
+        description: 'While it is pending or on a draft.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: invoiceItemId,
+        body: updateInvoiceItemParams,
+        response: invoiceItemSchema,
+        sdk: 'invoiceItems.update',
+        expandable: 'invoiceitem',
+    }),
+    defineRoute({
+        operationId: 'deleteInvoiceItem',
+        method: 'delete',
+        path: '/v1/invoiceitems/{id}',
+        tag: 'Invoice items',
+        summary: 'Delete an invoice item',
+        description: 'While it is pending or on a draft.',
+        auth: 'service',
+        scope: 'payments:write',
+        params: invoiceItemId,
+        response: deletedInvoiceItemSchema,
+        sdk: 'invoiceItems.del',
+    }),
+];