@rozoai/intent-common 0.0.28-beta.2 → 0.0.28-beta.4

package/src/api/base.ts

@@ -0,0 +1,215 @@
+/**
+ * RozoAI API Configuration Constants
+ */
+export const ROZO_API_URL = "https://intentapiv2.rozo.ai/functions/v1";
+export const ROZO_API_TOKEN =
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImZ4Y3Zmb2xobmNtdXZmYXp1cXViIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTI4Mzg2NjYsImV4cCI6MjA2ODQxNDY2Nn0.B4dV5y_-zCMKSNm3_qyCbAvCPJmoOGv_xB783LfAVUA";
+
+// HTTP methods type
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+
+// Request options type
+export interface RequestOptions {
+  method?: HttpMethod;
+  headers?: Record<string, string>;
+  body?: any;
+  params?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+// Response type with generic data
+export interface ApiResponse<T = any> {
+  data: T | null;
+  error: Error | null;
+  status: number | null;
+}
+
+// Request state for hooks (used in connectkit)
+export interface RequestState<T = any> extends ApiResponse<T> {
+  isLoading: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+}
+
+/**
+ * API Configuration
+ */
+export interface ApiConfig {
+  baseUrl: string;
+  apiToken: string;
+}
+
+// Default configuration (can be overridden via setApiConfig)
+let apiConfig: ApiConfig = {
+  baseUrl: ROZO_API_URL,
+  apiToken: ROZO_API_TOKEN,
+};
+
+/**
+ * Set API configuration
+ * @param config - API configuration
+ */
+export const setApiConfig = (config: Partial<ApiConfig>) => {
+  apiConfig = { ...apiConfig, ...config };
+};
+
+/**
+ * Get current API configuration
+ * @returns Current API configuration
+ */
+export const getApiConfig = (): ApiConfig => {
+  return apiConfig;
+};
+
+/**
+ * Creates a URL with query parameters
+ * @param url - Base URL
+ * @param params - Query parameters
+ * @returns Full URL with query parameters
+ */
+const createUrl = (url: string, params?: Record<string, string>): string => {
+  const fullUrl = url.startsWith("/")
+    ? `${apiConfig.baseUrl}${url}`
+    : `${apiConfig.baseUrl}/${url}`;
+
+  if (!params) return fullUrl;
+
+  const queryParams = new URLSearchParams();
+  Object.entries(params).forEach(([key, value]) => {
+    if (value !== undefined && value !== null) {
+      queryParams.append(key, value);
+    }
+  });
+
+  const queryString = queryParams.toString();
+  return queryString ? `${fullUrl}?${queryString}` : fullUrl;
+};
+
+/**
+ * Core fetch function for making API requests
+ * @param url - API endpoint path
+ * @param options - Request options
+ * @returns Promise with response data
+ */
+export const fetchApi = async <T = any>(
+  url: string,
+  options: RequestOptions = {}
+): Promise<ApiResponse<T>> => {
+  const { method = "GET", headers = {}, body, params, signal } = options;
+
+  try {
+    const fullUrl = createUrl(url, params);
+
+    const requestHeaders: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...headers,
+      Authorization: `Bearer ${apiConfig.apiToken}`,
+    };
+
+    const requestOptions: {
+      method: string;
+      headers: Record<string, string>;
+      signal?: AbortSignal;
+      body?: string;
+    } = {
+      method,
+      headers: requestHeaders,
+      signal,
+    };
+
+    if (body && method !== "GET") {
+      requestOptions.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(fullUrl, requestOptions);
+    const status = response.status;
+
+    // Handle non-JSON responses
+    const contentType = response.headers.get("content-type");
+    let data: T | null = null;
+
+    if (contentType && contentType.includes("application/json")) {
+      data = (await response.json()) as T;
+    } else if (contentType && contentType.includes("text/")) {
+      data = (await response.text()) as unknown as T;
+    }
+
+    if (!response.ok) {
+      throw new Error(data ? JSON.stringify(data) : response.statusText);
+    }
+
+    return { data, error: null, status };
+  } catch (error) {
+    return {
+      data: null,
+      error: error instanceof Error ? error : new Error(String(error)),
+      status: null,
+    };
+  }
+};
+
+/**
+ * API client with methods for different HTTP verbs
+ */
+export const apiClient = {
+  /**
+   * GET request
+   * @param url - API endpoint path
+   * @param options - Request options
+   * @returns Promise with response data
+   */
+  get: <T = any>(
+    url: string,
+    options: Omit<RequestOptions, "method" | "body"> = {}
+  ) => fetchApi<T>(url, { ...options, method: "GET" }),
+
+  /**
+   * POST request
+   * @param url - API endpoint path
+   * @param body - Request body
+   * @param options - Additional request options
+   * @returns Promise with response data
+   */
+  post: <T = any>(
+    url: string,
+    body: any,
+    options: Omit<RequestOptions, "method" | "body"> = {}
+  ) => fetchApi<T>(url, { ...options, method: "POST", body }),
+
+  /**
+   * PUT request
+   * @param url - API endpoint path
+   * @param body - Request body
+   * @param options - Additional request options
+   * @returns Promise with response data
+   */
+  put: <T = any>(
+    url: string,
+    body: any,
+    options: Omit<RequestOptions, "method" | "body"> = {}
+  ) => fetchApi<T>(url, { ...options, method: "PUT", body }),
+
+  /**
+   * PATCH request
+   * @param url - API endpoint path
+   * @param body - Request body
+   * @param options - Additional request options
+   * @returns Promise with response data
+   */
+  patch: <T = any>(
+    url: string,
+    body: any,
+    options: Omit<RequestOptions, "method" | "body"> = {}
+  ) => fetchApi<T>(url, { ...options, method: "PATCH", body }),
+
+  /**
+   * DELETE request
+   * @param url - API endpoint path
+   * @param options - Request options
+   * @returns Promise with response data
+   */
+  delete: <T = any>(
+    url: string,
+    options: Omit<RequestOptions, "method"> = {}
+  ) => fetchApi<T>(url, { ...options, method: "DELETE" }),
+};

package/src/api/payment.ts

@@ -0,0 +1,112 @@
+import { apiClient, ApiResponse } from "./base";
+
+/**
+ * Payment display information
+ */
+export interface PaymentDisplay {
+  intent: string;
+  paymentValue: string;
+  currency: string;
+}
+
+/**
+ * Payment destination information
+ */
+export interface PaymentDestination {
+  destinationAddress?: string;
+  chainId: string;
+  amountUnits: string;
+  tokenSymbol: string;
+  tokenAddress?: string;
+  txHash?: string | null;
+}
+
+/**
+ * Payment source information
+ */
+export interface PaymentSource {
+  sourceAddress?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Payment request data type
+ */
+export interface PaymentRequestData {
+  appId: string;
+  display: PaymentDisplay;
+  destination: PaymentDestination;
+  externalId?: string;
+  metadata?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * Payment response data type
+ */
+export interface PaymentResponseData {
+  id: string;
+  status: "payment_unpaid" | string;
+  createdAt: string;
+  display: {
+    intent: string;
+    currency: string;
+    paymentValue?: string;
+  };
+  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;
+}
+
+/**
+ * Creates a new payment
+ * @param paymentData - Payment data to send
+ * @returns Promise with payment response
+ */
+export const createRozoPayment = (
+  paymentData: PaymentRequestData
+): Promise<ApiResponse<PaymentResponseData>> => {
+  return apiClient.post<PaymentResponseData>("/payment-api", paymentData);
+};
+
+/**
+ * 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);
+};

package/src/bridge.ts

@@ -0,0 +1,382 @@
+import { parseUnits } from "viem";
+import {
+  base,
+  baseUSDC,
+  bscUSDT,
+  getKnownToken,
+  polygonUSDC,
+  RozoPayHydratedOrderWithOrg,
+  RozoPayIntentStatus,
+  RozoPayOrderMode,
+  RozoPayOrderStatusDest,
+  RozoPayOrderStatusSource,
+  RozoPayUserMetadata,
+  rozoSolanaUSDC,
+  rozoStellar,
+  rozoStellarUSDC,
+} from ".";
+import type { PaymentResponseData } from "./api/payment";
+
+export interface PaymentBridgeConfig {
+  toChain?: number;
+  toToken?: string;
+  toAddress: string;
+  toStellarAddress?: string;
+  toSolanaAddress?: string;
+  toUnits: string;
+  payInTokenAddress: string;
+  log?: (msg: string) => void;
+}
+
+export interface PreferredPaymentConfig {
+  preferredChain: string;
+  preferredToken: "USDC" | "USDT" | "XLM";
+  preferredTokenAddress?: string;
+}
+
+export interface DestinationConfig {
+  destinationAddress?: string;
+  chainId: string;
+  amountUnits: string;
+  tokenSymbol: string;
+  tokenAddress: string;
+}
+
+/**
+ * Creates payment bridge configuration for cross-chain payment routing
+ *
+ * Determines the optimal payment routing based on the destination chain/token
+ * and the wallet payment option selected by the user. This function handles
+ * the complexity of multi-chain payments by:
+ *
+ * 1. **Preferred Payment Method**: Identifies which chain/token the user will pay from
+ *    - Supports Base USDC, Polygon USDC, Solana USDC, Stellar USDC, and BSC USDT
+ *    - Sets appropriate chain ID and token address for the source transaction
+ *
+ * 2. **Destination Configuration**: Determines where funds will be received
+ *    - Supports Base, Solana, and Stellar as destination chains
+ *    - Handles special address formats for Solana and Stellar addresses
+ *    - Defaults to Base USDC when no special destination is specified
+ *
+ * 3. **Cross-Chain Bridging**: Configures the payment bridge parameters
+ *    - Maps user's selected wallet/token to the appropriate payment method
+ *    - Sets up destination chain and token configuration
+ *    - Handles token address formatting (e.g., Stellar's `USDC:issuerPK` format)
+ *
+ * @param config - Payment bridge configuration parameters
+ * @param config.toChain - Destination chain ID (defaults to Base: 8453)
+ * @param config.toToken - Destination token address (defaults to Base USDC)
+ * @param config.toAddress - Standard EVM destination address
+ * @param config.toStellarAddress - Stellar-specific destination address (if paying to Stellar)
+ * @param config.toSolanaAddress - Solana-specific destination address (if paying to Solana)
+ * @param config.toUnits - Amount in token units (smallest denomination)
+ * @param config.payInTokenAddress - Token address user selected to pay with
+ * @param config.log - Optional logging function for debugging
+ *
+ * @returns Payment routing configuration
+ * @returns preferred - Source payment configuration (chain, token user will pay from)
+ * @returns destination - Destination payment configuration (chain, token user will receive)
+ *
+ * @example
+ * ```typescript
+ * // User wants to pay with Polygon USDC to receive on Base
+ * const { preferred, destination } = createPaymentBridgeConfig({
+ *   toChain: 8453, // Base
+ *   toToken: baseUSDC.token,
+ *   toAddress: '0x123...',
+ *   toUnits: '1000000', // 1 USDC
+ *   payInTokenAddress: polygonUSDC.token,
+ *   log: console.log
+ * });
+ *
+ * // preferred = { preferredChain: '137', preferredToken: 'USDC', preferredTokenAddress: '0x2791...' }
+ * // destination = { destinationAddress: '0x123...', chainId: '8453', amountUnits: '1000000', ... }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // User wants to pay to a Stellar address
+ * const { preferred, destination } = createPaymentBridgeConfig({
+ *   toStellarAddress: 'GDZS...',
+ *   toUnits: '1000000',
+ *   payInTokenAddress: baseUSDC.token,
+ * });
+ *
+ * // destination will be configured for Stellar chain with USDC:issuerPK format
+ * ```
+ *
+ * @note Currently only supports Base USDC and Stellar USDC as destination chains.
+ *       Support for additional destination chains is planned.
+ *
+ * @see PreferredPaymentConfig
+ * @see DestinationConfig
+ */
+export function createPaymentBridgeConfig({
+  toChain = baseUSDC.chainId,
+  toToken = baseUSDC.token,
+  toAddress,
+  toStellarAddress,
+  toSolanaAddress,
+  toUnits,
+  payInTokenAddress,
+  log,
+}: PaymentBridgeConfig): {
+  preferred: PreferredPaymentConfig;
+  destination: DestinationConfig;
+} {
+  // Default configuration for Base USDC payments
+  let preferred: PreferredPaymentConfig = {
+    preferredChain: String(toChain),
+    preferredToken: "USDC",
+  };
+
+  let destination: DestinationConfig = {
+    destinationAddress: toAddress,
+    chainId: String(toChain),
+    amountUnits: toUnits,
+    tokenSymbol: "USDC",
+    tokenAddress: toToken,
+  };
+
+  /**
+   * IMPORTANT: Because we only support PAY OUT USDC BASE & STELLAR
+   * So, We force toChain and toToken to Base USDC as default PayParams
+   *
+   * @TODO: Adjust this when we support another PAY OUT chain
+   */
+  if (toChain === base.chainId && toToken === baseUSDC.token) {
+    // Determine preferred payment method based on wallet selection
+    if (payInTokenAddress) {
+      // Pay In USDC Polygon
+      if (payInTokenAddress === polygonUSDC.token) {
+        log?.(`[Payment Bridge] Pay In USDC Polygon`);
+        preferred = {
+          preferredChain: String(polygonUSDC.chainId),
+          preferredToken: "USDC",
+          preferredTokenAddress: polygonUSDC.token,
+        };
+      }
+      // Pay In USDC Solana
+      else if (payInTokenAddress === rozoSolanaUSDC.token) {
+        log?.(`[Payment Bridge] Pay In USDC Solana`);
+        preferred = {
+          preferredChain: String(rozoSolanaUSDC.chainId),
+          preferredToken: "USDC",
+          preferredTokenAddress: rozoSolanaUSDC.token,
+        };
+      }
+      // Pay In USDC Stellar
+      else if (payInTokenAddress === rozoStellarUSDC.token) {
+        log?.(`[Payment Bridge] Pay In USDC Stellar`);
+        preferred = {
+          preferredChain: String(rozoStellarUSDC.chainId),
+          preferredToken: "USDC",
+          preferredTokenAddress: `USDC:${rozoStellarUSDC.token}`,
+        };
+      }
+      // Pay In USDT BSC
+      else if (payInTokenAddress === bscUSDT.token) {
+        log?.(`[Payment Bridge] Pay In USDT BSC`);
+        preferred = {
+          preferredChain: String(bscUSDT.chainId),
+          preferredToken: "USDT",
+          preferredTokenAddress: bscUSDT.token,
+        };
+      }
+    }
+
+    // Determine destination based on special address types
+    if (toStellarAddress) {
+      log?.(`[Payment Bridge] Pay Out USDC Stellar`);
+      destination = {
+        destinationAddress: toStellarAddress,
+        chainId: String(rozoStellar.chainId),
+        amountUnits: toUnits,
+        tokenSymbol: "USDC",
+        tokenAddress: `USDC:${rozoStellarUSDC.token}`,
+      };
+    } else if (toSolanaAddress) {
+      log?.(`[Payment Bridge] Pay Out USDC Solana`);
+      destination = {
+        destinationAddress: toSolanaAddress,
+        chainId: String(rozoSolanaUSDC.chainId),
+        amountUnits: toUnits,
+        tokenSymbol: "USDC",
+        tokenAddress: rozoSolanaUSDC.token,
+      };
+    } else {
+      log?.(`[Payment Bridge] Pay Out USDC Base`);
+      // Keep default Base configuration
+    }
+  }
+
+  return { preferred, destination };
+}
+
+/**
+ * Transforms a payment API response into a fully hydrated order object
+ *
+ * Converts the payment response data from the RozoAI payment API into a complete
+ * `RozoPayHydratedOrderWithOrg` object that contains all the information needed
+ * to display order status, track payments, and handle cross-chain transactions.
+ *
+ * This function performs several key transformations:
+ *
+ * 1. **Token Resolution**: Identifies the correct token based on chain and address
+ *    - Uses `getKnownToken()` to resolve token metadata (decimals, symbol, logo, etc.)
+ *    - Handles special cases for Stellar tokens using issuer public key
+ *
+ * 2. **Order Structure**: Creates a complete order with all required fields
+ *    - Generates random order ID for internal tracking
+ *    - Sets up intent, handoff, and contract addresses
+ *    - Configures bridge token options and destination amounts
+ *
+ * 3. **Status Initialization**: Sets initial payment statuses
+ *    - Source status: WAITING_PAYMENT (awaiting user transaction)
+ *    - Destination status: PENDING (not yet received)
+ *    - Intent status: UNPAID (payment not initiated)
+ *
+ * 4. **Metadata Merge**: Combines various metadata sources
+ *    - Merges order metadata, user metadata, and custom metadata
+ *    - Preserves external ID and organization information
+ *
+ * @param order - Payment response data from the RozoAI payment API
+ * @param order.metadata - Payment metadata including chain, token, and routing info
+ * @param order.destination - Destination configuration (chain, token, amount, address)
+ * @param order.source - Source transaction info (if payment has been initiated)
+ * @param order.orgId - Organization ID for the payment
+ * @param order.externalId - External reference ID (if provided by merchant)
+ *
+ * @returns Complete hydrated order object with all payment tracking information
+ * @returns id - Unique order identifier (random BigInt)
+ * @returns mode - Order mode (HYDRATED)
+ * @returns sourceStatus - Source transaction status
+ * @returns destStatus - Destination transaction status
+ * @returns intentStatus - Overall payment intent status
+ * @returns metadata - Merged metadata from all sources
+ * @returns org - Organization information
+ *
+ * @example
+ * ```typescript
+ * const paymentResponse = await getRozoPayment(paymentId);
+ *
+ * const hydratedOrder = formatPaymentResponseDataToHydratedOrder(
+ *   paymentResponse.data,
+ *   'GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN'
+ * );
+ *
+ * console.log(hydratedOrder.sourceStatus); // 'WAITING_PAYMENT'
+ * console.log(hydratedOrder.destFinalCallTokenAmount.token.symbol); // 'USDC'
+ * console.log(hydratedOrder.usdValue); // 10.00
+ * ```
+ *
+ * @note The generated order ID is random and intended for client-side tracking only.
+ *       Use `externalId` or the API payment ID for server-side reference.
+ *
+ * @note The function sets a 5-minute expiration timestamp from the current time.
+ *
+ * @see PaymentResponseData
+ * @see RozoPayHydratedOrderWithOrg
+ * @see getKnownToken
+ */
+export function formatResponseToHydratedOrder(
+  order: PaymentResponseData
+): RozoPayHydratedOrderWithOrg {
+  const destAddress = order.metadata.receivingAddress as `0x${string}`;
+
+  const requiredChain = order.metadata.preferredChain || baseUSDC.chainId;
+
+  const chain = getKnownToken(
+    Number(requiredChain),
+    Number(requiredChain) === rozoStellar.chainId
+      ? rozoStellarUSDC.token
+      : order.metadata.preferredTokenAddress
+  );
+
+  return {
+    id: BigInt(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)),
+    mode: RozoPayOrderMode.HYDRATED,
+    intentAddr: destAddress,
+    handoffAddr: destAddress,
+    escrowContractAddress: destAddress,
+    bridgerContractAddress: destAddress,
+    // @TODO: use correct destination token
+    bridgeTokenOutOptions: [
+      {
+        token: {
+          chainId: baseUSDC.chainId,
+          token: baseUSDC.token,
+          symbol: baseUSDC.symbol,
+          usd: 1,
+          priceFromUsd: 1,
+          decimals: baseUSDC.decimals,
+          displayDecimals: 2,
+          logoSourceURI: baseUSDC.logoSourceURI,
+          logoURI: baseUSDC.logoURI,
+          maxAcceptUsd: 100000,
+          maxSendUsd: 0,
+        },
+        amount: parseUnits(
+          order.destination.amountUnits,
+          baseUSDC.decimals
+        ).toString() as `${bigint}`,
+        usd: Number(order.destination.amountUnits),
+      },
+    ],
+    selectedBridgeTokenOutAddr: null,
+    selectedBridgeTokenOutAmount: null,
+    destFinalCallTokenAmount: {
+      token: {
+        chainId: chain ? chain.chainId : baseUSDC.chainId,
+        token: chain ? chain.token : baseUSDC.token,
+        symbol: chain ? chain.symbol : baseUSDC.symbol,
+        usd: 1,
+        priceFromUsd: 1,
+        decimals: chain ? chain.decimals : baseUSDC.decimals,
+        displayDecimals: 2,
+        logoSourceURI: chain ? chain.logoSourceURI : baseUSDC.logoSourceURI,
+        logoURI: chain ? chain.logoURI : baseUSDC.logoURI,
+        maxAcceptUsd: 100000,
+        maxSendUsd: 0,
+      },
+      amount: parseUnits(
+        order.destination.amountUnits,
+        chain ? chain.decimals : baseUSDC.decimals
+      ).toString() as `${bigint}`,
+      usd: Number(order.destination.amountUnits),
+    },
+    usdValue: Number(order.destination.amountUnits),
+    destFinalCall: {
+      to: destAddress,
+      value: BigInt("0"),
+      data: "0x",
+    },
+    refundAddr: (order.source?.sourceAddress as `0x${string}`) || null,
+    nonce: order.nonce as unknown as bigint,
+    sourceTokenAmount: null,
+    sourceFulfillerAddr: null,
+    sourceInitiateTxHash: null,
+    sourceStartTxHash: null,
+    sourceStatus: RozoPayOrderStatusSource.WAITING_PAYMENT,
+    destStatus: RozoPayOrderStatusDest.PENDING,
+    intentStatus: RozoPayIntentStatus.UNPAID,
+    destFastFinishTxHash: null,
+    destClaimTxHash: null,
+    redirectUri: null,
+    createdAt: Math.floor(Date.now() / 1000),
+    lastUpdatedAt: Math.floor(Date.now() / 1000),
+    orgId: order.orgId as string,
+    metadata: {
+      ...(order?.metadata ?? {}),
+      ...(order.userMetadata ?? {}),
+      ...(order.metadata ?? {}),
+    } as any,
+    externalId: order.externalId as string | null,
+    userMetadata: order.userMetadata as RozoPayUserMetadata | null,
+    expirationTs: BigInt(Math.floor(Date.now() / 1000 + 5 * 60).toString()),
+    org: {
+      orgId: order.orgId as string,
+      name: "Pay Rozo",
+    },
+  };
+}

package/src/index.ts

@@ -1,4 +1,6 @@
+export * from "./api/payment";
 export * from "./assert";
+export * from "./bridge";
 export * from "./chain";
 export * from "./daimoPay";
 export * from "./debug";