business-as-code/dist/finance/port.d.ts

Primitives for expressing business logic and processes as code

/**
 * FinanceProvider — port for adapter implementations (Stripe, Tempo, x402,
 * Privy, Lightspark). Every method is optional and gated by ProviderCapabilities;
 * adapters declare which capabilities they support.
 *
 * Adapter implementations are forthcoming and ship outside the substrate —
 * none are bundled here.
 */
import type { Currency, Money, Cost } from './types.js';
import type { Account, AccountSpec, TransferOpts, TransferResult } from './account.js';
import type { Card, CardSpec } from './card.js';
import type { OutcomeContract, ProofOfResult } from './outcome-contract.js';
import type { StablecoinCurrency } from './types.js';
import type { MerchantCapable } from './merchant.js';
export type ProviderRail = 'mpp' | 'spt' | 'x402' | 'streaming' | 'card' | 'wire' | 'ach' | 'lightning' | 'on-chain';
export interface ProviderCapabilities {
    payments: boolean;
    refunds: boolean;
    issuing: boolean;
    treasury: boolean;
    escrow: boolean;
    subscriptions: boolean;
    metering: boolean;
    /** Platform/Connect product-line provisioning + hosted checkout (see MerchantCapable). */
    merchant: boolean;
    multiCurrency: boolean;
    currencies: Currency[];
    stablecoins: StablecoinCurrency[];
    rails: ProviderRail[];
}
export interface ChargeOpts {
    /** Counterparty Worker paying the charge (ThingRef shape). */
    buyer: string;
    amount: Money;
    /** Service or invocation reference for attribution. */
    ref?: string;
    /** Idempotency key for at-most-once semantics. */
    idempotencyKey?: string;
    /** Provider-specific opts; pass-through. */
    providerOpts?: Record<string, unknown>;
}
export interface ChargeResult {
    $id: string;
    $type: 'Charge';
    amount: Money;
    status: 'pending' | 'authorized' | 'captured' | 'failed' | 'refunded';
    /** ISO-8601 timestamp. */
    createdAt: string;
    providerData: {
        provider: string;
        externalId: string;
    };
}
export interface RefundResult {
    $id: string;
    $type: 'Refund';
    chargeId: string;
    amount: Money;
    /** ISO-8601 timestamp. */
    createdAt: string;
}
export interface EscrowHandle {
    $id: string;
    contractRef: string;
    state: 'held' | 'released' | 'expired' | 'cancelled';
    providerData: {
        provider: string;
        externalId: string;
    };
}
export interface ReleaseResult {
    $id: string;
    escrowHandle: string;
    releasedAt: string;
    /** ISO-8601 timestamp. */
    amount: Money;
}
export interface SubscribeOpts {
    buyer: string;
    planRef: string;
    /** Provider-specific opts; pass-through. */
    providerOpts?: Record<string, unknown>;
}
export interface Subscription {
    $id: string;
    $type: 'Subscription';
    buyer: string;
    planRef: string;
    state: 'active' | 'paused' | 'cancelled' | 'past-due';
    /** ISO-8601 timestamp. */
    startedAt: string;
    providerData: {
        provider: string;
        externalId: string;
    };
}
export interface MeterEvent {
    /** Subscription or customer this event meters against. */
    subscriptionRef: string;
    event: string;
    quantity: bigint;
    /** ISO-8601 timestamp. */
    occurredAt: string;
}
export interface FinanceProvider extends Partial<MerchantCapable> {
    readonly name: string;
    readonly capabilities: ProviderCapabilities;
    charge(opts: ChargeOpts): Promise<ChargeResult>;
    refund(chargeId: string, amount?: Money): Promise<RefundResult>;
    issueCard?(spec: CardSpec): Promise<Card>;
    lockCard?(cardId: string): Promise<void>;
    openAccount?(spec: AccountSpec): Promise<Account>;
    balance?(accountId: string): Promise<Money>;
    transfer?(opts: TransferOpts): Promise<TransferResult>;
    escrow?(contract: OutcomeContract): Promise<EscrowHandle>;
    release?(escrowHandle: string, proof: ProofOfResult): Promise<ReleaseResult>;
    subscribe?(opts: SubscribeOpts): Promise<Subscription>;
    meter?(event: MeterEvent): Promise<void>;
    captureCost?(cost: Omit<Cost, '$id' | '$type'>): Promise<Cost>;
}
//# sourceMappingURL=port.d.ts.map