@happyvertical/payments 0.74.8

package/AGENT.md

@@ -0,0 +1,33 @@
+# @happyvertical/payments
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+Payment backend abstraction with adapters for Base USDC, BTCPay Server, and Stripe
+
+## Package Map
+- Package: `@happyvertical/payments`
+- Hierarchy path: `@happyvertical/sdk > packages > payments`
+- Workspace position: `20 of 30` local packages
+- Internal dependencies: none
+- Internal dependents: none
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/payments build
+pnpm --filter @happyvertical/payments test
+pnpm --filter @happyvertical/payments clean
+```
+
+## Agent Correction Loops
+- If Vite or TypeScript reports missing packages, run `pnpm install` at the repo root and rerun `pnpm --filter @happyvertical/payments build`.
+- If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/payments clean` followed by `pnpm --filter @happyvertical/payments build` and `pnpm --filter @happyvertical/payments test`.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: Payment backend abstraction with adapters for Base USDC, BTCPay Server, and Stripe
+- Implements: none
+- Requires: @noble/curves, @noble/hashes, @scure/bip32
+- Stability: stable (Primary package surface is described as implemented and production-oriented.)
+<!-- END AGENT:GENERATED -->
+

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @happyvertical/payments
+
+Multi-backend payment provider abstraction for crypto and fiat checkout.
+
+The root import exposes the shared `PaymentBackend` contract, common types,
+errors, and dynamic factory:
+
+```ts
+import { createPaymentBackend } from '@happyvertical/payments';
+
+const payments = await createPaymentBackend({
+  type: 'stripe',
+  secretKey: process.env.STRIPE_SECRET_KEY!,
+  successUrl: 'https://example.com/pay/success',
+  cancelUrl: 'https://example.com/pay/cancel',
+});
+```
+
+Adapters are also available as selective subpath exports:
+
+```ts
+import { BaseUsdcAdapter } from '@happyvertical/payments/base-usdc';
+import { BtcAdapter } from '@happyvertical/payments/btc';
+import { StripeAdapter } from '@happyvertical/payments/stripe';
+```
+
+## Adapters
+
+- `BaseUsdcAdapter`: USDC on Base via JSON-RPC, deterministic xpub child
+  addresses, x402 proof verification, and injected signer payouts.
+- `BtcAdapter`: BTCPay Server invoice, polling/webhook status, tiered
+  confirmation policy, and unsigned PSBT payout creation.
+- `StripeAdapter`: Stripe Checkout URL settlement, webhook verification,
+  refunds, and Stripe Connect transfers.
+
+The package does not depend on SMRT or a database. Consumers own quote
+persistence, webhook routing, and operational policy.
+
+Public payment amounts follow Stripe's convention: `amount` is an integer in
+the smallest currency unit, paired with a `currency` code. For example,
+`{ amount: 1234, currency: 'USD' }` means USD 12.34. Crypto settlement uses the
+same rule at the public boundary: `{ amount: 10000, currency: 'BTC' }` means
+10,000 satoshis, and `{ amount: 1000000, currency: 'USDC' }` means 1 USDC.
+Adapters convert those integers to provider-specific decimal strings or atomic
+unit strings internally when a protocol requires it.
+
+Stripe-compatible whole-unit currencies that still have two-decimal ISO minor
+units, such as `ISK` and `UGX`, must be passed in whole-unit increments:
+`{ amount: 500, currency: 'UGX' }` means UGX 5.00, and `amount` must be evenly
+divisible by 100.
+
+## Operational Notes
+
+### Migration Notes
+
+Webhook parsing now requires configured secrets. Callers that previously parsed
+Stripe or BTCPay webhooks without `webhookSecret` must configure the provider
+secret or handle trusted test fixtures outside `parseWebhookEvent`.
+
+Webhook parsing is fail-closed. `StripeAdapter.parseWebhookEvent` and
+`BtcAdapter.parseWebhookEvent` require a configured `webhookSecret` and a valid
+signature. BTCPay webhook payloads must include `deliveryId`; the exported
+`BtcpayWebhookEvent.deliveryId` type is required. Duplicate webhook detection is
+bounded, in-memory replay protection for the current adapter instance;
+production webhook handlers should still persist Stripe event ids and BTCPay
+delivery ids before applying side effects, especially across restarts or
+multiple replicas.
+
+Base x402 receipt replay protection is also bounded and in-memory. Persist the
+accepted transaction id in the application layer if a verified x402 proof
+unlocks durable access.
+
+`StripeAdapter` sends Checkout Sessions with Stripe API-compatible expiry
+values only. Expiries outside Stripe's 30 minute to 24 hour Checkout window are
+rejected instead of being silently clamped.
+
+`BtcAdapter` defaults to the BTCPay on-chain method id `BTC-CHAIN` while still
+matching exact `BTC` and `BITCOIN` aliases.
+
+`BaseUsdcAdapter` records `metadata.searchStartBlock` on created payment
+options. Persist it with quote state and pass it back as
+`PaymentStatusContext.searchStartBlock` after process restarts so old transfers
+cannot satisfy a new quote. Stateless `getStatus` calls that provide an amount
+must also provide `searchStartBlock` unless the adapter was configured with
+`fromBlock`. Long-lived unpaid quotes may force `eth_getLogs` ranges that exceed
+some RPC provider limits; use an archive provider, provider-supported range, or
+application-level batching for old `searchStartBlock` values. Cumulative
+split-transfer matching is disabled by default; enable
+`allowCumulativeTransferMatching` only when every quote receives a unique deposit
+address and the search start block is persisted. When quote currency is `USD`,
+Base settlement assumes a 1:1 USD-to-USDC amount; callers that need live FX or
+spread handling should convert to `USDC` amounts before creating payment
+options.
+
+`pollPaymentStatus` emits `event: 'timeout'` when polling times out. The
+associated `status` remains the last observed status, or `pending` if no status
+was observed, rather than being coerced to `failed`.

package/dist/adapters/base-usdc.d.ts

@@ -0,0 +1,85 @@
+import { FetchLike } from '../shared.js';
+import { CreatePaymentOptionInput, PaymentBackend, PaymentBackendCapabilities, PaymentEvent, PaymentOption, PaymentStatusContext, PaymentStatusResult, PayoutResult, RefundPaymentInput, RefundResult, SendPayoutInput, VerifyX402ProofInput, WatchPaymentInput, X402VerificationResult } from '../types.js';
+export declare const BASE_USDC_BACKEND_ID = "base-usdc";
+export declare const BASE_MAINNET_CHAIN_ID = 8453;
+export declare const BASE_MAINNET_CAIP2 = "eip155:8453";
+export declare const BASE_USDC_CONTRACT = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+export declare const USDC_DECIMALS = 6;
+export interface BaseUsdcAddressDeriverInput {
+    quoteId: string;
+    index: number;
+    indexes: number[];
+    path: string;
+}
+export interface BaseUsdcSendTransactionInput {
+    destination: string;
+    amount: number;
+    amountAtomic: string;
+    currency: 'USDC';
+    tokenAddress: string;
+    memo?: string;
+    quoteId?: string;
+    idempotencyKey?: string;
+    metadata?: Record<string, string | number | boolean | null | undefined>;
+}
+export interface BaseUsdcAdapterOptions {
+    rpcUrl: string;
+    fetch?: FetchLike;
+    usdcContractAddress?: string;
+    masterXpub?: string;
+    derivationPathPrefix?: string;
+    addressDeriver?: (input: BaseUsdcAddressDeriverInput) => string | Promise<string>;
+    addressIndexForQuote?: (quoteId: string) => number;
+    fromBlock?: string | number | bigint;
+    confirmations?: number;
+    pollIntervalMs?: number;
+    maxStoredPaymentOptions?: number;
+    /**
+     * Opt in only when each quote has a unique deposit address and the
+     * returned metadata.searchStartBlock is persisted with quote state.
+     */
+    allowCumulativeTransferMatching?: boolean;
+    x402FacilitatorUrl?: string;
+    sendTransaction?: (input: BaseUsdcSendTransactionInput) => Promise<{
+        transactionId: string;
+        raw?: unknown;
+    }>;
+}
+export declare class BaseUsdcAdapter implements PaymentBackend {
+    private readonly options;
+    readonly capabilities: PaymentBackendCapabilities;
+    private readonly fetch;
+    private readonly rpcUrl;
+    private readonly usdcContractAddress;
+    private readonly confirmations;
+    private readonly configuredFromBlock;
+    private readonly masterXpub;
+    private readonly derivationPathPrefix;
+    private readonly x402FacilitatorUrl;
+    private readonly maxStoredPaymentOptions;
+    private readonly allowCumulativeTransferMatching;
+    private readonly optionsByQuote;
+    private readonly seenX402TransactionIds;
+    private rpcId;
+    constructor(options: BaseUsdcAdapterOptions);
+    createPaymentOption(input: CreatePaymentOptionInput): Promise<PaymentOption>;
+    watchPayment(input: WatchPaymentInput): AsyncIterable<PaymentEvent>;
+    getStatus(quoteId: string, payTo: string, context?: PaymentStatusContext): Promise<PaymentStatusResult>;
+    verifyX402Proof(input: VerifyX402ProofInput): Promise<X402VerificationResult>;
+    sendPayout(input: SendPayoutInput): Promise<PayoutResult>;
+    refundPayment(input: RefundPaymentInput): Promise<RefundResult>;
+    private deriveAddress;
+    private getTransferLogs;
+    private getDefaultFromBlock;
+    private getCurrentBlockNumber;
+    private rpc;
+    private verifyX402Receipt;
+    private verifyWithFacilitator;
+}
+export declare function deriveBaseUsdcAddress(input: {
+    masterXpub: string;
+    path: string;
+}): Promise<string>;
+export declare function quoteIdToDerivationIndex(quoteId: string): number;
+export declare function quoteIdToDerivationIndexes(quoteId: string): number[];
+//# sourceMappingURL=base-usdc.d.ts.map

package/dist/adapters/base-usdc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-usdc.d.ts","sourceRoot":"","sources":["../../src/adapters/base-usdc.ts"],"names":[],"mappings":"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"}