@p2pdotme/sdk 1.0.5 → 1.1.0

package/dist/orders.d.cts

@@ -0,0 +1,399 @@
+import { ResultAsync } from 'neverthrow';
+import { Address, WalletClient, TransactionReceipt } from 'viem';
+import { z } from 'zod';
+
+/**
+ * Minimal viem PublicClient interface — consumers pass their own client.
+ * The SDK uses `readContract` for single reads and `multicall` where available
+ * to batch multiple reads into one RPC round-trip.
+ */
+interface PublicClientLike {
+    readContract(args: {
+        address: Address;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+    }): Promise<unknown>;
+    multicall?(args: {
+        contracts: readonly {
+            address: Address;
+            abi: readonly unknown[];
+            functionName: string;
+            args?: readonly unknown[];
+        }[];
+        allowFailure?: boolean;
+    }): Promise<readonly unknown[]>;
+}
+
+declare class SdkError<TCode extends string = string> extends Error {
+    readonly code: TCode;
+    readonly cause?: unknown;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options: {
+        code: TCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+type OrdersErrorCode = "VALIDATION_ERROR" | "INVALID_ORDER_ID" | "INVALID_GET_ORDERS_PARAMS" | "INVALID_FEE_CONFIG_PARAMS" | "ORDER_NOT_FOUND" | "CONTRACT_READ_FAILED" | "SUBGRAPH_REQUEST_FAILED" | "SUBGRAPH_VALIDATION_FAILED" | "MALFORMED_ORDER" | "CIRCLE_SELECTION_FAILED" | "ENCRYPTION_FAILED" | "RELAY_IDENTITY_CORRUPT" | "RELAY_IDENTITY_STORE_FAILED" | "TX_SUBMISSION_FAILED" | "RECEIPT_TIMEOUT" | "TX_REVERTED" | "EVENT_WATCH_FAILED";
+declare class OrdersError extends SdkError<OrdersErrorCode> {
+    constructor(message: string, options: {
+        code: OrdersErrorCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+
+interface RelayIdentity {
+    readonly address: `0x${string}`;
+    readonly publicKey: string;
+    readonly privateKey: `0x${string}`;
+}
+/**
+ * Generates a fresh relay identity keypair. Pure — no side effects.
+ * Consumers decide how to persist the result via a `RelayIdentityStore`.
+ */
+declare function createRelayIdentity(): RelayIdentity;
+
+interface RelayIdentityStore {
+    get(): Promise<RelayIdentity | null>;
+    set(identity: RelayIdentity): Promise<void>;
+}
+/**
+ * Ephemeral in-process store. Lost on process restart. Used as the default
+ * when the consumer doesn't supply one.
+ */
+declare function createInMemoryRelayStore(): RelayIdentityStore;
+/**
+ * Browser-only adapter that persists the identity as JSON in `localStorage`.
+ * Throws at call time if `localStorage` is unavailable — do not use in SSR/RN.
+ */
+declare function createLocalStorageRelayStore(options?: {
+    key?: string;
+}): RelayIdentityStore;
+
+declare const ZodGetOrderParamsSchema: z.ZodObject<{
+    orderId: z.ZodBigInt;
+}, z.core.$strip>;
+type GetOrderParams = z.infer<typeof ZodGetOrderParamsSchema>;
+declare const ZodGetFeeConfigParamsSchema: z.ZodObject<{
+    currency: z.ZodEnum<{
+        IDR: "IDR";
+        INR: "INR";
+        BRL: "BRL";
+        ARS: "ARS";
+        MEX: "MEX";
+        VEN: "VEN";
+        EUR: "EUR";
+        NGN: "NGN";
+        USD: "USD";
+        COP: "COP";
+    }>;
+}, z.core.$strip>;
+type GetFeeConfigParams = z.infer<typeof ZodGetFeeConfigParamsSchema>;
+declare const ZodGetOrdersParamsSchema: z.ZodObject<{
+    userAddress: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+    skip: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type GetOrdersParams = z.input<typeof ZodGetOrdersParamsSchema>;
+declare const ZodPlaceOrderParamsSchema: z.ZodObject<{
+    orderType: z.ZodNumber;
+    currency: z.ZodEnum<{
+        IDR: "IDR";
+        INR: "INR";
+        BRL: "BRL";
+        ARS: "ARS";
+        MEX: "MEX";
+        VEN: "VEN";
+        EUR: "EUR";
+        NGN: "NGN";
+        USD: "USD";
+        COP: "COP";
+    }>;
+    user: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+    amount: z.ZodBigInt;
+    fiatAmount: z.ZodBigInt;
+    fiatAmountLimit: z.ZodDefault<z.ZodOptional<z.ZodBigInt>>;
+    recipientAddr: z.ZodString & z.ZodType<`0x${string}`, string, z.core.$ZodTypeInternals<`0x${string}`, string>>;
+    preferredPaymentChannelConfigId: z.ZodOptional<z.ZodBigInt>;
+    pubKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PlaceOrderParams = z.input<typeof ZodPlaceOrderParamsSchema>;
+declare const ZodCancelOrderParamsSchema: z.ZodObject<{
+    orderId: z.ZodBigInt;
+}, z.core.$strip>;
+type CancelOrderParams = z.infer<typeof ZodCancelOrderParamsSchema>;
+declare const ZodSetSellOrderUpiParamsSchema: z.ZodObject<{
+    orderId: z.ZodBigInt;
+    paymentAddress: z.ZodString;
+    merchantPublicKey: z.ZodString;
+    updatedAmount: z.ZodBigInt;
+}, z.core.$strip>;
+type SetSellOrderUpiParams = z.infer<typeof ZodSetSellOrderUpiParamsSchema>;
+declare const ZodRaiseDisputeParamsSchema: z.ZodObject<{
+    orderId: z.ZodBigInt;
+    redactTransId: z.ZodBigInt;
+}, z.core.$strip>;
+type RaiseDisputeParams = z.infer<typeof ZodRaiseDisputeParamsSchema>;
+declare const ZodApproveUsdcParamsSchema: z.ZodObject<{
+    amount: z.ZodBigInt;
+}, z.core.$strip>;
+type ApproveUsdcParams = z.infer<typeof ZodApproveUsdcParamsSchema>;
+declare const ZodPaidBuyOrderParamsSchema: z.ZodObject<{
+    orderId: z.ZodBigInt;
+}, z.core.$strip>;
+type PaidBuyOrderParams = z.infer<typeof ZodPaidBuyOrderParamsSchema>;
+
+type OrderType = "buy" | "sell" | "pay";
+type OrderStatus = "placed" | "accepted" | "paid" | "completed" | "cancelled";
+type DisputeStatus = "none" | "open" | "resolved";
+/**
+ * Normalized order record returned by both `getOrder` and `getOrders`.
+ * Amounts are 6-decimal bigints; timestamps are unix seconds.
+ */
+interface Order {
+    orderId: bigint;
+    type: OrderType;
+    status: OrderStatus;
+    usdcAmount: bigint;
+    fiatAmount: bigint;
+    actualUsdcAmount: bigint;
+    actualFiatAmount: bigint;
+    currency: string;
+    user: Address;
+    recipient: Address;
+    acceptedMerchant: Address;
+    placedAt: bigint;
+    acceptedAt: bigint;
+    paidAt: bigint;
+    completedAt: bigint;
+    circleId: bigint;
+    fixedFeePaid: bigint;
+    tipsPaid: bigint;
+    disputeStatus: DisputeStatus;
+    /**
+     * Encrypted UPI / payment address that the merchant published for this order
+     * (set when the merchant accepts a buy order). Empty string until set.
+     * Decrypt with `decryptPaymentAddress`.
+     */
+    encUpi: string;
+    /**
+     * Encrypted merchant UPI for the seller-side flow (set by `setSellOrderUpi`).
+     * Empty string until set.
+     */
+    encMerchantUpi: string;
+    /** Public key associated with the order, used for ECIES encryption setup. */
+    pubkey: string;
+}
+/**
+ * Per-currency small-order fee config read from the Diamond.
+ * Amounts are 6-decimal bigints.
+ */
+interface FeeConfig {
+    /** Order amounts at or below this threshold are billed the fixed fee. */
+    smallOrderThreshold: bigint;
+    /** Fixed fee applied to small orders (6 decimals). */
+    smallOrderFixedFee: bigint;
+}
+interface OrdersConfig {
+    readonly publicClient: PublicClientLike;
+    readonly diamondAddress: Address;
+    readonly usdcAddress: Address;
+    readonly subgraphUrl: string;
+    readonly relayIdentityStore?: RelayIdentityStore;
+    readonly relayIdentity?: RelayIdentity;
+    readonly logger?: Logger;
+}
+interface PreparedTxMeta {
+    readonly circleId?: bigint;
+    readonly relayIdentity?: RelayIdentity;
+}
+interface PreparedTx {
+    readonly to: `0x${string}`;
+    readonly data: `0x${string}`;
+    readonly value: bigint;
+    readonly meta?: PreparedTxMeta;
+}
+interface TxResultMeta extends PreparedTxMeta {
+    /**
+     * Populated on `placeOrder.execute({ waitForReceipt: true })` — the orderId
+     * parsed from the `OrderPlaced` event in the receipt's logs. Undefined when
+     * `waitForReceipt` is not set (no receipt means no logs to parse).
+     */
+    readonly orderId?: bigint;
+}
+interface TxResult {
+    readonly hash: `0x${string}`;
+    readonly receipt?: TransactionReceipt;
+    readonly meta?: TxResultMeta;
+}
+interface ExecuteBase {
+    readonly walletClient: WalletClient;
+    readonly waitForReceipt?: boolean;
+}
+type OrderEvent = {
+    readonly type: "placed";
+    readonly orderId: bigint;
+    readonly user: Address;
+    readonly orderType: 0 | 1 | 2;
+    readonly blockNumber: bigint;
+    readonly txHash: `0x${string}`;
+} | {
+    readonly type: "accepted";
+    readonly orderId: bigint;
+    readonly merchant: Address;
+    readonly blockNumber: bigint;
+    readonly txHash: `0x${string}`;
+} | {
+    readonly type: "paid";
+    readonly orderId: bigint;
+    readonly blockNumber: bigint;
+    readonly txHash: `0x${string}`;
+} | {
+    readonly type: "completed";
+    readonly orderId: bigint;
+    readonly blockNumber: bigint;
+    readonly txHash: `0x${string}`;
+} | {
+    readonly type: "cancelled";
+    readonly orderId: bigint;
+    readonly blockNumber: bigint;
+    readonly txHash: `0x${string}`;
+};
+
+interface ApproveUsdcAction {
+    prepare(params: ApproveUsdcParams): ResultAsync<PreparedTx, OrdersError>;
+    execute(params: ApproveUsdcParams & ExecuteBase): ResultAsync<TxResult, OrdersError>;
+}
+
+interface CancelOrderAction {
+    prepare(params: CancelOrderParams): ResultAsync<PreparedTx, OrdersError>;
+    execute(params: CancelOrderParams & ExecuteBase): ResultAsync<TxResult, OrdersError>;
+}
+
+interface PaidBuyOrderAction {
+    prepare(params: PaidBuyOrderParams): ResultAsync<PreparedTx, OrdersError>;
+    execute(params: PaidBuyOrderParams & ExecuteBase): ResultAsync<TxResult, OrdersError>;
+}
+
+interface PlaceOrderAction {
+    prepare(params: PlaceOrderParams): ResultAsync<PreparedTx, OrdersError>;
+    execute(params: PlaceOrderParams & ExecuteBase): ResultAsync<TxResult, OrdersError>;
+}
+
+interface RaiseDisputeAction {
+    prepare(params: RaiseDisputeParams): ResultAsync<PreparedTx, OrdersError>;
+    execute(params: RaiseDisputeParams & ExecuteBase): ResultAsync<TxResult, OrdersError>;
+}
+
+interface SetSellOrderUpiAction {
+    prepare(params: SetSellOrderUpiParams): ResultAsync<PreparedTx, OrdersError>;
+    execute(params: SetSellOrderUpiParams & ExecuteBase): ResultAsync<TxResult, OrdersError>;
+}
+
+interface WatchEventsParams {
+    readonly user?: Address;
+    readonly onEvent: (event: OrderEvent) => void;
+    readonly onError?: (error: OrdersError) => void;
+}
+type WatchEvents = (params: WatchEventsParams) => () => void;
+
+interface OrdersClient {
+    /** Reads a single order by id from the Diamond contract. */
+    getOrder(params: GetOrderParams): ResultAsync<Order, OrdersError>;
+    /**
+     * Lists orders created by `userAddress` from the subgraph, newest first.
+     * Defaults: `skip = 0`, `limit = 20`. Max `limit` is 100.
+     */
+    getOrders(params: GetOrdersParams): ResultAsync<Order[], OrdersError>;
+    /**
+     * Reads the per-currency small-order fee config from the Diamond via
+     * multicall: threshold (below which the fixed fee applies) and the fixed
+     * fee itself. Both are 6-decimal bigints.
+     */
+    getFeeConfig(params: GetFeeConfigParams): ResultAsync<FeeConfig, OrdersError>;
+    readonly placeOrder: PlaceOrderAction;
+    readonly cancelOrder: CancelOrderAction;
+    readonly setSellOrderUpi: SetSellOrderUpiAction;
+    readonly raiseDispute: RaiseDisputeAction;
+    readonly approveUsdc: ApproveUsdcAction;
+    readonly paidBuyOrder: PaidBuyOrderAction;
+    watchEvents: WatchEvents;
+    /**
+     * Decrypts an `encUpi` / `encMerchantUpi` ciphertext from an order using the
+     * relay identity resolved from the configured store. Returns the plaintext
+     * payment address.
+     */
+    decryptPaymentAddress(params: {
+        encrypted: string;
+    }): ResultAsync<string, OrdersError>;
+    /**
+     * Signs `paymentAddress` with the resolved relay identity and ECIES-encrypts
+     * the payload for `recipientPublicKey`. Returns the hex-stringified ciphertext
+     * suitable for on-chain storage (e.g. as the merchant's encUpi when calling
+     * `setSellOrderUpi`).
+     */
+    encryptPaymentAddress(params: {
+        paymentAddress: string;
+        recipientPublicKey: string;
+    }): ResultAsync<string, OrdersError>;
+}
+/**
+ * Creates the unified orders client — reads (getOrder, getOrders, getFeeConfig)
+ * and circle-routing-backed writes (placeOrder, cancelOrder, setSellOrderUpi,
+ * raiseDispute, approveUsdc). The relay identity store defaults to in-memory
+ * when none is supplied.
+ *
+ * For USDC balance / allowance reads use `@p2pdotme/sdk/profile` (those are
+ * user-scoped and live there).
+ */
+declare function createOrders(config: OrdersConfig): OrdersClient;
+
+interface Encrypted {
+    readonly iv: string;
+    readonly ephemPublicKey: string;
+    readonly ciphertext: string;
+    readonly mac: string;
+}
+/**
+ * Serializes an Encrypted object to a compact hex string.
+ * Format: IV (16 bytes) || compressed ephemPublicKey (33 bytes) || MAC (32 bytes) || ciphertext.
+ */
+declare function cipherStringify(encrypted: Encrypted): string;
+/**
+ * Parses a compact hex string back into an Encrypted object.
+ * Inverse of cipherStringify.
+ */
+declare function cipherParse(str: string): Encrypted;
+
+interface EncryptPaymentAddressInput {
+    readonly paymentAddress: string;
+    readonly recipientPublicKey: string;
+    readonly senderIdentity: RelayIdentity;
+}
+/**
+ * Signs `paymentAddress` with the sender relay identity's private key, then
+ * ECIES-encrypts the `{ message, signature }` payload for the recipient. Returns
+ * the hex-stringified ciphertext suitable for on-chain storage.
+ */
+declare function encryptPaymentAddress(input: EncryptPaymentAddressInput): ResultAsync<string, OrdersError>;
+interface DecryptPaymentAddressInput {
+    readonly encrypted: string;
+    readonly recipientIdentity: RelayIdentity;
+}
+/**
+ * Decrypts a ciphertext produced by `encryptPaymentAddress` using the recipient
+ * relay identity's private key. Returns the plaintext payment address.
+ */
+declare function decryptPaymentAddress(input: DecryptPaymentAddressInput): ResultAsync<string, OrdersError>;
+
+export { type ApproveUsdcParams, type CancelOrderParams, type DisputeStatus, type ExecuteBase, type FeeConfig, type GetFeeConfigParams, type GetOrderParams, type GetOrdersParams, type Order, type OrderEvent, type OrderStatus, type OrderType, type OrdersClient, type OrdersConfig, OrdersError, type OrdersErrorCode, type PaidBuyOrderAction, type PaidBuyOrderParams, type PlaceOrderParams, type PreparedTx, type PreparedTxMeta, type RaiseDisputeParams, type RelayIdentity, type RelayIdentityStore, type SetSellOrderUpiParams, type TxResult, type TxResultMeta, type WatchEventsParams, cipherParse, cipherStringify, createInMemoryRelayStore, createLocalStorageRelayStore, createOrders, createRelayIdentity, decryptPaymentAddress, encryptPaymentAddress };