@peable.to/contracts 0.4.0 → 1.0.0

package/dist/cjs/resources/checkout/contributions.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contributionRoutes = exports.contributionPatchSchema = exports.contributionOperationKeySchema = exports.contributionMintSchema = exports.contributionPageQuerySchema = exports.contributionScopeQuerySchema = exports.contributionCollectionListSchema = exports.contributionCollectionSchema = exports.contributionListSchema = exports.contributionLinkSchema = exports.createContributionSchema = exports.contributionDetailsSchema = exports.contributionAmountSchema = void 0;
+exports.decimalContributionAmount = decimalContributionAmount;
+exports.formatContributionAmount = formatContributionAmount;
+const zod_1 = require("zod");
+const envelopes_1 = require("../../common/envelopes");
+const objects_1 = require("../../common/objects");
+const params_1 = require("../../common/params");
+const route_1 = require("../../route");
+const merchants_1 = require("../../vocabulary/merchants");
+/**
+ * Organization contributions — an Oxy organization's FairCoin collection,
+ * managed by its members with their Oxy USER session (never a merchant service
+ * token). A contribution is a payment link whose one line is the contribution
+ * itself: a fixed amount, or one the payer chooses.
+ *
+ * Zod-light on purpose: `@peable.to/contracts/contributions` re-exports this
+ * module for the hosted checkout and Orbit, which must not construct every
+ * schema of the API.
+ */
+const FAIR_UNITS_PER_COIN = 100000000n;
+/** A FairCoin base-unit amount a contribution can carry: positive, within a JS-safe integer. */
+exports.contributionAmountSchema = zod_1.z
+    .string()
+    .regex(/^[1-9][0-9]{0,15}$/)
+    .refine((v) => /^[1-9][0-9]{0,15}$/.test(v) && BigInt(v) <= 9007199254740991n, 'Enter a positive FairCoin base-unit amount within the supported range');
+/** Every instant on the wire is integer Unix seconds (ADR 0014 D1). */
+const unixSecondsSchema = zod_1.z.number().int().nonnegative();
+exports.contributionDetailsSchema = (0, objects_1.defineComponent)('ContributionDetails', zod_1.z
+    .object({
+    organization_id: zod_1.z.string().min(1).max(200).describe('The Oxy organization collecting.'),
+    purpose: zod_1.z.string().trim().min(1).max(500),
+    amount_mode: zod_1.z
+        .enum(['fixed', 'free'])
+        .describe('`fixed`: the link names the amount; `free`: the payer chooses it.'),
+    expires_at: unixSecondsSchema.nullable(),
+})
+    .strict());
+exports.createContributionSchema = zod_1.z
+    .object({
+    purpose: exports.contributionDetailsSchema.shape.purpose,
+    amount_mode: exports.contributionDetailsSchema.shape.amount_mode,
+    amount: exports.contributionAmountSchema.optional(),
+    currency: zod_1.z.literal('FAIR'),
+    expires_at: unixSecondsSchema.nullable().optional(),
+})
+    .strict()
+    .refine((v) => (v.amount_mode === 'free' ? v.amount === undefined : v.amount !== undefined), 'Fixed contributions require an amount; free contributions omit it');
+/** A contribution link, as its members manage it. */
+exports.contributionLinkSchema = (0, objects_1.defineComponent)('ContributionLink', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('payment_link'),
+    amount: zod_1.z.string().describe('FAIR base units; `"0"` when the payer chooses.'),
+    currency: zod_1.z.literal('FAIR'),
+    network: zod_1.z.enum(['mainnet', 'testnet']),
+    active: zod_1.z.boolean(),
+    url: zod_1.z.url().describe('The hosted link to share.'),
+    contribution: exports.contributionDetailsSchema,
+    created: unixSecondsSchema,
+})
+    .strict());
+exports.contributionListSchema = (0, envelopes_1.listOf)(exports.contributionLinkSchema);
+/** A payment made through a contribution link. Non-custodial: Peable cannot refund it. */
+exports.contributionCollectionSchema = (0, objects_1.defineComponent)('ContributionCollection', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('payment_intent'),
+    amount: zod_1.z.string(),
+    currency: zod_1.z.literal('FAIR'),
+    status: zod_1.z.string(),
+    created: unixSecondsSchema,
+    refund_capability: zod_1.z.literal('unsupported_non_custodial'),
+    refunds: zod_1.z.array(zod_1.z
+        .object({
+        id: zod_1.z.string(),
+        object: zod_1.z.literal('refund'),
+        amount: zod_1.z.string(),
+        status: zod_1.z.string(),
+        created: unixSecondsSchema,
+    })
+        .strict()),
+})
+    .strict());
+exports.contributionCollectionListSchema = (0, envelopes_1.listOf)(exports.contributionCollectionSchema);
+/** The environment the Test/Live toggle selects: the application's merchant in it is the scope. */
+const environmentParam = zod_1.z
+    .enum(merchants_1.MERCHANT_ENVIRONMENTS)
+    .describe("Which of the application's merchants: its Test/Live toggle.");
+/** The query of every contribution write: the environment and nothing else. */
+exports.contributionScopeQuerySchema = zod_1.z.object({ environment: environmentParam }).strict();
+/**
+ * Paging a contribution list: the list parameters every list accepts
+ * (`link_…` cursors for links, `pi_…` for collections) plus the environment.
+ */
+exports.contributionPageQuerySchema = (0, params_1.listQuery)({ environment: environmentParam });
+/** What a payer may say when starting a free contribution's checkout. */
+exports.contributionMintSchema = zod_1.z
+    .object({ amount: exports.contributionAmountSchema.optional() })
+    .strict();
+/** A contribution start's `Idempotency-Key`: a UUID the page writes before the request. */
+exports.contributionOperationKeySchema = zod_1.z.uuid();
+exports.contributionPatchSchema = zod_1.z.object({ active: zod_1.z.boolean() }).strict();
+/** `"1.25"` FAIR → `"125000000"` base units, with exact integer arithmetic. */
+function decimalContributionAmount(value) {
+    if (!/^(0|[1-9][0-9]{0,7})(\.[0-9]{1,8})?$/.test(value))
+        throw new Error('Enter a FAIR amount with at most eight decimals');
+    const [whole = '0', fraction = ''] = value.split('.');
+    return exports.contributionAmountSchema.parse((BigInt(whole) * FAIR_UNITS_PER_COIN + BigInt(fraction.padEnd(8, '0'))).toString());
+}
+/** Base units → the shortest exact FAIR decimal. */
+function formatContributionAmount(value) {
+    const units = BigInt(value);
+    const fraction = (units % FAIR_UNITS_PER_COIN).toString().padStart(8, '0').replace(/0+$/, '');
+    return (units / FAIR_UNITS_PER_COIN).toString() + (fraction ? `.${fraction}` : '');
+}
+const scopeParams = {
+    organizationId: 'The Oxy organization.',
+    applicationId: "The organization's Oxy application whose merchant collects.",
+};
+const root = '/v1/organizations/{organizationId}/applications/{applicationId}/contributions';
+exports.contributionRoutes = [
+    (0, route_1.defineRoute)({
+        operationId: 'createContribution',
+        method: 'post',
+        path: root,
+        tag: 'Contributions',
+        summary: 'Create a contribution link',
+        description: 'Requires a UUID `Idempotency-Key` header: the operation key, so a retry after a lost answer returns the same link.',
+        auth: 'user',
+        params: scopeParams,
+        query: exports.contributionScopeQuerySchema,
+        body: exports.createContributionSchema,
+        response: exports.contributionLinkSchema,
+        status: 201,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listContributions',
+        method: 'get',
+        path: root,
+        tag: 'Contributions',
+        summary: "List an organization's contribution links",
+        auth: 'user',
+        params: scopeParams,
+        query: exports.contributionPageQuerySchema,
+        response: exports.contributionListSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'updateContribution',
+        method: 'post',
+        path: `${root}/{id}`,
+        tag: 'Contributions',
+        summary: 'Enable or disable a contribution link',
+        auth: 'user',
+        params: { ...scopeParams, id: 'The contribution link (`link_…`).' },
+        query: exports.contributionScopeQuerySchema,
+        body: exports.contributionPatchSchema,
+        response: exports.contributionLinkSchema,
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listContributionCollections',
+        method: 'get',
+        path: `${root}/{id}/collections`,
+        tag: 'Contributions',
+        summary: 'List the payments made through a contribution link',
+        auth: 'user',
+        params: { ...scopeParams, id: 'The contribution link (`link_…`).' },
+        query: exports.contributionPageQuerySchema,
+        response: exports.contributionCollectionListSchema,
+    }),
+];

package/dist/cjs/resources/checkout/files.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileRoutes = exports.listFilesQuery = exports.createFileFromOxyParams = exports.createFileUploadParams = exports.fileSchema = void 0;
+const zod_1 = require("zod");
+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");
+const files_1 = require("../../vocabulary/files");
+/**
+ * Files (`file_…`) — bytes a merchant gives Orbit for one stated purpose
+ * (ADR 0016: Orbit owns the object; the storage is Oxy Files, a binding that
+ * never reaches the wire). Stripe's Files API, with Oxy Files underneath.
+ */
+exports.fileSchema = (0, objects_1.defineObject)('file', 'File', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('file'),
+    livemode: primitives_1.livemode,
+    purpose: zod_1.z.enum(files_1.FILE_PURPOSES),
+    filename: zod_1.z
+        .string()
+        .nullable()
+        .describe('The name it was uploaded with, if it had a printable one.'),
+    size: zod_1.z.number().int().nonnegative().describe('Bytes.'),
+    type: zod_1.z.enum(files_1.FILE_TYPES),
+    status: zod_1.z.enum(files_1.FILE_STATUSES),
+    url: zod_1.z
+        .string()
+        .nullable()
+        .describe('Where the bytes can be read while the file is `available`: a public URL for a `business_logo`, `GET /v1/files/{id}/contents` for a `finance_report_run`. `null` for every other purpose — evidence and identity documents are never addressable by URL.'),
+    created: primitives_1.unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'file_0193b8f2c1a87d3e9f4a',
+            object: 'file',
+            livemode: false,
+            purpose: 'business_logo',
+            filename: 'logo.png',
+            size: 18432,
+            type: 'png',
+            status: 'available',
+            url: 'https://cloud.oxy.so/assets/0193b8f2c1a87d3e9f4b',
+            created: 1793750400,
+        },
+    ],
+});
+/**
+ * `POST /v1/files` as `multipart/form-data`: a `purpose` field and a `file`
+ * part. The gateway reads the form itself, bounded by the largest purpose's
+ * ceiling, and checks each part with these schemas.
+ */
+exports.createFileUploadParams = zod_1.z
+    .object({
+    purpose: zod_1.z.enum(files_1.FILE_UPLOAD_PURPOSES, {
+        error: `purpose must be one of ${files_1.FILE_UPLOAD_PURPOSES.join(', ')}`,
+    }),
+    file: zod_1.z.file({ error: 'file is required' }).describe('The bytes, with their filename.'),
+})
+    .strict();
+/**
+ * `POST /v1/files` as JSON: an Oxy file the caller already owns (their
+ * application's, or an account they are or act for). Its ownership is checked
+ * once, here, and never again.
+ */
+exports.createFileFromOxyParams = zod_1.z
+    .object({
+    purpose: zod_1.z.enum(files_1.FILE_UPLOAD_PURPOSES),
+    oxy_file: zod_1.z.string().min(1).max(128).describe('The Oxy file id.'),
+})
+    .strict();
+exports.listFilesQuery = (0, params_1.listQuery)({ purpose: zod_1.z.enum(files_1.FILE_PURPOSES).optional() });
+exports.fileRoutes = [
+    (0, route_1.defineRoute)({
+        operationId: 'createFile',
+        method: 'post',
+        path: '/v1/files',
+        tag: 'Files',
+        summary: 'Upload a file',
+        description: 'The bytes as `multipart/form-data` (`purpose`, `file`), or — as JSON — `{ purpose, oxy_file }` to import an Oxy file you own. The type is recognised from the bytes, never from a `Content-Type`; each purpose has its own formats and size ceiling.',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.createFileUploadParams,
+        bodyEncoding: 'multipart',
+        response: exports.fileSchema,
+        sdk: 'files.create',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'listFiles',
+        method: 'get',
+        path: '/v1/files',
+        tag: 'Files',
+        summary: 'List files',
+        auth: 'service',
+        scope: 'payments:read',
+        query: exports.listFilesQuery,
+        response: (0, envelopes_1.listOf)(exports.fileSchema),
+        sdk: 'files.list',
+        expandable: 'file',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveFile',
+        method: 'get',
+        path: '/v1/files/{id}',
+        tag: 'Files',
+        summary: 'Retrieve a file',
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The file (`file_…`).' },
+        query: params_1.expandOnlyQuery,
+        response: exports.fileSchema,
+        sdk: 'files.retrieve',
+        expandable: 'file',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveFileContents',
+        method: 'get',
+        path: '/v1/files/{id}/contents',
+        tag: 'Files',
+        summary: "Download a file's contents",
+        description: "The bytes of a file you read back — a report run's CSV — as an attachment. Any other purpose answers 404: evidence and identity documents leave Peable only to their provider.",
+        auth: 'service',
+        scope: 'payments:read',
+        params: { id: 'The file (`file_…`).' },
+        query: params_1.emptyQuery,
+        response: { kind: 'binary', contentType: 'text/csv' },
+        sdk: 'files.contents',
+    }),
+];

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

@@ -0,0 +1,57 @@
+"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.checkoutRoutes = exports.merchantDisplaySchema = exports.customFieldsParam = exports.checkoutTotalDetailsSchema = exports.checkoutTaxIdSchema = exports.checkoutShippingDetailsSchema = exports.checkoutLineItemSchema = exports.checkoutDiscountSchema = exports.checkoutCustomFieldSchema = exports.checkoutCustomerDetailsSchema = exports.checkoutConsentSchema = exports.checkoutConsentCollectionSchema = exports.checkoutBrandingSchema = exports.checkoutAutomaticTaxSchema = exports.checkoutAdjustableQuantitySchema = exports.adjustableBoundsOf = void 0;
+const checkoutSessions_1 = require("./checkoutSessions");
+const contributions_1 = require("./contributions");
+const files_1 = require("./files");
+const merchants_1 = require("./merchants");
+const paymentLinks_1 = require("./paymentLinks");
+const paymentMethodConfigurations_1 = require("./paymentMethodConfigurations");
+__exportStar(require("./checkoutSessions"), exports);
+__exportStar(require("./contributions"), exports);
+__exportStar(require("./files"), exports);
+__exportStar(require("./merchants"), exports);
+__exportStar(require("./paymentLinks"), exports);
+__exportStar(require("./paymentMethodConfigurations"), exports);
+// The shared building blocks' public half: the sub-objects sessions and links
+// return, and what a backend needs to store a parsed request. The rest of
+// `./shared` (rail, locale, URL and amount params) stays internal to checkout.
+var shared_1 = require("./shared");
+Object.defineProperty(exports, "adjustableBoundsOf", { enumerable: true, get: function () { return shared_1.adjustableBoundsOf; } });
+Object.defineProperty(exports, "checkoutAdjustableQuantitySchema", { enumerable: true, get: function () { return shared_1.checkoutAdjustableQuantitySchema; } });
+Object.defineProperty(exports, "checkoutAutomaticTaxSchema", { enumerable: true, get: function () { return shared_1.checkoutAutomaticTaxSchema; } });
+Object.defineProperty(exports, "checkoutBrandingSchema", { enumerable: true, get: function () { return shared_1.checkoutBrandingSchema; } });
+Object.defineProperty(exports, "checkoutConsentCollectionSchema", { enumerable: true, get: function () { return shared_1.checkoutConsentCollectionSchema; } });
+Object.defineProperty(exports, "checkoutConsentSchema", { enumerable: true, get: function () { return shared_1.checkoutConsentSchema; } });
+Object.defineProperty(exports, "checkoutCustomerDetailsSchema", { enumerable: true, get: function () { return shared_1.checkoutCustomerDetailsSchema; } });
+Object.defineProperty(exports, "checkoutCustomFieldSchema", { enumerable: true, get: function () { return shared_1.checkoutCustomFieldSchema; } });
+Object.defineProperty(exports, "checkoutDiscountSchema", { enumerable: true, get: function () { return shared_1.checkoutDiscountSchema; } });
+Object.defineProperty(exports, "checkoutLineItemSchema", { enumerable: true, get: function () { return shared_1.checkoutLineItemSchema; } });
+Object.defineProperty(exports, "checkoutShippingDetailsSchema", { enumerable: true, get: function () { return shared_1.checkoutShippingDetailsSchema; } });
+Object.defineProperty(exports, "checkoutTaxIdSchema", { enumerable: true, get: function () { return shared_1.checkoutTaxIdSchema; } });
+Object.defineProperty(exports, "checkoutTotalDetailsSchema", { enumerable: true, get: function () { return shared_1.checkoutTotalDetailsSchema; } });
+Object.defineProperty(exports, "customFieldsParam", { enumerable: true, get: function () { return shared_1.customFieldsParam; } });
+Object.defineProperty(exports, "merchantDisplaySchema", { enumerable: true, get: function () { return shared_1.merchantDisplaySchema; } });
+/** Checkout, payment links, the merchant and its branding, files and contributions. */
+exports.checkoutRoutes = [
+    ...checkoutSessions_1.checkoutSessionRoutes,
+    ...paymentLinks_1.paymentLinkRoutes,
+    ...paymentMethodConfigurations_1.paymentMethodConfigurationRoutes,
+    ...merchants_1.merchantRoutes,
+    ...files_1.fileRoutes,
+    ...contributions_1.contributionRoutes,
+];

package/dist/cjs/resources/checkout/merchants.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.merchantRoutes = exports.updateMerchantEmailSettingsParams = exports.merchantEmailSettingsSchema = exports.updateMerchantBrandingParams = exports.merchantBrandingSchema = exports.updateMerchantParams = exports.registerMerchantParams = exports.merchantSchema = void 0;
+const zod_1 = require("zod");
+const objects_1 = require("../../common/objects");
+const primitives_1 = require("../../common/primitives");
+const route_1 = require("../../route");
+const merchants_1 = require("../../vocabulary/merchants");
+/**
+ * The merchant (`merch_…`) — one per Oxy application and environment — with
+ * its branding and customer-email settings. `next_derivation_index` is never
+ * on the wire: it is an internal derivation counter with no meaning to an
+ * integration. Where events go is not a merchant field: it is the
+ * `webhook_endpoint` resource.
+ */
+exports.merchantSchema = (0, objects_1.defineObject)('merchant', 'Merchant', zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    object: zod_1.z.literal('merchant'),
+    livemode: primitives_1.livemode.describe('`true` for a `production` merchant (ADR 0017).'),
+    oxy_app_id: zod_1.z.string().describe('The Oxy application this merchant belongs to.'),
+    environment: zod_1.z.enum(merchants_1.MERCHANT_ENVIRONMENTS),
+    network: primitives_1.network
+        .nullable()
+        .describe('The FairCoin chain this merchant accepts on; `null` on a card-only merchant. Nullable together with `xpub`.'),
+    xpub: zod_1.z
+        .string()
+        .nullable()
+        .describe('The watch-only account key receive addresses derive from; `null` on a card-only merchant.'),
+    required_confirmations: zod_1.z.number().int().positive(),
+    display_name: zod_1.z
+        .string()
+        .optional()
+        .describe('Payer-facing name. Absent when unset: payer surfaces substitute a fallback.'),
+    avatar_file_id: zod_1.z
+        .string()
+        .optional()
+        .describe('The square identity image: a bare Oxy file id. Absent again once Oxy reports the file deleted or taken down.'),
+    business_logo: zod_1.z
+        .string()
+        .optional()
+        .describe('The wide wordmark payer surfaces show: a `file_…` of purpose `business_logo`.'),
+    description: zod_1.z.string().optional(),
+    created: primitives_1.unixSeconds,
+    updated_at: primitives_1.unixSeconds,
+})
+    .strict(), {
+    examples: [
+        {
+            id: 'merch_0193b8f2c1a87d3e9f4a',
+            object: 'merchant',
+            livemode: false,
+            oxy_app_id: 'app_0193b8f2c1a87d3e9f4b',
+            environment: 'development',
+            network: 'testnet',
+            xpub: 'tpubDC5FSnBiZDMmhiuCmWAYsLwgLYrrT9rAqvTySfuCCrgsWz8wxMXUS9Tb9iVMvcRbvFcAHGkMD5Kx8koh4GquNGNTfohfk7pgjhaPCdXpoba',
+            required_confirmations: 6,
+            display_name: 'Jenny’s Plants',
+            created: 1793750400,
+            updated_at: 1793750400,
+        },
+    ],
+});
+// The branding columns are bare `text()` with no CHECK, so these bounds are
+// the ONLY thing between a merchant and an unbounded write. `display_name` is
+// rendered in a payer's transaction history and on the checkout chip, so it is
+// held to a chip-sized length rather than a paragraph.
+const displayName = zod_1.z.string().min(1).max(64);
+const avatarFileId = zod_1.z.string().min(1).max(128);
+const merchantDescription = zod_1.z.string().min(1).max(512);
+/**
+ * `POST /v1/merchants`. The FairCoin half is OPTIONAL — both `network` and
+ * `xpub`, or neither: a card-only merchant supplies no key for a chain it
+ * never intends to use.
+ */
+exports.registerMerchantParams = zod_1.z
+    .object({
+    network: primitives_1.network.optional(),
+    xpub: zod_1.z
+        .string()
+        .min(1)
+        .optional()
+        .describe('A watch-only account xpub. A private extended key is refused.'),
+    required_confirmations: zod_1.z.number().int().positive().optional(),
+    display_name: displayName.optional(),
+    avatar_file_id: avatarFileId.optional(),
+    description: merchantDescription.optional(),
+})
+    .strict()
+    .refine((body) => (body.network === undefined) === (body.xpub === undefined), {
+    message: 'accepting FairCoin needs both a network and a watch-only xpub, or neither — ' +
+        'omit both to register a card-only merchant',
+});
+/**
+ * `POST /v1/merchants/me`. `null` clears a field. The key, network and
+ * environment never change: addresses already derived from the key, and the
+ * test/live firewall, depend on them.
+ */
+exports.updateMerchantParams = zod_1.z
+    .object({
+    required_confirmations: zod_1.z.number().int().positive().optional(),
+    display_name: displayName.nullable().optional(),
+    avatar_file_id: avatarFileId.nullable().optional(),
+    business_logo: zod_1.z
+        .string()
+        .min(1)
+        .max(255)
+        .nullable()
+        .optional()
+        .describe('A `file_…` of purpose `business_logo` — set on an update, never at registration.'),
+    description: merchantDescription.nullable().optional(),
+})
+    .strict();
+// ---- Branding ----------------------------------------------------------------
+/** A merchant's branding: what its hosted checkout, embedded checkout and receipts look like. */
+exports.merchantBrandingSchema = (0, objects_1.defineObject)('branding_settings', 'BrandingSettings', zod_1.z
+    .object({
+    object: zod_1.z.literal('branding_settings'),
+    livemode: primitives_1.livemode,
+    use_avatar_as_icon: zod_1.z
+        .boolean()
+        .describe('Show the merchant avatar (`avatar_file_id`) as the square icon.'),
+    logo: zod_1.z
+        .string()
+        .nullable()
+        .describe('The wide logo: a `file_…` of purpose `business_logo`, or `null` — the same field as `POST /v1/merchants/me {business_logo}`.'),
+    primary_color: zod_1.z.string().nullable().describe('`#rrggbb`; `null` for Peable’s default.'),
+    accent_color: zod_1.z.string().nullable(),
+    font: zod_1.z.enum(merchants_1.BRANDING_FONTS).nullable(),
+    border_style: zod_1.z.enum(merchants_1.BRANDING_BORDER_STYLES).nullable(),
+    terms_of_service_url: zod_1.z
+        .string()
+        .nullable()
+        .describe('Your terms (`https://`). Required before a session or link can ask for terms acceptance.'),
+    updated_at: primitives_1.unixSeconds.nullable(),
+})
+    .strict());
+/** `#rgb` or `#rrggbb`, any case — stored as lowercase `#rrggbb`. */
+const colorParam = zod_1.z
+    .string()
+    .regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, 'must be a #rrggbb colour')
+    .transform((value) => {
+    const hex = value.slice(1).toLowerCase();
+    return `#${hex.length === 3 ? [...hex].map((c) => c + c).join('') : hex}`;
+});
+const httpsUrlParam = zod_1.z
+    .string()
+    .max(2048)
+    .regex(/^https:\/\/\S+$/, 'must be an https URL');
+exports.updateMerchantBrandingParams = zod_1.z
+    .object({
+    use_avatar_as_icon: zod_1.z.boolean().optional(),
+    logo: zod_1.z
+        .string()
+        .min(1)
+        .max(255)
+        .nullable()
+        .optional()
+        .describe('A `file_…` of purpose `business_logo`; `null` removes it.'),
+    primary_color: colorParam
+        .nullable()
+        .optional()
+        .describe('`#rrggbb` (any case; stored lowercase), `null` for Peable’s default.'),
+    accent_color: colorParam.nullable().optional(),
+    font: zod_1.z.enum(merchants_1.BRANDING_FONTS).nullable().optional(),
+    border_style: zod_1.z.enum(merchants_1.BRANDING_BORDER_STYLES).nullable().optional(),
+    terms_of_service_url: httpsUrlParam.nullable().optional(),
+})
+    .strict();
+/** Which customer emails Peable sends for this merchant. */
+exports.merchantEmailSettingsSchema = (0, objects_1.defineObject)('email_settings', 'EmailSettings', zod_1.z
+    .object({
+    object: zod_1.z.literal('email_settings'),
+    livemode: primitives_1.livemode,
+    payment_receipts: zod_1.z
+        .boolean()
+        .describe('A receipt when a payment succeeds and has a `receipt_email` (or a collected one).'),
+    refund_notices: zod_1.z.boolean().describe('A notice when a refund succeeds.'),
+    checkout_confirmations: zod_1.z
+        .boolean()
+        .describe('A confirmation when a checkout session completes.'),
+    support_email: zod_1.z
+        .string()
+        .nullable()
+        .describe('The reply-to address shown on emails, or `null` for none.'),
+    updated_at: primitives_1.unixSeconds.nullable(),
+})
+    .strict());
+exports.updateMerchantEmailSettingsParams = zod_1.z
+    .object({
+    payment_receipts: zod_1.z.boolean().optional(),
+    refund_notices: zod_1.z.boolean().optional(),
+    checkout_confirmations: zod_1.z.boolean().optional(),
+    support_email: zod_1.z
+        .string()
+        .trim()
+        .max(254)
+        .email('must be an email address')
+        .nullable()
+        .optional(),
+})
+    .strict();
+exports.merchantRoutes = [
+    (0, route_1.defineRoute)({
+        operationId: 'registerMerchant',
+        method: 'post',
+        path: '/v1/merchants',
+        tag: 'Merchants',
+        summary: 'Register the merchant',
+        description: "Registers the calling application's merchant in the credential's environment. A non-production credential can register a testnet merchant only. A second registration for the same application and environment answers 409. Outside the generic idempotency layer: the merchant is the scope it keys on.",
+        auth: 'service',
+        scope: 'payments:write',
+        body: exports.registerMerchantParams,
+        response: exports.merchantSchema,
+        status: 201,
+        sdk: 'merchants.register',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveMerchant',
+        method: 'get',
+        path: '/v1/merchants/me',
+        tag: 'Merchants',
+        summary: 'Retrieve your merchant',
+        auth: 'service',
+        scope: 'payments:read',
+        response: exports.merchantSchema,
+        sdk: 'merchants.retrieve',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'updateMerchant',
+        method: 'post',
+        path: '/v1/merchants/me',
+        tag: 'Merchants',
+        summary: 'Update your merchant',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.updateMerchantParams,
+        response: exports.merchantSchema,
+        sdk: 'merchants.update',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveBrandingSettings',
+        method: 'get',
+        path: '/v1/merchants/me/branding',
+        tag: 'Merchants',
+        summary: 'Retrieve your branding',
+        auth: 'service',
+        scope: 'payments:read',
+        response: exports.merchantBrandingSchema,
+        sdk: 'merchants.branding.retrieve',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'updateBrandingSettings',
+        method: 'post',
+        path: '/v1/merchants/me/branding',
+        tag: 'Merchants',
+        summary: 'Update your branding',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.updateMerchantBrandingParams,
+        response: exports.merchantBrandingSchema,
+        sdk: 'merchants.branding.update',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'retrieveEmailSettings',
+        method: 'get',
+        path: '/v1/merchants/me/email_settings',
+        tag: 'Merchants',
+        summary: 'Retrieve your customer email settings',
+        auth: 'service',
+        scope: 'payments:read',
+        response: exports.merchantEmailSettingsSchema,
+        sdk: 'merchants.emailSettings.retrieve',
+    }),
+    (0, route_1.defineRoute)({
+        operationId: 'updateEmailSettings',
+        method: 'post',
+        path: '/v1/merchants/me/email_settings',
+        tag: 'Merchants',
+        summary: 'Update your customer email settings',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: exports.updateMerchantEmailSettingsParams,
+        response: exports.merchantEmailSettingsSchema,
+        sdk: 'merchants.emailSettings.update',
+    }),
+];