@rozoai/intent-common 0.1.0-beta.2 → 0.1.0-beta.3

package/src/api/payment.ts

@@ -1,104 +1,273 @@
-import { createPaymentBridgeConfig } from "../bridge";
+import { createPaymentBridgeConfig } from "../bridge-utils";
+import { getChainById } from "../chain";
+import { getKnownToken } from "../token";
 import { apiClient, ApiResponse } from "./base";
-import { DisplayInfo } from "./new-payment";
 
 /**
- * Payment display information
+ * FeeType, Fee calculation type:
+ * - exactIn (default): Fee deducted from input, recipient receives amount - fee
+ * - exactOut: Fee added to input, recipient receives exact amount
  */
-export interface PaymentDisplay {
-  intent: string;
-  paymentValue: string;
-  currency: string;
+export enum FeeType {
+  ExactIn = "exactIn",
+  ExactOut = "exactOut",
 }
 
 /**
- * Payment destination information
+ * PaymentStatus, Payment status
  */
-export interface PaymentDestination {
-  destinationAddress?: string;
-  chainId: string;
-  amountUnits: string;
-  tokenSymbol: string;
+export enum PaymentStatus {
+  PaymentBounced = "payment_bounced",
+  PaymentCompleted = "payment_completed",
+  PaymentExpired = "payment_expired",
+  PaymentPayinCompleted = "payment_payin_completed",
+  PaymentPayoutCompleted = "payment_payout_completed",
+  PaymentRefunded = "payment_refunded",
+  PaymentStarted = "payment_started",
+  PaymentUnpaid = "payment_unpaid",
+}
+
+/**
+ * PaymentErrorCode, Error code (only present when status is payment_bounced)
+ */
+export enum PaymentErrorCode {
+  AmountTooHigh = "amountTooHigh",
+  AmountTooLow = "amountTooLow",
+  ChainUnavailable = "chainUnavailable",
+  InsufficientLiquidity = "insufficientLiquidity",
+  InvalidRecipient = "invalidRecipient",
+  MissingTrustline = "missingTrustline",
+  NetworkError = "networkError",
+  ProviderError = "providerError",
+  ServiceMaintenance = "serviceMaintenance",
+}
+
+/**
+ * DestinationRequest
+ */
+export interface DestinationRequest {
+  /**
+   * Receive amount (required for type=exactOut).
+   * For exactIn, this field is omitted in request and calculated in response.
+   */
+  amount?: string;
+  chainId: number;
+  /**
+   * Final recipient's wallet address
+   */
+  receiverAddress: string;
+  /**
+   * Memo for Stellar/Solana destinations
+   */
+  receiverMemo?: string;
+  /**
+   * Override default token address
+   */
   tokenAddress?: string;
-  txHash?: string | null;
+  tokenSymbol: string;
+  [property: string]: any;
 }
 
 /**
- * Payment source information
+ * DisplayInfo
  */
-export interface PaymentSource {
-  sourceAddress?: string;
-  [key: string]: unknown;
+export interface DisplayInfo {
+  /**
+   * Display currency
+   */
+  currency: string;
+  /**
+   * Detailed description
+   */
+  description?: string;
+  /**
+   * Short title
+   */
+  title: string;
+  [property: string]: any;
 }
 
 /**
- * Payment request data type
+ * SourceRequest
  */
-export interface PaymentRequestData {
+export interface SourceRequest {
+  /**
+   * Pay-in amount (required for type=exactIn).
+   * For exactOut, this field is omitted in request and calculated in response.
+   */
+  amount?: string;
+  chainId: number;
+  /**
+   * Override default token address
+   */
+  tokenAddress?: string;
+  tokenSymbol: string;
+  [property: string]: any;
+}
+
+/**
+ * PaymentRequest
+ */
+export interface CreatePaymentRequest {
+  /**
+   * Your application ID
+   */
   appId: string;
-  display: PaymentDisplay;
-  destination: PaymentDestination;
-  externalId?: string;
-  metadata?: Record<string, unknown>;
-  [key: string]: unknown;
+  destination: DestinationRequest;
+  display: DisplayInfo;
+  /**
+   * Custom metadata (max 4 KB recommended)
+   */
+  metadata?: { [key: string]: any };
+  /**
+   * Your order reference ID (for idempotency)
+   */
+  orderId?: string;
+  source: SourceRequest;
+  type?: FeeType;
+  /**
+   * Secret for HMAC-SHA256 signature verification.
+   * If not provided, a unique secret is auto-generated.
+   * The secret is returned in the response for you to store and use for verification.
+   */
+  webhookSecret?: string;
+  /**
+   * URL to receive payment status updates
+   */
+  webhookUrl?: string;
+  [property: string]: any;
 }
 
 /**
- * Payment response data type
+ * DestinationResponse
  */
-export interface PaymentResponseData {
+export interface DestinationResponse {
+  /**
+   * Amount to be sent to recipient
+   */
+  amount?: string;
+  chainId?: number;
+  /**
+   * Withdrawal confirmation time
+   */
+  confirmedAt?: Date;
+  /**
+   * Final recipient's wallet
+   */
+  receiverAddress?: string;
+  /**
+   * Memo for Stellar/Solana
+   */
+  receiverMemo?: string;
+  /**
+   * Token contract address
+   */
+  tokenAddress?: string;
+  tokenSymbol?: string;
+  /**
+   * Withdrawal transaction hash
+   */
+  txHash?: string;
+  [property: string]: any;
+}
+
+/**
+ * SourceResponse
+ */
+export interface SourceResponse {
+  /**
+   * Amount payer must send
+   */
+  amount?: string;
+  /**
+   * Actual amount received
+   */
+  amountReceived?: string;
+  chainId?: number;
+  /**
+   * Deposit confirmation time
+   */
+  confirmedAt?: Date;
+  /**
+   * Fee amount
+   */
+  fee?: string;
+  /**
+   * Deposit address (where payer sends funds)
+   */
+  receiverAddress?: string;
+  /**
+   * Memo for Stellar/Solana deposits
+   */
+  receiverMemo?: string;
+  /**
+   * Payer's wallet address (populated after deposit)
+   */
+  senderAddress?: string;
+  /**
+   * Token contract address
+   */
+  tokenAddress?: string;
+  tokenSymbol?: string;
+  /**
+   * Deposit transaction hash
+   */
+  txHash?: string;
+  [property: string]: any;
+}
+
+/**
+ * PaymentResponse
+ */
+export interface PaymentResponse {
+  /**
+   * Your application ID
+   */
+  appId: string;
+  /**
+   * ISO 8601 timestamp
+   */
+  createdAt: Date;
+  destination: DestinationResponse;
+  display: DisplayInfo;
+  errorCode: PaymentErrorCode | null;
+  /**
+   * ISO 8601 timestamp (when payment expires)
+   */
+  expiresAt: Date;
+  /**
+   * Payment ID
+   */
   id: string;
-  status: "payment_unpaid" | string;
-  createdAt: string;
-  updatedAt: string;
-  expiresAt: string;
-  display:
-    | {
-        intent: string;
-        currency: string;
-        paymentValue?: string;
-      }
-    | DisplayInfo;
-  source: PaymentSource | null;
-  destination: {
-    destinationAddress: string;
-    txHash: string | null;
-    chainId: string;
-    amountUnits: string;
-    tokenSymbol: string;
-    tokenAddress: string;
-  };
-  metadata: {
-    daimoOrderId?: string;
-    intent: string;
-    items: unknown[];
-    payer: Record<string, unknown>;
-    appId: string;
-    orderDate: string;
-    webhookUrl: string;
-    provider: string;
-    receivingAddress: string;
-    memo: string | null;
-    payinchainid: string;
-    payintokenaddress: string;
-    preferredChain: string;
-    preferredToken: string;
-    preferredTokenAddress: string;
-    source_tx_hash?: string;
-    [key: string]: unknown;
-  };
-  url: string;
-  [key: string]: unknown;
+  metadata: { [key: string]: any } | null;
+  /**
+   * Your order reference ID
+   */
+  orderId: string | null;
+  source: SourceResponse;
+  status: PaymentStatus;
+  type: FeeType;
+  /**
+   * ISO 8601 timestamp
+   */
+  updatedAt: Date;
+  /**
+   * Secret for webhook signature verification.
+   * Only present when webhookUrl was provided in the request.
+   * Store this securely to verify incoming webhook signatures.
+   */
+  webhookSecret: string | null;
+  [property: string]: any;
 }
 
 /**
- * Simplified interface for creating a payment bridge
+ * Parameters for creating a new payment using the new backend interface
  */
-export interface CreatePaymentBridgeParams {
+export interface CreateNewPaymentParams {
   /** App ID for authentication */
   appId: string;
   // Destination (where funds will be received)
-  /** Destination chain ID (e.g., 8453 for Base, 900 for Solana, 10001 for Stellar) */
+  /** Destination chain ID (e.g., 8453 for Base, 900 for Solana, 1500 for Stellar) */
   toChain: number;
   /** Destination token address */
   toToken: string;
@@ -115,111 +284,53 @@ export interface CreatePaymentBridgeParams {
   /** Amount in human-readable units (e.g., "1" for 1 USDC, "0.5" for half a USDC) */
   toUnits?: string;
 
-  // Optional metadata
+  // Optional fields
   /** Additional metadata to include */
   metadata?: Record<string, unknown>;
+  /** Display title for the payment */
+  title?: string;
+  /** Display description for the payment */
+  description?: string;
+  /** Order reference ID (for idempotency) */
+  orderId?: string;
+  /** Fee calculation type (exactIn or exactOut) */
+  type?: FeeType;
+  /** Webhook URL to receive payment status updates */
+  webhookUrl?: string;
+  /** Secret for HMAC-SHA256 signature verification */
+  webhookSecret?: string;
+  /** Memo for Stellar/Solana destinations */
+  receiverMemo?: string;
 }
 
 /**
- * Gets payment details by ID
- * @param paymentId - Payment ID
- * @returns Promise with payment response
- */
-export const getRozoPayment = (
-  paymentId: string
-): Promise<ApiResponse<PaymentResponseData>> => {
-  const isMugglePay = paymentId.includes("mugglepay_order");
-  const endpoint = isMugglePay
-    ? `payment-api/${paymentId}`
-    : `payment/id/${paymentId}`;
-  return apiClient.get<PaymentResponseData>(endpoint);
-};
-
-/**
- * Creates a payment bridge configuration and initiates a Rozo payment
+ * Creates a payment using the new backend interface
  *
- * This function combines the payment bridge configuration logic with payment creation,
- * handling cross-chain payment routing and metadata merging. It provides a simplified
- * API that doesn't require understanding internal types like WalletPaymentOption.
+ * This function creates a payment using the new backend API structure with
+ * separate source and destination objects, enum-based chain IDs and token symbols.
  *
- * @param params - Payment bridge creation parameters
+ * @param params - Payment creation parameters
  * @returns Promise resolving to the payment response data
  * @throws Error if payment creation fails or required parameters are missing
  *
  * @example
  * ```typescript
  * // Simple same-chain payment
- * const payment = await createPaymentBridge({
+ * const payment = await createPayment({
  *   toChain: 8453, // Base
  *   toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
  *   toAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
- *   preferredChainId: 8453, // User pays from Base
- *   preferredToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
+ *   preferredChain: 8453, // User pays from Base
+ *   preferredTokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
  *   toUnits: "1", // 1 USDC
  *   appId: "my-app-id",
- *   intent: "Pay",
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Cross-chain payment: Polygon to Base
- * const payment = await createPaymentBridge({
- *   toChain: 8453, // Base (destination)
- *   toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
- *   toAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
- *   preferredChainId: 137, // Polygon (user pays from)
- *   preferredToken: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174", // Polygon USDC
- *   toUnits: "1",
- *   appId: "my-app-id",
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Payment to Solana address (payout → Solana)
- * const payment = await createPaymentBridge({
- *   toChain: 900, // Solana
- *   toToken: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Solana USDC
- *   toAddress: "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU", // Solana address
- *   preferredChainId: 8453, // User pays from Base
- *   preferredToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
- *   toUnits: "1",
- *   appId: "my-app-id",
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Payment paid in from Stellar account
- * const payment = await createPaymentBridge({
- *   toChain: 8453, // Payout on Base
- *   toToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
- *   toAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", // EVM address
- *   preferredChainId: 1500, // Pay in from Stellar
- *   preferredToken: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", // Stellar USDC (token format: code:issuer)
- *   toUnits: "10",
- *   appId: "my-app-id",
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Payment paying out to Stellar address (payout → Stellar)
- * const payment = await createPaymentBridge({
- *   toChain: 1500, // Stellar
- *   toToken: "USDC:GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", // Stellar USDC (token format: code:issuer)
- *   toAddress: "GA5ZSEPRY3STUGUUXZGHV5CDEQ2AJGEAAUUMSZK2QIPICFL2JVP4X6T4", // Stellar address
- *   preferredChainId: 8453, // User pays from Base
- *   preferredToken: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // Base USDC
- *   toUnits: "1",
- *   appId: "my-app-id",
+ *   title: "Payment",
  * });
  * ```
  */
-export async function createRozoPayment(
-  params: CreatePaymentBridgeParams
-): Promise<PaymentResponseData> {
+export async function createPayment(
+  params: CreateNewPaymentParams
+): Promise<PaymentResponse> {
   const {
     toChain,
     toToken,
@@ -229,36 +340,76 @@ export async function createRozoPayment(
     toUnits,
     appId,
     metadata,
+    title,
+    description,
+    orderId,
+    type,
+    webhookUrl,
+    webhookSecret,
+    receiverMemo,
   } = params;
+
   // Create payment bridge configuration
-  const { preferred, destination, isIntentPayment } = createPaymentBridgeConfig(
-    {
-      toChain,
-      toToken,
-      toAddress,
-      toUnits: toUnits ?? "0",
-      // Preferred payment method (what user will pay with)
-      preferredChain,
-      preferredTokenAddress,
-    }
+  const { preferred, destination } = createPaymentBridgeConfig({
+    toChain,
+    toToken,
+    toAddress,
+    toUnits: toUnits ?? "0",
+    // Preferred payment method (what user will pay with)
+    preferredChain,
+    preferredTokenAddress,
+  });
+
+  const sourceChain = getChainById(Number(preferred.preferredChain));
+  const sourceToken = getKnownToken(
+    Number(preferred.preferredChain),
+    preferred.preferredTokenAddress
+  );
+  const destinationChain = getChainById(Number(destination.chainId));
+  const destinationToken = getKnownToken(
+    Number(destination.chainId),
+    destination.tokenAddress
   );
 
-  // Build payment request data
-  const paymentData: PaymentRequestData = {
+  if (!sourceToken || !destinationToken) {
+    throw new Error("Source or destination token not found");
+  }
+
+  // Build payment request data matching new backend interface
+  const paymentData: CreatePaymentRequest = {
     appId,
+    type: type ?? FeeType.ExactIn,
+    ...(orderId ? { orderId } : {}),
+    source: {
+      chainId: sourceChain.chainId,
+      tokenSymbol: sourceToken.symbol,
+      amount: destination.amountUnits, // Use same amount for source
+      ...(preferred.preferredTokenAddress
+        ? { tokenAddress: preferred.preferredTokenAddress }
+        : {}),
+    },
+    destination: {
+      chainId: destinationChain.chainId,
+      receiverAddress: destination.destinationAddress ?? toAddress,
+      tokenSymbol: destinationToken.symbol,
+      amount: destination.amountUnits,
+      ...(destination.tokenAddress
+        ? { tokenAddress: destination.tokenAddress }
+        : {}),
+      ...(receiverMemo ? { receiverMemo } : {}),
+    },
     display: {
-      intent: "",
-      paymentValue: String(toUnits ?? ""),
       currency: "USD",
+      title: title ?? "Pay",
+      ...(description ? { description } : {}),
     },
-    destination,
-    ...preferred,
-    ...(metadata ?? {}),
-    ...(isIntentPayment ? { intents: true } : {}),
+    ...(metadata ? { metadata } : {}),
+    ...(webhookUrl ? { webhookUrl } : {}),
+    ...(webhookSecret ? { webhookSecret } : {}),
   };
 
   // Create payment via API
-  const response = await apiClient.post<PaymentResponseData>(
+  const response = await apiClient.post<PaymentResponse>(
     "/payment-api",
     paymentData
   );
@@ -269,3 +420,14 @@ export async function createRozoPayment(
 
   return response.data;
 }
+
+/**
+ * Gets payment details by ID using the new backend API
+ * @param paymentId - Payment ID
+ * @returns Promise with payment response
+ */
+export const getPayment = (
+  paymentId: string
+): Promise<ApiResponse<PaymentResponse>> => {
+  return apiClient.get<PaymentResponse>(`/payment-api/payments/${paymentId}`);
+};