@peable.to/shared-types 0.2.0 → 0.3.1-oxy-one.0

package/dist/types/money.d.ts

@@ -1,7 +1,35 @@
+/**
+ * The currencies this gateway can denominate a payment in.
+ *
+ * A closed set, and the database mirrors it as a CHECK
+ * (`db/schema/valueSets.ts`). ADR 0001 D4: the scale of an amount is a property
+ * of its currency and is NOT implied by the field's type, which is why
+ * {@link CURRENCY_DECIMALS} exists and why {@link UNITS_PER_COIN} must never be
+ * used to interpret a fiat amount.
+ */
+export declare const CURRENCY_CODES: readonly ["FAIR", "EUR", "USD"];
+export type CurrencyCode = (typeof CURRENCY_CODES)[number];
+/** Whether an arbitrary string is a currency this gateway knows. */
+export declare function isCurrencyCode(value: string): value is CurrencyCode;
+/**
+ * How many decimal places each currency's smallest unit represents — i.e. an
+ * amount of `1` means `10^-decimals` of one whole unit.
+ *
+ * FairCoin's 8 is a consensus constant and is pinned against
+ * {@link UNITS_PER_COIN} by this package's own tests, so the two spellings of
+ * one fact cannot drift.
+ */
+export declare const CURRENCY_DECIMALS: Readonly<Record<CurrencyCode, number>>;
+/** The decimal places of `currency`'s smallest unit. */
+export declare function decimalsFor(currency: CurrencyCode): number;
 export declare const UNITS_PER_COIN = 100000000n;
 /**
- * True only for a canonical non-negative integer string in base units:
- * one or more decimal digits, no sign, no decimal point, no leading zeros
- * (except the literal "0"). Floats and negatives are rejected.
+ * True only for a canonical non-negative integer string in the currency's
+ * smallest unit: one or more decimal digits, no sign, no decimal point, no
+ * leading zeros (except the literal "0"). Floats and negatives are rejected.
+ *
+ * Currency-agnostic on purpose — the pattern is about the SPELLING of an
+ * amount, not its scale, and the same one is restated as a CHECK in the
+ * database (`BASE_UNIT_STRING_PATTERN`), byte-identical.
  */
 export declare function isBaseUnitString(s: string): boolean;

package/dist/types/paymentIntent.d.ts

@@ -1,21 +1,80 @@
+import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
-export type PaymentIntentStatus = 'created' | 'awaiting_approval' | 'approved' | 'broadcast' | 'confirming' | 'settled' | 'expired' | 'failed' | 'rejected';
+/**
+ * Which rail moves the money (ADR 0001 D1).
+ *
+ * On the INTENT, not on the merchant: one merchant takes both, and a merchant's
+ * capabilities are a different question from what this particular payment is.
+ * The rail decides which of the fields below mean anything.
+ */
+export type PaymentIntentRail = 'faircoin' | 'card';
+/** {@link PaymentIntentRail} as the tuple the database CHECK reads. */
+export declare const PAYMENT_INTENT_RAILS: readonly PaymentIntentRail[];
+export type PaymentIntentStatus = 'created' | 'awaiting_approval' | 'approved' | 'broadcast' | 'confirming' | 'requires_action' | 'processing' | 'settled' | 'refunded' | 'partially_refunded' | 'expired' | 'failed' | 'rejected';
+/**
+ * Which statuses belong to which rail (ADR 0001 D5).
+ *
+ * The four chain states describe a transaction on a blockchain and the four
+ * card states describe an authorization at a card acquirer; neither set is
+ * expressible on the other rail. Mapping a card authorization onto `broadcast`
+ * would be cheaper and would be a lie — nothing was broadcast, there is no
+ * transaction, and `payment_intents_broadcast_requires_txid_check` would then
+ * be demanding a txid from a payment that can never have one.
+ *
+ * `db/schema/payments.ts` renders these two sets into CHECK constraints, so the
+ * restriction holds against a write that skipped the application.
+ */
+export declare const CHAIN_ONLY_STATUSES: readonly PaymentIntentStatus[];
+export declare const CARD_ONLY_STATUSES: readonly PaymentIntentStatus[];
 export declare function isValidStatusTransition(from: PaymentIntentStatus, to: PaymentIntentStatus): boolean;
 /** Every legal `PaymentIntentStatus`, derived from `ALLOWED`'s keys — the
  * single source of truth consumed by the Gateway's list-route status filter. */
 export declare const PAYMENT_INTENT_STATUSES: readonly PaymentIntentStatus[];
+/**
+ * Whether a payer can still complete a payment against an intent in this
+ * status.
+ *
+ * `settled` answers `false`: it is where paying ENDS. `partially_refunded`
+ * answers `false` too — money can still move, but not from the payer.
+ */
+export declare function canStillBePaid(status: PaymentIntentStatus): boolean;
+/**
+ * The statuses a payment reaches only AFTER the payer has finished.
+ *
+ * Exported for the gate below rather than for production use: the property that
+ * makes `PAYABLE_STATUSES` checkable is that a payable status reaches `settled`
+ * without going through one of these.
+ */
+export declare const POST_SETTLEMENT_STATUSES: readonly PaymentIntentStatus[];
+/**
+ * Whether `settled` is reachable from `status` without passing through a
+ * post-settlement status. The derivation `canStillBePaid` used to BE, kept as
+ * the thing that checks it rather than as the thing that answers it.
+ */
+export declare function reachesSettlementFromPayer(status: PaymentIntentStatus): boolean;
 export interface PaymentIntent {
     id: string;
     object: 'payment_intent';
     status: PaymentIntentStatus;
-    /** Amount in base units (m⊜) as a canonical integer string. Never a float. */
+    /** Which rail moves this payment. Decides which fields below are populated. */
+    rail: PaymentIntentRail;
+    /**
+     * Amount in the currency's SMALLEST unit as a canonical integer string.
+     * Never a float, and never interpretable without `currency`: m⊜ (10^-8 FAIR)
+     * on the faircoin rail, cents on a fiat one.
+     */
     amount: string;
-    currency: 'FAIR';
-    network: NetworkType;
-    /** Watch-only receive address derived per-intent from the merchant xpub. */
-    address: string;
+    currency: CurrencyCode;
+    /** FairCoin rail only. `null` on a card payment, which has no network. */
+    network: NetworkType | null;
+    /**
+     * Watch-only receive address derived per-intent from the merchant xpub.
+     * FairCoin rail only; `null` on a card payment, which reserves no address.
+     */
+    address: string | null;
     merchantId: string;
     txid: string | null;
+    /** On-chain confirmations. Structurally `0` for the whole life of a card payment. */
     confirmations: number;
     clientSecret: string;
     metadata: Record<string, string>;
@@ -24,9 +83,17 @@ export interface PaymentIntent {
     updatedAt: string;
 }
 export interface CreatePaymentIntentParams {
-    /** Amount in base units (m⊜) as a canonical integer string. */
+    /** Amount in the currency's smallest unit, as a canonical integer string. */
     amount: string;
-    network: NetworkType;
+    /**
+     * Defaults to `'faircoin'` — the rail this gateway shipped with, so every
+     * integration written before ADR 0001 keeps working unchanged.
+     */
+    rail?: PaymentIntentRail;
+    /** Required on the faircoin rail; refused on the card rail, which has none. */
+    network?: NetworkType;
+    /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
+    currency?: CurrencyCode;
     metadata?: Record<string, string>;
     expiresInSeconds?: number;
 }

package/dist/types/paymentLink.d.ts

@@ -1,12 +1,20 @@
+import type { CurrencyCode } from './money';
 import type { NetworkType } from './network';
 import type { MerchantDisplay } from './merchantDisplay';
+import type { PaymentIntentRail } from './paymentIntent';
 /** The merchant-facing DTO — returned by the merchant-authed CRUD routes. */
 export interface PaymentLink {
     id: string;
     object: 'payment_link';
-    /** Amount in base units (m⊜) as a canonical integer string. Never a float. */
+    /**
+     * Amount in the currency's smallest unit, as a canonical integer string.
+     * Never a float, and never interpretable without `currency`.
+     */
     amount: string;
-    network: NetworkType;
+    currency: CurrencyCode;
+    rail: PaymentIntentRail;
+    /** FairCoin rail only; `null` on a card link. */
+    network: NetworkType | null;
     active: boolean;
     metadata: Record<string, string>;
     /** Optional post-payment redirect target for the checkout page. */
@@ -21,13 +29,20 @@ export interface PublicPaymentLink {
     id: string;
     object: 'payment_link';
     amount: string;
-    network: NetworkType;
+    currency: CurrencyCode;
+    rail: PaymentIntentRail;
+    network: NetworkType | null;
     active: boolean;
     merchant: MerchantDisplay;
 }
 export interface CreatePaymentLinkParams {
     amount: string;
-    network: NetworkType;
+    /** Defaults to `'faircoin'`, so pre-ADR-0001 integrations keep working. */
+    rail?: PaymentIntentRail;
+    /** Required on the faircoin rail; refused on the card rail. */
+    network?: NetworkType;
+    /** Defaults to `'FAIR'` on the faircoin rail; required on the card rail. */
+    currency?: CurrencyCode;
     metadata?: Record<string, string>;
     successUrl?: string;
 }

package/dist/types/settlement.d.ts

@@ -0,0 +1,171 @@
+import type { CurrencyCode } from './money';
+/** How a provider reports one capability on a seller's account. */
+export type CapabilityStatus = 'active' | 'pending' | 'inactive';
+/** Where one settlement stands. */
+export type TransferStatus = 'pending' | 'paid' | 'partially_reversed' | 'reversed' | 'failed';
+/** Where one reversal of a settlement stands. */
+export type TransferReversalStatus = 'pending' | 'succeeded' | 'failed';
+export interface ConnectedAccount {
+    id: string;
+    object: 'connected_account';
+    /** The merchant's OWN id for this seller — how they address it. */
+    externalRef: string;
+    /** ISO 3166-1 alpha-2, upper-case. */
+    country: string;
+    defaultCurrency: string | null;
+    /**
+     * Whether this seller can receive a settlement right now.
+     *
+     * A CONVENIENCE, not the authority: every field it is derived from is here
+     * too, and a marketplace with its own readiness policy reads those instead.
+     * Offering only this boolean would make the gateway the authority on a
+     * question that belongs to the merchant.
+     */
+    payable: boolean;
+    payoutsEnabled: boolean;
+    chargesEnabled: boolean;
+    /**
+     * `null` means the capability was never REQUESTED, which is a different fact
+     * from the provider declining it (`inactive`). Collapsing the two makes "why
+     * is this seller stuck" unanswerable.
+     */
+    transfersCapability: CapabilityStatus | null;
+    cardPaymentsCapability: 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.
+     */
+    requirements: {
+        currentlyDue: number;
+        eventuallyDue: number;
+        pastDue: number;
+        pendingVerification: number;
+    };
+    disabledReasonCodes: readonly string[];
+    lastSyncedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Transfer {
+    id: string;
+    object: 'transfer';
+    /** The merchant's OWN id for what this settles. Their idempotency. */
+    externalRef: string;
+    /** The `ca_…` of the seller — never their account id at the provider. */
+    connectedAccountId: string;
+    /** The `pi_…` this settlement was funded by — never an internal primary key. */
+    paymentIntentId: string;
+    amount: string;
+    currency: string;
+    /**
+     * CUMULATIVE, in the same units as `amount` — never one reversal's figure.
+     *
+     * A caller deciding whether a settlement is fully reversed must not have to
+     * add up reversals it may not have all seen, which is why this is the
+     * provider's own total rather than a sum of the reversals below.
+     */
+    amountReversed: string;
+    status: TransferStatus;
+    failureMessage: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * One reversal operation, returned beside the settlement it acted on.
+ *
+ * It exists as an object because an AMOUNT IS NOT AN IDENTITY: two reversals of
+ * one settlement for the same amount are two operations, and a caller needs to
+ * be able to tell which one a response is about.
+ */
+export interface TransferReversal {
+    id: string;
+    object: 'transfer_reversal';
+    /** The merchant's own id for this reversal — their `Idempotency-Key`. */
+    externalRef: string;
+    amount: string;
+    currency: string;
+    status: TransferReversalStatus;
+    failureMessage: string | null;
+    createdAt: string;
+}
+/** What `POST /v1/transfers/:id/reversals` answers: the transfer, and the leg. */
+export interface TransferWithReversal extends Transfer {
+    reversal: TransferReversal;
+}
+/**
+ * What a payment actually came to, as the PROVIDER reports it.
+ *
+ * ## Every figure is nullable, and that is the contract
+ *
+ * The difference between "the fee was zero" and "the fee is not known yet" is
+ * the whole reason this shape exists. A report that renders an unknown as `0`
+ * is one a merchant reconciles against and cannot explain — and zero is a
+ * number somebody will subtract. `status` says which of the three situations
+ * produced the nulls.
+ *
+ * ## What it does NOT say
+ *
+ * It reports what the provider took. It does **not** attribute that cost to an
+ * entity: a fee paid by the operator of a Peable deployment is not
+ * automatically an expense of the marketplace running on it, and that is a
+ * commercial decision no contract can make. Nothing here implies one.
+ *
+ * `gross` is not the payment's `amount`: a partial capture, a refund or a
+ * currency conversion all make them differ, which is why it is reported rather
+ * than assumed.
+ */
+export interface Settlement {
+    object: 'settlement';
+    /** The `pi_…` this describes. */
+    paymentIntentId: string;
+    /**
+     *  - `available` — settled; these figures are final.
+     *  - `pending`   — a settlement record exists and is not final yet.
+     *  - `unknown`   — there is none to read. **Not zero.**
+     */
+    status: 'available' | 'pending' | 'unknown';
+    /** Minor units, as canonical integer strings, in `currency`. */
+    gross: string | null;
+    fee: string | null;
+    net: string | null;
+    /** The SETTLEMENT currency, which may differ from the payment's. */
+    currency: string | null;
+    /** When the funds become available, ISO-8601. */
+    availableOn: string | null;
+    /** Present only when a conversion happened. `null` is not a rate of 1. */
+    exchangeRate: number | null;
+}
+/** Where one refund stands — the MONEY's own lifecycle, not the payment's. */
+export type RefundStatus = 'pending' | 'succeeded' | 'failed';
+/**
+ * Who created a refund.
+ *
+ * `provider` means it appeared at the acquirer — a dashboard refund, or the
+ * network resolving a dispute — and was imported. Such a refund carries no
+ * `externalRef`, because the merchant did not make it and has no id for it.
+ */
+export type RefundOrigin = 'merchant' | 'provider';
+export interface Refund {
+    id: string;
+    object: 'refund';
+    /** `null` on an IMPORTED refund; see {@link RefundOrigin}. */
+    externalRef: string | null;
+    origin: RefundOrigin;
+    paymentIntentId: string;
+    amount: string;
+    currency: CurrencyCode | string;
+    status: RefundStatus;
+    /**
+     * Where the PAYMENT stands after this refund.
+     *
+     * On the refund deliberately: a caller that has just refunded needs to know
+     * whether the payment is now `partially_refunded` or `refunded`, and making
+     * them re-read the intent is a round trip whose answer can move on before it
+     * arrives.
+     */
+    paymentStatus: string;
+    failureCode: string | null;
+    createdAt: string;
+    updatedAt: string;
+}

package/dist/types/social.d.ts

@@ -1,3 +1,59 @@
+import type { NetworkType } from './network';
+/**
+ * Longest `SocialPaymentSource.app` the gateway accepts. An app slug, not a
+ * label — 32 characters is more than any Oxy app id needs and short enough that
+ * the column can never become a place to put prose.
+ *
+ * Published with the contract because it is what a request is REFUSED for: a
+ * caller that cannot read the bound from the types finds it out with a 422.
+ */
+export declare const SOCIAL_SOURCE_APP_MAX_LENGTH = 32;
+/**
+ * Longest `SocialPaymentSource.ref` the gateway accepts.
+ *
+ * The bound is the whole defence here, because the value is opaque: Peable
+ * never parses, resolves or links a `ref`, so nothing downstream would notice
+ * it growing. 128 characters holds any id an app mints (a uuid, a snowflake, a
+ * base64 hash) and refuses a payload.
+ */
+export declare const SOCIAL_SOURCE_REF_MAX_LENGTH = 128;
+/**
+ * Display-only context for one social payment: which app the payer was in, and
+ * that app's own id for what the payment was for (a Mention post, say).
+ *
+ * **Opaque to Peable, by design.** `ref` is never parsed, resolved, joined or
+ * shown to anyone but the two parties — the gateway stores a string and hands
+ * the same string back. That is what keeps "tip a post" from widening what the
+ * payment gateway knows about a user: it learns that an id exists, not what it
+ * names. The app that minted the `ref` is the only thing that can resolve it,
+ * and it already knows.
+ *
+ * It affects NOTHING about the money. The address a payer is shown comes from
+ * the recipient's identity key and the reservation cursor, neither of which
+ * this is an input to; a request carrying a source and one carrying none
+ * reserve the same index.
+ */
+export interface SocialPaymentSource {
+    /** The calling app, e.g. `'mention'`. At most {@link SOCIAL_SOURCE_APP_MAX_LENGTH} characters. */
+    app: string;
+    /**
+     * That app's own opaque id for what the payment was for, e.g. a post id. At
+     * most {@link SOCIAL_SOURCE_REF_MAX_LENGTH} characters. Absent when the app
+     * has no single thing to name.
+     */
+    ref?: string;
+}
+/**
+ * Body of `POST /v1/social/:username/next_address` (spec §4.4 step 3).
+ *
+ * `source` is OPTIONAL and stays that way: a plain person-to-person payment is
+ * for nothing in particular, and a required field would make every caller
+ * invent an answer.
+ */
+export interface SocialNextAddressRequest {
+    network: NetworkType;
+    source?: SocialPaymentSource;
+}
 /** Response of `POST /v1/social/:username/next_address` (spec §4.4 step 3). */
 export interface SocialNextAddressResponse {
     address: string;
@@ -23,6 +79,16 @@ export interface SocialReceiveCursorResponse {
      * caller's stable default address and is never reserved through this flow.
      */
     reservedThrough: number;
+    /**
+     * The identity public key (hex) those addresses were derived from, as the
+     * backend saw it. A device compares it with the key it derives from itself:
+     * if they differ, its watch window is in the wrong tree and widening it only
+     * watches more addresses nobody is paying into.
+     *
+     * `null` means exactly one thing: this caller has no cursor, so no address
+     * has ever been reserved for them. Every cursor that exists names its key.
+     */
+    identityPublicKey: string | null;
 }
 /** Where a transaction's counterparty identity came from (spec §4.8). */
 export type EnrichmentKind = 'merchant' | 'user' | 'unknown';
@@ -48,3 +114,47 @@ export interface EnrichRequest {
 export interface EnrichResponse {
     data: Record<string, EnrichmentResult>;
 }
+/** Which side of a social payment the caller was on. */
+export type SocialPaymentDirection = 'sent' | 'received';
+/**
+ * One social payment as the CALLER saw it, for `GET /v1/social/me/payments`.
+ *
+ * The address-free view, and the only payment history a surface without a key
+ * can ask for: deriving addresses needs a seed, so a browser cannot use the
+ * address-list endpoints (`POST /v1/enrich`, the cursor) at all. `direction` is
+ * the field that cannot be recovered from the address alone — the backend knows
+ * it because the attribution names both parties, and resolving it here is what
+ * keeps the caller from having to learn its own user id to compare against.
+ *
+ * Carries NO amount. An attribution records which address was minted for a
+ * payment relationship, not what was paid; the amount lives on-chain, and the
+ * client reads it from the Explorer against `address`.
+ */
+export interface SocialPayment {
+    /** The single-use social-receive address minted for this payment. */
+    address: string;
+    direction: SocialPaymentDirection;
+    /**
+     * The other party. Reuses the enrichment contract, including its degradation:
+     * a failed identity lookup answers `{ kind: 'unknown' }` rather than dropping
+     * the payment, so a history never silently loses rows to an Oxy outage.
+     */
+    counterparty: EnrichmentResult;
+    /**
+     * What the payment was for, as the paying app named it at reservation time.
+     * Absent for a plain person-to-person payment, which is most of them —
+     * present only when the payer's app sent one, and never invented here.
+     *
+     * Display-only, exactly like `counterparty`: rendering it is all a client may
+     * do with it, and a client that cannot resolve `source.ref` (because it is
+     * not the app that minted it) shows the payment without the context rather
+     * than dropping the payment.
+     */
+    source?: SocialPaymentSource;
+    /** ISO-8601. When the address was minted, which is when the payment was set up. */
+    createdAt: string;
+}
+/** Response of `GET /v1/social/me/payments`, newest first. */
+export interface SocialPaymentsResponse {
+    payments: SocialPayment[];
+}

package/dist/types/webhookDelivery.d.ts

@@ -1,15 +1,51 @@
 import type { WebhookEventType } from './event';
+/**
+ * Where one webhook delivery stands (ADR 0001 D7).
+ *
+ * Was `'delivered' | 'failed'` — the two outcomes an inline, best-effort
+ * delivery could report once it had already given up. Delivery is now a durable
+ * outbox, so a delivery exists BEFORE any attempt and this set has to say so.
+ *
+ *  - `pending`   — enqueued and will be attempted. `nextAttemptAt` says when.
+ *  - `delivered` — terminal success.
+ *  - `failed`    — the endpoint REFUSED it (a 4xx, a blocked address). No retry
+ *                  can fix that, so none is made.
+ *  - `dead`      — every attempt failed transiently and the budget ran out. The
+ *                  envelope is kept and can be redelivered by hand.
+ *
+ * ⚠️ Widening a published union is a breaking change for a consumer that
+ * switches exhaustively on it. It is the honest shape: the previous one could
+ * not describe a delivery that had not been attempted yet, which is now the
+ * state every delivery starts in.
+ */
+export type WebhookDeliveryStatus = 'pending' | 'delivered' | 'failed' | 'dead';
 export interface WebhookDelivery {
     id: string;
     object: 'webhook_delivery';
     merchantId: string;
-    intentId: string;
+    /**
+     * The `pi_…` this delivery is about — `null` when the event is not about a
+     * payment.
+     *
+     * Nullable since `connected_account.updated`, which is about a SELLER. The
+     * alternative was to name an unrelated payment to keep the field a string,
+     * which is worse than a null: a consumer correlating on it would attach a
+     * seller's readiness change to a payment that has nothing to do with it.
+     */
+    intentId: string | null;
     eventId: string;
     eventType: WebhookEventType;
     url: string;
     attempts: number;
     delivered: boolean;
-    lastStatus: 'delivered' | 'failed';
+    lastStatus: WebhookDeliveryStatus;
+    /**
+     * Why the last attempt did not succeed — operator-facing, never a secret.
+     * Absent while pending with no attempts, and after a success.
+     */
+    lastError?: string;
+    /** When the next attempt is due, ISO-8601. Absent once the delivery is terminal. */
+    nextAttemptAt?: string;
     createdAt: string;
     updatedAt: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peable.to/shared-types",
-  "version": "0.2.0",
+  "version": "0.3.1-oxy-one.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",
@@ -8,7 +8,9 @@
   "source": "src/index.ts",
   "sideEffects": false,
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "oxy-one"
   },
   "exports": {
     ".": {