@peable.to/contracts 0.3.0 → 1.0.0

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

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.customerRoutes = exports.listCustomersQuery = exports.updateCustomerParams = exports.createCustomerParams = exports.deletedCustomerSchema = exports.customerSchema = void 0;
+const zod_1 = require("zod");
+const address_1 = require("../../common/address");
+const envelopes_1 = require("../../common/envelopes");
+const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+/**
+ * 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.
+ */
+exports.customerSchema = (0, objects_1.defineObject)('customer', 'Customer', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('customer'),
+    livemode: primitives_1.livemode,
+    email: zod_1.z.string().nullable(),
+    name: zod_1.z.string().nullable(),
+    phone: zod_1.z.string().nullable(),
+    description: zod_1.z.string().nullable(),
+    address: address_1.addressSchema.nullable(),
+    shipping: address_1.shippingSchema.nullable(),
+    invoice_settings: zod_1.z
+        .object({
+        default_payment_method: (0, objects_1.expandable)('payment_method', '`pm_…`, or the PaymentMethod with `expand[]=invoice_settings.default_payment_method`.').nullable(),
+    })
+        .strict(),
+    metadata: primitives_1.metadata,
+    balance: primitives_1.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: primitives_1.currency
+        .nullable()
+        .describe("The customer's billing currency, set by its first balance movement, subscription or invoice."),
+    test_clock: zod_1.z
+        .string()
+        .nullable()
+        .describe('The test clock (`clock_…`) it lives on; test mode only.'),
+    created: primitives_1.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. */
+exports.deletedCustomerSchema = (0, objects_1.defineComponent)('DeletedCustomer', (0, envelopes_1.deletedOf)('customer'));
+const name = zod_1.z.string().max(500);
+const phone = zod_1.z.string().max(40);
+const description = zod_1.z.string().max(1000);
+exports.createCustomerParams = zod_1.z
+    .object({
+    email: address_1.emailParam.optional(),
+    name: name.optional(),
+    phone: phone.optional(),
+    description: description.optional(),
+    address: address_1.addressParams.optional(),
+    shipping: address_1.shippingParams.optional(),
+    invoice_settings: zod_1.z.object({ default_payment_method: params_1.idParam.optional() }).strict().optional(),
+    metadata: params_1.metadataCreateParam.optional(),
+    test_clock: params_1.idParam
+        .optional()
+        .describe('Create only, test mode only: attach the customer to a test clock (`clock_…`).'),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+/** A field sent as `""` is cleared; `metadata` is a patch. */
+exports.updateCustomerParams = zod_1.z
+    .object({
+    email: (0, params_1.clearable)(address_1.emailParam).optional(),
+    name: (0, params_1.clearable)(name).optional(),
+    phone: (0, params_1.clearable)(phone).optional(),
+    description: (0, params_1.clearable)(description).optional(),
+    address: (0, params_1.clearable)(address_1.addressParams).optional(),
+    shipping: (0, params_1.clearable)(address_1.shippingParams).optional(),
+    invoice_settings: zod_1.z
+        .object({ default_payment_method: (0, params_1.clearable)(params_1.idParam).optional() })
+        .strict()
+        .optional(),
+    metadata: params_1.metadataUpdateParam.optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+exports.listCustomersQuery = (0, params_1.listQuery)({
+    email: zod_1.z.string().min(1).max(512).optional().describe('Exact match.'),
+});
+const customerOrDeleted = zod_1.z.union([exports.customerSchema, exports.deletedCustomerSchema]);
+exports.customerRoutes = [
+    (0, route_1.defineRoute)({
+        operationId: 'createCustomer',
+        method: 'post',
+        path: '/v1/customers',
+        tag: 'Customers',
+        summary: 'Create a customer',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.createCustomerParams,
+        response: exports.customerSchema,
+        status: 201,
+        sdk: 'customers.create',
+        expandable: 'customer',
+    }),
+    (0, route_1.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: exports.listCustomersQuery,
+        response: (0, envelopes_1.listOf)(exports.customerSchema),
+        sdk: 'customers.list',
+        expandable: 'customer',
+    }),
+    (0, route_1.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: params_1.expandOnlyQuery,
+        response: customerOrDeleted,
+        sdk: 'customers.retrieve',
+        expandable: 'customer',
+    }),
+    (0, route_1.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: exports.updateCustomerParams,
+        response: exports.customerSchema,
+        sdk: 'customers.update',
+        expandable: 'customer',
+    }),
+    (0, route_1.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: exports.deletedCustomerSchema,
+        sdk: 'customers.del',
+    }),
+    (0, route_1.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: params_1.searchQuery,
+        response: (0, envelopes_1.searchResultOf)(exports.customerSchema),
+        sdk: 'customers.search',
+        expandable: 'customer',
+    }),
+];

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

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coreRoutes = void 0;
+const customers_1 = require("./customers");
+const paymentMethods_1 = require("./paymentMethods");
+__exportStar(require("./customers"), exports);
+__exportStar(require("./paymentMethods"), exports);
+/** Customers and their saved payment methods. */
+exports.coreRoutes = [...customers_1.customerRoutes, ...paymentMethods_1.paymentMethodRoutes];

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

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paymentMethodRoutes = exports.listPaymentMethodsQuery = exports.detachPaymentMethodParams = exports.updatePaymentMethodParams = exports.paymentMethodSchema = exports.billingDetailsSchema = exports.cardDetailsSchema = void 0;
+const zod_1 = require("zod");
+const address_1 = require("../../common/address");
+const envelopes_1 = require("../../common/envelopes");
+const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+/**
+ * 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. */
+exports.cardDetailsSchema = (0, objects_1.defineComponent)('CardDetails', zod_1.z
+    .object({
+    brand: zod_1.z.string().nullable(),
+    last4: zod_1.z.string().nullable(),
+    exp_month: zod_1.z.number().int().nullable(),
+    exp_year: zod_1.z.number().int().nullable(),
+    country: zod_1.z.string().nullable().describe('ISO 3166-1 alpha-2 of the issuer.'),
+    funding: zod_1.z.string().nullable().describe('`credit`, `debit`, `prepaid` or `unknown`.'),
+})
+    .strict());
+exports.billingDetailsSchema = (0, objects_1.defineComponent)('BillingDetails', zod_1.z
+    .object({
+    address: address_1.addressSchema.nullable(),
+    email: zod_1.z.string().nullable(),
+    name: zod_1.z.string().nullable(),
+    phone: zod_1.z.string().nullable(),
+})
+    .strict());
+exports.paymentMethodSchema = (0, objects_1.defineObject)('payment_method', 'PaymentMethod', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('payment_method'),
+    livemode: primitives_1.livemode,
+    type: zod_1.z.literal('card'),
+    card: exports.cardDetailsSchema,
+    billing_details: exports.billingDetailsSchema,
+    customer: (0, objects_1.expandable)('customer', '`cus_…`, or the Customer with `expand[]=customer`; `null` once detached.').nullable(),
+    metadata: primitives_1.metadata,
+    created: primitives_1.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.
+ */
+exports.updatePaymentMethodParams = zod_1.z
+    .object({
+    billing_details: zod_1.z
+        .object({
+        address: address_1.addressParams.optional(),
+        email: address_1.emailParam.optional(),
+        name: zod_1.z.string().max(500).optional(),
+        phone: zod_1.z.string().max(40).optional(),
+    })
+        .strict()
+        .optional(),
+    metadata: params_1.metadataUpdateParam.optional(),
+    expand: params_1.expandParam.optional(),
+})
+    .strict();
+exports.detachPaymentMethodParams = zod_1.z.object({ expand: params_1.expandParam.optional() }).strict();
+/** `customer` is REQUIRED: Stripe lists a customer's methods, never a merchant's whole wallet. */
+exports.listPaymentMethodsQuery = (0, params_1.listQuery)({
+    customer: params_1.idParam.describe('The customer (`cus_…`) whose methods to list.'),
+    type: zod_1.z.literal('card').optional(),
+});
+exports.paymentMethodRoutes = [
+    (0, route_1.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: exports.listPaymentMethodsQuery,
+        response: (0, envelopes_1.listOf)(exports.paymentMethodSchema),
+        sdk: 'paymentMethods.list',
+        expandable: 'payment_method',
+    }),
+    (0, route_1.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: params_1.expandOnlyQuery,
+        response: exports.paymentMethodSchema,
+        sdk: 'paymentMethods.retrieve',
+        expandable: 'payment_method',
+    }),
+    (0, route_1.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: exports.updatePaymentMethodParams,
+        response: exports.paymentMethodSchema,
+        sdk: 'paymentMethods.update',
+        expandable: 'payment_method',
+    }),
+    (0, route_1.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: exports.detachPaymentMethodParams,
+        response: exports.paymentMethodSchema,
+        sdk: 'paymentMethods.detach',
+        expandable: 'payment_method',
+    }),
+];