cspr402 0.4.7

package/dist/ows.d.ts

@@ -0,0 +1,190 @@
+import { type Transaction } from '@stellar/stellar-sdk';
+import type { CardDetails, PaymentInstructions } from './client';
+import { buildContractPaymentTx, submitSorobanTx } from './soroban';
+/**
+ * Create an OWS wallet, or return the existing one if a wallet with this
+ * name already exists in the vault. Idempotent by design — calling it
+ * twice with the same name is safe and returns the same keys, so skill.md
+ * flows and agent retries don't duplicate state.
+ *
+ * Wallets are stored encrypted at `~/.ows/wallets/<name>.vault` by
+ * default. If the vault file is lost, the funds it controls become
+ * unreachable — cards402 never sees private keys and can't recover
+ * them. Agents running on ephemeral filesystems (Lambda, Cloud Run,
+ * scratch containers) should pass a `vaultPath` pointing at a
+ * persistent volume, or set the `OWS_VAULT_PATH` environment variable.
+ */
+export declare function createOWSWallet(name: string, passphrase?: string, vaultPath?: string): {
+    walletId: string;
+    publicKey: string;
+};
+/**
+ * Import an existing Stellar secret key (S...) into an OWS wallet.
+ * Useful for migrating from a raw STELLAR_WALLET_SECRET to OWS custody.
+ */
+export declare function importStellarKey(name: string, stellarSecret: string, passphrase?: string, vaultPath?: string): {
+    walletId: string;
+    publicKey: string;
+};
+/** Get the Stellar public key (G-address) for a named OWS wallet. */
+export declare function getOWSPublicKey(walletName: string, vaultPath?: string): string;
+/** Check XLM and USDC balances for an OWS wallet. */
+export declare function getOWSBalance(walletName: string, vaultPath?: string, networkPassphrase?: string): Promise<{
+    xlm: string;
+    usdc: string;
+}>;
+export interface OnboardAgentOpts {
+    /** cards402 API key (cards402_…) */
+    apiKey: string;
+    /** Local name for the wallet in the OWS vault, e.g. 'my-agent' */
+    walletName: string;
+    /** Override the default https://api.cards402.com/v1 */
+    baseUrl?: string;
+    /** Optional passphrase for extra at-rest encryption */
+    passphrase?: string;
+    /** Override the default ~/.ows/wallets vault path — use a persistent
+     *  volume if you're running on ephemeral storage (Lambda, Cloud Run,
+     *  scratch containers). Lost vault = lost funds. */
+    vaultPath?: string;
+}
+export interface OnboardAgentResult {
+    publicKey: string;
+    balance: {
+        xlm: string;
+        usdc: string;
+    };
+}
+/**
+ * One-shot agent setup: reports `initializing` to cards402, creates or
+ * fetches the OWS wallet, reports `awaiting_funding` with the wallet
+ * address, and returns the public key + current balance. Idempotent —
+ * safe to call on every agent startup.
+ *
+ * The backend broadcasts these transitions over the live SSE dashboard
+ * feed, so operators see the agent moving through states in real time.
+ */
+export declare function onboardAgent(opts: OnboardAgentOpts): Promise<OnboardAgentResult>;
+/**
+ * Check whether a Soroban tx hash has materialized on the Stellar
+ * ledger. Returns:
+ *   - 'landed'  — Horizon returned a successful tx record
+ *   - 'dropped' — Horizon 404s and the caller has already exhausted
+ *                 the inclusion window client-side, so the tx is
+ *                 almost certainly gone
+ *   - 'pending' — Horizon is down or the tx is still in the
+ *                 mempool; caller should wait rather than resubmit
+ *
+ * Used by purchaseCardOWS's resume branch to decide whether a
+ * dropped-pre-apply Soroban tx should be re-submitted or whether we
+ * should wait for a still-in-flight one to finalize.
+ */
+export declare function checkSorobanTxLanded(txHash: string, opts?: {
+    networkPassphrase?: string;
+}): Promise<'landed' | 'dropped' | 'pending'>;
+export interface TrustlineOpts {
+    walletName: string;
+    passphrase?: string;
+    vaultPath?: string;
+    networkPassphrase?: string;
+}
+/**
+ * Add a USDC trustline to the OWS wallet's Stellar account.
+ *
+ * Idempotent: if the trustline already exists, returns `null` without
+ * submitting a tx (Stellar accepts redundant `changeTrust` ops and
+ * silently no-ops them, but charges the base fee each time — so
+ * pre-checking saves ~0.00001 XLM per accidental re-run). Returns the
+ * new tx hash when a trustline is actually opened.
+ */
+export declare function addUsdcTrustlineOWS(opts: TrustlineOpts): Promise<string | null>;
+export interface PayViaContractOwsOpts {
+    walletName: string;
+    payment: PaymentInstructions;
+    paymentAsset?: 'usdc' | 'xlm';
+    passphrase?: string;
+    vaultPath?: string;
+    networkPassphrase?: string;
+    sorobanRpcUrl?: string;
+}
+/**
+ * Pay the cards402 receiver contract using an OWS-custody wallet. Builds a
+ * Soroban `pay_usdc` or `pay_xlm` invocation, signs the transaction hash via
+ * OWS, and submits it to the Soroban RPC. Returns the transaction hash.
+ */
+/**
+ * Injectable dependency bundle for payViaContractOWS. Production
+ * callers omit this entirely — the defaults point at the real
+ * build / submit / sign / pubkey helpers. Tests inject stubs to
+ * exercise the retry state machine without touching real Soroban
+ * or a real wallet vault.
+ */
+export interface PayViaContractOwsDeps {
+    buildContractPaymentTx?: typeof buildContractPaymentTx;
+    submitSorobanTx?: typeof submitSorobanTx;
+    owsSignTx?: (tx: Transaction, walletName: string, publicKey: string, passphrase?: string, vaultPath?: string) => void;
+    getOWSPublicKey?: (walletName: string, vaultPath?: string) => string;
+}
+export declare function payViaContractOWS(opts: PayViaContractOwsOpts, deps?: PayViaContractOwsDeps): Promise<string>;
+/** @deprecated Use `payViaContractOWS` — the old direct-Stellar path no longer matches the backend. */
+export declare const payVCCOWS: typeof payViaContractOWS;
+/** @deprecated Kept for one migration cycle. */
+export type PayVCCOwsOpts = PayViaContractOwsOpts;
+export interface PurchaseCardOwsOpts {
+    apiKey: string;
+    walletName: string;
+    amountUsdc: string;
+    paymentAsset?: 'usdc' | 'xlm';
+    passphrase?: string;
+    vaultPath?: string;
+    baseUrl?: string;
+    networkPassphrase?: string;
+    /**
+     * Resume an existing order instead of creating a new one. Three shapes:
+     *
+     *   - bare string              — wait for the backend to finish an
+     *                                in-flight payment. Conservative
+     *                                default when we have no context.
+     *
+     *   - { orderId, payment }     — caller has rebuilt the payment
+     *                                instructions (e.g. from a cached
+     *                                order response) and wants to
+     *                                resubmit.
+     *
+     *   - { orderId, txHash,       — caller has the txHash from a prior
+     *       phase }                  ResumableError. purchaseCardOWS
+     *                                checks whether that tx landed on
+     *                                the ledger and, if not, re-fetches
+     *                                the order's payment instructions
+     *                                from the backend and resubmits.
+     *                                This is the shape saved to
+     *                                ~/.cards402/last-order so the CLI
+     *                                --resume flow recovers cleanly
+     *                                from a dropped Soroban submit.
+     */
+    resume?: string | {
+        orderId: string;
+        payment?: PaymentInstructions;
+        txHash?: string;
+        phase?: 'unpaid' | 'paid';
+    };
+    /** Tune the card-ready poll. Default: { timeoutMs: 300_000, intervalMs: 3_000 }. */
+    waitForCardOpts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    };
+}
+/**
+ * Full purchase flow using an OWS wallet: create order → pay the receiver
+ * contract on Stellar → wait for card. Any failure after the order exists
+ * is wrapped as a ResumableError so the caller can retry via `--resume`
+ * without minting a new order.
+ *
+ * Soroban RPC backpressure is tolerated: if submitSorobanTx throws with a
+ * txHash attached (deadline reached but tx may still land), we proceed to
+ * waitForCard — the cards402 backend watcher is the source of truth and
+ * will credit the order when the tx finalizes.
+ */
+export declare function purchaseCardOWS(opts: PurchaseCardOwsOpts): Promise<CardDetails & {
+    order_id: string;
+}>;
+//# sourceMappingURL=ows.d.ts.map

package/dist/ows.d.ts.map

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