@mystars-tg/faas-wallet 0.1.2

package/dist/index.d.cts

@@ -0,0 +1,327 @@
+import * as _ton_core from '@ton/core';
+import { MessageRelaxed, SendMode, StateInit, Cell } from '@ton/core';
+import { KeyPair } from '@ton/crypto';
+import { PaymentInstruction, CreateOrderResult, CreateOrderParams, CreateOrderOptions, WaitForOrderOptions, Order } from '@mystars-tg/faas-sdk';
+
+/**
+ * The minimal TON RPC surface the wallet + payer need. Inject a custom one for
+ * tests (so nothing touches the network or moves funds); use `ToncenterRpc` in
+ * production.
+ */
+/**
+ * The minimal TON RPC surface the wallet + payer depend on. Implement it (or
+ * use {@link ToncenterRpc}) to read balances/seqno, resolve jetton wallets, and
+ * broadcast. Inject a mock in tests so nothing touches the network or moves funds.
+ */
+interface TonRpc {
+    /** Account TON balance, in nanoTON. */
+    getBalance(address: string): Promise<bigint>;
+    /** The wallet's current seqno (0 if the wallet contract isn't deployed yet). */
+    getSeqno(address: string): Promise<number>;
+    /** Resolve an owner's jetton wallet address from the jetton master (get_wallet_address). */
+    resolveJettonWallet(owner: string, jettonMaster: string): Promise<string>;
+    /** A jetton wallet's token balance, in the jetton's smallest unit (get_wallet_data). */
+    getJettonBalance(jettonWallet: string): Promise<bigint>;
+    /** Broadcast a serialized external-message BoC. */
+    sendBoc(boc: Uint8Array): Promise<void>;
+}
+/** Options for {@link ToncenterRpc}. */
+interface ToncenterRpcOptions {
+    /** JSON-RPC endpoint, e.g. `https://toncenter.com/api/v2/jsonRPC` (or a testnet URL). */
+    endpoint: string;
+    /** toncenter API key (recommended to avoid tight rate limits). */
+    apiKey?: string;
+}
+/**
+ * Default {@link TonRpc} backed by toncenter via `@ton/ton`'s `TonClient`.
+ *
+ * @example
+ * ```ts
+ * const rpc = new ToncenterRpc({
+ *   endpoint: "https://toncenter.com/api/v2/jsonRPC",
+ *   apiKey: process.env.TONCENTER_KEY,
+ * });
+ * ```
+ */
+declare class ToncenterRpc implements TonRpc {
+    private readonly client;
+    /** @param opts - the {@link ToncenterRpcOptions} (endpoint + optional API key) */
+    constructor(opts: ToncenterRpcOptions);
+    /** {@inheritDoc TonRpc.getBalance} */
+    getBalance(address: string): Promise<bigint>;
+    /** {@inheritDoc TonRpc.getSeqno} */
+    getSeqno(address: string): Promise<number>;
+    /** {@inheritDoc TonRpc.resolveJettonWallet} */
+    resolveJettonWallet(owner: string, jettonMaster: string): Promise<string>;
+    /** {@inheritDoc TonRpc.getJettonBalance} */
+    getJettonBalance(jettonWallet: string): Promise<bigint>;
+    /** {@inheritDoc TonRpc.sendBoc} */
+    sendBoc(boc: Uint8Array): Promise<void>;
+}
+
+/** Base error for the wallet module. */
+declare class WalletError extends Error {
+    constructor(message: string);
+}
+/** The wallet doesn't hold enough TON / jetton balance to cover a payment. */
+declare class InsufficientBalanceError extends WalletError {
+}
+/** Arguments for {@link TonWallet.createTransfer} — the unsigned pieces of a wallet-v4 transfer. */
+interface CreateTransferArgs {
+    /** The wallet's current seqno (fetch via {@link TonWallet.getSeqno}); 0 deploys the contract. */
+    seqno: number;
+    /** The internal messages to send in this transfer. */
+    messages: MessageRelaxed[];
+    /** The send mode flags (`@ton/core` `SendMode`). */
+    sendMode: SendMode;
+    /** Transfer validity window as a unix-seconds expiry; the wallet rejects it after this. */
+    timeout?: number;
+}
+/**
+ * An in-memory TON wallet (WalletContractV4). Construct via {@link TonWallet.generate} /
+ * {@link TonWallet.fromMnemonic} / {@link TonWallet.fromKeyPair}. Keys never leave memory and are
+ * redacted from serialization. See the module overview for the custody stance.
+ */
+declare class TonWallet {
+    /** The in-memory key pair. Treat `secretKey` as a secret — never log or persist it. */
+    readonly keyPair: KeyPair;
+    private readonly contract;
+    private constructor();
+    /** Redacted serialization — NEVER exposes the secret key. */
+    toJSON(): {
+        address: string;
+        publicKey: string;
+    };
+    /**
+     * Generate a NEW wallet. Returns the 24-word mnemonic ONCE — store it securely;
+     * it is never persisted.
+     *
+     * @returns the in-memory `wallet` and its `mnemonic` (the only time you see it)
+     * @example
+     * ```ts
+     * const { wallet, mnemonic } = await TonWallet.generate();
+     * await secureVault.store(mnemonic);     // YOUR job — it is never written to disk by the SDK
+     * console.log("fund this:", wallet.address);
+     * ```
+     */
+    static generate(): Promise<{
+        wallet: TonWallet;
+        mnemonic: string[];
+    }>;
+    /** Import a wallet from its 24-word mnemonic. */
+    static fromMnemonic(words: string[]): Promise<TonWallet>;
+    /** Import a wallet from a raw Ed25519 key pair. */
+    static fromKeyPair(publicKey: Uint8Array, secretKey: Uint8Array): TonWallet;
+    /** Friendly, non-bounceable (`UQ…`) address — FUND THIS to pay invoices. */
+    get address(): string;
+    /** Raw `0:hex` address form. */
+    get rawAddress(): string;
+    /** @internal The contract's StateInit, needed for the first (deploying) transfer. */
+    get init(): StateInit;
+    /** @internal The contract address as a TON `Address`. */
+    get tonAddress(): _ton_core.Address;
+    /** @internal Sign a transfer body. */
+    createTransfer(args: CreateTransferArgs): Cell;
+    /**
+     * This wallet's native TON balance.
+     *
+     * @param rpc - the RPC to query through
+     * @returns the balance in nanoTON
+     */
+    getBalance(rpc: TonRpc): Promise<bigint>;
+    /**
+     * This wallet's current sequence number.
+     *
+     * @param rpc - the RPC to query through
+     * @returns the seqno (`0` when the wallet contract isn't deployed yet)
+     */
+    getSeqno(rpc: TonRpc): Promise<number>;
+    /**
+     * This wallet's balance of a given jetton (e.g. USDT).
+     *
+     * @param rpc - the RPC to query through
+     * @param jettonMaster - the jetton master address (e.g. `DEFAULT_USDT_MASTER` from `@mystars-tg/faas-wallet`)
+     * @returns the token balance in the jetton's smallest unit (micro-USDT for USDT)
+     */
+    getJettonBalance(rpc: TonRpc, jettonMaster: string): Promise<bigint>;
+}
+
+/**
+ * `OrderPayer` — pay a FaaS order invoice from your own `TonWallet`.
+ *
+ * Signs ONCE and broadcasts. For `ton` it sends an exact-amount transfer with the
+ * order memo as an op-0 comment; for `usdt_ton` it resolves the payer's own USDT
+ * jetton wallet and sends a TEP-74 transfer whose `destination` is the FaaS
+ * `pay_to_address` and whose forward payload carries the memo.
+ *
+ * NOTE: this moves the PARTNER's own funds from the partner's own wallet — never
+ * the MyStars treasury. Tests use a mock `TonRpc` so nothing broadcasts.
+ */
+
+/** Mainnet Tether USDT jetton master on TON. Override via `PayOrderOptions.jettonMaster` for testnet. */
+declare const DEFAULT_USDT_MASTER = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
+/** TON attached to a USDT jetton transfer to cover its gas (excess refunds to the sender). Matches the core invoice builder. */
+declare const DEFAULT_JETTON_GAS_TON = "0.05";
+/** Options for {@link OrderPayer.payOrder} / {@link OrderPayer.planMessages}. */
+interface PayOrderOptions {
+    /** The RPC used to resolve the jetton wallet, read balances, and broadcast. */
+    rpc: TonRpc;
+    /** USDT jetton master (defaults to mainnet Tether). */
+    jettonMaster?: string;
+    /** TON gas attached to a USDT transfer (default 0.05). */
+    jettonGasTon?: string;
+    /** Transfer validity window in seconds (default 120 — a non-landed send dies fast, safe to retry). */
+    validForSeconds?: number;
+    /** Skip the pre-sign balance check (saves 1-2 RPC calls; default false). */
+    skipBalanceCheck?: boolean;
+    /** Injectable clock (epoch ms) for deterministic tests. */
+    now?: number;
+}
+/** The outcome of a broadcast payment from {@link OrderPayer.payOrder}. */
+interface PayOrderResult {
+    /** The order id paid. */
+    orderId?: string;
+    /** The paying wallet address. */
+    from: string;
+    /** The recipient (FaaS treasury owner) address. */
+    to: string;
+    /** The smallest-unit amount sent (nanoTON for ton, micro-USDT for usdt_ton). */
+    amountSmallestUnit: string;
+}
+/** An internal message the payer will sign into a transfer. Exposed for testing. */
+interface PlannedMessage {
+    to: string;
+    value: bigint;
+    body: Cell;
+    bounce: boolean;
+}
+/**
+ * Pays a FaaS order invoice from a single {@link TonWallet}.
+ *
+ * @example
+ * ```ts
+ * const order = await client.createOrder(
+ *   { type: "stars", recipient: { username: "durov" }, quantity: 100 },
+ *   { idempotencyKey: `order-${myId}` },
+ * );
+ * const rpc = new ToncenterRpc({ endpoint: "https://toncenter.com/api/v2/jsonRPC" });
+ * const { from, to, amountSmallestUnit } = await new OrderPayer(wallet).payOrder(order, { rpc });
+ * const finished = await client.waitForOrder(order.order_id);
+ * ```
+ */
+declare class OrderPayer {
+    private readonly wallet;
+    /** @param wallet - the funded {@link TonWallet} whose own funds will pay invoices */
+    constructor(wallet: TonWallet);
+    /**
+     * Plan the internal message(s) for an order WITHOUT signing or broadcasting.
+     * `ton` is pure; `usdt_ton` resolves the payer's jetton wallet via `rpc`.
+     */
+    planMessages(payment: PaymentInstruction, opts: PayOrderOptions): Promise<PlannedMessage[]>;
+    /** Throw `InsufficientBalanceError` if the wallet can't cover the planned payment + gas. */
+    private assertFunded;
+    /**
+     * Build, sign, and broadcast the payment for an order. Signs exactly ONCE.
+     *
+     * MONEY: this broadcasts a real on-chain transfer of the wallet's OWN funds.
+     * It is not idempotent — calling it twice for the same order pays twice. Guard
+     * retries at the order layer (a stable `Idempotency-Key` on `createOrder`, or
+     * use `fulfill` which only pays an order still `awaiting_payment`).
+     *
+     * @param order - a `CreateOrderResult`, or any object carrying a `payment` block (and optional `order_id`)
+     * @param opts - the {@link PayOrderOptions} (at minimum `rpc`)
+     * @returns the {@link PayOrderResult} — `from`/`to` addresses and the smallest-unit amount sent
+     * @throws `WalletError` if the order's `payment` block is missing `pay_to_address`/`memo`
+     * @throws `MyStarsValidationError` if the amount is non-positive
+     * @throws {@link InsufficientBalanceError} if the wallet can't cover the payment + gas (unless `skipBalanceCheck`)
+     */
+    payOrder(order: CreateOrderResult | {
+        payment: PaymentInstruction;
+        order_id?: string;
+    }, opts: PayOrderOptions): Promise<PayOrderResult>;
+}
+
+/**
+ * `fulfill()` — the one-call convenience: create an order, pay it from your
+ * wallet, and wait until it's delivered (or failed/reversed/expired).
+ *
+ * RETRY HAZARD (money): this broadcasts a REAL payment. A naive retry of a
+ * `fulfill` that already broadcast would create a SECOND order and pay it AGAIN.
+ * Two safeguards make retries safe:
+ *   1. A stable `idempotencyKey` is REQUIRED — re-running `fulfill` with the same
+ *      key returns the SAME order from the server (idempotent replay) instead of
+ *      minting a duplicate.
+ *   2. We only broadcast when the (possibly replayed) order is still
+ *      `awaiting_payment`. If the replay shows the order already advanced
+ *      (`paid`/`delivered`/…), we SKIP the payment and just wait — so a retry
+ *      never double-pays an order whose first payment already landed.
+ * If anything throws after the order exists, the error carries `order_id` so you
+ * re-attach via `getOrder`/`waitForOrder` instead of re-paying.
+ */
+
+/** The slice of `MyStarsClient` `fulfill` needs (structurally typed so it's easy to mock). */
+interface FulfillClient {
+    createOrder(params: CreateOrderParams, opts?: CreateOrderOptions): Promise<CreateOrderResult>;
+    waitForOrder(orderId: string, opts?: WaitForOrderOptions): Promise<Order>;
+}
+/** Options for {@link fulfill} — the {@link PayOrderOptions} (e.g. `rpc`) plus order-create/wait wiring. */
+interface FulfillOptions extends PayOrderOptions {
+    /**
+     * REQUIRED stable idempotency key — derive it from YOUR OWN order id so a retry
+     * of `fulfill` reuses the same key and the server returns the same order instead
+     * of creating a duplicate. May also be supplied via `createOptions.idempotencyKey`.
+     */
+    idempotencyKey?: string;
+    /** Options forwarded to `createOrder` (e.g. a caller-supplied idempotency key). */
+    createOptions?: CreateOrderOptions;
+    /** Options forwarded to `waitForOrder`. */
+    wait?: WaitForOrderOptions;
+}
+/**
+ * An error thrown AFTER the order was created carries the `order_id` so you can
+ * re-attach (`getOrder`/`waitForOrder`) instead of re-running `fulfill` (which
+ * would re-pay). The error may be any class (a `MyStarsApiError` from the wait, a
+ * `WalletError` from the payer, …), so the id rides as an optional property —
+ * read it with the type-safe {@link orderIdFromError} accessor.
+ */
+type ErrorWithOrderId = Error & {
+    order_id?: string;
+};
+/**
+ * Read the `order_id` that `fulfill` attaches to a post-create failure. Returns
+ * `undefined` when the error carries none. Use it to recover safely after a
+ * `fulfill` throw — re-attach with `client.waitForOrder(id)` / `getOrder(id)`
+ * rather than re-running `fulfill` (which would broadcast a second payment).
+ */
+declare function orderIdFromError(err: unknown): string | undefined;
+/**
+ * create → pay → wait-until-terminal, in one call.
+ *
+ * Creates the order with the required stable `idempotencyKey`, broadcasts the
+ * payment from `wallet` ONLY if the (possibly idempotent-replayed) order is still
+ * `awaiting_payment`, then polls until the order is terminal. See the module note
+ * for the money-retry safeguards.
+ *
+ * @param client - the order-layer client (a `MyStarsClient`, or any {@link FulfillClient})
+ * @param wallet - the funded {@link TonWallet} that pays the invoice
+ * @param params - the order to create (`CreateOrderParams`)
+ * @param opts - {@link FulfillOptions} — MUST include a stable `idempotencyKey` (or `createOptions.idempotencyKey`) plus `rpc`
+ * @returns the final {@link Order} (terminal status — `delivered`/`failed`/`reversed`/`expired`)
+ * @throws `MyStarsValidationError` if no stable `idempotencyKey` was supplied
+ * @throws `RecipientIneligibleError` (422) if the recipient cannot receive the item (no order created)
+ * @throws `InsufficientBalanceError` if the wallet can't cover the payment
+ * @throws `OrderWaitTimeoutError` if the order doesn't finish before the wait deadline
+ * @throws `MyStarsApiError` on other API failures — after the order exists the thrown error carries `order_id` (read via {@link orderIdFromError}); re-attach with `client.waitForOrder(orderId)` instead of re-running `fulfill`
+ * @example
+ * ```ts
+ * const order = await fulfill(
+ *   client, wallet,
+ *   { type: "stars", recipient: { username: "durov" }, quantity: 100 },
+ *   { rpc, idempotencyKey: `order-${myOrderId}` },
+ * );
+ * if (order.status !== "delivered") console.warn("not delivered:", order.failure_reason);
+ * ```
+ */
+declare function fulfill(client: FulfillClient, wallet: TonWallet, params: CreateOrderParams, opts: FulfillOptions): Promise<Order>;
+
+export { type CreateTransferArgs, DEFAULT_JETTON_GAS_TON, DEFAULT_USDT_MASTER, type ErrorWithOrderId, type FulfillClient, type FulfillOptions, InsufficientBalanceError, OrderPayer, type PayOrderOptions, type PayOrderResult, type PlannedMessage, type TonRpc, TonWallet, ToncenterRpc, type ToncenterRpcOptions, WalletError, fulfill, orderIdFromError };

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+import * as _ton_core from '@ton/core';
+import { MessageRelaxed, SendMode, StateInit, Cell } from '@ton/core';
+import { KeyPair } from '@ton/crypto';
+import { PaymentInstruction, CreateOrderResult, CreateOrderParams, CreateOrderOptions, WaitForOrderOptions, Order } from '@mystars-tg/faas-sdk';
+
+/**
+ * The minimal TON RPC surface the wallet + payer need. Inject a custom one for
+ * tests (so nothing touches the network or moves funds); use `ToncenterRpc` in
+ * production.
+ */
+/**
+ * The minimal TON RPC surface the wallet + payer depend on. Implement it (or
+ * use {@link ToncenterRpc}) to read balances/seqno, resolve jetton wallets, and
+ * broadcast. Inject a mock in tests so nothing touches the network or moves funds.
+ */
+interface TonRpc {
+    /** Account TON balance, in nanoTON. */
+    getBalance(address: string): Promise<bigint>;
+    /** The wallet's current seqno (0 if the wallet contract isn't deployed yet). */
+    getSeqno(address: string): Promise<number>;
+    /** Resolve an owner's jetton wallet address from the jetton master (get_wallet_address). */
+    resolveJettonWallet(owner: string, jettonMaster: string): Promise<string>;
+    /** A jetton wallet's token balance, in the jetton's smallest unit (get_wallet_data). */
+    getJettonBalance(jettonWallet: string): Promise<bigint>;
+    /** Broadcast a serialized external-message BoC. */
+    sendBoc(boc: Uint8Array): Promise<void>;
+}
+/** Options for {@link ToncenterRpc}. */
+interface ToncenterRpcOptions {
+    /** JSON-RPC endpoint, e.g. `https://toncenter.com/api/v2/jsonRPC` (or a testnet URL). */
+    endpoint: string;
+    /** toncenter API key (recommended to avoid tight rate limits). */
+    apiKey?: string;
+}
+/**
+ * Default {@link TonRpc} backed by toncenter via `@ton/ton`'s `TonClient`.
+ *
+ * @example
+ * ```ts
+ * const rpc = new ToncenterRpc({
+ *   endpoint: "https://toncenter.com/api/v2/jsonRPC",
+ *   apiKey: process.env.TONCENTER_KEY,
+ * });
+ * ```
+ */
+declare class ToncenterRpc implements TonRpc {
+    private readonly client;
+    /** @param opts - the {@link ToncenterRpcOptions} (endpoint + optional API key) */
+    constructor(opts: ToncenterRpcOptions);
+    /** {@inheritDoc TonRpc.getBalance} */
+    getBalance(address: string): Promise<bigint>;
+    /** {@inheritDoc TonRpc.getSeqno} */
+    getSeqno(address: string): Promise<number>;
+    /** {@inheritDoc TonRpc.resolveJettonWallet} */
+    resolveJettonWallet(owner: string, jettonMaster: string): Promise<string>;
+    /** {@inheritDoc TonRpc.getJettonBalance} */
+    getJettonBalance(jettonWallet: string): Promise<bigint>;
+    /** {@inheritDoc TonRpc.sendBoc} */
+    sendBoc(boc: Uint8Array): Promise<void>;
+}
+
+/** Base error for the wallet module. */
+declare class WalletError extends Error {
+    constructor(message: string);
+}
+/** The wallet doesn't hold enough TON / jetton balance to cover a payment. */
+declare class InsufficientBalanceError extends WalletError {
+}
+/** Arguments for {@link TonWallet.createTransfer} — the unsigned pieces of a wallet-v4 transfer. */
+interface CreateTransferArgs {
+    /** The wallet's current seqno (fetch via {@link TonWallet.getSeqno}); 0 deploys the contract. */
+    seqno: number;
+    /** The internal messages to send in this transfer. */
+    messages: MessageRelaxed[];
+    /** The send mode flags (`@ton/core` `SendMode`). */
+    sendMode: SendMode;
+    /** Transfer validity window as a unix-seconds expiry; the wallet rejects it after this. */
+    timeout?: number;
+}
+/**
+ * An in-memory TON wallet (WalletContractV4). Construct via {@link TonWallet.generate} /
+ * {@link TonWallet.fromMnemonic} / {@link TonWallet.fromKeyPair}. Keys never leave memory and are
+ * redacted from serialization. See the module overview for the custody stance.
+ */
+declare class TonWallet {
+    /** The in-memory key pair. Treat `secretKey` as a secret — never log or persist it. */
+    readonly keyPair: KeyPair;
+    private readonly contract;
+    private constructor();
+    /** Redacted serialization — NEVER exposes the secret key. */
+    toJSON(): {
+        address: string;
+        publicKey: string;
+    };
+    /**
+     * Generate a NEW wallet. Returns the 24-word mnemonic ONCE — store it securely;
+     * it is never persisted.
+     *
+     * @returns the in-memory `wallet` and its `mnemonic` (the only time you see it)
+     * @example
+     * ```ts
+     * const { wallet, mnemonic } = await TonWallet.generate();
+     * await secureVault.store(mnemonic);     // YOUR job — it is never written to disk by the SDK
+     * console.log("fund this:", wallet.address);
+     * ```
+     */
+    static generate(): Promise<{
+        wallet: TonWallet;
+        mnemonic: string[];
+    }>;
+    /** Import a wallet from its 24-word mnemonic. */
+    static fromMnemonic(words: string[]): Promise<TonWallet>;
+    /** Import a wallet from a raw Ed25519 key pair. */
+    static fromKeyPair(publicKey: Uint8Array, secretKey: Uint8Array): TonWallet;
+    /** Friendly, non-bounceable (`UQ…`) address — FUND THIS to pay invoices. */
+    get address(): string;
+    /** Raw `0:hex` address form. */
+    get rawAddress(): string;
+    /** @internal The contract's StateInit, needed for the first (deploying) transfer. */
+    get init(): StateInit;
+    /** @internal The contract address as a TON `Address`. */
+    get tonAddress(): _ton_core.Address;
+    /** @internal Sign a transfer body. */
+    createTransfer(args: CreateTransferArgs): Cell;
+    /**
+     * This wallet's native TON balance.
+     *
+     * @param rpc - the RPC to query through
+     * @returns the balance in nanoTON
+     */
+    getBalance(rpc: TonRpc): Promise<bigint>;
+    /**
+     * This wallet's current sequence number.
+     *
+     * @param rpc - the RPC to query through
+     * @returns the seqno (`0` when the wallet contract isn't deployed yet)
+     */
+    getSeqno(rpc: TonRpc): Promise<number>;
+    /**
+     * This wallet's balance of a given jetton (e.g. USDT).
+     *
+     * @param rpc - the RPC to query through
+     * @param jettonMaster - the jetton master address (e.g. `DEFAULT_USDT_MASTER` from `@mystars-tg/faas-wallet`)
+     * @returns the token balance in the jetton's smallest unit (micro-USDT for USDT)
+     */
+    getJettonBalance(rpc: TonRpc, jettonMaster: string): Promise<bigint>;
+}
+
+/**
+ * `OrderPayer` — pay a FaaS order invoice from your own `TonWallet`.
+ *
+ * Signs ONCE and broadcasts. For `ton` it sends an exact-amount transfer with the
+ * order memo as an op-0 comment; for `usdt_ton` it resolves the payer's own USDT
+ * jetton wallet and sends a TEP-74 transfer whose `destination` is the FaaS
+ * `pay_to_address` and whose forward payload carries the memo.
+ *
+ * NOTE: this moves the PARTNER's own funds from the partner's own wallet — never
+ * the MyStars treasury. Tests use a mock `TonRpc` so nothing broadcasts.
+ */
+
+/** Mainnet Tether USDT jetton master on TON. Override via `PayOrderOptions.jettonMaster` for testnet. */
+declare const DEFAULT_USDT_MASTER = "EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs";
+/** TON attached to a USDT jetton transfer to cover its gas (excess refunds to the sender). Matches the core invoice builder. */
+declare const DEFAULT_JETTON_GAS_TON = "0.05";
+/** Options for {@link OrderPayer.payOrder} / {@link OrderPayer.planMessages}. */
+interface PayOrderOptions {
+    /** The RPC used to resolve the jetton wallet, read balances, and broadcast. */
+    rpc: TonRpc;
+    /** USDT jetton master (defaults to mainnet Tether). */
+    jettonMaster?: string;
+    /** TON gas attached to a USDT transfer (default 0.05). */
+    jettonGasTon?: string;
+    /** Transfer validity window in seconds (default 120 — a non-landed send dies fast, safe to retry). */
+    validForSeconds?: number;
+    /** Skip the pre-sign balance check (saves 1-2 RPC calls; default false). */
+    skipBalanceCheck?: boolean;
+    /** Injectable clock (epoch ms) for deterministic tests. */
+    now?: number;
+}
+/** The outcome of a broadcast payment from {@link OrderPayer.payOrder}. */
+interface PayOrderResult {
+    /** The order id paid. */
+    orderId?: string;
+    /** The paying wallet address. */
+    from: string;
+    /** The recipient (FaaS treasury owner) address. */
+    to: string;
+    /** The smallest-unit amount sent (nanoTON for ton, micro-USDT for usdt_ton). */
+    amountSmallestUnit: string;
+}
+/** An internal message the payer will sign into a transfer. Exposed for testing. */
+interface PlannedMessage {
+    to: string;
+    value: bigint;
+    body: Cell;
+    bounce: boolean;
+}
+/**
+ * Pays a FaaS order invoice from a single {@link TonWallet}.
+ *
+ * @example
+ * ```ts
+ * const order = await client.createOrder(
+ *   { type: "stars", recipient: { username: "durov" }, quantity: 100 },
+ *   { idempotencyKey: `order-${myId}` },
+ * );
+ * const rpc = new ToncenterRpc({ endpoint: "https://toncenter.com/api/v2/jsonRPC" });
+ * const { from, to, amountSmallestUnit } = await new OrderPayer(wallet).payOrder(order, { rpc });
+ * const finished = await client.waitForOrder(order.order_id);
+ * ```
+ */
+declare class OrderPayer {
+    private readonly wallet;
+    /** @param wallet - the funded {@link TonWallet} whose own funds will pay invoices */
+    constructor(wallet: TonWallet);
+    /**
+     * Plan the internal message(s) for an order WITHOUT signing or broadcasting.
+     * `ton` is pure; `usdt_ton` resolves the payer's jetton wallet via `rpc`.
+     */
+    planMessages(payment: PaymentInstruction, opts: PayOrderOptions): Promise<PlannedMessage[]>;
+    /** Throw `InsufficientBalanceError` if the wallet can't cover the planned payment + gas. */
+    private assertFunded;
+    /**
+     * Build, sign, and broadcast the payment for an order. Signs exactly ONCE.
+     *
+     * MONEY: this broadcasts a real on-chain transfer of the wallet's OWN funds.
+     * It is not idempotent — calling it twice for the same order pays twice. Guard
+     * retries at the order layer (a stable `Idempotency-Key` on `createOrder`, or
+     * use `fulfill` which only pays an order still `awaiting_payment`).
+     *
+     * @param order - a `CreateOrderResult`, or any object carrying a `payment` block (and optional `order_id`)
+     * @param opts - the {@link PayOrderOptions} (at minimum `rpc`)
+     * @returns the {@link PayOrderResult} — `from`/`to` addresses and the smallest-unit amount sent
+     * @throws `WalletError` if the order's `payment` block is missing `pay_to_address`/`memo`
+     * @throws `MyStarsValidationError` if the amount is non-positive
+     * @throws {@link InsufficientBalanceError} if the wallet can't cover the payment + gas (unless `skipBalanceCheck`)
+     */
+    payOrder(order: CreateOrderResult | {
+        payment: PaymentInstruction;
+        order_id?: string;
+    }, opts: PayOrderOptions): Promise<PayOrderResult>;
+}
+
+/**
+ * `fulfill()` — the one-call convenience: create an order, pay it from your
+ * wallet, and wait until it's delivered (or failed/reversed/expired).
+ *
+ * RETRY HAZARD (money): this broadcasts a REAL payment. A naive retry of a
+ * `fulfill` that already broadcast would create a SECOND order and pay it AGAIN.
+ * Two safeguards make retries safe:
+ *   1. A stable `idempotencyKey` is REQUIRED — re-running `fulfill` with the same
+ *      key returns the SAME order from the server (idempotent replay) instead of
+ *      minting a duplicate.
+ *   2. We only broadcast when the (possibly replayed) order is still
+ *      `awaiting_payment`. If the replay shows the order already advanced
+ *      (`paid`/`delivered`/…), we SKIP the payment and just wait — so a retry
+ *      never double-pays an order whose first payment already landed.
+ * If anything throws after the order exists, the error carries `order_id` so you
+ * re-attach via `getOrder`/`waitForOrder` instead of re-paying.
+ */
+
+/** The slice of `MyStarsClient` `fulfill` needs (structurally typed so it's easy to mock). */
+interface FulfillClient {
+    createOrder(params: CreateOrderParams, opts?: CreateOrderOptions): Promise<CreateOrderResult>;
+    waitForOrder(orderId: string, opts?: WaitForOrderOptions): Promise<Order>;
+}
+/** Options for {@link fulfill} — the {@link PayOrderOptions} (e.g. `rpc`) plus order-create/wait wiring. */
+interface FulfillOptions extends PayOrderOptions {
+    /**
+     * REQUIRED stable idempotency key — derive it from YOUR OWN order id so a retry
+     * of `fulfill` reuses the same key and the server returns the same order instead
+     * of creating a duplicate. May also be supplied via `createOptions.idempotencyKey`.
+     */
+    idempotencyKey?: string;
+    /** Options forwarded to `createOrder` (e.g. a caller-supplied idempotency key). */
+    createOptions?: CreateOrderOptions;
+    /** Options forwarded to `waitForOrder`. */
+    wait?: WaitForOrderOptions;
+}
+/**
+ * An error thrown AFTER the order was created carries the `order_id` so you can
+ * re-attach (`getOrder`/`waitForOrder`) instead of re-running `fulfill` (which
+ * would re-pay). The error may be any class (a `MyStarsApiError` from the wait, a
+ * `WalletError` from the payer, …), so the id rides as an optional property —
+ * read it with the type-safe {@link orderIdFromError} accessor.
+ */
+type ErrorWithOrderId = Error & {
+    order_id?: string;
+};
+/**
+ * Read the `order_id` that `fulfill` attaches to a post-create failure. Returns
+ * `undefined` when the error carries none. Use it to recover safely after a
+ * `fulfill` throw — re-attach with `client.waitForOrder(id)` / `getOrder(id)`
+ * rather than re-running `fulfill` (which would broadcast a second payment).
+ */
+declare function orderIdFromError(err: unknown): string | undefined;
+/**
+ * create → pay → wait-until-terminal, in one call.
+ *
+ * Creates the order with the required stable `idempotencyKey`, broadcasts the
+ * payment from `wallet` ONLY if the (possibly idempotent-replayed) order is still
+ * `awaiting_payment`, then polls until the order is terminal. See the module note
+ * for the money-retry safeguards.
+ *
+ * @param client - the order-layer client (a `MyStarsClient`, or any {@link FulfillClient})
+ * @param wallet - the funded {@link TonWallet} that pays the invoice
+ * @param params - the order to create (`CreateOrderParams`)
+ * @param opts - {@link FulfillOptions} — MUST include a stable `idempotencyKey` (or `createOptions.idempotencyKey`) plus `rpc`
+ * @returns the final {@link Order} (terminal status — `delivered`/`failed`/`reversed`/`expired`)
+ * @throws `MyStarsValidationError` if no stable `idempotencyKey` was supplied
+ * @throws `RecipientIneligibleError` (422) if the recipient cannot receive the item (no order created)
+ * @throws `InsufficientBalanceError` if the wallet can't cover the payment
+ * @throws `OrderWaitTimeoutError` if the order doesn't finish before the wait deadline
+ * @throws `MyStarsApiError` on other API failures — after the order exists the thrown error carries `order_id` (read via {@link orderIdFromError}); re-attach with `client.waitForOrder(orderId)` instead of re-running `fulfill`
+ * @example
+ * ```ts
+ * const order = await fulfill(
+ *   client, wallet,
+ *   { type: "stars", recipient: { username: "durov" }, quantity: 100 },
+ *   { rpc, idempotencyKey: `order-${myOrderId}` },
+ * );
+ * if (order.status !== "delivered") console.warn("not delivered:", order.failure_reason);
+ * ```
+ */
+declare function fulfill(client: FulfillClient, wallet: TonWallet, params: CreateOrderParams, opts: FulfillOptions): Promise<Order>;
+
+export { type CreateTransferArgs, DEFAULT_JETTON_GAS_TON, DEFAULT_USDT_MASTER, type ErrorWithOrderId, type FulfillClient, type FulfillOptions, InsufficientBalanceError, OrderPayer, type PayOrderOptions, type PayOrderResult, type PlannedMessage, type TonRpc, TonWallet, ToncenterRpc, type ToncenterRpcOptions, WalletError, fulfill, orderIdFromError };