@coin-voyage/shared 0.0.1

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@coin-voyage/shared",
+  "version": "0.0.1",
+  "private": false,
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": [
+      "./src/*/index.ts",
+      "./src/*/index.tsx"
+    ]
+  },
+  "files": [
+    "src"
+  ],
+  "typesVersions": {
+    "*": {
+      "*": [
+        "src/*/index.d.ts"
+      ]
+    }
+  },
+  "dependencies": {
+    "detect-browser": "^5.3.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.22.8",
+    "zod": "^3.22.4"
+  },
+  "scripts": {
+    "build": "tsc --build --force",
+    "release:build": "pnpm build",
+    "clean": "rm -rf node_modules",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/api/config.ts

@@ -0,0 +1,2 @@
+export const API_URL = "https://dev-api.coinvoyage.io"
+// export const API_URL = "http://localhost:8000"

package/src/api/fetcher.ts

@@ -0,0 +1,38 @@
+import { API_URL } from "./config";
+
+type FetchApiOptions = {
+    path: string;
+    options?: RequestInit;
+    throwOnFailure?: boolean;
+}
+
+export async function fetchApi<T>(opts: FetchApiOptions): Promise<T | undefined> {
+    try {
+        const response = await fetch(`${API_URL}/${opts.path}`, {
+            ...opts.options,
+            headers: {
+                ...opts.options?.headers,
+                "Content-Type": "application/json",
+                "Accept-Encoding": "gzip, deflate, br",
+            },
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            console.error(
+                JSON.stringify({
+                    path: opts.path,
+                    status: response.status,
+                    statusText: response.statusText,
+                    details: text
+                })
+            );
+            return;
+        }
+        return await response.json();
+    } catch (error: any) {
+        console.error(`path: ${opts.path}, message: ${error.message}`);
+        if (opts.throwOnFailure) {
+            throw error;
+        }
+    }
+}

package/src/api/index.ts

@@ -0,0 +1,3 @@
+export * from "./config"
+export * from "./fetcher"
+export * from "./pay-order"

package/src/api/pay-order.ts

@@ -0,0 +1,349 @@
+import { z } from "zod";
+import { ChainId, ChainType, CurrencyAmount, CurrencyBase, CurrencyWithAmount, CurrencyWithBalance, PayOrder, PayOrderMetadata, PayOrderMode, PayOrderStatus, zDepositPayOrder, zPayOrderMetadata } from "../common/index";
+import { fetchApi } from "./fetcher";
+
+/**
+ * Fetches a PayOrder by its ID.
+ * 
+ * Retrieves a PayOrder object from the API using the provided payOrderId.
+ * This function requires an API key for authentication.
+ * 
+ * @param {string} payOrderId - The unique identifier of the PayOrder.
+ * @param {string} apiKey - The API key required for authentication.
+ * @returns {Promise<PayOrder | undefined>} - The PayOrder object if the request is successful.
+ * 
+ * @example
+ * const apiKey = 'yourApiKey';
+ * const payOrder = await getPayOrder('123456', apiKey);
+ */
+export async function getPayOrder(payOrderId: string, apiKey: string): Promise<PayOrder | undefined> {
+  return fetchApi<PayOrder>({
+    path: `pay-orders/${payOrderId}`,
+    options: {
+      headers: {
+        "X-API-KEY": apiKey
+      }
+    }
+  })
+}
+
+/** PayOrder parameters. The payOrder is created only after user taps pay. */
+export interface DepositPayOrderParams {
+  /**
+   * Metadata to attach to the payOrder.
+   */
+  metadata?: PayOrderMetadata
+  /**
+   * Value in USD received from the Deposit.
+   */
+  destination_value_usd?: number
+  /**
+   * Desired output token + chain.
+   */
+  destination_currency: CurrencyBase
+  /**
+   * Output amount to deposit.
+   */
+  destination_amount?: string
+  /**
+   * Receiving address for the deposit.
+   */
+  receiving_address: string
+}
+
+/**
+ * Creates a `DEPOSIT` type PayOrder.
+ * 
+ * Generates a PayOrder of type `DEPOSIT` with the provided parameters.
+ * This function ensures the request parameters are valid using a schema validation.
+ * 
+ * @param {DepositPayOrderParams} createOrderParams - Parameters required to create a deposit PayOrder.
+ * @param {string} apiKey - The API key required for authentication.
+ * @param {boolean} [throwOnFailure] - Whether to throw an error if the request fails.
+ * @returns {Promise<PayOrder | undefined>} - The PayOrder object if the request is successful.
+ * 
+ * @example
+ * const apiKey = 'yourApiKey';
+ * const depositOrderParams = {
+ *   amount: 1000,
+ *   currency: 'USD',
+ *   metadata: { description: 'Deposit for account' }
+ * };
+ * const depositPayOrder = await createDepositPayOrder(depositOrderParams, apiKey);
+ */
+export async function createDepositPayOrder(createOrderParams: DepositPayOrderParams, apiKey: string, throwOnFailure?: boolean): Promise<PayOrder | undefined> {
+  const result = zDepositPayOrder.safeParse(createOrderParams);
+  if (!result.success) {
+    return
+  }
+
+  return fetchApi<PayOrder>({
+    path: `pay-orders`, options: {
+      method: "POST",
+      body: JSON.stringify({
+        mode: PayOrderMode.DEPOSIT,
+        ...createOrderParams
+      }),
+      headers: {
+        "X-API-KEY": apiKey
+      }
+    },
+    throwOnFailure: throwOnFailure
+  })
+}
+
+export type SalePayOrderParams = {
+  /**
+   * Metadata to attach to the payOrder.
+   */
+  metadata?: PayOrderMetadata
+  /**
+   * Expected value in USD to be received from the Sale.
+   */
+  destination_value_usd: number
+  /**
+   * Expected token on what chain to receive the value from the Sale.
+   */
+  destination_currency?: CurrencyBase
+  /**
+   * Expected receiving address to receive the value from the Sale.
+   */
+  receiving_address?: string
+} | {
+  /**
+   * Metadata to attach to the payOrder.
+   */
+  metadata?: PayOrderMetadata
+  /**
+   * Expected token on what chain to receive the value from the Sale.
+   */
+  destination_currency: CurrencyBase
+  /**
+   * Expected amount to be received from the Sale.
+   */
+  destination_amount: string
+  /**
+   * Expected receiving address to receive the value from the Sale.
+   */
+  receiving_address?: string
+}
+
+
+/**
+ * Generates a `sale` type PayOrder.
+ * 
+ * Creates a `sale` type PayOrder with a fixed valueOut `destination_value_usd`.
+ * This function should be executed
+ * 
+ * and a SHA-512 hash signature of the concatenated API key, secret, and timestamp. 
+ * 
+ * @param {SalePayOrderParams} payOrderParams - destination_value_usd and metadata for this payOrder.
+ * @param {string} signature - signature generated by the `generateAuthorizationSignature` function.
+ * @returns {PayOrder | undefined} - A PayOrder object if the request was successful.
+ * 
+ * @example
+ * const apiKey = 'yourApiKey';
+ * const apiSecret = 'yourApiSecret';
+ * const authSignature = generateAuthorizationSignature(apiKey, apiSecret);
+ * const payOrder = await createSalePayOrder(
+ * createSalePayOrder({
+ *  destination_value_usd: 200,
+ *  metadata: {
+ *    items: [
+ *     {
+ *       name: "t-shirt",
+ *       description: "a nice t-shirt",
+ *       image: "https://example.com/tshirt.jpg",
+ *       quantity: 1,
+ *       unit_price: 200,
+ *       currency: "USD"
+ *     }
+ *   ]
+ *  }}, authSignature)
+ */
+export async function createSalePayOrder(createOrderParams: SalePayOrderParams, signature: string): Promise<PayOrder | undefined> {
+  try {
+    if (createOrderParams?.metadata) {
+      zPayOrderMetadata.parse(createOrderParams.metadata);
+    }
+    return fetchApi<PayOrder>({
+      path: `pay-orders`, options: {
+        method: "POST",
+        body: JSON.stringify({
+          mode: PayOrderMode.SALE,
+          ...createOrderParams
+        }),
+        headers: {
+          "Authorization": signature
+        }
+      }
+    })
+  }
+  catch (err) {
+    if (err instanceof z.ZodError) {
+      throw new Error(err.errors.map(e => e.message).join(", "))
+    }
+    throw err
+  }
+}
+
+export type PayOrderQuoteParams = {
+  wallet_address: string
+  chain_type: ChainType,
+  chain_id?: ChainId
+}
+
+/**
+ * Generates a PayOrder Quote.
+ * 
+ * Creates a PayOrder Quote for an existing PayOrder by providing wallet information and chain details.
+ * This function requires an API key for authentication.
+ * 
+ * @param {string} orderId - The unique identifier of the PayOrder for which the quote is requested.
+ * @param {PayOrderQuoteParams} quoteParams - Contains `wallet_address`, `chain_type`, chain_id`.
+ * @param {string} apiKey - The API key for authorization.
+ * @returns {CurrencyWithBalance[] | undefined} - An array of PayTokens if the request was successful.
+ * 
+ * @example
+ * const orderId = 'existingOrderId';
+ * const apiKey = 'yourApiKey';
+ * const quoteParams = {
+ *   wallet_address: '0x1234...abcd',
+ *   chain_type: ChainType.EVM,
+ *   chain_id: 1 // Ethereum Mainnet
+ * };
+ * 
+ * const payOrderQuote = await payOrderQuote(orderId, quoteParams, apiKey);
+
+ */
+export async function payOrderQuote(orderId: string, quoteParams: PayOrderQuoteParams, apiKey: string): Promise<CurrencyWithBalance[] | undefined> {
+  return fetchApi<CurrencyWithBalance[]>({
+    path: `pay-orders/${orderId}/quote`, options: {
+      method: "POST",
+      body: JSON.stringify({
+        ...quoteParams
+      }),
+      headers: {
+        "X-API-KEY": apiKey
+      },
+    }
+  })
+}
+
+
+export type PaymentDetailsParams = {
+  payOrderId: string
+  outTokenAddress?: string
+  outChainId: ChainId
+  refundAddress: string
+  apiKey: string
+}
+
+export type PaymentDetails = {
+  payorder_id: string
+  status: PayOrderStatus
+  expires_at: Date
+
+  refund_address: string
+  deposit_address: string
+  receiving_address?: string
+
+  source_currency: CurrencyWithAmount
+  source_amount: CurrencyAmount
+  destination_currency?: CurrencyWithAmount
+  destination_amount?: CurrencyAmount
+}
+
+/**
+ * Retrieves payment details for a specific PayOrder.
+ * 
+ * This function fetches payment details associated with a specific PayOrder ID. 
+ * It allows specifying the token and blockchain network (via `outTokenAddress` and `outChainId`) 
+ * to retrieve source currency information, as well as a refund address for the transaction.
+ * 
+ * The request is authenticated using the provided API key in the headers.
+ * 
+ * @param {PaymentDetailsParams} params - Parameters to retrieve the payment details.
+ * @param {string} params.payOrderId - The unique identifier of the PayOrder for which payment details are fetched.
+ * @param {string} [params.outTokenAddress] - (Optional) The token address of the source currency.
+ * @param {ChainId} params.outChainId - The blockchain network ID where the token resides.
+ * @param {string} params.refundAddress - The address where funds will be refunded in case of a failed transaction.
+ * @param {string} params.apiKey - The API key used to authenticate the request.
+ * 
+ * @returns {Promise<PaymentDetails | undefined>} - The payment details object if the request is successful.
+ * 
+ * @example
+ * const paymentDetails = await payOrderPaymentDetails({
+ *   payOrderId: '12345',
+ *   outTokenAddress: '0x1234567890abcdef1234567890abcdef12345678',
+ *   outChainId: 1,
+ *   refundAddress: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+ *   apiKey: 'yourApiKey'
+ * });
+ * 
+ * console.log(paymentDetails);
+ */
+export async function payOrderPaymentDetails({
+  payOrderId,
+  outTokenAddress,
+  outChainId,
+  refundAddress,
+  apiKey
+}: PaymentDetailsParams): Promise<PaymentDetails | undefined> {
+  return fetchApi<PaymentDetails>({
+    path: `pay-orders/${payOrderId}/payment-details`, options: {
+      method: "POST",
+      body: JSON.stringify({
+        source_currency: {
+          address: outTokenAddress,
+          chain_id: outChainId
+        },
+        refund_address: refundAddress
+      }),
+      headers: {
+        "X-API-KEY": apiKey
+      },
+    }
+  })
+}
+
+/**
+ * Processes a PayOrder transaction.
+ * 
+ * This function triggers the processing of a PayOrder by providing the transaction hash 
+ * that represents the payment on the blockchain. The request is authenticated using an API key.
+ * 
+ * @param {Object} params - Parameters required to process the PayOrder.
+ * @param {string} params.payOrderId - The unique identifier of the PayOrder to be processed.
+ * @param {string} params.sourceTransactionHash - The transaction hash representing the payment on the blockchain.
+ * @param {string} params.apiKey - The API key used to authenticate the request.
+ * 
+ * @returns {Promise<void>}
+ * 
+ * @example
+ * const processedPayment = await processPayOrder({
+ *   payOrderId: '12345',
+ *   sourceTransactionHash: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+ *   apiKey: 'yourApiKey'
+ * });
+ * 
+ * console.log(processedPayment);
+ */
+export async function processPayOrder({
+  payOrderId,
+  sourceTransactionHash,
+  apiKey
+}: {
+  payOrderId: string
+  sourceTransactionHash: string
+  apiKey: string
+}): Promise<void> {
+  return fetchApi<void>({
+    path: `pay-orders/${payOrderId}/process?tx_hash=${sourceTransactionHash}`, options: {
+      method: "GET",
+      headers: {
+        "X-API-KEY": apiKey
+      },
+    }
+  })
+}

package/src/common/assert.ts

@@ -0,0 +1,21 @@
+import { debugJson } from "./debug"
+
+export function assert(condition: boolean, ...args: any[]): asserts condition {
+  if (!condition) {
+    throw new Error(
+      `Assertion failed: ${args.map((a) => debugJson(a)).join(", ")}`
+    )
+  }
+}
+
+export function assertNotNull<T>(
+  value: T | null | undefined,
+  ...args: any[]
+): T {
+  assert(value !== null && value !== undefined, ...args)
+  return value
+}
+
+export function assertEqual<T>(a: T, b: T, ...args: any[]): void {
+  assert(a === b, ...args)
+}

package/src/common/chainExplorer.ts

@@ -0,0 +1,27 @@
+import { ChainId } from "./chains"
+
+const chainExplorerUrls: Record<ChainId, string> = {
+  [ChainId.ETH]: "https://etherscan.io",
+  [ChainId.ARB]: "https://arbiscan.io",
+  [ChainId.BASE]: "https://basescan.org",
+  [ChainId.BLAST]: "https://blastexplorer.io",
+  [ChainId.OP]: "https://optimistic.etherscan.io",
+  [ChainId.POL]: "https://polygonscan.com",
+  [ChainId.AVAX]: "https://snowtrace.io",
+  [ChainId.SEPOLIA]: "https://sepolia.etherscan.io",
+  [ChainId.SEPOLIA_BASE]: "https://sepolia.basescan.org",
+  [ChainId.SEPOLIA_ARB]: "https://sepolia.arbiscan.io",
+  [ChainId.SEPOLIA_OP]: "https://sepolia-optimism.etherscan.io",
+  [ChainId.BSC]: "https://bscscan.com",
+  [ChainId.ZKSYNC]: "https://explorer.zksync.io",
+  [ChainId.FTM]: "https://ftmscan.com",
+  [ChainId.SOL]: "https://solscan.io",
+  [ChainId.SUI]: "https://suiscan.xyz",
+  [ChainId.TRX]: "https://tronscan.org",
+  [ChainId.BTC]: "https://mempool.space",
+}
+
+export function getChainExplorerTxUrl(chainId: ChainId, txHash?: string) {
+  const explorer = chainExplorerUrls[chainId]
+  return `${explorer}/tx/${txHash}`
+}

package/src/common/chains.ts

@@ -0,0 +1,130 @@
+import * as chains from "viem/chains"
+
+export enum ChainType {
+  EVM = "EVM",
+  // Solana virtual machine
+  SOL = "SOL",
+  SUI = "SUI",
+  TRON = "TRON",
+  // Unspent transaction output (e.g. Bitcoin, Litecoin, Dogecoin)
+  UTXO = "UTXO",
+}
+
+export function getChainTypeName(chainType?: ChainType): string {
+  switch (chainType) {
+    case ChainType.EVM:
+      return "Ethereum"
+    case ChainType.SOL:
+      return "Solana"
+    case ChainType.SUI:
+      return "Sui"
+    case ChainType.TRON:
+      return "Tron"
+    case ChainType.UTXO:
+      return "Bitcoin"
+    default:
+      return ""
+  }
+}
+
+export enum ChainId {
+  ETH = 1,
+  OP = 10,
+  BSC = 56,
+  POL = 137,
+  FTM = 250,
+  ZKSYNC = 324,
+  BASE = 8453,
+  ARB = 42161,
+  AVAX = 43114,
+  BLAST = 81457,
+
+  // testnet
+  SEPOLIA = 11155111,
+  SEPOLIA_BASE = 84532,
+  SEPOLIA_ARB = 421614,
+  SEPOLIA_OP = 11155420,
+
+  // UTXO (IDs are made up)
+  BTC = 20000000000001,
+  // BCH = 20000000000002,
+  // LTC = 20000000000003,
+  // DGE = 20000000000004,
+
+  // None-EVM (IDs are made up)
+  SOL = 30000000000001,
+  SUI = 30000000000002,
+  TRX = 30000000000003,
+  // XRPL = 30000000000004,
+}
+
+export function getChainTypeByChainId(chainId?: ChainId): ChainType {
+  switch (chainId) {
+    case ChainId.ETH:
+    case ChainId.OP:
+    case ChainId.BSC:
+    case ChainId.POL:
+    case ChainId.FTM:
+    case ChainId.ZKSYNC:
+    case ChainId.BASE:
+    case ChainId.ARB:
+    case ChainId.AVAX:
+    case ChainId.BLAST:
+      return ChainType.EVM
+    case ChainId.SOL:
+      return ChainType.SOL
+    case ChainId.SUI:
+      return ChainType.SUI
+    case ChainId.TRX:
+      return ChainType.TRON
+    case ChainId.BTC:
+      return ChainType.UTXO
+    default:
+      return ChainType.EVM
+  }
+}
+
+export function isTestnetChain(chainId: number): boolean {
+  return Boolean(
+    Object.values(chains).find((chain) => chain.id === chainId)?.testnet
+  )
+}
+
+export function getChainName(chainId?: ChainId): string | undefined {
+  if (!chainId) {
+    return
+  }
+
+  switch (chainId) {
+    case ChainId.ETH:
+      return "Ethereum"
+    case ChainId.OP:
+      return "Optimism"
+    case ChainId.BSC:
+      return "Binance Smart Chain"
+    case ChainId.POL:
+      return "Polygon"
+    case ChainId.FTM:
+      return "Fantom"
+    case ChainId.ZKSYNC:
+      return "zkSync"
+    case ChainId.BASE:
+      return "Base"
+    case ChainId.ARB:
+      return "Arbitrum"
+    case ChainId.AVAX:
+      return "Avalanche"
+    case ChainId.BLAST:
+      return "Blast"
+    case ChainId.SOL:
+      return "Solana"
+    case ChainId.SUI:
+      return "Sui"
+    case ChainId.TRX:
+      return "Tron"
+    case ChainId.BTC:
+      return "Bitcoin"
+    default:
+      return
+  }
+}

package/src/common/currencies.ts

@@ -0,0 +1,42 @@
+export interface CurrencyExchangeRate {
+  name: string
+  symbol: string
+  currency: string
+  decimals: number
+  rateUSD: number
+}
+
+export const currencyRateUSD: CurrencyExchangeRate = {
+  name: "US Dollar",
+  symbol: "$",
+  currency: "USD",
+  decimals: 2,
+  rateUSD: 1,
+}
+
+const data: [string, string, string, number][] = [
+  ["Euro", "€", "EUR", 2],
+  ["Argentine Peso", "ARS", "ARS", 0],
+  ["Bolivian Boliviano", "$Bs", "BOB", 0],
+  ["Turkish Lira", "₺", "TRY", 0],
+  ["New Taiwan Dollar", "NT$", "TWD", 0],
+  ["Ukrainian Hryvnia", "₴", "UAH", 0],
+  ["Naira", "₦", "NGN", 0],
+  ["Swiss Franc", "₣", "CHF", 2],
+  ["Japanese Yen", "¥", "JPY", 0],
+  ["Korean Won", "₩", "KRW", 0],
+  ["Yuan", "¥", "CNY", 0],
+  ["Pound", "£", "GBP", 2],
+  ["Canadian Dollar", "C$", "CAD", 2],
+  ["Australian Dollar", "A$", "AUD", 2],
+  ["Singapore Dollar", "S$", "SGD", 2],
+]
+
+export const nonUsdCurrencies = data.map(
+  ([name, symbol, currency, decimals]) => ({
+    name,
+    symbol,
+    currency,
+    decimals,
+  })
+)

package/src/common/debug.ts

@@ -0,0 +1,11 @@
+// Return compact JSON, 1000 chars max. Never throws.
+export function debugJson(obj: any) {
+  try {
+    const serialized = JSON.stringify(obj, (_, value) =>
+      typeof value === "bigint" ? value.toString() : value
+    )
+    return serialized.slice(0, 1000)
+  } catch (e: any) {
+    return `<JSON error: ${e.message}>`
+  }
+}

package/src/common/format.ts

@@ -0,0 +1,3 @@
+export function capitalize(str: string) {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}

package/src/common/i18n/index.ts

@@ -0,0 +1,18 @@
+import { en } from "./languages/en"
+import { es } from "./languages/es"
+
+export interface Locale {
+  languageCode?: string
+}
+
+export type I18NTranslation = typeof en
+
+// Return i18n translation based on locale
+export const i18n = (locale: Locale | undefined): I18NTranslation => {
+  switch (locale?.languageCode) {
+    case "es":
+      return es
+    default:
+      return en
+  }
+}

package/src/common/i18n/languages/en.ts

@@ -0,0 +1,38 @@
+export const en = {
+  // format.ts
+  format: {
+    fee: () => "Fee:",
+  },
+
+  // op.ts
+  op: {
+    acceptedInbound: (
+      readableAmount: string,
+      otherCoinSymbol: string,
+      homeCoinSymbol: string,
+      chain?: string
+    ) =>
+      `Accepted ${readableAmount} ${otherCoinSymbol}${
+        chain ? ` on ${chain}` : ""
+      } as ${homeCoinSymbol}`,
+    sentOutbound: (
+      readableAmount: string,
+      coinSymbol: string,
+      chain?: string
+    ) => `Sent ${readableAmount} ${coinSymbol}${chain ? ` on ${chain}` : ""}`,
+  },
+
+  // time.ts
+  time: {
+    soon: () => "soon",
+    now: (long?: boolean) => `${long ? "just now" : "now"}`,
+    minutesAgo: (minutes: number, long?: boolean) =>
+      `${minutes}m ${long ? "ago" : ""}`,
+    hoursAgo: (hours: number, long?: boolean) =>
+      `${hours}h ${long ? "ago" : ""}`,
+    daysAgo: (days: number, long?: boolean) => `${days}d ${long ? "ago" : ""}`,
+    inDays: (days: number, long?: boolean) => `${long ? "in" : ""} ${days}d`,
+  },
+}
+
+export type LanguageDefinition = typeof en

package/src/common/i18n/languages/es.ts

@@ -0,0 +1,38 @@
+import type { LanguageDefinition } from "./en"
+export const es: LanguageDefinition = {
+  // format.ts
+  format: {
+    fee: () => "Tasas:",
+  },
+
+  // op.ts
+  op: {
+    acceptedInbound: (
+      readableAmount: string,
+      otherCoinSymbol: string,
+      homeCoinSymbol: string,
+      chain?: string
+    ) =>
+      `Aceptado ${readableAmount} ${otherCoinSymbol}${
+        chain ? ` en ${chain}` : ""
+      } como ${homeCoinSymbol}`,
+    sentOutbound: (
+      readableAmount: string,
+      coinSymbol: string,
+      chain?: string
+    ) =>
+      `Envidado ${readableAmount} ${coinSymbol}${chain ? ` en ${chain}` : ""}`,
+  },
+
+  // time.ts
+  time: {
+    soon: () => "pronto",
+    now: () => "ahora",
+    minutesAgo: (minutes: number, long?: boolean) =>
+      `${long ? "hace" : ""} ${minutes}m`,
+    hoursAgo: (hours: number, long?: boolean) =>
+      `${long ? "hace" : ""} ${hours}h`,
+    daysAgo: (days: number, long?: boolean) => `${long ? "hace" : ""} ${days}d`,
+    inDays: (days: number, long?: boolean) => `${long ? "en" : ""} ${days}d`,
+  },
+}

package/src/common/index.ts

@@ -0,0 +1,12 @@
+export * from "./assert"
+export * from "./chainExplorer"
+export * from "./chains"
+export * from "./currencies"
+export * from "./organization"
+export * from "./pay"
+export * from "./debug"
+export * from "./format"
+export * from "./model"
+export * from "./retryBackoff"
+export * from "./time"
+export * from "./i18n"

package/src/common/model.ts

@@ -0,0 +1,43 @@
+import type { Address } from "viem"
+import { z } from "zod"
+import { ChainId } from "./chains"
+
+export const zSolanaPublicKey = z.string().regex(/^[1-9A-HJ-NP-Za-km-z]+$/)
+
+export type SolanaPublicKey = z.infer<typeof zSolanaPublicKey>
+
+export interface Currency extends CurrencyBase {
+  id?: string
+  name: string
+  ticker: string
+  decimals: number
+  image_uri?: string
+  price_usd?: number
+}
+
+export interface CurrencyBase {
+  chain_id: ChainId
+  address: string | null
+}
+
+export const zAddress = z
+  .string()
+  .regex(/^0x[0-9a-f]{40}$/i)
+  .refine((s): s is Address => true)
+
+export const zBigIntStr = z
+  .string()
+  .regex(/^[0-9]+$/i)
+  .refine((s): s is BigIntStr => true)
+
+export type BigIntStr = `${bigint}`
+
+export type PlatformType = "ios" | "android" | "other"
+
+export function dateToUnix(d: Date): number {
+  return Math.floor(d.getTime() / 1000)
+}
+
+export function unixToDate(unix: number): Date {
+  return new Date(unix * 1000)
+}

package/src/common/organization.ts

@@ -0,0 +1,5 @@
+import { Currency } from "./model";
+
+export type SettlementCurrency = {
+    receiving_address: string;
+} & Currency

package/src/common/pay.ts

@@ -0,0 +1,194 @@
+import { Address, Hex, zeroAddress } from "viem"
+import z from "zod"
+import { Currency, zAddress, zBigIntStr } from "./model"
+
+
+export enum PayOrderMode {
+  SALE = "SALE", // product or item sale, value out can only be adjusted by the merchant 
+  DEPOSIT = "DEPOSIT", // deposit into user account, let the user specify the value out
+}
+
+export const zBridgeTokenOutOptions = z.array(
+  z.object({
+    token: zAddress,
+    amount: zBigIntStr.transform((a) => BigInt(a)),
+  })
+)
+
+export type BridgeTokenOutOptions = z.infer<typeof zBridgeTokenOutOptions>
+
+// NOTE: be careful to modify this type only in backward-compatible ways.
+//       Add OPTIONAL fields, etc. Anything else requires a migration.
+export const zPayOrderMetadata = z.object({
+  items: z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        image: z.string().optional(),
+        quantity: z.number().int().optional(),
+        unit_price: z.number().optional(),
+        currency: z.string().optional(),
+      })
+    )
+    .describe("Details about what's being ordered, donated, deposited, etc."),
+})
+
+// also validate not both destination_value_usd and destination_amount are present
+export const zDepositPayOrder = z.object({
+  metadata: zPayOrderMetadata.optional(),
+  destination_value_usd: z.number().optional()
+    .refine((val) => val === undefined || Number(val) > 0, {
+      message: "destination_value_usd must be greater than zero if defined",
+    }),
+  destination_currency: z.object({
+    chain_id: z.number(),
+    address: z.string().nullable(),
+  }),
+  destination_amount: z.string().optional()
+    .refine((val) => val === undefined || Number(val) > 0, {
+      message: "destination_amount must be greater than zero if defined",
+    }),
+  receiving_address: z.string().min(1),
+}).refine(
+  (data) =>
+    !(data.destination_value_usd && data.destination_amount), // Ensure not both are present
+  {
+    message: "Only one of destination_value_usd or destination_amount should be present.",
+    path: ["destination_value_usd", "destination_amount"],
+  }
+);
+
+export type PayOrderMetadata = z.infer<typeof zPayOrderMetadata>
+
+export enum PayOrderStatus {
+  PENDING = "PENDING",
+  FAILED = "FAILED",
+  AWAITING_PAYMENT = "AWAITING_PAYMENT",
+  AWAITING_CONFIRMATION = "AWAITING_CONFIRMATION",
+  EXECUTING_ORDER = "EXECUTING_ORDER",
+  COMPLETED = "COMPLETED",
+  EXPIRED = "EXPIRED",
+  REFUNDED = "REFUNDED",
+}
+
+export type PayOrder = {
+  id: string
+
+  mode: PayOrderMode.SALE | PayOrderMode.DEPOSIT
+  status: PayOrderStatus
+  metadata?: PayOrderMetadata
+  expires_at?: Date
+
+  source_currency?: Currency
+  source_amount?: CurrencyAmount
+  deposit_tx_hash?: string
+
+  destination_currency?: Currency
+  destination_amount?: CurrencyAmount
+  receiving_tx_hash?: string
+
+  receiving_address?: string
+  refund_address?: string
+  deposit_address?: string
+
+  refund_tx_hash?: string
+}
+
+export interface CurrencyWithAmount extends Currency {
+  currency_amount: CurrencyAmount
+}
+
+export interface CurrencyWithBalance extends CurrencyWithAmount {
+  balance?: CurrencyAmount
+}
+
+export interface CurrencyAmount {
+  ui_amount: number
+  raw_amount: bigint
+  value_usd: number
+}
+
+export type OnChainCall = {
+  to: Address
+  data: Hex
+  value: bigint
+}
+
+export const emptyOnChainCall: OnChainCall = {
+  to: zeroAddress,
+  data: "0x",
+  value: BigInt(0),
+}
+
+export const zUUID = z.string().uuid()
+
+export type UUID = z.infer<typeof zUUID>
+
+export type PaymentCreationErrorEvent = {
+  type: "payment_creation_error"
+  errorMessage: string
+}
+
+export type PaymentStartedEvent = {
+  type: "payment_started"
+  paymentId: string
+  chainId: number
+  txHash: Hex | string | null
+}
+
+export type PaymentCompletedEvent = {
+  type: "payment_completed"
+  paymentId: UUID
+  chainId: number
+  txHash: Hex | string
+}
+
+export type PaymentBouncedEvent = {
+  type: "payment_bounced"
+  paymentId: UUID
+  chainId: number
+  txHash: Hex | string
+}
+
+export type PayEvent =
+  | PaymentStartedEvent
+  | PaymentCompletedEvent
+  | PaymentBouncedEvent
+
+export interface WebhookEndpoint {
+  id: string
+  organization_id: string
+  active: boolean
+  url: string
+  webhook_secret: string
+  subscription_events: WebhookEventStatus[]
+  created_at: Date
+}
+
+export enum WebhookEventStatus {
+  ORDER_CREATED = "ORDER_CREATED",
+  ORDER_AWAITING_PAYMENT = "ORDER_AWAITING_PAYMENT",
+  ORDER_CONFIRMING = "ORDER_CONFIRMING",
+  ORDER_EXECUTING = "ORDER_EXECUTING",
+  ORDER_COMPLETED = "ORDER_COMPLETED",
+  ORDER_ERROR = "ORDER_ERROR",
+  ORDER_REFUNDED = "ORDER_REFUNDED"
+}
+
+export interface WebhookEvent {
+  id: UUID
+  endpoint: WebhookEndpoint
+  body: PayEvent
+  status: WebhookEventStatus
+  //deliveries: WebhookDelivery[]
+  createdAt: Date
+}
+
+// export interface WebhookDelivery {
+//   id: UUID
+//   eventId: UUID
+//   httpStatus: number | null
+//   body: string | null
+//   createdAt: Date
+// }

package/src/common/retryBackoff.ts

@@ -0,0 +1,24 @@
+// Retries a function up to a maximum number of times, with exponential backoff.
+// Current settings, max total wait time is ~10 seconds.
+export async function retryBackoff<T>(
+  name: string,
+  fn: () => Promise<T>,
+  maxRetries = 5,
+  backoffFn: (i: number) => number = (i) => Math.min(2000, 250 * 2 ** i)
+): Promise<T> {
+  for (let i = 1; ; i++) {
+    try {
+      return await fn()
+    } catch (e) {
+      if (i <= maxRetries) {
+        const sleepMs = backoffFn(i)
+        await new Promise((r) => setTimeout(r, sleepMs))
+      } else {
+        console.warn(`[RETRY] ${name} QUITTING after try ${i}, error: ${e}`)
+        break
+      }
+    }
+  }
+  // TODO: add performance logging
+  throw new Error(`too many retries: ${name}`)
+}

package/src/common/time.ts

@@ -0,0 +1,78 @@
+import { i18n, Locale } from "./i18n"
+
+/** Returns current unix time, in seconds */
+export function now() {
+  return Math.floor(Date.now() / 1000)
+}
+
+/** Returns "now", "1m", "2h", etc. Long form: "just now", "1m ago", ... */
+export function timeAgo(
+  sinceS: number,
+  locale?: Locale,
+  nowS?: number,
+  long?: boolean
+): string {
+  const i18 = i18n(locale).time
+  if (nowS == null) {
+    nowS = now()
+  }
+
+  const seconds = Math.floor(nowS - sinceS)
+  if (seconds < 60) {
+    return i18.now(long)
+  }
+  const minutes = Math.floor(seconds / 60)
+  if (minutes < 60) {
+    return i18.minutesAgo(minutes, long)
+  }
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) {
+    return i18.hoursAgo(hours, long)
+  }
+  const days = Math.floor(hours / 24)
+  return `${days}d${long ? " ago" : ""}`
+}
+
+/** Returns "soon", "1d", "2d", etc. Long form: "in 1d", "in 2d", ... */
+export function daysUntil(
+  untilS: number,
+  locale?: Locale,
+  nowS?: number,
+  long?: boolean
+): string {
+  const i18 = i18n(locale).time
+  if (nowS == null) {
+    nowS = now()
+  }
+
+  const seconds = Math.floor(untilS - nowS)
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+  const days = Math.floor(hours / 24)
+  if (days < 1) {
+    return i18.soon()
+  }
+  return i18.inDays(days, long)
+}
+
+/** Returns eg "12/11/2023, 10:44" */
+export function timeString(s: number) {
+  const date = new Date(s * 1000)
+  return date.toLocaleString([], {
+    year: "numeric",
+    month: "numeric",
+    day: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+    dayPeriod: "short",
+  })
+}
+
+/** Returns eg "Aug 2023" */
+export function timeMonth(s: number) {
+  const date = new Date(s * 1000)
+  return date.toLocaleString([], {
+    month: "short",
+    year: "numeric",
+  })
+}

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export { useIsMobile } from "./use-is-mobile";

package/src/hooks/use-is-mobile.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from "react"
+import { isMobile } from "../utils/browser"
+
+export function useIsMobile() {
+  const [mobile, setMobile] = useState(isMobile())
+
+  useEffect(() => {
+    const handleResize = () => {
+      setMobile(isMobile())
+    }
+    window.addEventListener("resize", handleResize)
+    return () => window.removeEventListener("resize", handleResize)
+  }, [])
+
+  return mobile
+}

package/src/utils/account.ts

@@ -0,0 +1,3 @@
+export function shortenAddress(address: string, length = 4): string {
+  return `${address.slice(0, 2 + length)}…${address.slice(-length)}`
+}

package/src/utils/browser.ts

@@ -0,0 +1,24 @@
+import { detect } from "detect-browser"
+
+const detectBrowser = () => {
+    const browser = detect()
+    return browser?.name ?? ""
+}
+const detectOS = () => {
+    const browser = detect()
+    return browser?.os ?? ""
+}
+
+const isIOS = () => {
+    const os = detectOS()
+    return os.toLowerCase().includes("ios")
+}
+const isAndroid = () => {
+    const os = detectOS()
+    return os.toLowerCase().includes("android")
+}
+const isMobile = () => {
+    return isAndroid() || isIOS()
+}
+
+export { detectBrowser, detectOS, isAndroid, isIOS, isMobile }

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from "./account"
+export * from "./browser"
+export * from "./plurar"

package/src/utils/plurar.ts

@@ -0,0 +1,5 @@
+export const withPlural = (totalQuantity: number, singular: string, plural: string) => {
+    if (totalQuantity == 1) return `${totalQuantity} ${singular}`;
+    else return `${totalQuantity} ${plural}`;
+  };
+