@peable.to/shared-types 0.13.0 → 0.15.0

package/dist/esm/paymentMethodConfiguration.js

@@ -0,0 +1,51 @@
+// 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).
+import { FIAT_CURRENCY_CODES } from './money.js';
+/**
+ * The methods a configuration can turn on.
+ *
+ * `apple_pay` and `google_pay` are WALLETS over a card: a payment made with one
+ * is a `card` payment, so they appear here and never in a PaymentIntent's
+ * `payment_method_types`. `bizum` is listed because merchants ask for it and the
+ * honest answer is a reason, not an absence: the provider does not offer it.
+ *
+ * Deliberately absent: the provider's own consumer wallet (its brand on Orbit's
+ * checkout, `payment-provider-boundary.md`) and giropay (discontinued by the
+ * scheme).
+ */
+export const PAYMENT_METHOD_CONFIGURATION_TYPES = [
+    'card',
+    'apple_pay',
+    'google_pay',
+    'sepa_debit',
+    'ideal',
+    'bancontact',
+    'eps',
+    'bizum',
+];
+/** The card-rail types a PaymentIntent can carry in `payment_method_types`. */
+export const CARD_RAIL_PAYMENT_METHOD_TYPES = [
+    'card',
+    'sepa_debit',
+    'ideal',
+    'bancontact',
+    'eps',
+];
+/**
+ * The currencies each method can take a payment in. A method is offered on a
+ * payment only when its currency is listed — so iDEAL never appears on a USD
+ * payment, and a payer is never shown a method that would fail.
+ */
+export const PAYMENT_METHOD_CURRENCIES = Object.freeze({
+    card: FIAT_CURRENCY_CODES,
+    apple_pay: FIAT_CURRENCY_CODES,
+    google_pay: FIAT_CURRENCY_CODES,
+    sepa_debit: ['EUR'],
+    ideal: ['EUR'],
+    bancontact: ['EUR'],
+    eps: ['EUR'],
+    bizum: ['EUR'],
+});

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/dispute.d.ts

@@ -1,28 +1,88 @@
+import type { Charge } from './charge';
+import type { CurrencyCode } from './money';
 import type { PaymentIntent } from './paymentIntent';
 /**
- * A dispute — the card network holding a settled payment's money while a
- * cardholder contests it.
+ * A dispute — the card network holding a payment's money while a cardholder
+ * contests it. Stripe's Dispute object (`dp_…`), Orbit's row.
  *
- * Published because `charge.dispute.created`, `charge.dispute.updated` and
- * `charge.dispute.closed` carry it as their `data.object`. It was route-local at first, with the webhook
- * carrying the PaymentIntent and the detail reachable only through
- * `GET /v1/payment_intents/:id/disputes`. That was inconsistent with the reason
- * those two events exist: `disputed` is a DEADLINE, and a merchant who has to
- * make a second call to learn when evidence is due is a merchant who can miss it
- * while their integration is working exactly as documented.
- *
- * It is also what the provider does. Stripe's `charge.dispute.created` carries
- * the dispute, not the charge — the parity was half-applied.
+ * `charge.dispute.created|updated|closed|funds_withdrawn|funds_reinstated`
+ * carry it as `data.object`. A dispute is a DEADLINE: `created` carries
+ * `evidence_details.due_by`, so a merchant never needs a second call to learn
+ * when their response is due.
  */
 /**
  * Where the dispute stands.
  *
  * `needs_response` and `under_review` are open; `won` and `lost` are terminal
- * and are the only two that say where the money ended up. There is deliberately
- * no `closed`: a merchant who is told a dispute "closed" without being told
- * which way has been given a notification and no information.
+ * and are the only two that say where the money ended up. The provider's
+ * `warning_*` inquiry states collapse onto the state they warn about. There is
+ * deliberately no `closed`: a merchant told a dispute "closed" without being
+ * told which way has been given a notification and no information.
  */
 export type DisputeStatus = 'needs_response' | 'under_review' | 'won' | 'lost';
+/**
+ * Why the cardholder disputed — Stripe's enum. A network reason code the
+ * provider does not map to one of these reads `general`; the row keeps the
+ * provider's own word, so nothing is lost by the normalisation.
+ */
+export declare const DISPUTE_REASONS: readonly ["bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "fraudulent", "general", "incorrect_account_details", "insufficient_funds", "noncompliant", "product_not_received", "product_unacceptable", "subscription_canceled", "unrecognized"];
+export type DisputeReason = (typeof DISPUTE_REASONS)[number];
+/** Map any provider reason onto {@link DisputeReason}: unknown or absent is `general`. */
+export declare function normalizeDisputeReason(reason: string | null | undefined): DisputeReason;
+/**
+ * The TEXT evidence fields — the network's names, spelled the way the rest of
+ * these contracts spell things, never a Peable paraphrase: a merchant assembling
+ * a defence is reading their acquirer's guidance, and renamed fields would make
+ * that guidance not apply.
+ *
+ * Declared ONCE. The route's schema is `satisfies Record<DisputeTextEvidenceField, …>`
+ * and the Stripe adapter's name map is a total `Record`, so a field added here
+ * does not compile until both carry it — the drift that would let a merchant
+ * send a field the network never sees.
+ */
+export declare const DISPUTE_TEXT_EVIDENCE_FIELDS: readonly ["access_activity_log", "billing_address", "cancellation_policy_disclosure", "cancellation_rebuttal", "customer_email_address", "customer_name", "customer_purchase_ip", "duplicate_charge_explanation", "product_description", "refund_policy_disclosure", "refund_refusal_explanation", "service_date", "shipping_address", "shipping_carrier", "shipping_date", "shipping_tracking_number", "uncategorized_text"];
+export type DisputeTextEvidenceField = (typeof DISPUTE_TEXT_EVIDENCE_FIELDS)[number];
+/**
+ * The FILE evidence fields. Each names a `file_…` of purpose `dispute_evidence`
+ * uploaded by the same merchant; its bytes go to the provider when the response
+ * is submitted, and only then.
+ */
+export declare const DISPUTE_FILE_EVIDENCE_FIELDS: readonly ["cancellation_policy", "customer_communication", "customer_signature", "duplicate_charge_documentation", "receipt", "refund_policy", "service_documentation", "shipping_documentation", "uncategorized_file"];
+export type DisputeFileEvidenceField = (typeof DISPUTE_FILE_EVIDENCE_FIELDS)[number];
+export type DisputeEvidenceField = DisputeTextEvidenceField | DisputeFileEvidenceField;
+/**
+ * A merchant's evidence as the dispute holds it: every field, `null` when unset.
+ *
+ * Present ONLY on a live read — `GET /v1/disputes/:id` and the answers of
+ * `POST /v1/disputes/:id` and `…/close`. The text half is read from the
+ * provider, which is where a draft lives (Peable never stores it); the file half
+ * is the `file_…` ids the merchant attached. Lists and event payloads never
+ * carry it: an event is stored, and evidence carries a customer's name, email,
+ * address and correspondence.
+ */
+export type DisputeEvidence = Record<DisputeEvidenceField, string | null>;
+/**
+ * `evidence` on `POST /v1/disputes/:id`: any subset of the fields. A text field
+ * is the merchant's words; a file field is a `file_…`. An empty string UNSETS
+ * the field, as on Stripe.
+ */
+export type DisputeEvidenceParams = Partial<Record<DisputeEvidenceField, string>>;
+/** The response's bookkeeping — Stripe's `evidence_details`, plus when it was submitted. */
+export interface DisputeEvidenceDetails {
+    /**
+     * When the network stops accepting evidence, Unix seconds. `null` once the
+     * dispute is closed — there is no deadline for a decision already made.
+     */
+    due_by: number | null;
+    /** Whether any evidence has been staged or submitted. */
+    has_evidence: boolean;
+    /** Whether the deadline passed without a submission. */
+    past_due: boolean;
+    /** `0` or `1`: a response is one-shot at the network. */
+    submission_count: number;
+    /** When the response reached the network, Unix seconds; `null` while it has not. */
+    submitted_at: number | null;
+}
 export interface Dispute {
     id: string;
     object: 'dispute';
@@ -31,100 +91,47 @@ export interface Dispute {
      * `true` for a `production` merchant, `false` for every other environment.
      */
     livemode: boolean;
-    /** The disputed payment's `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
-    payment_intent: string | PaymentIntent;
     /**
-     * Amount in the currency's smallest unit as a canonical integer string —
-     * the same encoding every other money field on these contracts uses.
-     *
-     * It is the DISPUTED amount, which may be less than the payment's: a
-     * cardholder can contest part of a charge.
+     * The DISPUTED amount in the currency's smallest unit, as a canonical integer
+     * string. It may be less than the payment's: a cardholder can contest part of
+     * a charge.
      */
     amount: string;
-    currency: string;
+    currency: CurrencyCode;
+    /** `ch_…`, or the {@link Charge} with `expand[]=charge`. */
+    charge: string | Charge | null;
+    /** The disputed payment's `pi_…`, or the {@link PaymentIntent} with `expand[]=payment_intent`. */
+    payment_intent: string | PaymentIntent;
     status: DisputeStatus;
+    reason: DisputeReason;
     /**
-     * The network's reason, verbatim and unmapped.
-     *
-     * Deliberately an open string rather than a closed set. It is the one field a
-     * merchant argues against, and a gateway paraphrase would be the words they
-     * quote while the acquirer holds different ones. `null` when the network sent
-     * none.
-     */
-    reason: string | null;
-    /**
-     * When the network stops accepting evidence, Unix seconds.
-     *
-     * `null` once the dispute is closed — there is no deadline for a decision
-     * already made, and a closed dispute still showing one would put a response
-     * in front of a merchant that can no longer be given.
-     */
-    evidence_due_at: number | null;
-    /**
-     * When the merchant's response reached the network, Unix seconds. `null` while
-     * none has been submitted.
-     *
-     * The timestamp and nothing else: the evidence itself is forwarded to the
-     * acquirer and never stored here. What it SAID is readable there, by someone
-     * with their own authorization — this gateway does not keep a copy of a
-     * customer's name, address and correspondence.
-     *
-     * Together with `evidenceDueAt` it answers the only two questions a merchant
-     * has about a live dispute: whether they still owe a response, and by when.
+     * Whether the disputed payment can still be refunded. Once it has been in
+     * full, no further funds are withdrawn because of this dispute.
      */
-    evidence_submitted_at: number | null;
+    is_charge_refundable: boolean;
+    evidence_details: DisputeEvidenceDetails;
+    /** Live reads only — see {@link DisputeEvidence}. */
+    evidence?: DisputeEvidence;
+    metadata: Record<string, string>;
     created: number;
     updated_at: number;
 }
 /**
- * A merchant's response to a dispute — the whole field set, declared once.
+ * `POST /v1/disputes/:id`.
  *
- * ## Why this is the wire contract and not four private copies
- *
- * It was four: the backend's provider port, the route's zod schema, the Stripe
- * adapter's name map, and the SDK's params type. Every one of them is the SAME
- * list, and the cost of them drifting is specific and silent — a field added to
- * three of the four is one a merchant sends, the gateway accepts, and the
- * network never sees. They find out when the dispute is decided against them.
- *
- * So the set lives here, with the wire contracts, and the other three are
- * pinned to it: `provider.ts` aliases it, `routes/disputes.ts` declares its
- * schema `satisfies Record<keyof DisputeEvidence, …>`, and the Stripe adapter's
- * map is a total `Record<keyof DisputeEvidence, …>`. Adding a field here makes
- * all three fail to compile until they carry it.
- *
- * ## What is not here
- *
- * The field NAMES are the network's, spelled the way the rest of these
- * contracts spell things. They are not a Peable vocabulary and are not mapped
- * to one: a merchant assembling a defence is reading their acquirer's guidance,
- * and a gateway that renamed the fields would make that guidance not apply.
- *
- * FILE attachments are deliberately absent. They need the provider's upload
- * API, a size and type policy, and somewhere for the bytes to live on the way
- * through — and offering half of that would let a merchant submit a defence
- * missing the receipt it rests on.
- *
- * None of it is ever stored. It carries a customer's name, their email, a
- * billing address and correspondence; it is forwarded to the acquirer and
- * forgotten. What is recorded is `evidenceSubmittedAt` and nothing more.
+ * `submit: false` (the default) STAGES the evidence: text goes to the provider
+ * as a draft, files are attached by id. `submit: true` uploads the attached
+ * files to the provider and submits everything — ONCE; a second submission is
+ * refused, because the network takes one response.
  */
-export interface DisputeEvidence {
-    product_description?: string;
-    customer_name?: string;
-    customer_email_address?: string;
-    customer_purchase_ip?: string;
-    billing_address?: string;
-    shipping_address?: string;
-    shipping_carrier?: string;
-    shipping_date?: string;
-    shipping_tracking_number?: string;
-    service_date?: string;
-    access_activity_log?: string;
-    cancellation_policy_disclosure?: string;
-    cancellation_rebuttal?: string;
-    duplicate_charge_explanation?: string;
-    refund_policy_disclosure?: string;
-    refund_refusal_explanation?: string;
-    uncategorized_text?: string;
+export interface UpdateDisputeParams {
+    evidence?: DisputeEvidenceParams;
+    /** A PATCH (`""` unsets a key). */
+    metadata?: Record<string, string>;
+    submit?: boolean;
+}
+/** `GET /v1/disputes`. */
+export interface ListDisputesParams {
+    payment_intent?: string;
+    charge?: string;
 }