@iamgame/wallet-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,470 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+type AuthMethod = "siws" | "telegram";
+interface IUserIdentity {
+    id: string;
+    type: AuthMethod;
+    /** For SIWS: base58 Solana pubkey. For Telegram: numeric user id as string. */
+    externalId: string;
+}
+interface IUser {
+    id: string;
+    appId: string;
+    studioUserId?: string;
+    primaryIdentity: IUserIdentity;
+    identities: IUserIdentity[];
+    createdAt: string;
+}
+/** SIWS challenge issued by the signer; the client signs it with its external wallet. */
+interface ISiwsChallenge {
+    nonce: string;
+    domain: string;
+    statement: string;
+    uri: string;
+    /** ISO timestamp; rejected if older than the freshness window on verify. */
+    issuedAt: string;
+    /** ISO timestamp after which the challenge cannot be redeemed. */
+    expiresAt: string;
+}
+interface ISiwsVerifyRequest {
+    challenge: ISiwsChallenge;
+    /** base58 Solana pubkey */
+    publicKey: string;
+    /** base64 ed25519 signature over the challenge message */
+    signature: string;
+}
+interface ITelegramVerifyRequest {
+    /** Raw `window.Telegram.WebApp.initData` string (URL-encoded). */
+    initData: string;
+}
+interface ISession {
+    /** Short-lived JWT (1h) signed with IAMGame session secret. Sent as bearer. */
+    accessToken: string;
+    /** Longer-lived (7d) refresh token. */
+    refreshToken: string;
+    expiresAt: string;
+    user: IUser;
+}
+
+type WalletCustody = "operator" | "self";
+type WalletStatus = "active" | "exported" | "archived";
+interface IWallet {
+    id: string;
+    userId: string;
+    appId: string;
+    /** base58 Solana pubkey */
+    address: string;
+    custody: WalletCustody;
+    status: WalletStatus;
+    createdAt: string;
+}
+interface ITokenBalance {
+    /** "SOL" or an SPL mint address. */
+    mint: string;
+    /** Stringified BigInt of base units (lamports for SOL, micro-units for USDC, etc.). */
+    amount: string;
+    decimals: number;
+    symbol?: string;
+}
+interface IWalletBalance {
+    walletId: string;
+    address: string;
+    tokens: ITokenBalance[];
+    /** Updated-at ISO timestamp for the cached snapshot; clients can re-fetch if stale. */
+    asOf: string;
+}
+interface IExportPreflightResponse {
+    /** Whether export is currently allowed. */
+    allowed: boolean;
+    /** Human-readable reason when not allowed (e.g. balance gate). */
+    reason?: string;
+    /** Lamports of SOL required to satisfy the balance gate. */
+    minBalanceLamports: string;
+    /** Lamports of SOL currently in W_old. */
+    currentBalanceLamports: string;
+    /** Lamports of SOL that will be bootstrapped into W_new. */
+    bootstrapLamports: string;
+}
+interface IExportInitiateRequest {
+    /** Idempotency key on the wallet level (one export per id). */
+    idempotencyKey: string;
+}
+interface IExportInitiateResponse {
+    /** base58 Solana pubkey of the new IAMGame wallet (W_new). */
+    newWalletAddress: string;
+    /** base58 ed25519 private key of W_old, revealed once. Never persisted server-side after this call. */
+    exportedPrivateKey: string;
+    /** Signature of the bootstrap transfer tx (W_old -> W_new). */
+    bootstrapTxSignature: string;
+}
+
+interface ISignActionRequest {
+    walletId: string;
+    /** base64-encoded serialized Solana transaction (versioned or legacy). */
+    txBase64: string;
+    /** Optional client-supplied label used in audit log. */
+    label?: string;
+}
+interface ISignActionResponse {
+    /** base64-encoded fully signed transaction, ready to submit to RPC. */
+    signedTxBase64: string;
+    /** Solana transaction signature (base58) for tracking. */
+    signature: string;
+}
+interface IWithdrawRequest {
+    walletId: string;
+    /** base58 destination Solana address. */
+    toAddress: string;
+    /** "SOL" or SPL mint address. */
+    mint: string;
+    /** Stringified BigInt of base units to transfer. */
+    amount: string;
+    idempotencyKey: string;
+}
+interface IWithdrawResponse {
+    /** Solana transaction signature (base58). */
+    signature: string;
+    status: "submitted" | "confirmed" | "failed";
+}
+
+type WebhookEventType = "user.created" | "user.suspended" | "wallet.created" | "wallet.exported" | "wallet.migrated" | "compliance.passed" | "compliance.failed" | "compliance.review_required" | "deposit.received" | "withdrawal.completed" | "withdrawal.failed";
+interface IWebhookEnvelope<T = unknown> {
+    id: string;
+    type: WebhookEventType;
+    /** ISO timestamp the event was generated. */
+    createdAt: string;
+    appId: string;
+    /** Monotonically increasing per-app sequence number; lets consumers detect gaps/reorders. */
+    sequence: number;
+    data: T;
+}
+interface IWebhookSignatureHeader {
+    /** `t=<unix>,v1=<hex hmac>` — Stripe-style. */
+    raw: string;
+    timestamp: number;
+    signature: string;
+}
+
+type IAMGameErrorCode = "auth/invalid_signature" | "auth/challenge_expired" | "auth/challenge_already_redeemed" | "auth/invalid_init_data" | "auth/init_data_stale" | "auth/init_data_replayed" | "auth/missing_token" | "auth/invalid_token" | "auth/expired_token" | "wallet/not_found" | "wallet/insufficient_balance" | "wallet/export_blocked" | "wallet/already_exported" | "user/not_found" | "user/suspended" | "compliance/blocked" | "sign/invalid_transaction" | "sign/wallet_archived" | "sign/internal_failure" | "withdrawal/insufficient_balance" | "withdrawal/limit_exceeded" | "ratelimit/exceeded" | "idempotency/key_in_use" | "validation/bad_request" | "server/internal";
+interface IIAMGameErrorEnvelope {
+    code: IAMGameErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+
+type ComplianceModuleType = "kyc" | "aml" | "screening" | "sanctions";
+type ComplianceStatus = "not_started" | "pending" | "passed" | "failed" | "review_required";
+interface IComplianceState {
+    userId: string;
+    moduleType: ComplianceModuleType;
+    status: ComplianceStatus;
+    /** Provider-specific reference (e.g. Smile ID job id) for debugging. */
+    providerRef?: string;
+    updatedAt: string;
+}
+
+interface ISessionStorage {
+    get(): ISession | null;
+    set(session: ISession | null): void;
+}
+declare const localStorageSession: ISessionStorage;
+declare const inMemorySession: () => ISessionStorage;
+
+interface IAMGameClientOptions {
+    publishableKey: string;
+    /** Base URL incl. version path, e.g. "https://api.solven.xyz/v1" or "http://localhost:4100/v1". */
+    baseUrl: string;
+    storage?: ISessionStorage;
+    fetchImpl?: typeof fetch;
+}
+declare class IAMGameClient {
+    private readonly opts;
+    constructor(options: IAMGameClientOptions);
+    requestSiwsChallenge(publicKey: string): Promise<ISiwsChallenge>;
+    verifySiws(req: ISiwsVerifyRequest): Promise<ISession>;
+    verifyTelegram(req: ITelegramVerifyRequest): Promise<ISession>;
+    refreshSession(): Promise<ISession | null>;
+    logout(): Promise<void>;
+    getSession(): ISession | null;
+    getMe(): Promise<IUser>;
+    getMyWallet(): Promise<IWallet>;
+    getBalance(walletId: string): Promise<IWalletBalance>;
+    signAction(req: ISignActionRequest, idempotencyKey?: string): Promise<ISignActionResponse>;
+    withdraw(req: IWithdrawRequest): Promise<IWithdrawResponse>;
+    exportPreflight(walletId: string): Promise<IExportPreflightResponse>;
+    exportWallet(walletId: string, idempotencyKey: string): Promise<IExportInitiateResponse>;
+    private publicCall;
+    private userCall;
+    private doFetch;
+}
+
+declare class IAMGameSdkError extends Error {
+    readonly code: IAMGameErrorCode | "client/network" | "client/aborted";
+    readonly httpStatus?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(args: {
+        code: IAMGameErrorCode | "client/network" | "client/aborted";
+        message: string;
+        httpStatus?: number;
+        details?: Record<string, unknown>;
+    });
+    static fromEnvelope(envelope: IIAMGameErrorEnvelope, httpStatus: number): IAMGameSdkError;
+}
+
+interface IExternalWalletAdapter {
+    /** Returns the wallet's public key (base58). May trigger a connect prompt. */
+    connect(): Promise<{
+        publicKey: string;
+    }>;
+    /** Disconnect the wallet, if supported. Some adapters no-op. */
+    disconnect?(): Promise<void>;
+    /**
+     * Sign an arbitrary UTF-8 message and return a detached ed25519 signature (base64).
+     * Both Phantom and Solflare expose this via signMessage(Uint8Array) → { signature: Uint8Array }.
+     */
+    signMessage(message: string): Promise<{
+        signature: string;
+        publicKey: string;
+    }>;
+}
+/**
+ * Default adapter for the Phantom-style `window.solana` injection.
+ * Usage: pass `phantomAdapter()` to IAMGameLogin or call useIAMGameAuth().connectExternal.
+ */
+declare function phantomAdapter(): IExternalWalletAdapter;
+
+interface IUseIAMGameAuth {
+    user: IUser | null;
+    status: "loading" | "anonymous" | "authenticated";
+    /** Run the SIWS flow with the supplied external wallet adapter. */
+    connectExternal: (adapter: IExternalWalletAdapter) => Promise<void>;
+    /** Run the Telegram TMA flow. Reads `window.Telegram.WebApp.initData` and posts to IAMGame. */
+    connectTelegram: () => Promise<void>;
+    logout: () => Promise<void>;
+}
+declare function useIAMGameAuth(): IUseIAMGameAuth;
+declare function useIAMGameWallet(): IWallet | null;
+declare function useIAMGameBalance(walletId: string | null, pollMs?: number): IWalletBalance | null;
+interface IUseIAMGameSign {
+    signAction: (args: {
+        walletId: string;
+        txBase64: string;
+        label?: string;
+        idempotencyKey?: string;
+    }) => Promise<{
+        signedTxBase64: string;
+        signature: string;
+    }>;
+}
+declare function useIAMGameSign(): IUseIAMGameSign;
+interface IUseIAMGameExport {
+    preflight: IExportPreflightResponse | null;
+    refreshPreflight: () => Promise<void>;
+    exportKey: (idempotencyKey: string) => Promise<IExportInitiateResponse>;
+}
+declare function useIAMGameExport(walletId: string | null): IUseIAMGameExport;
+interface IUseIAMGameTransferIn {
+    /** Returns the destination address (the user's IAMGame wallet) for the top-up. */
+    destinationAddress: string | null;
+}
+declare function useIAMGameTransferIn(): IUseIAMGameTransferIn;
+
+interface IAMGameLoginTheme {
+    primary?: string;
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    /** Surface for secondary (un-detected wallet) buttons. */
+    surface?: string;
+    border?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+interface CommonProps {
+    theme?: IAMGameLoginTheme;
+    /**
+     * Optional override for the default wallet picker. Pass a single adapter
+     * factory to force one wallet; omit to render the multi-wallet picker.
+     */
+    adapterFactory?: () => IExternalWalletAdapter;
+    /** Called once a session is successfully created. */
+    onSignIn?: () => void;
+    title?: React$1.ReactNode;
+    subtitle?: React$1.ReactNode;
+    /**
+     * If true and TMA context is detected, runs Telegram verify on mount with
+     * no clicks. Defaults to true.
+     */
+    autoTelegram?: boolean;
+}
+type IAMGameLoginProps = CommonProps;
+interface IAMGameLoginModalProps extends CommonProps {
+    isOpen: boolean;
+    onClose: () => void;
+    /** Backdrop click closes by default. Set false to disable. */
+    closeOnBackdrop?: boolean;
+    /** Esc key closes by default. Set false to disable. */
+    closeOnEscape?: boolean;
+}
+declare function IAMGameLogin(props: IAMGameLoginProps): react_jsx_runtime.JSX.Element | null;
+declare function IAMGameLoginModal(props: IAMGameLoginModalProps): React$1.ReactPortal | null;
+
+interface IAMGameAddressTheme {
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    surface?: string;
+    border?: string;
+    primary?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+interface IAMGameAddressProps {
+    theme?: IAMGameAddressTheme;
+    /** Number of leading + trailing chars shown in the truncated address. Default 6. */
+    truncateChars?: number;
+    /** Render a custom QR code element. Receives the wallet address. Omit to skip QR. */
+    renderQr?: (address: string) => React$1.ReactNode;
+    /** Show copy button. Default true. */
+    showCopy?: boolean;
+    /** Label text above the address. Default "Wallet Address". */
+    label?: string;
+}
+declare function IAMGameAddress(props: IAMGameAddressProps): react_jsx_runtime.JSX.Element | null;
+
+interface IAMGameBalanceTheme {
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    surface?: string;
+    border?: string;
+    primary?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+interface IAMGameBalanceProps {
+    theme?: IAMGameBalanceTheme;
+    /** Polling interval in ms. Default 15000. */
+    pollMs?: number;
+    /** Show only specific mints. Omit to show all. */
+    filterMints?: string[];
+    /** Show a manual refresh button. Default true. */
+    showRefresh?: boolean;
+    /** Label text. Default "Balance". */
+    label?: string;
+    /** Compact mode — single line, no card chrome. Default false. */
+    compact?: boolean;
+}
+declare function IAMGameBalance(props: IAMGameBalanceProps): react_jsx_runtime.JSX.Element | null;
+
+interface IAMGameWithdrawTheme {
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    surface?: string;
+    border?: string;
+    primary?: string;
+    danger?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+interface IAMGameWithdrawProps {
+    theme?: IAMGameWithdrawTheme;
+    /** Restrict to a single mint. Omit to let user pick SOL or available SPL tokens. */
+    mint?: string;
+    /** Called after a successful withdrawal with the tx signature. */
+    onSuccess?: (signature: string) => void;
+    /** Called on error. */
+    onError?: (error: Error) => void;
+    /** Label text. Default "Withdraw". */
+    label?: string;
+}
+declare function IAMGameWithdraw(props: IAMGameWithdrawProps): react_jsx_runtime.JSX.Element | null;
+
+interface IAMGameExportTheme {
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    surface?: string;
+    border?: string;
+    primary?: string;
+    danger?: string;
+    radius?: string;
+    fontFamily?: string;
+}
+interface IAMGameExportProps {
+    theme?: IAMGameExportTheme;
+    /** Called after successful export. */
+    onSuccess?: (newWalletAddress: string) => void;
+    /** Called on error. */
+    onError?: (error: Error) => void;
+    /** Label text. Default "Export Wallet". */
+    label?: string;
+}
+declare function IAMGameExport(props: IAMGameExportProps): react_jsx_runtime.JSX.Element | null;
+
+type WalletId = "phantom" | "solflare" | "backpack";
+interface WalletDescriptor {
+    id: WalletId;
+    name: string;
+    /** Whether the wallet's injection is detectable on `window` right now. */
+    detected: boolean;
+    /** Download / discovery URL for users who don't have it installed. */
+    downloadUrl: string;
+    buildAdapter: () => IExternalWalletAdapter;
+}
+declare const solflareAdapter: () => IExternalWalletAdapter;
+declare const backpackAdapter: () => IExternalWalletAdapter;
+declare function listSupportedWallets(): WalletDescriptor[];
+
+interface TransferInDeps {
+    Connection: any;
+    PublicKey: any;
+    Transaction: any;
+    SystemProgram: any;
+    TOKEN_PROGRAM_ID?: any;
+    createTransferCheckedInstruction?: any;
+    getAssociatedTokenAddressSync?: any;
+    createAssociatedTokenAccountInstruction?: any;
+    getMint?: any;
+}
+interface BuildSolTransferOpts {
+    /** base58 source wallet (the external wallet). */
+    fromAddress: string;
+    /** base58 destination wallet (the user's IAMGame wallet). */
+    toAddress: string;
+    /** Stringified BigInt of lamports. */
+    lamports: string;
+    /** RPC endpoint. */
+    rpcUrl: string;
+}
+interface BuildSplTransferOpts extends BuildSolTransferOpts {
+    /** base58 SPL mint address (USDC, USDT, etc.). */
+    mint: string;
+    /** Base-unit amount (the raw integer, not the decimal float). */
+    amount: string;
+}
+/**
+ * Builds an unsigned base64-serialized SOL transfer from the user's external
+ * wallet to the IAMGame wallet. Caller signs the returned bytes with their
+ * external wallet adapter and submits to RPC.
+ */
+declare function buildSolTransferIn(deps: TransferInDeps, opts: BuildSolTransferOpts): Promise<string>;
+/**
+ * Builds an unsigned SPL transfer. If the destination's ATA doesn't exist, an
+ * AssociatedTokenAccount create instruction is included; the payer is the
+ * source wallet (the user pays the ~0.002 SOL rent for opening the ATA).
+ */
+declare function buildSplTransferIn(deps: TransferInDeps, opts: BuildSplTransferOpts): Promise<string>;
+
+declare function getTelegramInitData(): string | null;
+declare function isTelegramMiniApp(): boolean;
+declare function notifyTelegramReady(): void;
+
+interface IAMGameWalletProviderProps extends IAMGameClientOptions {
+    children: React.ReactNode;
+}
+declare const IAMGameWalletProvider: React.FC<IAMGameWalletProviderProps>;
+
+export { type AuthMethod, type BuildSolTransferOpts, type BuildSplTransferOpts, type ComplianceModuleType, type ComplianceStatus, IAMGameClient as IAMGameWalletClient, type IAMGameClientOptions as IAMGameWalletClientOptions, IAMGameWalletProvider, type IAMGameWalletProviderProps, type IComplianceState, type IExportInitiateRequest, type IExportInitiateResponse, type IExportPreflightResponse, type IExternalWalletAdapter, type ISession, type ISessionStorage, type ISignActionRequest, type ISignActionResponse, type ISiwsChallenge, type ISiwsVerifyRequest, type ITelegramVerifyRequest, type ITokenBalance, type IUseIAMGameAuth as IUseWalletAuth, type IUseIAMGameExport as IUseWalletExport, type IUseIAMGameSign as IUseWalletSign, type IUseIAMGameTransferIn as IUseWalletTransferIn, type IUser, type IUserIdentity, type IWallet, type IWalletBalance, type IIAMGameErrorEnvelope as IWalletErrorEnvelope, type IWebhookEnvelope, type IWebhookSignatureHeader, type IWithdrawRequest, type IWithdrawResponse, type TransferInDeps, IAMGameAddress as WalletAddress, type IAMGameAddressProps as WalletAddressProps, type IAMGameAddressTheme as WalletAddressTheme, IAMGameBalance as WalletBalance, type IAMGameBalanceProps as WalletBalanceProps, type IAMGameBalanceTheme as WalletBalanceTheme, type WalletCustody, type WalletDescriptor, type IAMGameErrorCode as WalletErrorCode, IAMGameExport as WalletExport, type IAMGameExportProps as WalletExportProps, type IAMGameExportTheme as WalletExportTheme, type WalletId, IAMGameLogin as WalletLogin, IAMGameLoginModal as WalletLoginModal, type IAMGameLoginModalProps as WalletLoginModalProps, type IAMGameLoginProps as WalletLoginProps, type IAMGameLoginTheme as WalletLoginTheme, IAMGameSdkError as WalletSdkError, type WalletStatus, IAMGameWithdraw as WalletWithdraw, type IAMGameWithdrawProps as WalletWithdrawProps, type IAMGameWithdrawTheme as WalletWithdrawTheme, type WebhookEventType, backpackAdapter, buildSolTransferIn, buildSplTransferIn, getTelegramInitData, inMemorySession, isTelegramMiniApp, listSupportedWallets, localStorageSession, notifyTelegramReady, phantomAdapter, solflareAdapter, useIAMGameWallet as useWallet, useIAMGameAuth as useWalletAuth, useIAMGameBalance as useWalletBalance, useIAMGameExport as useWalletExport, useIAMGameSign as useWalletSign, useIAMGameTransferIn as useWalletTransferIn };