@fibo-crypto/react-sdk 0.3.0

package/dist/client.d.ts

@@ -0,0 +1,284 @@
+interface EvmBalanceResponse {
+    address: string;
+    chain: 'base';
+    eth: {
+        wei: string;
+        formatted: string;
+    };
+    usdc: {
+        raw: string;
+        formatted: string;
+    };
+}
+interface QuoteFee {
+    label: string;
+    amount: string;
+    currency: string;
+    usd?: string;
+}
+interface SwapBreakdown {
+    source: {
+        token: string;
+        chain_id: number;
+        amount: string;
+        symbol: string;
+        decimals: number;
+    };
+    destination: {
+        token: string;
+        chain_id: number;
+        amount: string;
+        amount_min: string;
+        symbol: string;
+        decimals: number;
+    };
+    fees: QuoteFee[];
+    source_usd: string;
+    slippage_bps: number;
+    estimated_completion_seconds: number;
+}
+interface BuyEureBreakdown {
+    source: {
+        amount: string;
+        currency: 'EUR';
+    };
+    destination: {
+        amount: string;
+        currency: 'EURe';
+        chain: string;
+    };
+    fees: QuoteFee[];
+    ramping_provider: 'monerium';
+    estimated_completion_seconds: number;
+}
+type QuoteResponse = {
+    quote_id: string;
+    ttl_seconds: number;
+    expires_at: string;
+    kind: 'swap';
+    breakdown: SwapBreakdown;
+} | {
+    quote_id: string;
+    ttl_seconds: number;
+    expires_at: string;
+    kind: 'buy_eure';
+    breakdown: BuyEureBreakdown;
+};
+interface SignEip7702Payload {
+    contractAddress: `0x${string}`;
+}
+type PrepareStep = {
+    step_index: number;
+    kind: 'sign_eip7702';
+    chain_id: number;
+    payload: SignEip7702Payload;
+} | {
+    step_index: number;
+    kind: 'sign_evm_tx';
+    chain_id: number;
+    payload: unknown;
+} | {
+    step_index: number;
+    kind: 'redirect_ramping';
+    provider: string;
+    widget_url: string;
+};
+interface PrepareTxResponse {
+    transaction_id: string;
+    steps: PrepareStep[];
+}
+interface Eip7702Signature {
+    r: `0x${string}`;
+    s: `0x${string}`;
+    yParity: number;
+    /** Stringified bigint when the legacy-signature variant comes back from
+     *  viem's signedAuthorization. Never transport raw bigint over JSON. */
+    v?: string;
+    address: `0x${string}`;
+    chainId: number;
+    nonce: number;
+}
+interface SignMessageStep {
+    kind: 'sign_message';
+    chain_id: number;
+    payload: {
+        hash: `0x${string}`;
+    };
+}
+interface SubmitResponse {
+    transaction_id: string;
+    status: string;
+    /** D5: present when /submit successfully fetched a MEE quote and needs the
+     *  user to sign quote.hash before /execute-signed-quote can run. */
+    next_step?: SignMessageStep;
+    payment_info?: unknown;
+    tx_hash: string | null;
+    super_hash: string | null;
+    tracker_url: string | null;
+    note?: string;
+}
+interface ExecuteResponse {
+    transaction_id: string;
+    status: string;
+    super_hash: `0x${string}`;
+    tracker_url: string;
+}
+interface TransactionState {
+    id: string;
+    quoteId: string;
+    status: string;
+    txHash?: string;
+    superHash?: string;
+    failureReason?: string;
+}
+/**
+ * Full transaction row returned by GET /v1/transactions (list endpoint).
+ * Wider shape than `TransactionState` which is just the per-id lookup.
+ */
+type TransactionStatus = 'quoted' | 'preparing' | 'pending_signature' | 'submitted' | 'confirmed' | 'failed' | 'expired';
+interface Transaction {
+    id: string;
+    tenant_id: string;
+    user_id: string;
+    kind: string;
+    status: TransactionStatus;
+    user_address: string | null;
+    source_amount: string | null;
+    source_currency: string | null;
+    source_chain_id: number | null;
+    dest_amount: string | null;
+    dest_currency: string | null;
+    dest_chain_id: number | null;
+    usd_volume: string | null;
+    tx_hash: string | null;
+    super_hash: string | null;
+    tracker_url: string | null;
+    failure_reason: string | null;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+}
+interface TransactionListResponse {
+    data: Transaction[];
+    has_more: boolean;
+    next_before?: string;
+}
+interface TransactionListParams {
+    /** Maximum rows (1..200, default 50). */
+    limit?: number;
+    /** Filter by status. */
+    status?: TransactionStatus;
+    /** ISO 8601 cursor — return only rows created before this timestamp. */
+    before?: string;
+}
+interface MoneriumOrderResponse {
+    order_id: string;
+    status: string;
+    iban: string;
+    reference: string;
+    widget_url?: string;
+}
+
+/** Default API base URL — exported so callers and FiboProvider stay in sync. */
+declare const DEFAULT_BASE_URL = "https://api.fibo-crypto.fr";
+interface FiboClientConfig {
+    /** API base URL — defaults to https://api.fibo-crypto.fr if omitted. */
+    baseUrl?: string;
+    /**
+     * Bearer token used on every request. MUST be a publishable key
+     * (`pk_test_*` / `pk_live_*`) when used from browser contexts —
+     * secret keys (`sk_*`) are rejected to prevent accidentally embedding
+     * them in client bundles where any visitor could extract them.
+     *
+     * For trusted server-side contexts (Node scripts, CLI tools, backend-
+     * to-backend integrations) where an `sk_*` is intentional, set
+     * `allowSecretKey: true` to bypass the guard.
+     */
+    apiKey: string;
+    /**
+     * Opt-out of the `pk_*`-only check. Use only in trusted server-side
+     * contexts. Defaults to false. The `@fibo-crypto/cli` admin tool passes true.
+     */
+    allowSecretKey?: boolean;
+}
+interface FiboApiErrorInfo {
+    status: number;
+    code: string;
+    message: string;
+    details?: unknown;
+    request_id?: string;
+}
+declare class FiboApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    readonly request_id?: string;
+    constructor(info: FiboApiErrorInfo);
+}
+interface RequestArgs {
+    method: 'GET' | 'POST' | 'DELETE' | 'PUT';
+    path: string;
+    body?: unknown;
+    /** Pass to cancel the fetch — e.g., on component unmount or address change. */
+    signal?: AbortSignal;
+}
+interface FiboClient {
+    request<T>(args: RequestArgs): Promise<T>;
+    health(): Promise<{
+        ok: boolean;
+        ts: number;
+    }>;
+    quoteSwap(params: {
+        source: {
+            token: string;
+            chain_id: number;
+            amount: string;
+        };
+        destination: {
+            token: string;
+            chain_id: number;
+        };
+        user_address: string;
+    }): Promise<Extract<QuoteResponse, {
+        kind: 'swap';
+    }>>;
+    quoteBuyEure(params: {
+        fiat_amount: string;
+        user_address: string;
+    }): Promise<Extract<QuoteResponse, {
+        kind: 'buy_eure';
+    }>>;
+    prepareTx(params: {
+        quote_id: string;
+        user_address: string;
+    }): Promise<PrepareTxResponse>;
+    submit(params: {
+        quote_id: string;
+        transaction_id: string;
+        signatures: {
+            step_index: number;
+            signature: Eip7702Signature;
+        }[];
+    }): Promise<SubmitResponse>;
+    executeSignedQuote(params: {
+        transaction_id: string;
+        quote_signature: `0x${string}`;
+    }): Promise<ExecuteResponse>;
+    getTransaction(id: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<TransactionState>;
+    listTransactions(params?: TransactionListParams, opts?: {
+        signal?: AbortSignal;
+    }): Promise<TransactionListResponse>;
+    moneriumCreateOrder(params: {
+        user_address: string;
+        amount: string;
+        chain?: string;
+    }): Promise<MoneriumOrderResponse>;
+    getEvmBalance(address: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<EvmBalanceResponse>;
+}
+declare function createFiboClient(config: FiboClientConfig): FiboClient;
+
+export { type BuyEureBreakdown, DEFAULT_BASE_URL, type Eip7702Signature, type EvmBalanceResponse, type ExecuteResponse, FiboApiError, type FiboApiErrorInfo, type FiboClient, type FiboClientConfig, type MoneriumOrderResponse, type PrepareStep, type PrepareTxResponse, type QuoteFee, type QuoteResponse, type SignEip7702Payload, type SignMessageStep, type SubmitResponse, type SwapBreakdown, type Transaction, type TransactionListParams, type TransactionListResponse, type TransactionState, type TransactionStatus, createFiboClient };

package/dist/client.js

@@ -0,0 +1,3 @@
+export { DEFAULT_BASE_URL, FiboApiError, createFiboClient } from './chunk-FRD4NVYJ.js';
+//# sourceMappingURL=client.js.map
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"client.js"}

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { FiboClient, EvmBalanceResponse, Transaction, TransactionStatus, QuoteResponse, ExecuteResponse } from './client.js';
+export { BuyEureBreakdown, DEFAULT_BASE_URL, Eip7702Signature, FiboApiError, FiboApiErrorInfo, FiboClientConfig, MoneriumOrderResponse, PrepareStep, PrepareTxResponse, QuoteFee, SignEip7702Payload, SignMessageStep, SubmitResponse, SwapBreakdown, TransactionListParams, TransactionListResponse, TransactionState, createFiboClient } from './client.js';
+
+interface FiboTheme {
+    /** Accent color — must be a hex string starting with `#` (e.g. `#5B44F9`). */
+    accent?: `#${string}`;
+}
+type FiboLoginMethod = 'email' | 'google' | 'apple' | 'github' | 'discord' | 'twitter' | 'sms' | 'passkey';
+interface FiboProviderProps {
+    /** Publishable Fibo API key — `pk_test_*` or `pk_live_*`. */
+    publishableKey: string;
+    /** API base URL. Defaults to https://api.fibo-crypto.fr. */
+    baseUrl?: string;
+    /**
+     * Your own user identifier for this user. Echoed back on `wallet.created` /
+     * `tx.confirmed` webhooks so your backend can join Fibo's records with yours.
+     */
+    externalUserId?: string;
+    /**
+     * Privy login methods shown in the UI. Defaults to email + Google + Apple.
+     */
+    loginMethods?: FiboLoginMethod[];
+    /** UI theming applied to Privy modals. */
+    theme?: FiboTheme;
+    /**
+     * Override Fibo's shared Privy app id. Rarely needed — default covers all
+     * integrators per ADR 0002. Use only if your tenant has been provisioned
+     * with a dedicated Privy app (custom contractual setup).
+     */
+    privyAppIdOverride?: string;
+    children: ReactNode;
+}
+declare function FiboProvider({ publishableKey, baseUrl, externalUserId, loginMethods, theme, privyAppIdOverride, children, }: FiboProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function useFiboApi(): FiboClient;
+
+interface FiboUser {
+    /** Privy user DID. Use as a stable identifier across sessions / devices. */
+    id: string;
+    email?: string;
+    /** ISO string when the user was first created on Privy. */
+    createdAt?: string;
+}
+interface FiboAuthState {
+    /** True once Privy has finished bootstrapping (cookies / local storage read). */
+    isReady: boolean;
+    /** True once the user has completed login. */
+    isAuthenticated: boolean;
+    /** The current user, or null when not authenticated / not ready yet. */
+    user: FiboUser | null;
+    /** Open the Privy login modal. */
+    login: () => void;
+    /** Log the user out — clears cookies and disconnects embedded wallets. */
+    logout: () => Promise<void>;
+}
+declare function useFiboAuth(): FiboAuthState;
+
+interface FiboBalanceState {
+    /** Latest balance, or null while loading / on error / no address. */
+    balance: EvmBalanceResponse | null;
+    isLoading: boolean;
+    error: Error | null;
+    /** Manually re-fetch (e.g., after a swap completed). */
+    refetch: () => Promise<void>;
+}
+interface UseFiboBalanceOptions {
+    /**
+     * Auto-refresh every N milliseconds. Defaults to no polling.
+     * Set to ~10000 for a "live" balance display.
+     */
+    refreshIntervalMs?: number;
+}
+/**
+ * Fetches the on-chain balance for an EVM address. Returns `{ balance, isLoading, error, refetch }`.
+ * Pass `null` for `address` to skip the fetch (useful while waiting for a wallet to be ready).
+ *
+ * In-flight fetches are cancelled when `address` changes or the component unmounts —
+ * stale results never overwrite the current state.
+ */
+declare function useFiboBalance(address: string | null, opts?: UseFiboBalanceOptions): FiboBalanceState;
+
+interface FiboTransactionsState {
+    transactions: Transaction[];
+    /** True if more pages exist beyond the current view (use `nextBefore` cursor). */
+    hasMore: boolean;
+    /** Cursor to pass as `before` for the next page. */
+    nextBefore: string | undefined;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+interface UseFiboTransactionsOptions {
+    /** Filter by status. */
+    status?: TransactionStatus;
+    /** Max rows per fetch (1..200, default 50). */
+    limit?: number;
+    /** ISO 8601 cursor for pagination. Pass `state.nextBefore` to get the next page. */
+    before?: string;
+    /** Auto-refresh interval in ms. Defaults to no polling. */
+    refreshIntervalMs?: number;
+}
+declare function useFiboTransactions(opts?: UseFiboTransactionsOptions): FiboTransactionsState;
+
+type BitcoinChain = 'bitcoin-taproot' | 'bitcoin-segwit';
+interface FiboBitcoinWallet {
+    address: string;
+    chainType: BitcoinChain;
+    publicKey?: string;
+    walletIndex?: number;
+}
+interface FiboWalletState {
+    /** Privy ready flag — true once the SDK has bootstrapped. Wait on this before signing. */
+    isReady: boolean;
+    /** Convenience flattened addresses for common single-wallet flows. */
+    addresses: {
+        evm: string | null;
+        solana: string | null;
+        /** First taproot BTC address, if any. */
+        bitcoin: string | null;
+    };
+    /** All Bitcoin wallets (the user may own multiple BTC addresses). */
+    bitcoinWallets: FiboBitcoinWallet[];
+    /**
+     * Provision a new BTC taproot wallet for the user. Resolves with the new wallet.
+     * BTC isn't auto-created on login by Privy — call this when the user wants to receive BTC.
+     */
+    createBitcoinWallet: () => Promise<FiboBitcoinWallet>;
+}
+declare function useFiboWallet(): FiboWalletState;
+
+type FiboSwapPhase = 'idle' | 'quoting' | 'preparing' | 'signing_authorization' | 'submitting' | 'signing_mee_quote' | 'executing' | 'done' | 'error';
+interface FiboSwapQuoteParams {
+    source: {
+        token: string;
+        chainId: number;
+        amount: string;
+    };
+    destination: {
+        token: string;
+        chainId: number;
+    };
+    /**
+     * The user's EVM address. If omitted, the hook auto-resolves it from
+     * Privy's first embedded EVM wallet. Pass explicitly if your app uses
+     * a different wallet (multi-account scenarios).
+     */
+    userAddress?: string;
+}
+interface FiboSwapState {
+    /** Latest quote returned by quote(). null until the first quote() call. */
+    currentQuote: Extract<QuoteResponse, {
+        kind: 'swap';
+    }> | null;
+    /** ExecuteResponse on success: { super_hash, tracker_url, ... }. */
+    result: ExecuteResponse | null;
+    /** Latest error from any phase. Cleared by the next quote() / executeSwap() call. */
+    error: Error | null;
+    /** High-level state machine — useful for "Loading..." vs "Awaiting signature..." UI. */
+    phase: FiboSwapPhase;
+    /** True if quote has expired (auto-tick). False if no quote yet. */
+    isExpired: boolean;
+    /** Seconds until current quote expires. 0 if no quote / expired. */
+    expiresInSeconds: number;
+    /** Convenience boolean: phase is not 'idle' / 'done' / 'error'. */
+    isLoading: boolean;
+    /**
+     * Fetch a swap quote. Resolves with the QuoteResponse (also exposed via
+     * state.currentQuote). Auto-resolves user_address from Privy if not passed.
+     */
+    quote: (params: FiboSwapQuoteParams) => Promise<Extract<QuoteResponse, {
+        kind: 'swap';
+    }>>;
+    /**
+     * Execute the current quote (the last one returned by quote()).
+     * Runs the full prepare → sign → submit → sign MEE → execute ceremony.
+     * Resolves with the ExecuteResponse on success.
+     *
+     * Throws if no quote is pending or if the quote has expired (caller
+     * should call quote() again first).
+     */
+    executeSwap: () => Promise<ExecuteResponse>;
+    /** Clear the current quote + result + error. Returns the hook to 'idle'. */
+    reset: () => void;
+}
+declare function useFiboSwap(): FiboSwapState;
+
+export { type BitcoinChain, EvmBalanceResponse, ExecuteResponse, type FiboAuthState, type FiboBalanceState, type FiboBitcoinWallet, FiboClient, type FiboLoginMethod, FiboProvider, type FiboProviderProps, type FiboSwapPhase, type FiboSwapQuoteParams, type FiboSwapState, type FiboTheme, type FiboTransactionsState, type FiboUser, type FiboWalletState, QuoteResponse, Transaction, TransactionStatus, type UseFiboBalanceOptions, type UseFiboTransactionsOptions, useFiboApi, useFiboAuth, useFiboBalance, useFiboSwap, useFiboTransactions, useFiboWallet };