@peable.to/contracts 3.1.0 → 4.1.0

package/dist/cjs/resources/billingEngine/public.js

@@ -8,6 +8,7 @@ const params_1 = require("../../common/params");
 const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
 const billingPortal_1 = require("../../vocabulary/billingPortal");
+const checkout_1 = require("../../vocabulary/checkout");
 const invoices_1 = require("../../vocabulary/invoices");
 const subscriptions_1 = require("../../vocabulary/subscriptions");
 const billingPortal_2 = require("./billingPortal");
@@ -57,7 +58,17 @@ exports.publicInvoiceSchema = (0, objects_1.defineObject)('public_invoice', 'Pub
     paid_at: primitives_1.unixSeconds.nullable(),
     payment_method_types: zod_1.z
         .array(zod_1.z.enum(invoices_1.PUBLIC_INVOICE_PAYMENT_METHOD_TYPES))
-        .describe("Which rail pays it: a card through the provider's fields, FairCoin from the payer's wallet."),
+        .describe("What the payer may choose: `['card', 'faircoin']` on a fiat invoice, `['faircoin']` on a FAIR one. FairCoin is always offered (ADR 0021); on a fiat invoice it is quoted when chosen."),
+    faircoin: zod_1.z
+        .object({
+        available: zod_1.z.boolean(),
+        unavailable_reason: zod_1.z
+            .enum(checkout_1.FAIRCOIN_UNAVAILABLE_REASONS)
+            .nullable()
+            .describe('Why FairCoin cannot be paid with right now; it is still shown, never hidden.'),
+    })
+        .strict()
+        .describe('Whether the payer can choose FairCoin now (ADR 0021).'),
     invoice_pdf: zod_1.z.string(),
 })
     .strict());
@@ -181,7 +192,15 @@ exports.portalPaymentMethodUpdateResultSchema = (0, objects_1.defineComponent)('
 })
     .strict());
 // ---- Requests ------------------------------------------------------------------------
-exports.payPublicInvoiceParams = params_2.emptyBody;
+/** How the payer pays the invoice (ADR 0021 D3). */
+exports.payPublicInvoiceParams = zod_1.z
+    .object({
+    payment_method_type: zod_1.z
+        .enum(invoices_1.PUBLIC_INVOICE_PAYMENT_METHOD_TYPES)
+        .optional()
+        .describe("One of the invoice's `payment_method_types`. Default: the rail of its currency (`card` on a fiat invoice). `faircoin` on a fiat invoice quotes the amount due in FAIR for 10 minutes; paying again with the other method replaces a payment that has not started moving money."),
+})
+    .strict();
 /** A portal action on one of the customer's subscriptions. */
 exports.portalSubscriptionParams = zod_1.z.object({ subscription: params_1.idParam }).strict();
 /** Switch a (single-item) subscription to one of the configuration's plans, or change its quantity. */
@@ -224,7 +243,7 @@ exports.publicBillingRoutes = [
         path: '/v1/invoices/public/{token}/pay',
         tag: 'Hosted invoices',
         summary: 'Pay a hosted invoice',
-        description: 'The PaymentIntent the payer completes — a card through the provider’s own fields, FairCoin from the payer’s wallet. The same invoice answers the same intent while it can still be paid.',
+        description: 'The PaymentIntent the payer completes in the method they chose — a card through the provider’s own fields, or FairCoin from the payer’s wallet (quoted on a fiat invoice, ADR 0021). The same invoice answers the same intent while it can still be paid in that method.',
         auth: 'public',
         params: invoiceToken,
         body: exports.payPublicInvoiceParams,

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

@@ -33,8 +33,13 @@ const sessionFields = {
         .describe("The language checkout renders in; `null` follows the payer's browser."),
     submit_type: zod_1.z.enum(checkout_1.CHECKOUT_SUBMIT_TYPES),
     currency: primitives_1.currency,
-    rail: shared_1.railSchema,
-    network: primitives_1.network.nullable().describe('FairCoin rail only; `null` on a card session.'),
+    rail: shared_1.railSchema.describe("The rail that settles the order's currency: `faircoin` for a FAIR order, `card` for a fiat one. FairCoin is offered on every order beside it (`payment_method_types`, ADR 0021)."),
+    network: primitives_1.network
+        .nullable()
+        .describe('The FairCoin network a FairCoin payment of this order uses — the merchant’s (or the seller’s); `null` when the payee has no FairCoin key yet (test mode) and in `setup` mode.'),
+    payment_method_types: zod_1.z
+        .array(shared_1.railSchema)
+        .describe("What the payer may choose: `['card', 'faircoin']` on a fiat order (`['faircoin']` when the merchant offered FairCoin only), `['faircoin']` on a FAIR one. FairCoin is always offered (ADR 0021); `['card']` in `setup` mode."),
     amount_subtotal: primitives_1.amount,
     amount_total: primitives_1.amount,
     total_details: shared_1.checkoutTotalDetailsSchema,
@@ -49,7 +54,6 @@ const sessionFields = {
 exports.checkoutSessionSchema = (0, objects_2.defineObject)('checkout_session', 'CheckoutSession', zod_1.z
     .object({
     ...sessionFields,
-    payment_method_types: zod_1.z.array(shared_1.railSchema),
     discounts: zod_1.z.array(shared_1.checkoutDiscountSchema),
     customer: (0, objects_2.expandable)('customer', '`cus_…` (expandable) — given on create, or created at completion.').nullable(),
     customer_email: zod_1.z.string().nullable(),
@@ -93,8 +97,8 @@ exports.checkoutSessionSchema = (0, objects_2.defineObject)('checkout_session',
             submit_type: 'auto',
             currency: 'EUR',
             rail: 'card',
-            network: null,
-            payment_method_types: ['card'],
+            network: 'mainnet',
+            payment_method_types: ['card', 'faircoin'],
             amount_subtotal: '1999',
             amount_total: '1999',
             total_details: { amount_discount: '0', amount_tax: '0', amount_shipping: '0' },
@@ -182,6 +186,17 @@ exports.checkoutSessionPublicSchema = (0, objects_2.defineComponent)('CheckoutSe
         .string()
         .nullable()
         .describe("The card provider's PUBLIC key for this session's mode, so the payment fields can mount before the payment exists. `null` on FairCoin."),
+    faircoin: zod_1.z
+        .object({
+        available: zod_1.z.boolean(),
+        unavailable_reason: zod_1.z
+            .enum(checkout_1.FAIRCOIN_UNAVAILABLE_REASONS)
+            .nullable()
+            .describe('Why FairCoin cannot be paid with right now; it is still shown, never hidden.'),
+    })
+        .strict()
+        .nullable()
+        .describe('Whether the payer can choose FairCoin now (ADR 0021). On a fiat order the FAIR amount is quoted when the payer chooses it (`payment_intent.faircoin.quote`). `null` in `setup` mode.'),
 })
     .strict());
 // ---- Merchant create/update ---------------------------------------------------
@@ -282,9 +297,9 @@ exports.createCheckoutSessionParams = zod_1.z
     payment_method_types: zod_1.z
         .array(zod_1.z.enum(['card', 'faircoin']))
         .min(1)
-        .max(1)
+        .max(2)
         .optional()
-        .describe("`['card']` or `['faircoin']` — the rail the line items' currency allows."),
+        .describe("Must include `faircoin`, which is always offered (ADR 0021; leaving it out is 400 `payment_method_locked`). On a fiat order `['card', 'faircoin']` (the default) or `['faircoin']` — a FairCoin-only order, the fiat methods being the merchant's to turn off; on a FAIR order `['faircoin']`. Which card methods are offered comes from the payment method configuration."),
     locale: shared_1.localeParam.optional(),
     ui_mode: zod_1.z.enum(checkout_1.CHECKOUT_UI_MODES).optional(),
     success_url: shared_1.redirectUrlParam
@@ -428,8 +443,18 @@ exports.updateCheckoutSessionPublicParams = zod_1.z
         .optional(),
 })
     .strict();
-/** `POST /v1/checkout_sessions/{id}/public/confirm` takes nothing: the order is the session's. */
-exports.confirmCheckoutSessionPublicParams = zod_1.z.object({}).strict();
+/**
+ * `POST /v1/checkout_sessions/{id}/public/confirm` — the order is the
+ * session's; the payer only chooses how to pay it (ADR 0021 D3).
+ */
+exports.confirmCheckoutSessionPublicParams = zod_1.z
+    .object({
+    payment_method_type: zod_1.z
+        .enum(['card', 'faircoin'])
+        .optional()
+        .describe("How the payer pays: one of the session's `payment_method_types`. Default: the rail of the order's currency (`card` on a fiat order). `faircoin` on a fiat order quotes its total in FAIR for 10 minutes; confirming again with the other method replaces a payment that has not started moving money."),
+})
+    .strict();
 /** `POST /v1/test_helpers/checkout_sessions/{id}/expire` takes nothing. */
 exports.expireCheckoutSessionTestHelperParams = zod_1.z.object({}).strict();
 const sessionId = { id: 'The Checkout Session (`cs_…`).' };

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

@@ -20,13 +20,11 @@ exports.merchantSchema = (0, objects_1.defineObject)('merchant', 'Merchant', zod
     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
+    network: primitives_1.network.describe("The FairCoin network this merchant's payments use — its environment's: `mainnet` live, `testnet` otherwise (ADR 0021 D5)."),
+    owner_account: zod_1.z
         .string()
         .nullable()
-        .describe('The watch-only account key receive addresses derive from; `null` on a card-only merchant.'),
+        .describe('The Oxy account (a person or an organization) that owns the application — its Peable wallet receives the merchant’s FairCoin (ADR 0021 D5). No key is ever registered. `null` until Peable has seen the owner.'),
     required_confirmations: zod_1.z.number().int().positive(),
     display_name: zod_1.z
         .string()
@@ -53,7 +51,7 @@ exports.merchantSchema = (0, objects_1.defineObject)('merchant', 'Merchant', zod
             oxy_app_id: 'app_0193b8f2c1a87d3e9f4b',
             environment: 'development',
             network: 'testnet',
-            xpub: 'tpubDC5FSnBiZDMmhiuCmWAYsLwgLYrrT9rAqvTySfuCCrgsWz8wxMXUS9Tb9iVMvcRbvFcAHGkMD5Kx8koh4GquNGNTfohfk7pgjhaPCdXpoba',
+            owner_account: '0193b8f2-c1a8-7d3e-9f4a-5b6c7d8e9f01',
             required_confirmations: 6,
             display_name: 'Jenny’s Plants',
             created: 1793750400,
@@ -69,32 +67,21 @@ 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.
+ * `POST /v1/merchants`. No FairCoin key and no network: the network is the
+ * environment's, and FairCoin is received into the Peable wallet of the
+ * account that owns the application (ADR 0021 D5).
  */
 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',
-});
+    .strict();
 /**
- * `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.
+ * `POST /v1/merchants/me`. `null` clears a field. The network and environment
+ * never change: the test/live firewall depends on them.
  */
 exports.updateMerchantParams = zod_1.z
     .object({

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

@@ -9,11 +9,13 @@ const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
 const paymentMethodConfigurations_1 = require("../../vocabulary/paymentMethodConfigurations");
 /**
- * Payment method breadth on the card rail — which methods a merchant's payers
- * are offered (`pmc_…`), and the web domains wallets may run on (`pmd_…`).
- * Both are Orbit's objects; the provider's configuration and domain are
- * bindings behind them (ADR 0016). Card data and bank credentials are entered
- * in the provider's hosted fields and never reach Peable (PCI SAQ-A).
+ * Payment method breadth — which methods a merchant's payers are offered
+ * (`pmc_…`), and the web domains wallets may run on (`pmd_…`). FairCoin is an
+ * entry of every configuration and is locked on (ADR 0021 D2); the card-rail
+ * methods are the merchant's choice. Both are Orbit's objects; the provider's
+ * configuration and domain are bindings behind them (ADR 0016). Card data and
+ * bank credentials are entered in the provider's hosted fields and never reach
+ * Peable (PCI SAQ-A).
  */
 /** The merchant's choice (`none`: Orbit's default) and what is in effect. */
 exports.paymentMethodDisplayPreferenceSchema = zod_1.z
@@ -28,13 +30,28 @@ exports.paymentMethodConfigurationEntrySchema = (0, objects_1.defineComponent)('
         .boolean()
         .describe('Whether payers can be offered this method: it is on and nothing prevents it.'),
     display_preference: exports.paymentMethodDisplayPreferenceSchema,
+    locked: zod_1.z
+        .boolean()
+        .describe('Whether the merchant can change it. Only `faircoin` is locked: it is always on, because every payer can always pay with FairCoin (ADR 0021), and setting it `off` is refused with `payment_method_locked`.'),
     unavailable_reason: zod_1.z
         .enum(paymentMethodConfigurations_1.PAYMENT_METHOD_UNAVAILABLE_REASONS)
         .nullable()
         .describe('Why it cannot be offered whatever the merchant chooses; `null` when it can.'),
-    currencies: zod_1.z.array(primitives_1.fiatCurrency).describe('The payment currencies it is offered on.'),
+    currencies: zod_1.z.array(primitives_1.currency).describe('The payment currencies it is offered on.'),
 })
     .strict());
+/** One entry of the configuration's documented example (abbreviated currency lists). */
+function exampleEntry(preference, value, overrides = {}) {
+    const unavailable_reason = overrides.unavailable_reason ?? null;
+    return {
+        available: value === 'on' && unavailable_reason === null,
+        display_preference: { preference, value },
+        locked: false,
+        unavailable_reason,
+        currencies: ['EUR', 'USD', 'GBP'],
+        ...overrides,
+    };
+}
 const entryFields = Object.fromEntries(paymentMethodConfigurations_1.PAYMENT_METHOD_CONFIGURATION_TYPES.map((type) => [type, exports.paymentMethodConfigurationEntrySchema]));
 exports.paymentMethodConfigurationSchema = (0, objects_1.defineObject)('payment_method_configuration', 'PaymentMethodConfiguration', zod_1.z
     .object({
@@ -52,7 +69,32 @@ exports.paymentMethodConfigurationSchema = (0, objects_1.defineObject)('payment_
     updated_at: primitives_1.unixSeconds,
     ...entryFields,
 })
-    .strict());
+    .strict(), {
+    examples: [
+        {
+            id: 'pmc_0193b8f2c1a87d3e9f4b',
+            object: 'payment_method_configuration',
+            livemode: false,
+            name: 'Default',
+            active: true,
+            is_default: true,
+            created: 1793750400,
+            updated_at: 1793750400,
+            faircoin: exampleEntry('on', 'on', { locked: true, currencies: ['FAIR', 'EUR', 'USD'] }),
+            card: exampleEntry('none', 'on'),
+            apple_pay: exampleEntry('none', 'on'),
+            google_pay: exampleEntry('none', 'on'),
+            sepa_debit: exampleEntry('on', 'on', { currencies: ['EUR'] }),
+            ideal: exampleEntry('none', 'off', { currencies: ['EUR'] }),
+            bancontact: exampleEntry('none', 'off', { currencies: ['EUR'] }),
+            eps: exampleEntry('none', 'off', { currencies: ['EUR'] }),
+            bizum: exampleEntry('none', 'off', {
+                currencies: ['EUR'],
+                unavailable_reason: 'provider_unsupported',
+            }),
+        },
+    ],
+});
 /** A wallet's standing on one domain. */
 exports.paymentMethodDomainWalletStatusSchema = (0, objects_1.defineComponent)('PaymentMethodDomainWalletStatus', zod_1.z
     .object({
@@ -95,7 +137,11 @@ exports.paymentMethodDomainSchema = (0, objects_1.defineObject)('payment_method_
         },
     ],
 });
-/** One method's setting in a create or update. `none` returns it to Orbit's default. */
+/**
+ * One method's setting in a create or update. `none` returns it to Orbit's
+ * default. For `faircoin` only `on` and `none` are accepted, and neither stores
+ * anything: it is always on, and `off` is refused with `payment_method_locked`.
+ */
 exports.paymentMethodConfigurationEntryParams = zod_1.z
     .object({
     display_preference: zod_1.z.object({ preference: zod_1.z.enum(['on', 'off', 'none']) }).strict(),
@@ -153,7 +199,7 @@ exports.paymentMethodConfigurationRoutes = [
         path: '/v1/payment_method_configurations',
         tag: 'Payment method configurations',
         summary: 'Create a payment method configuration',
-        description: 'An additional, non-default configuration. Turning `on` a method the processing provider does not offer is refused.',
+        description: 'An additional, non-default configuration. Turning `on` a method the processing provider does not offer is refused, and so is turning `faircoin` `off` (`payment_method_locked`): FairCoin is always offered.',
         auth: 'service',
         scope: 'payments:write',
         idempotent: true,
@@ -181,7 +227,7 @@ exports.paymentMethodConfigurationRoutes = [
         path: '/v1/payment_method_configurations/{id}',
         tag: 'Payment method configurations',
         summary: 'Update a payment method configuration',
-        description: 'Method settings are merged; the default configuration is always active.',
+        description: 'Method settings are merged; the default configuration is always active. `faircoin` is locked on: setting it `off` is refused with `payment_method_locked`.',
         auth: 'service',
         scope: 'payments:write',
         idempotent: true,

package/dist/cjs/resources/connect/balance.js

@@ -7,6 +7,7 @@ const objects_1 = require("../../common/objects");
 const params_1 = require("../../common/params");
 const primitives_1 = require("../../common/primitives");
 const route_1 = require("../../route");
+const paymentIntents_1 = require("../payments/paymentIntents");
 const connect_1 = require("../../vocabulary/connect");
 /**
  * Balance and balance transactions (ADR 0015 §3–§5).
@@ -90,6 +91,9 @@ exports.balanceTransactionSchema = (0, objects_1.defineObject)('balance_transact
     created: primitives_1.unixSeconds.describe('When it happened at its source.'),
     description: zod_1.z.string().nullable(),
     exchange_rate: zod_1.z.number().nullable(),
+    faircoin_quote: paymentIntents_1.faircoinQuoteSchema
+        .nullable()
+        .describe('A FairCoin payment of a fiat order: the quote it was priced at — its fiat equivalent (ADR 0021). Informational; no fiat moved.'),
     fee_details: zod_1.z.array(exports.balanceTransactionFeeDetailSchema),
     source: zod_1.z
         .string()
@@ -121,6 +125,7 @@ exports.balanceTransactionSchema = (0, objects_1.defineObject)('balance_transact
             created: 1793750400,
             description: 'Order 6735',
             exchange_rate: null,
+            faircoin_quote: null,
             fee_details: [{ amount: '88', currency: 'EUR', type: 'processing_fee' }],
             source: 'ch_0193b8f2f7c94b1d8e02',
             payout: null,

package/dist/cjs/resources/connect/connectedAccounts.js

@@ -18,25 +18,24 @@ const account_1 = require("./account");
  * ADR 0001 D3: a merchant integrates against Peable and never learns which
  * acquirer sat behind their seller, because the day that changes should be a
  * Peable deploy and not a merchant migration. No `acct_…`, no provider name —
- * and no seller xpub (ADR 0012 D6): an account xpub reveals every address of
- * that account, so a platform holding it would learn the seller's whole history
- * and balance. Nothing a platform does needs it; each payment carries its own
+ * and no key of any kind: a seller's FairCoin is paid into the Peable wallet
+ * of their own Oxy account (ADR 0021 D5), and each payment carries its own
  * address.
  */
 const capabilityStatus = zod_1.z.enum(connect_1.ACCOUNT_CAPABILITY_STATUSES);
-/** The FairCoin half of a seller's account. The seller's xpub is deliberately ABSENT (ADR 0012 D6). */
+/** The FairCoin half of a seller's account: paid into the Peable wallet of the seller's own Oxy account (ADR 0021 D5). */
 exports.connectedAccountFaircoinSchema = (0, objects_1.defineComponent)('ConnectedAccountFaircoin', zod_1.z
     .object({
     network: primitives_1.network.describe('The chain the seller is paid on. Fixed when the half was opened.'),
     status: zod_1.z
         .enum(connect_1.CONNECTED_ACCOUNT_FAIRCOIN_STATUSES)
-        .describe('`pending`: the seller has not registered a key yet (an on-behalf payment is refused, `account_not_ready`). `active`: payments derive addresses from their key.'),
+        .describe('`pending`: the seller has not confirmed yet (an on-behalf payment is refused, `account_not_ready`). `active`: the seller confirmed, and payments go to the Peable wallet of their Oxy account.'),
     oxy_user_id: zod_1.z
         .string()
-        .describe('The Oxy user who may register the key — and, once `active`, who did.'),
+        .describe('The seller’s Oxy account — the only one that may confirm, and the one whose Peable wallet receives.'),
     registered_at: primitives_1.unixSeconds
         .nullable()
-        .describe('When the seller registered their key. `null` while `pending`.'),
+        .describe('When the seller confirmed. `null` while `pending`.'),
 })
     .strict());
 exports.connectedAccountSchema = (0, objects_1.defineObject)('connected_account', 'ConnectedAccount', zod_1.z
@@ -112,9 +111,9 @@ const OXY_USER_ID_MAX = 128;
  * `POST /v1/connected_accounts`: open (or return) the account for one seller.
  *
  * Two halves, at least one: the CARD half (`country` + `business_type`, both or
- * neither) and the FAIRCOIN half (`faircoin`). There is deliberately no `xpub`
- * here: the key comes from the SELLER's own session, never from the platform
- * (ADR 0012 D3).
+ * neither) and the FAIRCOIN half (`faircoin`). There is no key: the seller's
+ * FairCoin goes to their own account's Peable wallet, confirmed only from the
+ * SELLER's own session (ADR 0012 D3, ADR 0021 D5).
  */
 exports.createConnectedAccountParams = zod_1.z
     .object({
@@ -141,7 +140,7 @@ exports.createConnectedAccountParams = zod_1.z
             .string()
             .min(1)
             .max(OXY_USER_ID_MAX)
-            .describe("The seller's Oxy user id — the only person who may register the key."),
+            .describe("The seller's Oxy account id — the only one that may confirm, and whose Peable wallet receives."),
     })
         .strict()
         .optional()
@@ -165,7 +164,7 @@ exports.createConnectedAccountLinkParams = zod_1.z
     rail: zod_1.z
         .enum(connect_1.CONNECTED_ACCOUNT_RAILS)
         .optional()
-        .describe("Which half to onboard: `card` (the default) is the provider's hosted onboarding; `faircoin` is Peable's own page where the SELLER registers their watch-only key."),
+        .describe("Which half to onboard: `card` (the default) is the provider's hosted onboarding; `faircoin` is Peable's own page where the SELLER confirms, in their own Oxy session, that their FairCoin is paid into their Peable wallet."),
 })
     .strict();
 const accountIdParam = { accountId: 'The connected account (`ca_…`).' };

package/dist/cjs/resources/connect/onboarding.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.connectOnboardingRoutes = exports.registerFaircoinKeyParams = exports.connectOnboardingCompleteSchema = exports.connectOnboardingSchema = void 0;
+exports.connectOnboardingRoutes = exports.confirmFaircoinOnboardingParams = exports.connectOnboardingCompleteSchema = exports.connectOnboardingSchema = void 0;
 const zod_1 = require("zod");
 const objects_1 = require("../../common/objects");
 const primitives_1 = require("../../common/primitives");
@@ -10,10 +10,10 @@ const shared_1 = require("../checkout/shared");
  * The SELLER-facing half of FairCoin connected accounts (ADR 0012 D3).
  *
  * A platform mints an onboarding link for a seller's account; the SELLER opens
- * it signed in with Oxy and registers the watch-only key their FairCoin will be
- * paid to. These routes are `auth: 'user'` — the seller's own session, never a
- * service token — because the key that decides who receives a seller's money is
- * accepted only from the seller. A platform cannot reach them at all, and the
+ * it signed in with Oxy and confirms that their FairCoin is paid into the
+ * Peable wallet of that account (ADR 0021 D5). These routes are `auth: 'user'`
+ * — the seller's own session, never a service token — because who receives a
+ * seller's money is the seller's consent. A platform cannot reach them at all, and the
  * link token alone is not enough without the session it names.
  */
 exports.connectOnboardingSchema = (0, objects_1.defineObject)('connect_onboarding', 'ConnectOnboarding', zod_1.z
@@ -38,22 +38,11 @@ exports.connectOnboardingCompleteSchema = (0, objects_1.defineComponent)('Connec
 })
     .strict());
 /**
- * An extended public key is 111 characters in base58check; the bound is a
- * request-size guard with headroom, not a format check — the non-custody
- * firewall (`assertWatchOnly`) is.
+ * `POST /v1/connect/onboarding/{token}/faircoin` takes nothing: the seller
+ * confirms, in their own Oxy session, that their FairCoin is paid into the
+ * Peable wallet of that account (ADR 0021 D5). No key travels.
  */
-const XPUB_MAX_LENGTH = 200;
-/** `POST /v1/connect/onboarding/{token}/faircoin` — the seller's watch-only ACCOUNT xpub. */
-exports.registerFaircoinKeyParams = zod_1.z
-    .object({
-    xpub: zod_1.z
-        .string()
-        .trim()
-        .min(1)
-        .max(XPUB_MAX_LENGTH)
-        .describe('A watch-only extended PUBLIC key. A private extended key is refused (`watch_only_violation`) and never stored.'),
-})
-    .strict();
+exports.confirmFaircoinOnboardingParams = zod_1.z.object({}).strict();
 const tokenParam = { token: 'The onboarding link token (the last segment of its `url`).' };
 exports.connectOnboardingRoutes = [
     (0, route_1.defineRoute)({
@@ -68,15 +57,15 @@ exports.connectOnboardingRoutes = [
         response: exports.connectOnboardingSchema,
     }),
     (0, route_1.defineRoute)({
-        operationId: 'registerConnectOnboardingFaircoinKey',
+        operationId: 'confirmConnectOnboardingFaircoin',
         method: 'post',
         path: '/v1/connect/onboarding/{token}/faircoin',
         tag: 'Connect onboarding',
-        summary: "Register the seller's FairCoin key",
-        description: 'The ONLY way a key reaches a connected account: runs the non-custody firewall, consumes the link and tells the platform (`connected_account.updated`), in one transaction. The key is immutable once registered and never appears on any response.',
+        summary: 'Confirm FairCoin payments into the seller’s Peable wallet',
+        description: 'The seller, signed in as the account the link names, confirms that FairCoin paid to them goes to that account’s Peable wallet (ADR 0021 D5) — the only way a FairCoin half becomes payable. No key is sent: addresses derive from the account’s public identity key. 409 `faircoin_wallet_missing` while the account has no Peable wallet yet. Consumes the link and tells the platform (`connected_account.updated`) in one transaction.',
         auth: 'user',
         params: tokenParam,
-        body: exports.registerFaircoinKeyParams,
+        body: exports.confirmFaircoinOnboardingParams,
         response: exports.connectOnboardingCompleteSchema,
     }),
 ];

package/dist/cjs/resources/payments/paymentIntents.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.paymentIntentRoutes = exports.clientSecretQuery = exports.retrievePaymentIntentQuery = exports.clientSecretParam = exports.listPaymentIntentsQuery = exports.submitPaymentIntentTxParams = exports.cancelPaymentIntentParams = exports.capturePaymentIntentParams = exports.confirmPaymentIntentParams = exports.updatePaymentIntentParams = exports.createPaymentIntentParams = exports.connectedAccountParam = exports.railParams = exports.paymentIntentSchema = exports.paymentIntentClientActionSchema = exports.clientActionSchema = exports.paymentIntentTransferDataSchema = exports.paymentIntentFaircoinSchema = exports.paymentIntentNextActionSchema = exports.paymentErrorSchema = void 0;
+exports.paymentIntentRoutes = exports.clientSecretQuery = exports.retrievePaymentIntentQuery = exports.clientSecretParam = exports.listPaymentIntentsQuery = exports.submitPaymentIntentTxParams = exports.cancelPaymentIntentParams = exports.capturePaymentIntentParams = exports.confirmPaymentIntentParams = exports.updatePaymentIntentParams = exports.createPaymentIntentParams = exports.connectedAccountParam = exports.railParams = exports.paymentIntentSchema = exports.paymentIntentClientActionSchema = exports.clientActionSchema = exports.paymentIntentTransferDataSchema = exports.paymentIntentFaircoinSchema = exports.faircoinQuoteSchema = exports.paymentIntentNextActionSchema = exports.paymentErrorSchema = void 0;
 const zod_1 = require("zod");
 const address_1 = require("../../common/address");
 const envelopes_1 = require("../../common/envelopes");
@@ -52,6 +52,39 @@ exports.paymentIntentNextActionSchema = (0, objects_1.defineComponent)('PaymentI
         .strict(),
     zod_1.z.object({ type: zod_1.z.literal('use_peable_sdk') }).strict(),
 ]));
+/**
+ * The FairCoin price of a FIAT order (ADR 0021 D4), carried by the FairCoin
+ * payment the payer chose for it. Pricing, never exchange: the payer pays
+ * `amount` FAIR (the intent's) to the payee's own address, and no fiat moves.
+ * `rate` is for display; the FAIR amount is exactly
+ * `ceil(amount ÷ rate)` computed from the sources' own figures.
+ */
+exports.faircoinQuoteSchema = (0, objects_1.defineComponent)('FaircoinQuote', zod_1.z
+    .object({
+    currency: primitives_1.fiatCurrency.describe("The order's currency."),
+    amount: primitives_1.amount.describe("The order's total in base units of `currency` (tax included)."),
+    rate: zod_1.z.string().describe('`currency` per 1 FAIR, rounded to 10 significant digits.'),
+    price: zod_1.z
+        .object({
+        source: zod_1.z.literal('wfair-base'),
+        usd_per_fair: zod_1.z.string().describe("The FairCoin Explorer's FAIR/USD price."),
+        observed_at: primitives_1.unixSeconds,
+    })
+        .strict(),
+    reference_rates: zod_1.z
+        .object({
+        source: zod_1.z.literal('ecb'),
+        usd_per_eur: zod_1.z.string(),
+        currency_per_eur: zod_1.z.string().describe('`1` for EUR.'),
+        observed_at: primitives_1.unixSeconds,
+    })
+        .strict()
+        .nullable()
+        .describe("The European Central Bank's reference rates; `null` for a USD order."),
+    quoted_at: primitives_1.unixSeconds,
+    expires_at: primitives_1.unixSeconds.describe('The payment expires with its quote unless already broadcast.'),
+})
+    .strict());
 /**
  * The chain side of a FairCoin payment. `txid` and `confirmations` describe the
  * transaction the payer reported: `null`/`0` while `requires_action`, the
@@ -62,10 +95,13 @@ exports.paymentIntentFaircoinSchema = (0, objects_1.defineComponent)('PaymentInt
     network: primitives_1.network,
     address: zod_1.z
         .string()
-        .describe("Watch-only receive address derived per intent from the merchant's (or seller's) xpub."),
+        .describe("Receive address in the Peable wallet of the account this payment pays (the merchant's owner, or the seller), derived per payment from that account's public identity key (ADR 0021 D5)."),
     txid: primitives_1.nullableString,
     confirmations: zod_1.z.number().int().nonnegative(),
     required_confirmations: zod_1.z.number().int().nonnegative(),
+    quote: exports.faircoinQuoteSchema
+        .nullable()
+        .describe('The fiat order this payment pays, as quoted (ADR 0021); `null` on a FAIR-priced payment.'),
 })
     .strict());
 /** Where a destination charge's funds go (`transfer_data`, ADR 0015 §2). */
@@ -196,6 +232,7 @@ exports.paymentIntentSchema = (0, objects_1.defineObject)('payment_intent', 'Pay
                 txid: null,
                 confirmations: 0,
                 required_confirmations: 6,
+                quote: null,
             },
             merchant_id: 'merch_0193b8f2c1a87d3e9f4a',
             connected_account: null,

package/dist/cjs/vocabulary/checkout.js

@@ -4,7 +4,24 @@
 // the wallet import them without the schemas (`@peable.to/contracts/vocabulary`,
 // re-exported by `@peable.to/shared-types`).
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAYMENT_LINK_LIMITS = exports.CHECKOUT_SESSION_ID_TEMPLATE = exports.CHECKOUT_LIMITS = exports.CHECKOUT_TAX_ID_TYPES = exports.CHECKOUT_CUSTOM_FIELD_TYPES = exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = exports.CHECKOUT_CUSTOMER_CREATIONS = exports.CHECKOUT_SUBMIT_TYPES = exports.CHECKOUT_LOCALES = exports.CHECKOUT_UI_MODES = exports.CHECKOUT_PAYMENT_STATUSES = exports.CHECKOUT_SESSION_STATUSES = exports.CHECKOUT_SESSION_MODES = void 0;
+exports.PAYMENT_LINK_LIMITS = exports.CHECKOUT_SESSION_ID_TEMPLATE = exports.CHECKOUT_LIMITS = exports.CHECKOUT_TAX_ID_TYPES = exports.CHECKOUT_CUSTOM_FIELD_TYPES = exports.CHECKOUT_BILLING_ADDRESS_COLLECTIONS = exports.CHECKOUT_CUSTOMER_CREATIONS = exports.CHECKOUT_SUBMIT_TYPES = exports.CHECKOUT_LOCALES = exports.CHECKOUT_UI_MODES = exports.CHECKOUT_PAYMENT_STATUSES = exports.CHECKOUT_SESSION_STATUSES = exports.CHECKOUT_SESSION_MODES = exports.FAIRCOIN_UNAVAILABLE_REASONS = void 0;
+/**
+ * Why FairCoin cannot be paid with on an order right now (ADR 0021). It is
+ * still offered — never hidden — and says why:
+ *
+ *  - `faircoin_wallet_missing` — the Peable wallet of the account that receives
+ *    (the merchant's owner, or the seller) isn't set up yet: no identity key;
+ *  - `faircoin_network_closed` — this deployment does not open payments on the
+ *    order's FairCoin network yet (ADR 0002's gate);
+ *  - `price_unavailable` — no fresh FairCoin price exists to quote a fiat order;
+ *  - `temporarily_unavailable` — whether the wallet exists could not be checked.
+ */
+exports.FAIRCOIN_UNAVAILABLE_REASONS = [
+    'faircoin_wallet_missing',
+    'faircoin_network_closed',
+    'price_unavailable',
+    'temporarily_unavailable',
+];
 exports.CHECKOUT_SESSION_MODES = ['payment', 'setup', 'subscription'];
 exports.CHECKOUT_SESSION_STATUSES = ['open', 'complete', 'expired'];
 exports.CHECKOUT_PAYMENT_STATUSES = ['paid', 'unpaid', 'no_payment_required'];

package/dist/cjs/vocabulary/errors.js

@@ -60,6 +60,7 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     parameter_missing: 'A required parameter is missing; `param` names it.',
     parameter_unknown: 'The request carries a parameter this route does not accept; `param` names it.',
     payment_intent_unexpected_state: 'The PaymentIntent is in a status that does not allow this operation.',
+    payment_method_locked: 'The payment method cannot be turned off or removed: FairCoin is always offered to every payer; `param` names the field.',
     payout_not_allowed: 'Payouts cannot be created for this account.',
     rate_limited: 'Too many requests; back off and retry.',
     refund_not_cancelable: 'The refund has already left a cancelable state.',
@@ -70,7 +71,6 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     test_mode_only: 'This operation exists in test mode only.',
     too_many_streams: 'Too many live streams are open for this merchant.',
     url_invalid: 'The URL is not an allowed https URL.',
-    watch_only_violation: 'The extended key carries a private key. Peable only ever accepts watch-only (public) keys.',
     webhook_endpoint_disabled: 'The webhook endpoint is disabled.',
     webhook_endpoint_limit_reached: 'The merchant already has the maximum number of webhook endpoints.',
     account_not_ready: 'The connected account cannot take this payment yet: its onboarding or a capability is incomplete.',
@@ -131,6 +131,9 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     promotion_code_minimum_amount: 'The purchase is below the promotion code minimum amount.',
     payment_method_missing: 'No payment method is available to charge.',
     faircoin_cannot_debit: 'A FairCoin invoice cannot be charged automatically: the payer signs every payment.',
+    faircoin_price_unavailable: 'No fresh FairCoin price exists right now, so this order cannot be quoted in FAIR. The other payment methods still work; try FairCoin again shortly.',
+    faircoin_wallet_missing: "The Peable wallet that receives this payment (the merchant owner's, or the seller's) isn't set up yet, so it cannot be paid in FairCoin. The other payment methods still work.",
+    faircoin_network_closed: 'FairCoin payments on this network are not open on this deployment yet. The other payment methods still work.',
     credit_note_exceeds_invoice: "The credit note's amount exceeds what the invoice can still credit.",
     test_clock_unexpected_state: 'The test clock is advancing; wait until it is ready.',
     meter_event_customer_missing: 'The meter event names no customer of this merchant.',
@@ -143,8 +146,7 @@ exports.ERROR_CODE_DESCRIPTIONS = {
     // Connect onboarding (ADR 0012 D3): the seller-facing refusals.
     link_expired: 'The onboarding link has expired or was already used; `refresh_url` is where the seller gets a fresh one.',
     wrong_seller: 'The onboarding link names a different Oxy account; sign in as the seller it was minted for.',
-    already_registered: 'The seller already registered a FairCoin key, and it cannot be changed.',
-    key_in_use: 'The key already receives payments for another account.',
+    already_registered: 'The seller already confirmed FairCoin payments into their Peable wallet.',
     no_faircoin_half: 'The connected account has no FairCoin half to register a key for.',
     // The dashboard routes (`/v1/dashboard/*`, Orbit): the signed-in person, not a credential.
     merchant_missing: 'The application has no merchant in this environment yet; register one (Orbit shows "Set up payments").',