@peable.to/contracts 0.3.0 → 1.0.0

package/dist/esm/resources/connect/transfers.js

@@ -0,0 +1,224 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, idParam, listQuery } from '../../common/params.js';
+import { amount, livemode, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { TRANSFER_REVERSAL_STATUSES, TRANSFER_STATUSES } from '../../vocabulary/connect.js';
+import { isBaseUnitString } from '../../vocabulary/money.js';
+/**
+ * Transfers (`tr_…`) — a marketplace settling one seller out of a funded
+ * payment — and their reversals.
+ *
+ * The amounts come from the merchant and are recorded, never computed: Peable
+ * does not know what a marketplace fee is. The provider's own transfer id never
+ * crosses (ADR 0001 D3).
+ */
+export const transferSchema = defineObject('transfer', 'Transfer', z
+    .object({
+    id: z.string(),
+    object: z.literal('transfer'),
+    livemode,
+    external_ref: z
+        .string()
+        .describe("The merchant's OWN id for what this settles. Their idempotency."),
+    connected_account: expandable('connected_account', "The seller's `ca_…` — never their account id at the provider — or the ConnectedAccount with `expand[]=connected_account`."),
+    payment_intent: expandable('payment_intent', 'The `pi_…` this settlement was funded by, or the PaymentIntent with `expand[]=payment_intent`.'),
+    amount,
+    currency: z.string(),
+    amount_reversed: amount.describe("CUMULATIVE, in the units of `amount` — the provider's own total, never a sum of the reversals."),
+    status: z.enum(TRANSFER_STATUSES),
+    failure_message: z.string().nullable(),
+    created: unixSeconds,
+    updated_at: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'tr_0193b8f33c5a4b7e9d02',
+            object: 'transfer',
+            livemode: false,
+            external_ref: 'order_6735_seller_4821',
+            connected_account: 'ca_0193b8f2d4e1aa07c3b2',
+            payment_intent: 'pi_0193b8f2e8a14f6c9d31',
+            amount: '1700',
+            currency: 'EUR',
+            amount_reversed: '0',
+            status: 'paid',
+            failure_message: null,
+            created: 1793750400,
+            updated_at: 1793750402,
+        },
+    ],
+});
+/**
+ * One reversal operation. It exists as an object because an AMOUNT IS NOT AN
+ * IDENTITY: two reversals of one settlement for the same amount are two
+ * operations, and a caller needs to tell which one a response is about.
+ */
+export const transferReversalSchema = defineObject('transfer_reversal', 'TransferReversal', z
+    .object({
+    id: z.string(),
+    object: z.literal('transfer_reversal'),
+    livemode,
+    external_ref: z.string().describe("The merchant's own id for this reversal."),
+    amount,
+    currency: z.string(),
+    status: z.enum(TRANSFER_REVERSAL_STATUSES),
+    failure_message: z.string().nullable(),
+    created: unixSeconds,
+})
+    .strict());
+/** What `POST /v1/transfers/{transferId}/reversals` answers: the transfer, and the leg. */
+export const transferWithReversalSchema = defineComponent('TransferWithReversal', transferSchema.extend({ reversal: transferReversalSchema }).strict());
+/**
+ * A canonical base-unit integer string, validated with the SAME predicate the
+ * database CHECK is rendered from. A `z.number()` here would be a silent
+ * precision ceiling on a money value.
+ */
+const transferAmount = z
+    .string()
+    .refine(isBaseUnitString, "amount must be a canonical integer string in the currency's smallest unit")
+    // `'0'` passes the predicate above, and a zero transfer is not a transfer:
+    // it would consume the merchant's `external_ref`, so the REAL settlement of
+    // that order could never be created afterwards.
+    .refine((value) => value !== '0', 'a transfer of 0 is not a transfer');
+/**
+ * `POST /v1/transfers`: settle one seller out of a funded payment. The seller
+ * by exactly one of its two addresses; the currency is the payment's, never the
+ * request's (a transfer in another currency is an FX conversion nothing here
+ * performs).
+ */
+export const createTransferParams = z
+    .object({
+    payment_intent: z.string().min(1).describe('The `pi_…` this settles out of.'),
+    connected_account: z.string().min(1).optional().describe("The seller's `ca_…`."),
+    connected_account_ref: z
+        .string()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe('Or your own id for the seller (its `external_ref`).'),
+    external_ref: z
+        .string()
+        .min(1)
+        .max(255)
+        .describe('Your own id for what this settles — the idempotency: the same ref answers the stored settlement (200), a different payment or amount under it is a 409.'),
+    amount: transferAmount,
+})
+    .strict()
+    .refine((body) => Boolean(body.connected_account) !== Boolean(body.connected_account_ref), {
+    message: 'name the seller by exactly one of connected_account or connected_account_ref',
+});
+export const reverseTransferParams = z
+    .object({
+    amount: transferAmount,
+    // Required, and durable. It used to be satisfiable by the
+    // `Idempotency-Key` header instead; that header is now the generic 24-hour
+    // retry layer (ADR 0014 D3), which the SDK fills with a fresh uuid per call
+    // — accepting it here would hand every un-referenced reversal a random
+    // identity, and an application's own retry a second reversal.
+    external_ref: z
+        .string()
+        .min(1)
+        .max(255)
+        .describe('Your own id for THIS reversal — required and durable: two reversals for the same amount are two operations.'),
+})
+    .strict();
+export const listTransfersQuery = listQuery({
+    payment_intent: idParam.optional().describe('Only the settlements of this payment (`pi_…`).'),
+    connected_account: idParam.optional().describe('Only the settlements to this seller (`ca_…`).'),
+});
+/** The per-payment list: the payment is in the path. */
+export const listPaymentIntentTransfersQuery = listQuery({});
+const transferIdParam = { transferId: 'The transfer (`tr_…`).' };
+export const transferRoutes = [
+    defineRoute({
+        operationId: 'createTransfer',
+        method: 'post',
+        path: '/v1/transfers',
+        tag: 'Transfers',
+        summary: 'Create a transfer',
+        description: 'Settles one seller out of a funded payment (201). An order already settled answers the stored settlement (200): a merchant retrying after a timeout needs to know whether they just paid a seller twice.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createTransferParams,
+        response: transferSchema,
+        status: 201,
+        sdk: 'transfers.create',
+    }),
+    defineRoute({
+        operationId: 'createTransferReversal',
+        method: 'post',
+        path: '/v1/transfers/{transferId}/reversals',
+        tag: 'Transfers',
+        summary: 'Reverse a transfer',
+        description: 'Takes some or all of a settlement back (201), or answers the reversal this `external_ref` already made (200).',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: transferIdParam,
+        body: reverseTransferParams,
+        response: transferWithReversalSchema,
+        status: 201,
+        sdk: 'transfers.reverse',
+    }),
+    defineRoute({
+        operationId: 'listTransferReversals',
+        method: 'get',
+        path: '/v1/transfers/{transferId}/reversals',
+        tag: 'Transfers',
+        summary: "List a transfer's reversals",
+        description: 'Newest first. A complete set (`has_more: false`): a settlement can only be reversed down to zero.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: transferIdParam,
+        query: expandOnlyQuery,
+        response: listOf(transferReversalSchema),
+        sdk: 'transfers.listReversals',
+    }),
+    defineRoute({
+        operationId: 'listTransfers',
+        method: 'get',
+        path: '/v1/transfers',
+        tag: 'Transfers',
+        summary: 'List transfers',
+        description: 'Newest first, narrowed by `payment_intent` and/or `connected_account`.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listTransfersQuery,
+        response: listOf(transferSchema),
+        sdk: 'transfers.list',
+        expandable: 'transfer',
+    }),
+    defineRoute({
+        operationId: 'retrieveTransfer',
+        method: 'get',
+        path: '/v1/transfers/{transferId}',
+        tag: 'Transfers',
+        summary: 'Retrieve a transfer',
+        auth: 'service',
+        scope: 'payments:read',
+        params: transferIdParam,
+        query: expandOnlyQuery,
+        response: transferSchema,
+        sdk: 'transfers.retrieve',
+        expandable: 'transfer',
+    }),
+    defineRoute({
+        operationId: 'listPaymentIntentTransfers',
+        method: 'get',
+        path: '/v1/payment_intents/{intentId}/transfers',
+        tag: 'Transfers',
+        summary: "List a payment's transfers",
+        description: 'What one payment settled, newest first. The reconciliation read.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { intentId: 'The payment intent (`pi_…`).' },
+        query: listPaymentIntentTransfersQuery,
+        response: listOf(transferSchema),
+        sdk: 'transfers.listForPaymentIntent',
+        expandable: 'transfer',
+    }),
+];

package/dist/esm/resources/core/customers.js

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+import { addressParams, addressSchema, emailParam, shippingParams, shippingSchema, } from '../../common/address.js';
+import { deletedOf, listOf, searchResultOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { clearable, expandOnlyQuery, expandParam, idParam, listQuery, metadataCreateParam, metadataUpdateParam, searchQuery, } from '../../common/params.js';
+import { currency, livemode, metadata, signedAmount, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+/**
+ * Customers (`cus_…`) — Orbit's own object (ADR 0016). A provider customer is an
+ * internal binding created lazily, per mode, when a card payment method is
+ * first attached; it is never serialized.
+ */
+export const customerSchema = defineObject('customer', 'Customer', z
+    .object({
+    id: z.string(),
+    object: z.literal('customer'),
+    livemode,
+    email: z.string().nullable(),
+    name: z.string().nullable(),
+    phone: z.string().nullable(),
+    description: z.string().nullable(),
+    address: addressSchema.nullable(),
+    shipping: shippingSchema.nullable(),
+    invoice_settings: z
+        .object({
+        default_payment_method: expandable('payment_method', '`pm_…`, or the PaymentMethod with `expand[]=invoice_settings.default_payment_method`.').nullable(),
+    })
+        .strict(),
+    metadata,
+    balance: signedAmount.describe('SIGNED base units in `currency`: negative is credit the customer holds, positive is owed. Applied to the next invoice when it finalizes.'),
+    currency: currency
+        .nullable()
+        .describe("The customer's billing currency, set by its first balance movement, subscription or invoice."),
+    test_clock: z
+        .string()
+        .nullable()
+        .describe('The test clock (`clock_…`) it lives on; test mode only.'),
+    created: unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'cus_0193b8f2c1a87d3e9f4a',
+            object: 'customer',
+            livemode: false,
+            email: 'jenny@example.com',
+            name: 'Jenny Rosen',
+            phone: null,
+            description: null,
+            address: null,
+            shipping: null,
+            invoice_settings: { default_payment_method: null },
+            metadata: { order_id: '6735' },
+            balance: '0',
+            currency: 'EUR',
+            test_clock: null,
+            created: 1793750400,
+        },
+    ],
+});
+/** A deleted customer: a tombstone that still retrieves. */
+export const deletedCustomerSchema = defineComponent('DeletedCustomer', deletedOf('customer'));
+const name = z.string().max(500);
+const phone = z.string().max(40);
+const description = z.string().max(1000);
+export const createCustomerParams = z
+    .object({
+    email: emailParam.optional(),
+    name: name.optional(),
+    phone: phone.optional(),
+    description: description.optional(),
+    address: addressParams.optional(),
+    shipping: shippingParams.optional(),
+    invoice_settings: z.object({ default_payment_method: idParam.optional() }).strict().optional(),
+    metadata: metadataCreateParam.optional(),
+    test_clock: idParam
+        .optional()
+        .describe('Create only, test mode only: attach the customer to a test clock (`clock_…`).'),
+    expand: expandParam.optional(),
+})
+    .strict();
+/** A field sent as `""` is cleared; `metadata` is a patch. */
+export const updateCustomerParams = z
+    .object({
+    email: clearable(emailParam).optional(),
+    name: clearable(name).optional(),
+    phone: clearable(phone).optional(),
+    description: clearable(description).optional(),
+    address: clearable(addressParams).optional(),
+    shipping: clearable(shippingParams).optional(),
+    invoice_settings: z
+        .object({ default_payment_method: clearable(idParam).optional() })
+        .strict()
+        .optional(),
+    metadata: metadataUpdateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const listCustomersQuery = listQuery({
+    email: z.string().min(1).max(512).optional().describe('Exact match.'),
+});
+const customerOrDeleted = z.union([customerSchema, deletedCustomerSchema]);
+export const customerRoutes = [
+    defineRoute({
+        operationId: 'createCustomer',
+        method: 'post',
+        path: '/v1/customers',
+        tag: 'Customers',
+        summary: 'Create a customer',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: createCustomerParams,
+        response: customerSchema,
+        status: 201,
+        sdk: 'customers.create',
+        expandable: 'customer',
+    }),
+    defineRoute({
+        operationId: 'listCustomers',
+        method: 'get',
+        path: '/v1/customers',
+        tag: 'Customers',
+        summary: 'List customers',
+        description: 'Your live customers, newest first. Deleted customers are not listed.',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listCustomersQuery,
+        response: listOf(customerSchema),
+        sdk: 'customers.list',
+        expandable: 'customer',
+    }),
+    defineRoute({
+        operationId: 'retrieveCustomer',
+        method: 'get',
+        path: '/v1/customers/{id}',
+        tag: 'Customers',
+        summary: 'Retrieve a customer',
+        description: 'A deleted customer answers `{ id, object: "customer", deleted: true }`.',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The customer (`cus_…`).' },
+        query: expandOnlyQuery,
+        response: customerOrDeleted,
+        sdk: 'customers.retrieve',
+        expandable: 'customer',
+    }),
+    defineRoute({
+        operationId: 'updateCustomer',
+        method: 'post',
+        path: '/v1/customers/{id}',
+        tag: 'Customers',
+        summary: 'Update a customer',
+        description: 'A field sent as `""` is cleared; `metadata` is a patch.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The customer (`cus_…`).' },
+        body: updateCustomerParams,
+        response: customerSchema,
+        sdk: 'customers.update',
+        expandable: 'customer',
+    }),
+    defineRoute({
+        operationId: 'deleteCustomer',
+        method: 'delete',
+        path: '/v1/customers/{id}',
+        tag: 'Customers',
+        summary: 'Delete a customer',
+        description: 'A tombstone, with every saved payment method of the customer detached. Deleting a deleted customer answers the tombstone again.',
+        auth: 'service',
+        scope: 'payments:write',
+        params: { id: 'The customer (`cus_…`).' },
+        response: deletedCustomerSchema,
+        sdk: 'customers.del',
+    }),
+    defineRoute({
+        operationId: 'searchCustomers',
+        method: 'get',
+        path: '/v1/customers/search',
+        tag: 'Customers',
+        summary: 'Search customers',
+        description: "Stripe's query language over `email`, `name`, `phone`, `created` and `metadata['key']`.",
+        auth: 'service',
+        scope: 'payments:read',
+        query: searchQuery,
+        response: searchResultOf(customerSchema),
+        sdk: 'customers.search',
+        expandable: 'customer',
+    }),
+];

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

@@ -0,0 +1,6 @@
+import { customerRoutes } from './customers.js';
+import { paymentMethodRoutes } from './paymentMethods.js';
+export * from './customers.js';
+export * from './paymentMethods.js';
+/** Customers and their saved payment methods. */
+export const coreRoutes = [...customerRoutes, ...paymentMethodRoutes];

package/dist/esm/resources/core/paymentMethods.js

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+import { addressParams, addressSchema, emailParam } from '../../common/address.js';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent, defineObject, expandable } from '../../common/objects.js';
+import { expandOnlyQuery, expandParam, idParam, listQuery, metadataUpdateParam, } from '../../common/params.js';
+import { livemode, metadata, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+/**
+ * PaymentMethods (`pm_…`) — Peable's wrapper over a provider payment method
+ * (ADR 0016). Card details are collected by the provider's own Elements in the
+ * browser; the card number never reaches Peable. A FairCoin customer has no
+ * payment method: signing stays on the payer's device.
+ */
+/** Card details safe to show: never the number, never the CVC. */
+export const cardDetailsSchema = defineComponent('CardDetails', z
+    .object({
+    brand: z.string().nullable(),
+    last4: z.string().nullable(),
+    exp_month: z.number().int().nullable(),
+    exp_year: z.number().int().nullable(),
+    country: z.string().nullable().describe('ISO 3166-1 alpha-2 of the issuer.'),
+    funding: z.string().nullable().describe('`credit`, `debit`, `prepaid` or `unknown`.'),
+})
+    .strict());
+export const billingDetailsSchema = defineComponent('BillingDetails', z
+    .object({
+    address: addressSchema.nullable(),
+    email: z.string().nullable(),
+    name: z.string().nullable(),
+    phone: z.string().nullable(),
+})
+    .strict());
+export const paymentMethodSchema = defineObject('payment_method', 'PaymentMethod', z
+    .object({
+    id: z.string(),
+    object: z.literal('payment_method'),
+    livemode,
+    type: z.literal('card'),
+    card: cardDetailsSchema,
+    billing_details: billingDetailsSchema,
+    customer: expandable('customer', '`cus_…`, or the Customer with `expand[]=customer`; `null` once detached.').nullable(),
+    metadata,
+    created: unixSeconds,
+})
+    .strict());
+/**
+ * Billing details (each named field replaces that field) and metadata (a
+ * patch). Orbit's record of the card holder; the provider's copy is not
+ * rewritten — the card was verified against what the payer entered there.
+ */
+export const updatePaymentMethodParams = z
+    .object({
+    billing_details: z
+        .object({
+        address: addressParams.optional(),
+        email: emailParam.optional(),
+        name: z.string().max(500).optional(),
+        phone: z.string().max(40).optional(),
+    })
+        .strict()
+        .optional(),
+    metadata: metadataUpdateParam.optional(),
+    expand: expandParam.optional(),
+})
+    .strict();
+export const detachPaymentMethodParams = z.object({ expand: expandParam.optional() }).strict();
+/** `customer` is REQUIRED: Stripe lists a customer's methods, never a merchant's whole wallet. */
+export const listPaymentMethodsQuery = listQuery({
+    customer: idParam.describe('The customer (`cus_…`) whose methods to list.'),
+    type: z.literal('card').optional(),
+});
+export const paymentMethodRoutes = [
+    defineRoute({
+        operationId: 'listPaymentMethods',
+        method: 'get',
+        path: '/v1/payment_methods',
+        tag: 'Payment methods',
+        summary: "List a customer's payment methods",
+        auth: 'service',
+        scope: 'payments:read',
+        query: listPaymentMethodsQuery,
+        response: listOf(paymentMethodSchema),
+        sdk: 'paymentMethods.list',
+        expandable: 'payment_method',
+    }),
+    defineRoute({
+        operationId: 'retrievePaymentMethod',
+        method: 'get',
+        path: '/v1/payment_methods/{id}',
+        tag: 'Payment methods',
+        summary: 'Retrieve a payment method',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The payment method (`pm_…`).' },
+        query: expandOnlyQuery,
+        response: paymentMethodSchema,
+        sdk: 'paymentMethods.retrieve',
+        expandable: 'payment_method',
+    }),
+    defineRoute({
+        operationId: 'updatePaymentMethod',
+        method: 'post',
+        path: '/v1/payment_methods/{id}',
+        tag: 'Payment methods',
+        summary: 'Update a payment method',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The payment method (`pm_…`).' },
+        body: updatePaymentMethodParams,
+        response: paymentMethodSchema,
+        sdk: 'paymentMethods.update',
+        expandable: 'payment_method',
+    }),
+    defineRoute({
+        operationId: 'detachPaymentMethod',
+        method: 'post',
+        path: '/v1/payment_methods/{id}/detach',
+        tag: 'Payment methods',
+        summary: 'Detach a payment method',
+        description: 'Permanently. A second detach answers the detached method.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        params: { id: 'The payment method (`pm_…`).' },
+        body: detachPaymentMethodParams,
+        response: paymentMethodSchema,
+        sdk: 'paymentMethods.detach',
+        expandable: 'payment_method',
+    }),
+];