@peable.to/shared-types 0.14.0 → 0.15.0

package/dist/cjs/account.js

@@ -0,0 +1,23 @@
+"use strict";
+// The merchant's fiat account (ADR 0015 §1) — `GET /v1/account`.
+//
+// Orbit's funds never reach a Peable bank account: a merchant that takes fiat
+// has its OWN provider account, opened and onboarded through Peable, and this
+// object mirrors it. Everything here is what the provider last reported; the
+// provider is the authority and Orbit never decides readiness itself.
+//
+// A marketplace's sellers (`/v1/connected_accounts`) are provider accounts too,
+// and a platform reads one of them in this same shape by sending
+// `Peable-Account: ca_…` to `GET /v1/account`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PAYOUT_WEEKLY_ANCHORS = exports.PAYOUT_INTERVALS = void 0;
+exports.PAYOUT_INTERVALS = ['manual', 'daily', 'weekly', 'monthly'];
+exports.PAYOUT_WEEKLY_ANCHORS = [
+    'monday',
+    'tuesday',
+    'wednesday',
+    'thursday',
+    'friday',
+    'saturday',
+    'sunday',
+];

package/dist/cjs/balance.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECONCILIATION_MISMATCH_KINDS = exports.PAYOUT_STATUSES = exports.BALANCE_TRANSACTION_STATUSES = exports.BALANCE_TRANSACTION_TYPES = void 0;
+/** Orbit's vocabulary for what moved — the provider's own types, provider-neutral. */
+exports.BALANCE_TRANSACTION_TYPES = [
+    'charge',
+    'payment',
+    'refund',
+    'payment_refund',
+    'adjustment',
+    'application_fee',
+    'application_fee_refund',
+    'payout',
+    'payout_cancel',
+    'payout_failure',
+    'transfer',
+    'transfer_refund',
+    'dispute',
+    'dispute_reversal',
+    'processing_fee',
+    'faircoin_payment',
+    'faircoin_payment_reversal',
+    'other',
+];
+/**
+ * - `pending` / `available` — the provider's own status for the funds.
+ * - `informational` — a FairCoin payment: recorded, never part of a payable balance.
+ */
+exports.BALANCE_TRANSACTION_STATUSES = ['available', 'pending', 'informational'];
+exports.PAYOUT_STATUSES = ['pending', 'in_transit', 'paid', 'failed', 'canceled'];
+/** What the daily reconciliation found disagreeing with the provider. Never auto-corrected. */
+exports.RECONCILIATION_MISMATCH_KINDS = [
+    'missing_in_ledger',
+    'amount_mismatch',
+    'status_mismatch',
+    'missing_at_provider',
+    'payout_mismatch',
+    'unbalanced_journal',
+];

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyWebhook = exports.signWebhook = exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_METHODS = exports.PAYMENT_METHOD_CURRENCIES = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.FILE_TYPES = exports.FILE_STATUSES = exports.FILE_PURPOSE_POLICIES = exports.FILE_PURPOSES = exports.normalizeDisputeReason = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.CATALOG_LIMITS = exports.COUPON_DURATIONS = exports.TRANSFORM_QUANTITY_ROUNDS = exports.PRICE_TAX_BEHAVIORS = exports.RECURRING_USAGE_TYPES = exports.RECURRING_INTERVALS = exports.PRICE_TYPES = exports.PRICE_TIERS_MODES = exports.PRICE_BILLING_SCHEMES = exports.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = exports.WEBHOOK_ENDPOINT_STATUSES = exports.PEABLE_API_VERSION = exports.SETUP_INTENT_STATUSES = exports.isValidStatusTransition = exports.canStillBePaid = exports.canExpire = exports.TERMINAL_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.MERCHANT_CANCELLATION_REASONS = exports.EXPIRABLE_STATUSES = exports.CARD_ONLY_STATUSES = exports.isCurrencyCode = exports.decimalsFor = exports.FIAT_CURRENCY_CODES = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
-exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.canonicalBillingTaxQuote = exports.canonicalBillingAuthority = exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.MERCHANT_ENVIRONMENTS = void 0;
+exports.PAYOUT_STATUSES = exports.BALANCE_TRANSACTION_TYPES = exports.BALANCE_TRANSACTION_STATUSES = exports.PAYOUT_WEEKLY_ANCHORS = exports.PAYOUT_INTERVALS = exports.PAYMENT_METHOD_CURRENCIES = exports.PAYMENT_METHOD_CONFIGURATION_TYPES = exports.CARD_RAIL_PAYMENT_METHOD_TYPES = exports.FILE_TYPES = exports.FILE_STATUSES = exports.FILE_PURPOSE_POLICIES = exports.FILE_PURPOSES = exports.normalizeDisputeReason = exports.DISPUTE_TEXT_EVIDENCE_FIELDS = exports.DISPUTE_REASONS = exports.DISPUTE_FILE_EVIDENCE_FIELDS = exports.CATALOG_LIMITS = exports.COUPON_DURATIONS = exports.TRANSFORM_QUANTITY_ROUNDS = exports.PRICE_TAX_BEHAVIORS = exports.RECURRING_USAGE_TYPES = exports.RECURRING_INTERVALS = exports.PRICE_TYPES = exports.PRICE_TIERS_MODES = exports.PRICE_BILLING_SCHEMES = exports.WEBHOOK_SECRET_ROLL_MAX_EXPIRES_IN_SECONDS = exports.WEBHOOK_ENDPOINTS_MAX_PER_MERCHANT = exports.WEBHOOK_ENDPOINT_DISABLED_REASONS = exports.WEBHOOK_ENDPOINT_STATUSES = exports.PEABLE_API_VERSION = exports.SETUP_INTENT_STATUSES = exports.isValidStatusTransition = exports.canStillBePaid = exports.canExpire = exports.TERMINAL_STATUSES = exports.PAYMENT_INTENT_STATUSES = exports.PAYMENT_INTENT_SETUP_FUTURE_USAGES = exports.PAYMENT_INTENT_RAILS = exports.PAYMENT_INTENT_CAPTURE_METHODS = exports.PAYMENT_INTENT_CANCELLATION_REASONS = exports.MERCHANT_CANCELLATION_REASONS = exports.EXPIRABLE_STATUSES = exports.CARD_ONLY_STATUSES = exports.isCurrencyCode = exports.decimalsFor = exports.FIAT_CURRENCY_CODES = exports.CURRENCY_DECIMALS = exports.CURRENCY_CODES = exports.isBaseUnitString = exports.UNITS_PER_COIN = void 0;
+exports.TAX_LOCATION_EVIDENCE_TYPES = exports.TAX_REGISTRATION_SCHEMES = exports.PEABLE_BILLING_AUTHORITY_KEYS = exports.canonicalBillingTaxQuote = exports.canonicalBillingAuthority = exports.BILLING_SUBSCRIPTION_STATUSES = exports.SOCIAL_SOURCE_REF_MAX_LENGTH = exports.SOCIAL_SOURCE_APP_MAX_LENGTH = exports.MERCHANT_ENVIRONMENTS = exports.verifyWebhook = exports.signWebhook = exports.SIMULATED_FAIRCOIN_OUTCOMES = exports.REQUEST_LOG_RETENTION_DAYS = exports.REQUEST_LOG_METHODS = exports.REFUND_REASONS = exports.RECONCILIATION_MISMATCH_KINDS = void 0;
 // @peable.to/shared-types — public API for the Peable Gateway contract.
 var money_1 = require("./money");
 Object.defineProperty(exports, "UNITS_PER_COIN", { enumerable: true, get: function () { return money_1.UNITS_PER_COIN; } });
@@ -57,6 +57,16 @@ var paymentMethodConfiguration_1 = require("./paymentMethodConfiguration");
 Object.defineProperty(exports, "CARD_RAIL_PAYMENT_METHOD_TYPES", { enumerable: true, get: function () { return paymentMethodConfiguration_1.CARD_RAIL_PAYMENT_METHOD_TYPES; } });
 Object.defineProperty(exports, "PAYMENT_METHOD_CONFIGURATION_TYPES", { enumerable: true, get: function () { return paymentMethodConfiguration_1.PAYMENT_METHOD_CONFIGURATION_TYPES; } });
 Object.defineProperty(exports, "PAYMENT_METHOD_CURRENCIES", { enumerable: true, get: function () { return paymentMethodConfiguration_1.PAYMENT_METHOD_CURRENCIES; } });
+var account_1 = require("./account");
+Object.defineProperty(exports, "PAYOUT_INTERVALS", { enumerable: true, get: function () { return account_1.PAYOUT_INTERVALS; } });
+Object.defineProperty(exports, "PAYOUT_WEEKLY_ANCHORS", { enumerable: true, get: function () { return account_1.PAYOUT_WEEKLY_ANCHORS; } });
+var balance_1 = require("./balance");
+Object.defineProperty(exports, "BALANCE_TRANSACTION_STATUSES", { enumerable: true, get: function () { return balance_1.BALANCE_TRANSACTION_STATUSES; } });
+Object.defineProperty(exports, "BALANCE_TRANSACTION_TYPES", { enumerable: true, get: function () { return balance_1.BALANCE_TRANSACTION_TYPES; } });
+Object.defineProperty(exports, "PAYOUT_STATUSES", { enumerable: true, get: function () { return balance_1.PAYOUT_STATUSES; } });
+Object.defineProperty(exports, "RECONCILIATION_MISMATCH_KINDS", { enumerable: true, get: function () { return balance_1.RECONCILIATION_MISMATCH_KINDS; } });
+var settlement_1 = require("./settlement");
+Object.defineProperty(exports, "REFUND_REASONS", { enumerable: true, get: function () { return settlement_1.REFUND_REASONS; } });
 var requestLog_1 = require("./requestLog");
 Object.defineProperty(exports, "REQUEST_LOG_METHODS", { enumerable: true, get: function () { return requestLog_1.REQUEST_LOG_METHODS; } });
 Object.defineProperty(exports, "REQUEST_LOG_RETENTION_DAYS", { enumerable: true, get: function () { return requestLog_1.REQUEST_LOG_RETENTION_DAYS; } });

package/dist/cjs/settlement.js

@@ -1,2 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFUND_REASONS = void 0;
+/** Stripe's refund reasons. */
+exports.REFUND_REASONS = ['duplicate', 'fraudulent', 'requested_by_customer'];

package/dist/esm/account.js

@@ -0,0 +1,20 @@
+// The merchant's fiat account (ADR 0015 §1) — `GET /v1/account`.
+//
+// Orbit's funds never reach a Peable bank account: a merchant that takes fiat
+// has its OWN provider account, opened and onboarded through Peable, and this
+// object mirrors it. Everything here is what the provider last reported; the
+// provider is the authority and Orbit never decides readiness itself.
+//
+// A marketplace's sellers (`/v1/connected_accounts`) are provider accounts too,
+// and a platform reads one of them in this same shape by sending
+// `Peable-Account: ca_…` to `GET /v1/account`.
+export const PAYOUT_INTERVALS = ['manual', 'daily', 'weekly', 'monthly'];
+export const PAYOUT_WEEKLY_ANCHORS = [
+    'monday',
+    'tuesday',
+    'wednesday',
+    'thursday',
+    'friday',
+    'saturday',
+    'sunday',
+];

package/dist/esm/balance.js

@@ -0,0 +1,36 @@
+/** Orbit's vocabulary for what moved — the provider's own types, provider-neutral. */
+export const BALANCE_TRANSACTION_TYPES = [
+    'charge',
+    'payment',
+    'refund',
+    'payment_refund',
+    'adjustment',
+    'application_fee',
+    'application_fee_refund',
+    'payout',
+    'payout_cancel',
+    'payout_failure',
+    'transfer',
+    'transfer_refund',
+    'dispute',
+    'dispute_reversal',
+    'processing_fee',
+    'faircoin_payment',
+    'faircoin_payment_reversal',
+    'other',
+];
+/**
+ * - `pending` / `available` — the provider's own status for the funds.
+ * - `informational` — a FairCoin payment: recorded, never part of a payable balance.
+ */
+export const BALANCE_TRANSACTION_STATUSES = ['available', 'pending', 'informational'];
+export const PAYOUT_STATUSES = ['pending', 'in_transit', 'paid', 'failed', 'canceled'];
+/** What the daily reconciliation found disagreeing with the provider. Never auto-corrected. */
+export const RECONCILIATION_MISMATCH_KINDS = [
+    'missing_in_ledger',
+    'amount_mismatch',
+    'status_mismatch',
+    'missing_at_provider',
+    'payout_mismatch',
+    'unbalanced_journal',
+];

package/dist/esm/index.js

@@ -8,6 +8,9 @@ export { PRICE_BILLING_SCHEMES, PRICE_TIERS_MODES, PRICE_TYPES, RECURRING_INTERV
 export { DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_TEXT_EVIDENCE_FIELDS, normalizeDisputeReason, } from './dispute.js';
 export { FILE_PURPOSES, FILE_PURPOSE_POLICIES, FILE_STATUSES, FILE_TYPES, } from './file.js';
 export { CARD_RAIL_PAYMENT_METHOD_TYPES, PAYMENT_METHOD_CONFIGURATION_TYPES, PAYMENT_METHOD_CURRENCIES, } from './paymentMethodConfiguration.js';
+export { PAYOUT_INTERVALS, PAYOUT_WEEKLY_ANCHORS, } from './account.js';
+export { BALANCE_TRANSACTION_STATUSES, BALANCE_TRANSACTION_TYPES, PAYOUT_STATUSES, RECONCILIATION_MISMATCH_KINDS, } from './balance.js';
+export { REFUND_REASONS } from './settlement.js';
 export { REQUEST_LOG_METHODS, REQUEST_LOG_RETENTION_DAYS, } from './requestLog.js';
 export { SIMULATED_FAIRCOIN_OUTCOMES, } from './testHelpers.js';
 export { signWebhook, verifyWebhook } from './webhookSigner.js';

package/dist/esm/settlement.js

@@ -1 +1,2 @@
-export {};
+/** Stripe's refund reasons. */
+export const REFUND_REASONS = ['duplicate', 'fraudulent', 'requested_by_customer'];

package/dist/types/account.d.ts

@@ -0,0 +1,120 @@
+/** A capability's state as the provider reports it; `null` means never requested. */
+export type AccountCapabilityStatus = 'active' | 'pending' | 'inactive';
+/** Whose account this is: the merchant's own, or one of its marketplace sellers. */
+export type AccountType = 'merchant' | 'connected';
+/**
+ * What the provider is waiting on. Requirement IDENTIFIERS only
+ * (`individual.verification.document`), never their values: the gateway
+ * records that a document is owed and never learns what it says.
+ */
+export interface AccountRequirements {
+    currently_due: string[];
+    eventually_due: string[];
+    past_due: string[];
+    /** Submitted and being checked — nothing for the merchant to do. */
+    pending_verification: string[];
+    /** Why charges or payouts are disabled, in the provider's own code, or `null`. */
+    disabled_reason: string | null;
+}
+export interface AccountBusinessProfile {
+    name: string | null;
+    url: string | null;
+    support_email: string | null;
+    support_url: string | null;
+    product_description: string | null;
+    /** Merchant category code. */
+    mcc: string | null;
+}
+export declare const PAYOUT_INTERVALS: readonly ["manual", "daily", "weekly", "monthly"];
+export type PayoutInterval = (typeof PAYOUT_INTERVALS)[number];
+export declare const PAYOUT_WEEKLY_ANCHORS: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+export type PayoutWeeklyAnchor = (typeof PAYOUT_WEEKLY_ANCHORS)[number];
+/**
+ * When the provider pays the balance out. `manual` means only an explicit
+ * `POST /v1/payouts` does — the provider still executes it; Orbit never moves
+ * the money itself (ADR 0015 §4).
+ */
+export interface AccountPayoutSchedule {
+    interval: PayoutInterval;
+    /** Days between a payment and its funds becoming payable; `null` when not reported. */
+    delay_days: number | null;
+    /** `weekly` only. */
+    weekly_anchor: PayoutWeeklyAnchor | null;
+    /** `monthly` only: the day of the month, 1–31. */
+    monthly_anchor: number | null;
+}
+export interface AccountSettings {
+    payouts: {
+        schedule: AccountPayoutSchedule | null;
+        /** What the merchant's bank statement shows for a payout. */
+        statement_descriptor: string | null;
+    };
+    payments: {
+        /** What a cardholder's statement shows — the merchant is the merchant of record. */
+        statement_descriptor: string | null;
+    };
+    branding: {
+        primary_color: string | null;
+        secondary_color: string | null;
+    };
+}
+export interface Account {
+    /** `ca_…` — the same id space as a marketplace seller. */
+    id: string;
+    object: 'account';
+    /** `true` for a `production` merchant (ADR 0017). */
+    livemode: boolean;
+    type: AccountType;
+    /** ISO 3166-1 alpha-2. Fixed at the provider once created. */
+    country: string;
+    default_currency: string | null;
+    business_profile: AccountBusinessProfile;
+    capabilities: {
+        card_payments: AccountCapabilityStatus | null;
+        transfers: AccountCapabilityStatus | null;
+    };
+    requirements: AccountRequirements;
+    /** Whether the account can take payments as merchant of record (`on_behalf_of`). */
+    charges_enabled: boolean;
+    /** Whether the provider will pay this account's balance out. */
+    payouts_enabled: boolean;
+    settings: AccountSettings;
+    /** The last provider read; `null` before the first one completed. */
+    last_synced_at: number | null;
+    created: number;
+}
+/** `POST /v1/account`: the account's settings, written to the provider and read back. */
+export interface UpdateAccountParams {
+    /**
+     * Opening the account: required the first time (when the merchant has none),
+     * refused afterwards — a provider account's country cannot change.
+     */
+    country?: string;
+    business_type?: 'individual' | 'company';
+    business_profile?: Partial<AccountBusinessProfile>;
+    settings?: {
+        payouts?: {
+            schedule?: {
+                interval: PayoutInterval;
+                delay_days?: number;
+                weekly_anchor?: PayoutWeeklyAnchor;
+                monthly_anchor?: number;
+            };
+            statement_descriptor?: string;
+        };
+        payments?: {
+            statement_descriptor?: string;
+        };
+        branding?: {
+            primary_color?: string;
+            secondary_color?: string;
+        };
+    };
+}
+/** `POST /v1/account_links`: hosted onboarding (or an update of what was submitted). */
+export interface CreateAccountLinkParams {
+    refresh_url: string;
+    return_url: string;
+    /** Defaults to `account_onboarding`. */
+    type?: 'account_onboarding' | 'account_update';
+}

package/dist/types/balance.d.ts

@@ -0,0 +1,204 @@
+import type { CurrencyCode } from './money';
+import type { List } from './list';
+/** One currency's figure in a balance. */
+export interface BalanceAmount {
+    /** Signed base units. */
+    amount: string;
+    currency: CurrencyCode | string;
+}
+/**
+ * `GET /v1/balance` — read from the ledger, per currency.
+ *
+ * A merchant without a fiat account has NO balance and is told so (404
+ * `account_missing`), never shown zeros (ADR 0015 consequences).
+ */
+export interface Balance {
+    object: 'balance';
+    livemode: boolean;
+    /** Payable now: the provider has made these funds available. */
+    available: BalanceAmount[];
+    /** Not yet available at the provider. */
+    pending: BalanceAmount[];
+    /**
+     * FairCoin received straight into the merchant's own wallet (ADR 0015 §5).
+     * Recorded for the merchant's books only: Orbit never held it, so it is never
+     * payable and no payout draws on it.
+     */
+    informational: BalanceAmount[];
+    /** The account (`ca_…`) this balance mirrors; `null` for an Oxy first-party merchant. */
+    account: string | null;
+}
+/** Orbit's vocabulary for what moved — the provider's own types, provider-neutral. */
+export declare const BALANCE_TRANSACTION_TYPES: readonly ["charge", "payment", "refund", "payment_refund", "adjustment", "application_fee", "application_fee_refund", "payout", "payout_cancel", "payout_failure", "transfer", "transfer_refund", "dispute", "dispute_reversal", "processing_fee", "faircoin_payment", "faircoin_payment_reversal", "other"];
+export type BalanceTransactionType = (typeof BALANCE_TRANSACTION_TYPES)[number];
+/**
+ * - `pending` / `available` — the provider's own status for the funds.
+ * - `informational` — a FairCoin payment: recorded, never part of a payable balance.
+ */
+export declare const BALANCE_TRANSACTION_STATUSES: readonly ["available", "pending", "informational"];
+export type BalanceTransactionStatus = (typeof BALANCE_TRANSACTION_STATUSES)[number];
+/** One component of a transaction's fee. `processing_fee` is the acquirer's own. */
+export interface BalanceTransactionFeeDetail {
+    amount: string;
+    currency: string;
+    type: 'application_fee' | 'processing_fee' | 'tax' | 'other';
+}
+export interface BalanceTransaction {
+    /** `txn_…` */
+    id: string;
+    object: 'balance_transaction';
+    livemode: boolean;
+    /** Gross, signed. */
+    amount: string;
+    /** What was taken, or `null` when the source gave no figure (never `0` for unknown). */
+    fee: string | null;
+    /** `amount - fee`, as the provider reports it, or `null` with `fee`. */
+    net: string | null;
+    currency: string;
+    type: BalanceTransactionType;
+    /** A coarser grouping for reports (`charge`, `refund`, `payout`, `fee`, …). */
+    reporting_category: string;
+    status: BalanceTransactionStatus;
+    /** When the funds became (or become) available; `null` for an informational entry. */
+    available_on: number | null;
+    /** When it happened at its source. */
+    created: number;
+    description: string | null;
+    exchange_rate: number | null;
+    fee_details: BalanceTransactionFeeDetail[];
+    /**
+     * The Orbit object that caused it (`ch_…`, `re_…`, `po_…`, `fee_…`, `tr_…`,
+     * `pi_…`), or `null` when the provider's source is not an object Orbit holds.
+     */
+    source: string | null;
+    /** The payout (`po_…`) that paid this transaction out, once known. */
+    payout: string | null;
+    /** The account (`ca_…`) whose balance it moved; `null` for a first-party merchant. */
+    account: string | null;
+}
+/** `GET /v1/balance_transactions` filters, beside the list parameters. */
+export interface ListBalanceTransactionsParams {
+    type?: BalanceTransactionType;
+    /** `po_…`: only the transactions that payout paid out. */
+    payout?: string;
+    /** An Orbit object id the transaction was caused by. */
+    source?: string;
+    currency?: string;
+}
+export declare const PAYOUT_STATUSES: readonly ["pending", "in_transit", "paid", "failed", "canceled"];
+export type PayoutStatus = (typeof PAYOUT_STATUSES)[number];
+/**
+ * A payout (`po_…`) — the provider moving the merchant's balance to the
+ * merchant's bank. Executed by the provider, always; Orbit instructs (a manual
+ * payout) or mirrors (a scheduled one). The bank account itself stays at the
+ * provider and is never on this object.
+ */
+export interface Payout {
+    id: string;
+    object: 'payout';
+    livemode: boolean;
+    /** The account (`ca_…`) paid out. */
+    account: string;
+    amount: string;
+    currency: string;
+    status: PayoutStatus;
+    /** When the funds are expected in the bank, as the provider estimates. */
+    arrival_date: number | null;
+    /** `true` when the provider's schedule created it, `false` for `POST /v1/payouts`. */
+    automatic: boolean;
+    method: 'standard' | 'instant';
+    type: 'bank_account' | 'card';
+    description: string | null;
+    statement_descriptor: string | null;
+    /** The provider's failure code when `failed`; never its prose. */
+    failure_code: string | null;
+    /** The payout's own `txn_…` once ingested. */
+    balance_transaction: string | null;
+    metadata: Record<string, string>;
+    created: number;
+}
+/** `POST /v1/payouts` — a payout instruction for an account on a manual schedule. */
+export interface CreatePayoutParams {
+    amount: string;
+    currency: CurrencyCode;
+    description?: string;
+    statement_descriptor?: string;
+    method?: 'standard' | 'instant';
+    metadata?: Record<string, string>;
+}
+export interface ListPayoutsParams {
+    status?: PayoutStatus;
+}
+/** A refund of an application fee (`fr_…`). */
+export interface FeeRefund {
+    id: string;
+    object: 'fee_refund';
+    amount: string;
+    currency: string;
+    /** The `fee_…` it refunds. */
+    fee: string;
+    created: number;
+}
+/**
+ * Orbit's fee on one payment (`fee_…`, ADR 0015 §3), taken by the provider from
+ * the merchant's account when the charge succeeded. Created from the provider's
+ * own record, never computed after the fact.
+ */
+export interface ApplicationFee {
+    id: string;
+    object: 'application_fee';
+    livemode: boolean;
+    /** The account (`ca_…`) the fee was taken from. */
+    account: string;
+    amount: string;
+    amount_refunded: string;
+    currency: string;
+    /** The `ch_…` it was taken on, when Orbit holds the charge. */
+    charge: string | null;
+    /** The `pi_…` it was taken on. */
+    payment_intent: string;
+    /** Refunded in full. */
+    refunded: boolean;
+    refunds: List<FeeRefund>;
+    created: number;
+}
+/**
+ * `GET /v1/reports/payout_reconciliation?payout=po_…` — the balance
+ * transactions one payout paid out, with their totals. A list page with the
+ * report's fields beside it.
+ */
+export interface PayoutReconciliationReport extends List<BalanceTransaction> {
+    payout: string;
+    /**
+     * `complete` once the payout is `paid` and its transactions were read from
+     * the provider; `pending` before — the set is not final and the totals may grow.
+     */
+    status: 'complete' | 'pending';
+    currency: string;
+    /** Over EVERY transaction of the payout, not just this page. */
+    summary: {
+        count: number;
+        amount: string;
+        fee: string;
+        net: string;
+    };
+}
+/** What the daily reconciliation found disagreeing with the provider. Never auto-corrected. */
+export declare const RECONCILIATION_MISMATCH_KINDS: readonly ["missing_in_ledger", "amount_mismatch", "status_mismatch", "missing_at_provider", "payout_mismatch", "unbalanced_journal"];
+export type ReconciliationMismatchKind = (typeof RECONCILIATION_MISMATCH_KINDS)[number];
+export interface ReconciliationMismatch {
+    id: string;
+    object: 'reconciliation_mismatch';
+    livemode: boolean;
+    account: string | null;
+    kind: ReconciliationMismatchKind;
+    /** The Orbit object concerned (`txn_…`, `po_…`), when Orbit holds one. */
+    object_id: string | null;
+    /** What the provider says (`expected`) against what the ledger holds (`actual`). */
+    expected: Record<string, unknown> | null;
+    actual: Record<string, unknown> | null;
+    detected_at: number;
+    last_seen_at: number;
+    /** Set when a later run no longer sees the difference. */
+    resolved_at: number | null;
+}

package/dist/types/charge.d.ts

@@ -47,8 +47,15 @@ export interface Charge {
     } | null;
     /** Peable-hosted receipts land with Phase 3; the provider's own URL never reaches the wire. */
     receipt_url: string | null;
-    /** A Peable balance transaction (`txn_…`) once the ledger exists (Phase 5). */
+    /**
+     * The ledger's `txn_…` for this charge once the provider's balance
+     * transaction was ingested (ADR 0015 §4); `null` until then — never a guess.
+     */
     balance_transaction: string | null;
+    /** Orbit's `fee_…` taken on this charge, once the provider created it. */
+    application_fee: string | null;
+    /** The fee instructed on the payment (`application_fee_amount`), or `null`. */
+    application_fee_amount: string | null;
     description: string | null;
     receipt_email: string | null;
     metadata: Record<string, string>;

package/dist/types/event.d.ts

@@ -1,3 +1,5 @@
+import type { Account } from './account';
+import type { ApplicationFee, Balance, Payout } from './balance';
 import type { Charge } from './charge';
 import type { Coupon, Price, Product, PromotionCode } from './catalog';
 import type { Customer } from './customer';
@@ -105,6 +107,23 @@ export interface WebhookEventPayload {
      * intent.
      */
     'connected_account.updated': ConnectedAccount;
+    /**
+     * The merchant's OWN fiat account changed (ADR 0015 §1) — readiness,
+     * requirements, settings. Emitted when a field the merchant acts on moved.
+     */
+    'account.updated': Account;
+    /** Orbit's fee was taken on a succeeded charge (ADR 0015 §3). */
+    'application_fee.created': ApplicationFee;
+    /** Part or all of a fee went back (a refund with `refund_application_fee`). */
+    'application_fee.refunded': ApplicationFee;
+    /** A payout of the merchant's account, mirrored from the provider (ADR 0015 §5). */
+    'payout.created': Payout;
+    'payout.updated': Payout;
+    'payout.paid': Payout;
+    'payout.failed': Payout;
+    'payout.canceled': Payout;
+    /** Funds became available in the account; carries the balance read from the ledger. */
+    'balance.available': Balance;
     'billing.observation.updated': BillingObservation;
     /**
      * A synthetic event sent to ONE endpoint when its owner asks to test it

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
 export { UNITS_PER_COIN, isBaseUnitString, type CurrencyCode, type FiatCurrencyCode, CURRENCY_CODES, CURRENCY_DECIMALS, FIAT_CURRENCY_CODES, decimalsFor, isCurrencyCode, } from './money';
 export type { NetworkType } from './network';
 export type { ExpandParams, List, ListParams, RangeQuery } from './list';
-export { type Address, type AddressParams, type CancelPaymentIntentParams, type CapturePaymentIntentParams, type ConfirmPaymentIntentParams, type CreatePaymentIntentParams, type PaymentIntent, type PaymentIntentCancellationReason, type PaymentIntentCaptureMethod, type PaymentIntentFaircoin, type PaymentIntentLastPaymentError, type PaymentIntentNextAction, type PaymentIntentRail, type PaymentIntentSetupFutureUsage, type PaymentIntentStatus, type PaymentMethodType, type Shipping, type ShippingParams, type UpdatePaymentIntentParams, CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, MERCHANT_CANCELLATION_REASONS, PAYMENT_INTENT_CANCELLATION_REASONS, PAYMENT_INTENT_CAPTURE_METHODS, PAYMENT_INTENT_RAILS, PAYMENT_INTENT_SETUP_FUTURE_USAGES, PAYMENT_INTENT_STATUSES, TERMINAL_STATUSES, canExpire, canStillBePaid, isValidStatusTransition, } from './paymentIntent';
+export { type Address, type AddressParams, type CancelPaymentIntentParams, type CapturePaymentIntentParams, type ConfirmPaymentIntentParams, type CreatePaymentIntentParams, type PaymentIntent, type PaymentIntentCancellationReason, type PaymentIntentCaptureMethod, type PaymentIntentFaircoin, type PaymentIntentLastPaymentError, type PaymentIntentNextAction, type PaymentIntentRail, type PaymentIntentSetupFutureUsage, type PaymentIntentStatus, type PaymentIntentTransferData, type PaymentMethodType, type Shipping, type ShippingParams, type UpdatePaymentIntentParams, CARD_ONLY_STATUSES, EXPIRABLE_STATUSES, MERCHANT_CANCELLATION_REASONS, PAYMENT_INTENT_CANCELLATION_REASONS, PAYMENT_INTENT_CAPTURE_METHODS, PAYMENT_INTENT_RAILS, PAYMENT_INTENT_SETUP_FUTURE_USAGES, PAYMENT_INTENT_STATUSES, TERMINAL_STATUSES, canExpire, canStillBePaid, isValidStatusTransition, } from './paymentIntent';
 export type { CardDetails, Charge, ChargeOutcome } from './charge';
 export type { CreateCustomerParams, Customer, DeletedCustomer, UpdateCustomerParams, } from './customer';
 export type { AttachPaymentMethodParams, BillingDetails, PaymentMethod, UpdatePaymentMethodParams, } from './paymentMethod';
@@ -12,7 +12,10 @@ export { PRICE_BILLING_SCHEMES, PRICE_TIERS_MODES, PRICE_TYPES, RECURRING_INTERV
 export { DISPUTE_FILE_EVIDENCE_FIELDS, DISPUTE_REASONS, DISPUTE_TEXT_EVIDENCE_FIELDS, normalizeDisputeReason, type Dispute, type DisputeEvidence, type DisputeEvidenceDetails, type DisputeEvidenceField, type DisputeEvidenceParams, type DisputeFileEvidenceField, type DisputeReason, type DisputeStatus, type DisputeTextEvidenceField, type ListDisputesParams, type UpdateDisputeParams, } from './dispute';
 export { FILE_PURPOSES, FILE_PURPOSE_POLICIES, FILE_STATUSES, FILE_TYPES, type CreateFileFromOxyParams, type FileObject, type FilePurpose, type FileStatus, type FileType, type ListFilesParams, } from './file';
 export { CARD_RAIL_PAYMENT_METHOD_TYPES, PAYMENT_METHOD_CONFIGURATION_TYPES, PAYMENT_METHOD_CURRENCIES, type CardRailPaymentMethodType, type CreatePaymentMethodConfigurationParams, type CreatePaymentMethodDomainParams, type ListPaymentMethodDomainsParams, type PaymentMethodConfiguration, type PaymentMethodConfigurationEntry, type PaymentMethodConfigurationEntryParams, type PaymentMethodConfigurationType, type PaymentMethodDisplayPreference, type PaymentMethodDomain, type PaymentMethodDomainWalletStatus, type PaymentMethodUnavailableReason, type UpdatePaymentMethodConfigurationParams, type UpdatePaymentMethodDomainParams, } from './paymentMethodConfiguration';
-export type { CapabilityStatus, ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, Refund, RefundOrigin, RefundStatus, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
+export { PAYOUT_INTERVALS, PAYOUT_WEEKLY_ANCHORS, type Account, type AccountBusinessProfile, type AccountCapabilityStatus, type AccountPayoutSchedule, type AccountRequirements, type AccountSettings, type AccountType, type CreateAccountLinkParams, type PayoutInterval, type PayoutWeeklyAnchor, type UpdateAccountParams, } from './account';
+export { BALANCE_TRANSACTION_STATUSES, BALANCE_TRANSACTION_TYPES, PAYOUT_STATUSES, RECONCILIATION_MISMATCH_KINDS, type ApplicationFee, type Balance, type BalanceAmount, type BalanceTransaction, type BalanceTransactionFeeDetail, type BalanceTransactionStatus, type BalanceTransactionType, type CreatePayoutParams, type FeeRefund, type ListBalanceTransactionsParams, type ListPayoutsParams, type Payout, type PayoutReconciliationReport, type PayoutStatus, type ReconciliationMismatch, type ReconciliationMismatchKind, } from './balance';
+export { REFUND_REASONS } from './settlement';
+export type { CapabilityStatus, ConnectedAccount, ConnectedAccountFaircoin, ConnectedAccountFaircoinStatus, ConnectedAccountRail, CreateRefundParams, Refund, RefundOrigin, RefundReason, RefundStatus, UpdateRefundParams, Settlement, Transfer, TransferReversal, TransferReversalStatus, TransferStatus, TransferWithReversal, } from './settlement';
 export type { WebhookDelivery, WebhookDeliveryStatus, } from './webhookDelivery';
 export { REQUEST_LOG_METHODS, REQUEST_LOG_RETENTION_DAYS, type RequestLog, type RequestLogListParams, type RequestLogMethod, type RequestLogStatusFilter, } from './requestLog';
 export { SIMULATED_FAIRCOIN_OUTCOMES, type SimulatedFaircoinOutcome, type SimulateFaircoinPaymentParams, } from './testHelpers';

package/dist/types/paymentIntent.d.ts

@@ -231,6 +231,21 @@ export interface PaymentIntent {
      * FairCoin only, and `faircoin.address` derives from that seller's own key.
      */
     connected_account: string | ConnectedAccount | null;
+    /**
+     * Orbit's fee on this card payment, taken by the provider from the
+     * destination account when the charge succeeds (ADR 0015 §3) — the
+     * INSTRUCTION; the fee actually taken is the `application_fee` object.
+     * `null` on a platform charge.
+     */
+    application_fee_amount: string | null;
+    /**
+     * A destination charge (ADR 0015 §2): the account (`ca_…`) the funds go to,
+     * and the amount transferred when the platform named one. `null` on a
+     * platform charge.
+     */
+    transfer_data: PaymentIntentTransferData | null;
+    /** The account (`ca_…`) that is the merchant of record, or `null` (the platform). */
+    on_behalf_of: string | null;
     client_secret: string;
     metadata: Record<string, string>;
     /** When an UNPAID intent expires. Meaningful only while `can_expire`. */
@@ -240,6 +255,13 @@ export interface PaymentIntent {
     created: number;
     updated_at: number;
 }
+/** Where a destination charge's funds go (`transfer_data`). */
+export interface PaymentIntentTransferData {
+    /** `ca_…` */
+    destination: string;
+    /** Base units transferred; `null` means the whole amount less `application_fee_amount`. */
+    amount: string | null;
+}
 /** `POST /v1/payment_intents`. */
 export interface CreatePaymentIntentParams {
     /** Amount in the currency's smallest unit, as a canonical integer string. */
@@ -278,6 +300,19 @@ export interface CreatePaymentIntentParams {
     expires_in_seconds?: number;
     /** FairCoin only: pay this seller (`ca_…`, ADR 0012 D5). */
     connected_account?: string;
+    /**
+     * Card only, a platform acting for one of its connected accounts: Orbit's
+     * fee for this payment. Needs `transfer_data` (or `on_behalf_of`); refused
+     * beside `transfer_data.amount`.
+     */
+    application_fee_amount?: string;
+    /** Card only: a destination charge to one of the platform's connected accounts. */
+    transfer_data?: {
+        destination: string;
+        amount?: string;
+    };
+    /** Card only: make this connected account (`ca_…`) the merchant of record. */
+    on_behalf_of?: string;
     /** Card only, with `confirm`: where a redirect-based challenge returns. */
     return_url?: string;
 }

package/dist/types/settlement.d.ts

@@ -1,3 +1,4 @@
+import type { AccountRequirements } from './account';
 import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
 import type { PaymentIntent } from './paymentIntent';
@@ -84,17 +85,12 @@ export interface ConnectedAccount {
     transfers_capability: CapabilityStatus | null;
     card_payments_capability: CapabilityStatus | null;
     /**
-     * COUNTS of outstanding requirements, never the requirements themselves and
-     * never their values. The gateway records that a seller owes a document; it
-     * does not learn what the document says.
+     * What the provider is waiting on — requirement IDENTIFIERS, never their
+     * values (the gateway records that a seller owes a document; it never learns
+     * what the document says) — and the provider's own `disabled_reason`. The
+     * same shape as `Account.requirements`.
      */
-    requirements: {
-        currently_due: number;
-        eventually_due: number;
-        past_due: number;
-        pending_verification: number;
-    };
-    disabled_reason_codes: readonly string[];
+    requirements: AccountRequirements;
     last_synced_at: number | null;
     created: number;
     updated_at: number;
@@ -203,8 +199,15 @@ export interface Settlement {
     /** Present only when a conversion happened. `null` is not a rate of 1. */
     exchange_rate: number | null;
 }
-/** Where one refund stands — the MONEY's own lifecycle, not the payment's. */
-export type RefundStatus = 'pending' | 'succeeded' | 'failed';
+/**
+ * Where one refund stands — the MONEY's own lifecycle, not the payment's.
+ * `canceled` only through `POST /v1/refunds/:id/cancel`, where the provider
+ * still allows it.
+ */
+export type RefundStatus = 'pending' | 'succeeded' | 'failed' | 'canceled';
+/** Stripe's refund reasons. */
+export declare const REFUND_REASONS: readonly ["duplicate", "fraudulent", "requested_by_customer"];
+export type RefundReason = (typeof REFUND_REASONS)[number];
 /**
  * Who created a refund.
  *
@@ -229,7 +232,31 @@ export interface Refund {
     amount: string;
     currency: CurrencyCode | string;
     status: RefundStatus;
+    reason: RefundReason | null;
     failure_code: string | null;
+    metadata: Record<string, string>;
     created: number;
     updated_at: number;
 }
+/** `POST /v1/refunds`. */
+export interface CreateRefundParams {
+    /** The `pi_…` being refunded. */
+    payment_intent: string;
+    /** YOUR id for this refund. The idempotency. */
+    external_ref: string;
+    /** Minor units, as a canonical integer string. Zero is refused. */
+    amount: string;
+    reason?: RefundReason;
+    metadata?: Record<string, string>;
+    /**
+     * Also refund Orbit's application fee, in proportion to the amount refunded
+     * (a payment that carried one: a destination charge, ADR 0015 §2).
+     */
+    refund_application_fee?: boolean;
+    /** Also reverse the transfer to the destination account, in proportion. */
+    reverse_transfer?: boolean;
+}
+/** `POST /v1/refunds/:id` — the merchant's own bookkeeping; `metadata` is a patch. */
+export interface UpdateRefundParams {
+    metadata?: Record<string, string>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Shared TypeScript types for the Peable Gateway — the wire contract shared by the backend, SDK, and frontend.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",