@anywalletkit/wallet-ton 0.0.0-stage → 0.2.0

package/dist/history.d.cts

@@ -0,0 +1,163 @@
+import { ChainTx, HistoryPage, HistorySource, HistoryQuery, ChainTransfer, ChainCall } from '@anywalletkit/core';
+
+type HistoryFetch = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/** Which indexer answered: tonapi events or toncenter v3 transactions. */
+type TonHistoryBackend = 'tonapi' | 'toncenter';
+/** Options for `createTonHistory`: tonapi first, toncenter v3 as the fallback. */
+interface TonHistoryOptions {
+    /** tonapi root. Default `https://tonapi.io` (`https://testnet.tonapi.io` on testnet). `null` disables tonapi. */
+    tonapiUrl?: string | null;
+    /** tonapi Bearer key. Keyless tonapi allows ~1 request/s. */
+    apiKey?: string;
+    /** toncenter root for the v3 fallback. Default `https://toncenter.com` (`https://testnet.toncenter.com`). `null` disables it. */
+    toncenterUrl?: string | null;
+    /** toncenter `X-API-Key`. */
+    toncenterApiKey?: string;
+    network?: 'mainnet' | 'testnet';
+    fetch?: HistoryFetch;
+    /** tonapi requests per second. Default 1 without a key, 10 with one. */
+    rateLimit?: number;
+    /** Per request, ms. Default 15 000. */
+    timeoutMs?: number;
+}
+interface TonHistoryRaw {
+    backend: TonHistoryBackend;
+    /** The tonapi account event, or the toncenter v3 transaction row. */
+    event: unknown;
+    /** tonapi flagged the event as scam. */
+    scam?: boolean;
+    /** tonapi `value_flow` for the account when it had to be fetched to recover jetton movements. */
+    valueFlow?: unknown;
+}
+interface TonChainTx extends ChainTx {
+    /** Mirrors `raw.scam`; the app hides these by default. */
+    scam?: boolean;
+    raw: TonHistoryRaw;
+}
+interface TonHistoryPage extends HistoryPage {
+    items: TonChainTx[];
+    backend?: TonHistoryBackend;
+}
+/**
+ * TON history from tonapi events with a toncenter v3 fallback. Build it with `createTonHistory`.
+ */
+interface TonHistorySource extends HistorySource {
+    listActivity(address: string, query?: HistoryQuery): Promise<TonHistoryPage>;
+    getTransaction(hash: string, address: string): Promise<TonChainTx | undefined>;
+}
+/** Every configured history backend failed (or none was configured). */
+declare class HistoryUnavailableError extends Error {
+    readonly chain: string;
+    readonly reason: string;
+    readonly attempts: readonly string[];
+    constructor(chain: string, reason: string, attempts?: readonly string[]);
+}
+interface TonHistoryCursor {
+    v: 1;
+    b: TonHistoryBackend;
+    /** Next page = events / transactions with `lt < this` (decimal string). */
+    lt: string;
+}
+declare function encodeCursor(c: TonHistoryCursor): string;
+declare function decodeCursor(s: string): TonHistoryCursor;
+/** Any spelling → raw lowercase `wc:hex`; unparsable input is returned as-is. */
+declare function rawTonAddress(a: string): string;
+interface TonapiAccount {
+    address: string;
+    is_wallet?: boolean;
+    is_scam?: boolean;
+    name?: string;
+}
+interface TonapiJetton {
+    address: string;
+    symbol?: string;
+    decimals?: number;
+    name?: string;
+}
+interface TonapiAction {
+    type: string;
+    status: 'ok' | 'failed' | string;
+    [body: string]: unknown;
+}
+interface TonapiEvent {
+    event_id: string;
+    account?: TonapiAccount;
+    timestamp: number;
+    lt: number | string;
+    in_progress: boolean;
+    is_scam: boolean;
+    actions: TonapiAction[];
+    /** Account-scoped events only: TON the account lost beyond its actions (negative = fees). */
+    extra?: number;
+    value_flow?: Array<{
+        account: TonapiAccount;
+        ton: number;
+        jettons?: Array<{
+            jetton: TonapiJetton;
+            quantity: number | string;
+        }>;
+    }>;
+}
+interface MappedActions {
+    transfers: ChainTransfer[];
+    call?: ChainCall;
+    /** Who initiated the event as far as the first action tells. */
+    initiator?: string;
+    /** The event needs `value_flow` to recover a jetton movement tonapi did not spell out (unstake requests). */
+    needsValueFlow?: {
+        counterparty: string;
+    };
+}
+/** tonapi actions → transfers + the contract call. Only `ok` actions move value. */
+declare function mapActions(actions: TonapiAction[]): MappedActions;
+/** The account's jetton deltas from `value_flow` as transfers against `counterparty`. */
+declare function valueFlowTransfers(event: TonapiEvent, own: string, counterparty: string): ChainTransfer[];
+declare function mapTonapiEvent(chain: string, address: string, own: string, event: TonapiEvent, valueFlow?: TonapiEvent): TonChainTx;
+interface V3Message {
+    source?: string | null;
+    destination?: string | null;
+    value?: string | null;
+    opcode?: string | null;
+    decoded_opcode?: string | null;
+}
+interface V3Transaction {
+    account: string;
+    /** base64. */
+    hash: string;
+    lt: string;
+    now: number;
+    total_fees: string;
+    description?: {
+        aborted?: boolean;
+        compute_ph?: {
+            success?: boolean;
+            exit_code?: number;
+            skipped?: boolean;
+        };
+        action?: {
+            success?: boolean;
+        };
+    };
+    in_msg?: V3Message | null;
+    out_msgs?: V3Message[];
+}
+/** Reduced mapping: TON in / out and op codes of the account's own transaction; jettons are not visible here. */
+declare function mapToncenterTransaction(chain: string, address: string, row: V3Transaction): TonChainTx;
+/** Tonviewer link for a transaction. */
+declare function tonExplorerTxUrl(hash: string, network?: 'mainnet' | 'testnet'): string;
+/**
+ * A `HistorySource` for TON: tonapi account events first, toncenter v3 when
+ * tonapi is down or disabled. Both page by `lt`, so a cursor from one backend
+ * resumes on the other.
+ */
+declare function createTonHistory(options?: TonHistoryOptions): TonHistorySource;
+
+export { type HistoryFetch, HistoryUnavailableError, type TonChainTx, type TonHistoryBackend, type TonHistoryCursor, type TonHistoryOptions, type TonHistoryPage, type TonHistoryRaw, type TonHistorySource, type TonapiAction, type TonapiEvent, type V3Transaction, createTonHistory, decodeCursor, encodeCursor, mapActions, mapTonapiEvent, mapToncenterTransaction, rawTonAddress, tonExplorerTxUrl, valueFlowTransfers };

package/dist/history.d.ts

@@ -0,0 +1,163 @@
+import { ChainTx, HistoryPage, HistorySource, HistoryQuery, ChainTransfer, ChainCall } from '@anywalletkit/core';
+
+type HistoryFetch = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+/** Which indexer answered: tonapi events or toncenter v3 transactions. */
+type TonHistoryBackend = 'tonapi' | 'toncenter';
+/** Options for `createTonHistory`: tonapi first, toncenter v3 as the fallback. */
+interface TonHistoryOptions {
+    /** tonapi root. Default `https://tonapi.io` (`https://testnet.tonapi.io` on testnet). `null` disables tonapi. */
+    tonapiUrl?: string | null;
+    /** tonapi Bearer key. Keyless tonapi allows ~1 request/s. */
+    apiKey?: string;
+    /** toncenter root for the v3 fallback. Default `https://toncenter.com` (`https://testnet.toncenter.com`). `null` disables it. */
+    toncenterUrl?: string | null;
+    /** toncenter `X-API-Key`. */
+    toncenterApiKey?: string;
+    network?: 'mainnet' | 'testnet';
+    fetch?: HistoryFetch;
+    /** tonapi requests per second. Default 1 without a key, 10 with one. */
+    rateLimit?: number;
+    /** Per request, ms. Default 15 000. */
+    timeoutMs?: number;
+}
+interface TonHistoryRaw {
+    backend: TonHistoryBackend;
+    /** The tonapi account event, or the toncenter v3 transaction row. */
+    event: unknown;
+    /** tonapi flagged the event as scam. */
+    scam?: boolean;
+    /** tonapi `value_flow` for the account when it had to be fetched to recover jetton movements. */
+    valueFlow?: unknown;
+}
+interface TonChainTx extends ChainTx {
+    /** Mirrors `raw.scam`; the app hides these by default. */
+    scam?: boolean;
+    raw: TonHistoryRaw;
+}
+interface TonHistoryPage extends HistoryPage {
+    items: TonChainTx[];
+    backend?: TonHistoryBackend;
+}
+/**
+ * TON history from tonapi events with a toncenter v3 fallback. Build it with `createTonHistory`.
+ */
+interface TonHistorySource extends HistorySource {
+    listActivity(address: string, query?: HistoryQuery): Promise<TonHistoryPage>;
+    getTransaction(hash: string, address: string): Promise<TonChainTx | undefined>;
+}
+/** Every configured history backend failed (or none was configured). */
+declare class HistoryUnavailableError extends Error {
+    readonly chain: string;
+    readonly reason: string;
+    readonly attempts: readonly string[];
+    constructor(chain: string, reason: string, attempts?: readonly string[]);
+}
+interface TonHistoryCursor {
+    v: 1;
+    b: TonHistoryBackend;
+    /** Next page = events / transactions with `lt < this` (decimal string). */
+    lt: string;
+}
+declare function encodeCursor(c: TonHistoryCursor): string;
+declare function decodeCursor(s: string): TonHistoryCursor;
+/** Any spelling → raw lowercase `wc:hex`; unparsable input is returned as-is. */
+declare function rawTonAddress(a: string): string;
+interface TonapiAccount {
+    address: string;
+    is_wallet?: boolean;
+    is_scam?: boolean;
+    name?: string;
+}
+interface TonapiJetton {
+    address: string;
+    symbol?: string;
+    decimals?: number;
+    name?: string;
+}
+interface TonapiAction {
+    type: string;
+    status: 'ok' | 'failed' | string;
+    [body: string]: unknown;
+}
+interface TonapiEvent {
+    event_id: string;
+    account?: TonapiAccount;
+    timestamp: number;
+    lt: number | string;
+    in_progress: boolean;
+    is_scam: boolean;
+    actions: TonapiAction[];
+    /** Account-scoped events only: TON the account lost beyond its actions (negative = fees). */
+    extra?: number;
+    value_flow?: Array<{
+        account: TonapiAccount;
+        ton: number;
+        jettons?: Array<{
+            jetton: TonapiJetton;
+            quantity: number | string;
+        }>;
+    }>;
+}
+interface MappedActions {
+    transfers: ChainTransfer[];
+    call?: ChainCall;
+    /** Who initiated the event as far as the first action tells. */
+    initiator?: string;
+    /** The event needs `value_flow` to recover a jetton movement tonapi did not spell out (unstake requests). */
+    needsValueFlow?: {
+        counterparty: string;
+    };
+}
+/** tonapi actions → transfers + the contract call. Only `ok` actions move value. */
+declare function mapActions(actions: TonapiAction[]): MappedActions;
+/** The account's jetton deltas from `value_flow` as transfers against `counterparty`. */
+declare function valueFlowTransfers(event: TonapiEvent, own: string, counterparty: string): ChainTransfer[];
+declare function mapTonapiEvent(chain: string, address: string, own: string, event: TonapiEvent, valueFlow?: TonapiEvent): TonChainTx;
+interface V3Message {
+    source?: string | null;
+    destination?: string | null;
+    value?: string | null;
+    opcode?: string | null;
+    decoded_opcode?: string | null;
+}
+interface V3Transaction {
+    account: string;
+    /** base64. */
+    hash: string;
+    lt: string;
+    now: number;
+    total_fees: string;
+    description?: {
+        aborted?: boolean;
+        compute_ph?: {
+            success?: boolean;
+            exit_code?: number;
+            skipped?: boolean;
+        };
+        action?: {
+            success?: boolean;
+        };
+    };
+    in_msg?: V3Message | null;
+    out_msgs?: V3Message[];
+}
+/** Reduced mapping: TON in / out and op codes of the account's own transaction; jettons are not visible here. */
+declare function mapToncenterTransaction(chain: string, address: string, row: V3Transaction): TonChainTx;
+/** Tonviewer link for a transaction. */
+declare function tonExplorerTxUrl(hash: string, network?: 'mainnet' | 'testnet'): string;
+/**
+ * A `HistorySource` for TON: tonapi account events first, toncenter v3 when
+ * tonapi is down or disabled. Both page by `lt`, so a cursor from one backend
+ * resumes on the other.
+ */
+declare function createTonHistory(options?: TonHistoryOptions): TonHistorySource;
+
+export { type HistoryFetch, HistoryUnavailableError, type TonChainTx, type TonHistoryBackend, type TonHistoryCursor, type TonHistoryOptions, type TonHistoryPage, type TonHistoryRaw, type TonHistorySource, type TonapiAction, type TonapiEvent, type V3Transaction, createTonHistory, decodeCursor, encodeCursor, mapActions, mapTonapiEvent, mapToncenterTransaction, rawTonAddress, tonExplorerTxUrl, valueFlowTransfers };

package/dist/history.js

@@ -0,0 +1,25 @@
+import {
+  HistoryUnavailableError,
+  createTonHistory,
+  decodeCursor,
+  encodeCursor,
+  mapActions,
+  mapTonapiEvent,
+  mapToncenterTransaction,
+  rawTonAddress,
+  tonExplorerTxUrl,
+  valueFlowTransfers
+} from "./chunk-BLWBC6L2.js";
+export {
+  HistoryUnavailableError,
+  createTonHistory,
+  decodeCursor,
+  encodeCursor,
+  mapActions,
+  mapTonapiEvent,
+  mapToncenterTransaction,
+  rawTonAddress,
+  tonExplorerTxUrl,
+  valueFlowTransfers
+};
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}