@peable.to/contracts 0.3.0 → 1.0.0

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

@@ -0,0 +1,167 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineComponent } from '../../common/objects.js';
+import { listQuery } from '../../common/params.js';
+import { defineRoute } from '../../route.js';
+import { MERCHANT_ENVIRONMENTS } from '../../vocabulary/merchants.js';
+/**
+ * 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. */
+export const contributionAmountSchema = 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 = z.number().int().nonnegative();
+export const contributionDetailsSchema = defineComponent('ContributionDetails', z
+    .object({
+    organization_id: z.string().min(1).max(200).describe('The Oxy organization collecting.'),
+    purpose: z.string().trim().min(1).max(500),
+    amount_mode: z
+        .enum(['fixed', 'free'])
+        .describe('`fixed`: the link names the amount; `free`: the payer chooses it.'),
+    expires_at: unixSecondsSchema.nullable(),
+})
+    .strict());
+export const createContributionSchema = z
+    .object({
+    purpose: contributionDetailsSchema.shape.purpose,
+    amount_mode: contributionDetailsSchema.shape.amount_mode,
+    amount: contributionAmountSchema.optional(),
+    currency: 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. */
+export const contributionLinkSchema = defineComponent('ContributionLink', z
+    .object({
+    id: z.string(),
+    object: z.literal('payment_link'),
+    amount: z.string().describe('FAIR base units; `"0"` when the payer chooses.'),
+    currency: z.literal('FAIR'),
+    network: z.enum(['mainnet', 'testnet']),
+    active: z.boolean(),
+    url: z.url().describe('The hosted link to share.'),
+    contribution: contributionDetailsSchema,
+    created: unixSecondsSchema,
+})
+    .strict());
+export const contributionListSchema = listOf(contributionLinkSchema);
+/** A payment made through a contribution link. Non-custodial: Peable cannot refund it. */
+export const contributionCollectionSchema = defineComponent('ContributionCollection', z
+    .object({
+    id: z.string(),
+    object: z.literal('payment_intent'),
+    amount: z.string(),
+    currency: z.literal('FAIR'),
+    status: z.string(),
+    created: unixSecondsSchema,
+    refund_capability: z.literal('unsupported_non_custodial'),
+    refunds: z.array(z
+        .object({
+        id: z.string(),
+        object: z.literal('refund'),
+        amount: z.string(),
+        status: z.string(),
+        created: unixSecondsSchema,
+    })
+        .strict()),
+})
+    .strict());
+export const contributionCollectionListSchema = listOf(contributionCollectionSchema);
+/** The environment the Test/Live toggle selects: the application's merchant in it is the scope. */
+const environmentParam = z
+    .enum(MERCHANT_ENVIRONMENTS)
+    .describe("Which of the application's merchants: its Test/Live toggle.");
+/** The query of every contribution write: the environment and nothing else. */
+export const contributionScopeQuerySchema = 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.
+ */
+export const contributionPageQuerySchema = listQuery({ environment: environmentParam });
+/** What a payer may say when starting a free contribution's checkout. */
+export const contributionMintSchema = z
+    .object({ amount: contributionAmountSchema.optional() })
+    .strict();
+/** A contribution start's `Idempotency-Key`: a UUID the page writes before the request. */
+export const contributionOperationKeySchema = z.uuid();
+export const contributionPatchSchema = z.object({ active: z.boolean() }).strict();
+/** `"1.25"` FAIR → `"125000000"` base units, with exact integer arithmetic. */
+export 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 contributionAmountSchema.parse((BigInt(whole) * FAIR_UNITS_PER_COIN + BigInt(fraction.padEnd(8, '0'))).toString());
+}
+/** Base units → the shortest exact FAIR decimal. */
+export 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';
+export const contributionRoutes = [
+    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: contributionScopeQuerySchema,
+        body: createContributionSchema,
+        response: contributionLinkSchema,
+        status: 201,
+    }),
+    defineRoute({
+        operationId: 'listContributions',
+        method: 'get',
+        path: root,
+        tag: 'Contributions',
+        summary: "List an organization's contribution links",
+        auth: 'user',
+        params: scopeParams,
+        query: contributionPageQuerySchema,
+        response: contributionListSchema,
+    }),
+    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: contributionScopeQuerySchema,
+        body: contributionPatchSchema,
+        response: contributionLinkSchema,
+    }),
+    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: contributionPageQuerySchema,
+        response: contributionCollectionListSchema,
+    }),
+];

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

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import { listOf } from '../../common/envelopes.js';
+import { defineObject } from '../../common/objects.js';
+import { emptyQuery, expandOnlyQuery, listQuery } from '../../common/params.js';
+import { livemode, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { FILE_PURPOSES, FILE_STATUSES, FILE_TYPES, FILE_UPLOAD_PURPOSES, } from '../../vocabulary/files.js';
+/**
+ * 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.
+ */
+export const fileSchema = defineObject('file', 'File', z
+    .object({
+    id: z.string(),
+    object: z.literal('file'),
+    livemode,
+    purpose: z.enum(FILE_PURPOSES),
+    filename: z
+        .string()
+        .nullable()
+        .describe('The name it was uploaded with, if it had a printable one.'),
+    size: z.number().int().nonnegative().describe('Bytes.'),
+    type: z.enum(FILE_TYPES),
+    status: z.enum(FILE_STATUSES),
+    url: 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: 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.
+ */
+export const createFileUploadParams = z
+    .object({
+    purpose: z.enum(FILE_UPLOAD_PURPOSES, {
+        error: `purpose must be one of ${FILE_UPLOAD_PURPOSES.join(', ')}`,
+    }),
+    file: 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.
+ */
+export const createFileFromOxyParams = z
+    .object({
+    purpose: z.enum(FILE_UPLOAD_PURPOSES),
+    oxy_file: z.string().min(1).max(128).describe('The Oxy file id.'),
+})
+    .strict();
+export const listFilesQuery = listQuery({ purpose: z.enum(FILE_PURPOSES).optional() });
+export const fileRoutes = [
+    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: createFileUploadParams,
+        bodyEncoding: 'multipart',
+        response: fileSchema,
+        sdk: 'files.create',
+    }),
+    defineRoute({
+        operationId: 'listFiles',
+        method: 'get',
+        path: '/v1/files',
+        tag: 'Files',
+        summary: 'List files',
+        auth: 'service',
+        scope: 'payments:read',
+        query: listFilesQuery,
+        response: listOf(fileSchema),
+        sdk: 'files.list',
+        expandable: 'file',
+    }),
+    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: expandOnlyQuery,
+        response: fileSchema,
+        sdk: 'files.retrieve',
+        expandable: 'file',
+    }),
+    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: emptyQuery,
+        response: { kind: 'binary', contentType: 'text/csv' },
+        sdk: 'files.contents',
+    }),
+];

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

@@ -0,0 +1,25 @@
+import { checkoutSessionRoutes } from './checkoutSessions.js';
+import { contributionRoutes } from './contributions.js';
+import { fileRoutes } from './files.js';
+import { merchantRoutes } from './merchants.js';
+import { paymentLinkRoutes } from './paymentLinks.js';
+import { paymentMethodConfigurationRoutes } from './paymentMethodConfigurations.js';
+export * from './checkoutSessions.js';
+export * from './contributions.js';
+export * from './files.js';
+export * from './merchants.js';
+export * from './paymentLinks.js';
+export * from './paymentMethodConfigurations.js';
+// 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.
+export { adjustableBoundsOf, checkoutAdjustableQuantitySchema, checkoutAutomaticTaxSchema, checkoutBrandingSchema, checkoutConsentCollectionSchema, checkoutConsentSchema, checkoutCustomerDetailsSchema, checkoutCustomFieldSchema, checkoutDiscountSchema, checkoutLineItemSchema, checkoutShippingDetailsSchema, checkoutTaxIdSchema, checkoutTotalDetailsSchema, customFieldsParam, merchantDisplaySchema, } from './shared.js';
+/** Checkout, payment links, the merchant and its branding, files and contributions. */
+export const checkoutRoutes = [
+    ...checkoutSessionRoutes,
+    ...paymentLinkRoutes,
+    ...paymentMethodConfigurationRoutes,
+    ...merchantRoutes,
+    ...fileRoutes,
+    ...contributionRoutes,
+];

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

@@ -0,0 +1,287 @@
+import { z } from 'zod';
+import { defineObject } from '../../common/objects.js';
+import { livemode, network, unixSeconds } from '../../common/primitives.js';
+import { defineRoute } from '../../route.js';
+import { BRANDING_BORDER_STYLES, BRANDING_FONTS, MERCHANT_ENVIRONMENTS, } from '../../vocabulary/merchants.js';
+/**
+ * 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.
+ */
+export const merchantSchema = defineObject('merchant', 'Merchant', z
+    .object({
+    id: z.string(),
+    object: z.literal('merchant'),
+    livemode: livemode.describe('`true` for a `production` merchant (ADR 0017).'),
+    oxy_app_id: z.string().describe('The Oxy application this merchant belongs to.'),
+    environment: z.enum(MERCHANT_ENVIRONMENTS),
+    network: network
+        .nullable()
+        .describe('The FairCoin chain this merchant accepts on; `null` on a card-only merchant. Nullable together with `xpub`.'),
+    xpub: z
+        .string()
+        .nullable()
+        .describe('The watch-only account key receive addresses derive from; `null` on a card-only merchant.'),
+    required_confirmations: z.number().int().positive(),
+    display_name: z
+        .string()
+        .optional()
+        .describe('Payer-facing name. Absent when unset: payer surfaces substitute a fallback.'),
+    avatar_file_id: 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: z
+        .string()
+        .optional()
+        .describe('The wide wordmark payer surfaces show: a `file_…` of purpose `business_logo`.'),
+    description: z.string().optional(),
+    created: unixSeconds,
+    updated_at: 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 = z.string().min(1).max(64);
+const avatarFileId = z.string().min(1).max(128);
+const merchantDescription = 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.
+ */
+export const registerMerchantParams = z
+    .object({
+    network: network.optional(),
+    xpub: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('A watch-only account xpub. A private extended key is refused.'),
+    required_confirmations: 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.
+ */
+export const updateMerchantParams = z
+    .object({
+    required_confirmations: z.number().int().positive().optional(),
+    display_name: displayName.nullable().optional(),
+    avatar_file_id: avatarFileId.nullable().optional(),
+    business_logo: 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. */
+export const merchantBrandingSchema = defineObject('branding_settings', 'BrandingSettings', z
+    .object({
+    object: z.literal('branding_settings'),
+    livemode,
+    use_avatar_as_icon: z
+        .boolean()
+        .describe('Show the merchant avatar (`avatar_file_id`) as the square icon.'),
+    logo: 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: z.string().nullable().describe('`#rrggbb`; `null` for Peable’s default.'),
+    accent_color: z.string().nullable(),
+    font: z.enum(BRANDING_FONTS).nullable(),
+    border_style: z.enum(BRANDING_BORDER_STYLES).nullable(),
+    terms_of_service_url: z
+        .string()
+        .nullable()
+        .describe('Your terms (`https://`). Required before a session or link can ask for terms acceptance.'),
+    updated_at: unixSeconds.nullable(),
+})
+    .strict());
+/** `#rgb` or `#rrggbb`, any case — stored as lowercase `#rrggbb`. */
+const colorParam = 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 = z
+    .string()
+    .max(2048)
+    .regex(/^https:\/\/\S+$/, 'must be an https URL');
+export const updateMerchantBrandingParams = z
+    .object({
+    use_avatar_as_icon: z.boolean().optional(),
+    logo: 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: z.enum(BRANDING_FONTS).nullable().optional(),
+    border_style: z.enum(BRANDING_BORDER_STYLES).nullable().optional(),
+    terms_of_service_url: httpsUrlParam.nullable().optional(),
+})
+    .strict();
+/** Which customer emails Peable sends for this merchant. */
+export const merchantEmailSettingsSchema = defineObject('email_settings', 'EmailSettings', z
+    .object({
+    object: z.literal('email_settings'),
+    livemode,
+    payment_receipts: z
+        .boolean()
+        .describe('A receipt when a payment succeeds and has a `receipt_email` (or a collected one).'),
+    refund_notices: z.boolean().describe('A notice when a refund succeeds.'),
+    checkout_confirmations: z
+        .boolean()
+        .describe('A confirmation when a checkout session completes.'),
+    support_email: z
+        .string()
+        .nullable()
+        .describe('The reply-to address shown on emails, or `null` for none.'),
+    updated_at: unixSeconds.nullable(),
+})
+    .strict());
+export const updateMerchantEmailSettingsParams = z
+    .object({
+    payment_receipts: z.boolean().optional(),
+    refund_notices: z.boolean().optional(),
+    checkout_confirmations: z.boolean().optional(),
+    support_email: z
+        .string()
+        .trim()
+        .max(254)
+        .email('must be an email address')
+        .nullable()
+        .optional(),
+})
+    .strict();
+export const merchantRoutes = [
+    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: registerMerchantParams,
+        response: merchantSchema,
+        status: 201,
+        sdk: 'merchants.register',
+    }),
+    defineRoute({
+        operationId: 'retrieveMerchant',
+        method: 'get',
+        path: '/v1/merchants/me',
+        tag: 'Merchants',
+        summary: 'Retrieve your merchant',
+        auth: 'service',
+        scope: 'payments:read',
+        response: merchantSchema,
+        sdk: 'merchants.retrieve',
+    }),
+    defineRoute({
+        operationId: 'updateMerchant',
+        method: 'post',
+        path: '/v1/merchants/me',
+        tag: 'Merchants',
+        summary: 'Update your merchant',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: updateMerchantParams,
+        response: merchantSchema,
+        sdk: 'merchants.update',
+    }),
+    defineRoute({
+        operationId: 'retrieveBrandingSettings',
+        method: 'get',
+        path: '/v1/merchants/me/branding',
+        tag: 'Merchants',
+        summary: 'Retrieve your branding',
+        auth: 'service',
+        scope: 'payments:read',
+        response: merchantBrandingSchema,
+        sdk: 'merchants.branding.retrieve',
+    }),
+    defineRoute({
+        operationId: 'updateBrandingSettings',
+        method: 'post',
+        path: '/v1/merchants/me/branding',
+        tag: 'Merchants',
+        summary: 'Update your branding',
+        auth: 'service',
+        scope: 'payments:write',
+        idempotent: true,
+        body: updateMerchantBrandingParams,
+        response: merchantBrandingSchema,
+        sdk: 'merchants.branding.update',
+    }),
+    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: merchantEmailSettingsSchema,
+        sdk: 'merchants.emailSettings.retrieve',
+    }),
+    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: updateMerchantEmailSettingsParams,
+        response: merchantEmailSettingsSchema,
+        sdk: 'merchants.emailSettings.update',
+    }),
+];