@rozoai/intent-common 0.0.28-beta.1 → 0.0.28-beta.3

package/src/api/README.md

@@ -0,0 +1,275 @@
+# API Client Utility
+
+A clean, flexible TypeScript utility for handling API requests to the RozoAI API service.
+
+## Overview
+
+This utility provides a modular approach to API requests with:
+
+- A base client for core HTTP operations
+- Endpoint-specific modules for domain operations
+- TypeScript interfaces for type safety
+- Configuration management for API URLs and tokens
+- Pre-configured defaults for RozoAI API
+
+## Default Configuration
+
+The API client comes pre-configured with RozoAI production settings:
+
+```typescript
+import { ROZO_API_URL, ROZO_API_TOKEN } from "@rozoai/intent-common";
+
+console.log(ROZO_API_URL); // "https://intentapiv2.rozo.ai/functions/v1"
+console.log(ROZO_API_TOKEN); // Pre-configured production token
+```
+
+These defaults are automatically used by the API client, so you can start making requests immediately without any configuration.
+
+## Structure
+
+```bash
+api/
+├── base.ts         # Core API client functionality
+├── index.ts        # Re-exports all API modules
+├── payment.ts      # Payment-specific endpoints
+└── README.md       # Documentation
+```
+
+## Base API Client
+
+The base client (`base.ts`) provides the foundation for all API requests:
+
+```typescript
+import { apiClient, setApiConfig } from "@rozoai/intent-common";
+
+// Configure the API client (optional, uses defaults if not set)
+setApiConfig({
+  baseUrl: "https://intentapiv2.rozo.ai/functions/v1",
+  apiToken: "your-api-token",
+});
+
+// Make a GET request
+const response = await apiClient.get("/some-endpoint");
+
+// Make a POST request with data
+const response = await apiClient.post("/some-endpoint", { data: "value" });
+
+// Make a request with custom headers
+const response = await apiClient.get("/some-endpoint", {
+  headers: { "Custom-Header": "value" },
+});
+
+// Make a request with query parameters
+const response = await apiClient.get("/some-endpoint", {
+  params: { filter: "active", sort: "desc" },
+});
+```
+
+## Using Payment API
+
+The payment module provides typed functions for payment operations:
+
+```typescript
+import {
+  createRozoPayment,
+  getRozoPayment,
+  createRozoPaymentRequest,
+} from "@rozoai/intent-common";
+
+// Create a payment
+const handleSubmitPayment = async () => {
+  const paymentData = createRozoPaymentRequest({
+    appId: "your-app-id",
+    display: {
+      intent: "Pay for product",
+      paymentValue: "100.00",
+      currency: "USD",
+    },
+    destination: {
+      chainId: "8453",
+      amountUnits: "100000000",
+      tokenSymbol: "USDC",
+      tokenAddress: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    },
+  });
+
+  const response = await createRozoPayment(paymentData);
+
+  if (response.data) {
+    console.log("Payment created:", response.data.id);
+  } else if (response.error) {
+    console.error("Error creating payment:", response.error.message);
+  }
+};
+
+// Get payment details
+const fetchPaymentDetails = async (paymentId: string) => {
+  const response = await getRozoPayment(paymentId);
+
+  if (response.data) {
+    console.log("Payment status:", response.data.status);
+  }
+};
+```
+
+## React Hooks
+
+React hooks for these APIs are available in the `@rozoai/intent-pay` package:
+
+```typescript
+// In @rozoai/intent-pay
+import {
+  useCreateRozoPayment,
+  useRozoPayment,
+  useRozoPayments
+} from '@rozoai/intent-pay';
+
+// Use in React components
+const PaymentForm = () => {
+  const [paymentState, submitPayment] = useCreateRozoPayment();
+
+  const handleSubmit = (formData) => {
+    submitPayment({
+      appId: 'your-app-id',
+      display: { ... },
+      destination: { ... }
+    });
+  };
+
+  if (paymentState.isLoading) return <div>Processing...</div>;
+  if (paymentState.isError) return <div>Error: {paymentState.error?.message}</div>;
+  if (paymentState.isSuccess) return <div>Success! ID: {paymentState.data?.id}</div>;
+
+  return <FormComponent onSubmit={handleSubmit} />;
+};
+```
+
+## Error Handling
+
+All API responses include standardized error handling:
+
+```typescript
+const response = await createRozoPayment(data);
+
+if (response.error) {
+  // Handle error
+  console.error("API Error:", response.error.message);
+  return;
+}
+
+// Process successful response
+const paymentData = response.data;
+```
+
+## TypeScript Integration
+
+All functions are fully typed:
+
+```typescript
+import { PaymentResponseData, ApiResponse } from "@rozoai/intent-common";
+
+const response: ApiResponse<PaymentResponseData> = await getRozoPayment(
+  paymentId
+);
+// response.data will be typed as PaymentResponseData | null
+```
+
+## Configuration
+
+### Using Default Configuration
+
+The API client is pre-configured with production RozoAI settings, so you can use it immediately:
+
+```typescript
+import { createRozoPayment } from "@rozoai/intent-common";
+
+// Works out of the box with default configuration
+const response = await createRozoPayment({
+  appId: "your-app-id",
+  display: { intent: "Payment", paymentValue: "10.00", currency: "USD" },
+  destination: {
+    chainId: "8453",
+    amountUnits: "10000000",
+    tokenSymbol: "USDC",
+  },
+});
+```
+
+### Customizing Configuration
+
+For testing, staging, or custom environments, you can override the defaults:
+
+```typescript
+import {
+  setApiConfig,
+  getApiConfig,
+  ROZO_API_URL,
+  ROZO_API_TOKEN,
+} from "@rozoai/intent-common";
+
+// Override for staging environment
+setApiConfig({
+  baseUrl: "https://staging-api.rozo.ai/v1",
+  apiToken: "your-staging-token",
+});
+
+// Or reset to production defaults
+setApiConfig({
+  baseUrl: ROZO_API_URL,
+  apiToken: ROZO_API_TOKEN,
+});
+
+// Get current configuration
+const config = getApiConfig();
+console.log(config.baseUrl, config.apiToken);
+```
+
+### Configuration in Different Environments
+
+**Production (Default):**
+
+```typescript
+// No configuration needed - uses ROZO_API_URL and ROZO_API_TOKEN automatically
+import { createRozoPayment } from "@rozoai/intent-common";
+const response = await createRozoPayment(data);
+```
+
+**Staging:**
+
+```typescript
+import { setApiConfig } from "@rozoai/intent-common";
+
+setApiConfig({
+  baseUrl: "https://staging.intentapi.rozo.ai/v1",
+  apiToken: process.env.STAGING_API_TOKEN,
+});
+```
+
+**Development/Testing:**
+
+```typescript
+import { setApiConfig } from "@rozoai/intent-common";
+
+setApiConfig({
+  baseUrl: "http://localhost:3000/api",
+  apiToken: "dev_token",
+});
+```
+
+## Available Payment Functions
+
+- `createRozoPayment(paymentData)` - Create a new payment
+- `getRozoPayment(paymentId)` - Get payment by ID
+- `getRozoPaymentByExternalId(externalId)` - Get payment by external ID
+- `updateRozoPayment(paymentId, paymentData)` - Update a payment
+- `cancelRozoPayment(paymentId)` - Cancel a payment
+- `listRozoPayments(params?)` - List all payments with optional filters
+- `createRozoPaymentRequest(options)` - Create a payment request payload
+
+## Best Practices
+
+- Configure the API client once at app initialization
+- Leverage TypeScript interfaces for type safety
+- Handle loading, error, and success states properly
+- Use the React hooks (from @rozoai/intent-pay) when working in React components
+- Implement proper error handling for all API calls

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/index.ts

@@ -0,0 +1,14 @@
+/**
+ * API client utilities for RozoAI Intent Pay
+ *
+ * This module provides core API client functionality for making HTTP requests
+ * to the RozoAI payment API. It includes:
+ * - Base API client with support for GET, POST, PUT, PATCH, DELETE
+ * - Payment API functions and types
+ * - Type-safe interfaces for requests and responses
+ *
+ * Note: React hooks for these APIs are available in the @rozoai/intent-pay package.
+ */
+
+export * from "./base";
+export * from "./payment";

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);
+};