tapimo 0.0.0 → 0.0.2

package/dist/apps/transfers.d.ts

@@ -0,0 +1,589 @@
+import { type Context } from 'hono';
+import { Hex } from 'ox';
+import * as z from 'zod/mini';
+import type * as App from '../App.js';
+import * as Response from '../internal/Response.js';
+import * as Schema from '../internal/Schema.js';
+import type * as Tidx from '../internal/Tidx.js';
+export declare const signature = "event Transfer(address indexed from, address indexed to, uint256 value)";
+/** Zod schemas owned by the transfer handlers. */
+export declare namespace schema {
+    /**
+     * The token moved by a transfer: its contract address and the transferred
+     * amount, plus the trimmed token reference spread in when requested via
+     * `include=token`. Reference fields are absent on the base (no-`include`)
+     * response and best-effort when requested (a row whose metadata is
+     * unavailable keeps just `address`/`amount`). Shared by every per-row
+     * transfer response across the API.
+     *
+     * The optional metadata fields are inlined here (rather than spread from
+     * `Tokens.schema.Token` via `z.partial`) so this module avoids referencing
+     * the `tokens` schema namespace at module-init time — `transfers` and
+     * `tokens` import each other for runtime helpers (`Transfers.query`,
+     * `Tokens.resolveToken`), and the schema-evaluation back-edge would
+     * otherwise deadlock the namespace.
+     */
+    const SourceToken: z.ZodMiniObject<{
+        address: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+        amount: z.ZodMiniString<string>;
+        currency: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        decimals: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+        logoUri: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        symbol: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        verified: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+    }, z.core.$strip>;
+    /**
+     * Filter predicates shared verbatim by the `GET /transfers` list query
+     * ({@link getTransfers.Query}, which spreads `Predicates.shape`) and `transfer`
+     * webhook subscriptions (`Webhooks.schema.TransferFilters`), so the two never
+     * drift. Read-only concerns (pagination, windowing, ordering, `include`,
+     * `chainId`) are *not* here — they live only on the list query and have no
+     * meaning for an open-ended subscription. Consumers that need different
+     * per-field docs (e.g. the list query's mutually-exclusive `address`) override
+     * that one field.
+     */
+    const Predicates: z.ZodMiniObject<{
+        address: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>>;
+        recipient: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>>;
+        sender: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>>;
+        token: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>>;
+    }, z.core.$strip>;
+    /** Schemas for the getTransfers (list) operation. */
+    namespace getTransfers {
+        /** Optional related resources that callers opt into via `include`. */
+        const Include: z.ZodMiniEnum<{
+            crossToken: "crossToken";
+            memo: "memo";
+            token: "token";
+            totalCount: "totalCount";
+        }>;
+        /**
+         * Parses a comma-separated `include` query value into a list of optional
+         * resources to embed. Extra lookups (token metadata, the `TransferWithMemo`
+         * memo/attribution decode, the capped total count) each run only when their
+         * resource is requested, keeping the base transfer page fast.
+         */
+        const includeQuery: z.ZodMiniPipe<z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniUnknown>, z.ZodMiniTransform<string[], unknown>>, z.ZodMiniArray<z.ZodMiniEnum<{
+            crossToken: "crossToken";
+            memo: "memo";
+            token: "token";
+            totalCount: "totalCount";
+        }>>>;
+        /**
+         * Query parameters for top-level transfer list requests. `address` is a
+         * convenience for "either side" — passing it alongside an explicit
+         * `sender` or `recipient` is rejected as ambiguous (the helper would have
+         * to AND/OR them in a non-obvious way).
+         */
+        const Query: z.ZodMiniObject<{
+            recipient: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>>;
+            sender: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>>;
+            token: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>>;
+            address: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>>;
+            'blockNumber.from': z.ZodMiniOptional<z.ZodMiniNumber<unknown>>;
+            'blockNumber.to': z.ZodMiniOptional<z.ZodMiniNumber<unknown>>;
+            chainId: z.ZodMiniOptional<z.ZodMiniPipe<z.ZodMiniUnion<readonly [z.ZodMiniPipe<z.ZodMiniEnum<{
+                mainnet: "mainnet";
+                testnet: "testnet";
+            }>, z.ZodMiniTransform<4217 | 42431, "mainnet" | "testnet">>, z.ZodMiniNumber<unknown>]>, z.ZodMiniNumber<number>>>;
+            cursor: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            include: z.ZodMiniPipe<z.ZodMiniPipe<z.ZodMiniOptional<z.ZodMiniUnknown>, z.ZodMiniTransform<string[], unknown>>, z.ZodMiniArray<z.ZodMiniEnum<{
+                crossToken: "crossToken";
+                memo: "memo";
+                token: "token";
+                totalCount: "totalCount";
+            }>>>;
+            limit: z.ZodMiniDefault<z.ZodMiniNumber<unknown>>;
+            order: z.ZodMiniDefault<z.ZodMiniEnum<{
+                asc: "asc";
+                desc: "desc";
+            }>>;
+            page: z.ZodMiniOptional<z.ZodMiniNumber<unknown>>;
+            'timestamp.from': z.ZodMiniOptional<z.ZodMiniISODateTime>;
+            'timestamp.to': z.ZodMiniOptional<z.ZodMiniISODateTime>;
+        }, z.core.$strict>;
+        /**
+         * A single transfer row. The token contract is carried per-row via
+         * `sourceToken.address` because `/transfers` is unscoped and rows can span
+         * multiple contracts.
+         */
+        const Transfer: z.ZodMiniObject<{
+            attribution: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            blockNumber: z.ZodMiniNumber<number>;
+            destinationToken: z.ZodMiniOptional<z.ZodMiniObject<{
+                address: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+                amount: z.ZodMiniString<string>;
+                currency: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                decimals: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+                logoUri: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                symbol: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                verified: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+            }, z.core.$strip>>;
+            id: z.ZodMiniString<string>;
+            logIndex: z.ZodMiniNumber<number>;
+            memo: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            recipient: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+            sender: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+            sourceToken: z.ZodMiniObject<{
+                address: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+                amount: z.ZodMiniString<string>;
+                currency: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                decimals: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+                logoUri: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                symbol: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                verified: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+            }, z.core.$strip>;
+            timestamp: z.ZodMiniISODateTime;
+            transactionHash: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+        }, z.core.$strip>;
+        /** Page of TIP-20 token transfers across the chain, ordered by block then log index. */
+        const Response: z.ZodMiniObject<{
+            data: z.ZodMiniArray<z.ZodMiniObject<{
+                attribution: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                blockNumber: z.ZodMiniNumber<number>;
+                destinationToken: z.ZodMiniOptional<z.ZodMiniObject<{
+                    address: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+                    amount: z.ZodMiniString<string>;
+                    currency: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                    decimals: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+                    logoUri: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                    name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                    symbol: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                    verified: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+                }, z.core.$strip>>;
+                id: z.ZodMiniString<string>;
+                logIndex: z.ZodMiniNumber<number>;
+                memo: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                recipient: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+                sender: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+                sourceToken: z.ZodMiniObject<{
+                    address: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+                    amount: z.ZodMiniString<string>;
+                    currency: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                    decimals: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
+                    logoUri: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                    name: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                    symbol: z.ZodMiniOptional<z.ZodMiniString<string>>;
+                    verified: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+                }, z.core.$strip>;
+                timestamp: z.ZodMiniISODateTime;
+                transactionHash: z.ZodMiniPipe<z.ZodMiniTemplateLiteral<`0x${string}`>, z.ZodMiniTransform<`0x${string}`, `0x${string}`>>;
+            }, z.core.$strip>>;
+            meta: z.ZodMiniOptional<z.ZodMiniObject<{
+                totalCountCapped: z.ZodMiniBoolean<boolean>;
+                totalCount: z.ZodMiniNumber<number>;
+            }, z.core.$strip>>;
+            nextCursor: z.ZodMiniNullable<z.ZodMiniString<string>>;
+        }, z.core.$strip>;
+    }
+}
+/** Creates transfer handlers. */
+export declare function transfers(): import("hono/hono-base").HonoBase<App.Environment, {
+    "/": {
+        $get: {
+            output: null;
+            outputFormat: "body";
+            status: 402;
+            input: {
+                query?: {
+                    recipient?: string | string[];
+                    sender?: string | string[];
+                    token?: string | string[];
+                    address?: string | string[];
+                    'blockNumber.from'?: string | string[];
+                    'blockNumber.to'?: string | string[];
+                    chainId?: string | string[];
+                    cursor?: string | string[];
+                    include?: string | string[];
+                    limit?: string | string[];
+                    order?: string | string[];
+                    page?: string | string[];
+                    'timestamp.from'?: string | string[];
+                    'timestamp.to'?: string | string[];
+                } | undefined;
+            };
+        } | {
+            output: {
+                error: {
+                    code: "api_key_malformed";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
+            };
+            outputFormat: "json";
+            status: 400;
+            input: {
+                query?: {
+                    recipient?: string | string[];
+                    sender?: string | string[];
+                    token?: string | string[];
+                    address?: string | string[];
+                    'blockNumber.from'?: string | string[];
+                    'blockNumber.to'?: string | string[];
+                    chainId?: string | string[];
+                    cursor?: string | string[];
+                    include?: string | string[];
+                    limit?: string | string[];
+                    order?: string | string[];
+                    page?: string | string[];
+                    'timestamp.from'?: string | string[];
+                    'timestamp.to'?: string | string[];
+                } | undefined;
+            };
+        } | {
+            output: {
+                error: {
+                    code: "api_key_invalid" | "api_key_missing";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
+            };
+            outputFormat: "json";
+            status: 401;
+            input: {
+                query?: {
+                    recipient?: string | string[];
+                    sender?: string | string[];
+                    token?: string | string[];
+                    address?: string | string[];
+                    'blockNumber.from'?: string | string[];
+                    'blockNumber.to'?: string | string[];
+                    chainId?: string | string[];
+                    cursor?: string | string[];
+                    include?: string | string[];
+                    limit?: string | string[];
+                    order?: string | string[];
+                    page?: string | string[];
+                    'timestamp.from'?: string | string[];
+                    'timestamp.to'?: string | string[];
+                } | undefined;
+            };
+        } | {
+            output: {
+                error: {
+                    code: "api_key_forbidden";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
+            };
+            outputFormat: "json";
+            status: 403;
+            input: {
+                query?: {
+                    recipient?: string | string[];
+                    sender?: string | string[];
+                    token?: string | string[];
+                    address?: string | string[];
+                    'blockNumber.from'?: string | string[];
+                    'blockNumber.to'?: string | string[];
+                    chainId?: string | string[];
+                    cursor?: string | string[];
+                    include?: string | string[];
+                    limit?: string | string[];
+                    order?: string | string[];
+                    page?: string | string[];
+                    'timestamp.from'?: string | string[];
+                    'timestamp.to'?: string | string[];
+                } | undefined;
+            };
+        } | {
+            output: {
+                error: {
+                    code: "payment_required" | "rate_limit_exceeded";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
+            };
+            outputFormat: "json";
+            status: 429;
+            input: {
+                query?: {
+                    recipient?: string | string[];
+                    sender?: string | string[];
+                    token?: string | string[];
+                    address?: string | string[];
+                    'blockNumber.from'?: string | string[];
+                    'blockNumber.to'?: string | string[];
+                    chainId?: string | string[];
+                    cursor?: string | string[];
+                    include?: string | string[];
+                    limit?: string | string[];
+                    order?: string | string[];
+                    page?: string | string[];
+                    'timestamp.from'?: string | string[];
+                    'timestamp.to'?: string | string[];
+                } | undefined;
+            };
+        } | {
+            output: {
+                error: {
+                    code: "query_invalid";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
+            };
+            outputFormat: "json";
+            status: 400;
+            input: {
+                query?: {
+                    recipient?: string | string[];
+                    sender?: string | string[];
+                    token?: string | string[];
+                    address?: string | string[];
+                    'blockNumber.from'?: string | string[];
+                    'blockNumber.to'?: string | string[];
+                    chainId?: string | string[];
+                    cursor?: string | string[];
+                    include?: string | string[];
+                    limit?: string | string[];
+                    order?: string | string[];
+                    page?: string | string[];
+                    'timestamp.from'?: string | string[];
+                    'timestamp.to'?: string | string[];
+                } | undefined;
+            };
+        } | {
+            output: {
+                error: {
+                    code: "upstream_error";
+                    details?: readonly Response.error.Detail[] | undefined;
+                    message: string;
+                };
+                requestId: string;
+            };
+            outputFormat: "json";
+            status: 502;
+            input: {
+                query?: {
+                    recipient?: string | string[];
+                    sender?: string | string[];
+                    token?: string | string[];
+                    address?: string | string[];
+                    'blockNumber.from'?: string | string[];
+                    'blockNumber.to'?: string | string[];
+                    chainId?: string | string[];
+                    cursor?: string | string[];
+                    include?: string | string[];
+                    limit?: string | string[];
+                    order?: string | string[];
+                    page?: string | string[];
+                    'timestamp.from'?: string | string[];
+                    'timestamp.to'?: string | string[];
+                } | undefined;
+            };
+        } | {
+            output: {
+                data: {
+                    attribution?: string | undefined;
+                    blockNumber: number;
+                    destinationToken?: {
+                        address: `0x${string}`;
+                        amount: string;
+                        currency?: string | undefined;
+                        decimals?: number | undefined;
+                        logoUri?: string | undefined;
+                        name?: string | undefined;
+                        symbol?: string | undefined;
+                        verified?: boolean | undefined;
+                    } | undefined;
+                    id: string;
+                    logIndex: number;
+                    memo?: string | undefined;
+                    recipient: `0x${string}`;
+                    sender: `0x${string}`;
+                    sourceToken: {
+                        address: `0x${string}`;
+                        amount: string;
+                        currency?: string | undefined;
+                        decimals?: number | undefined;
+                        logoUri?: string | undefined;
+                        name?: string | undefined;
+                        symbol?: string | undefined;
+                        verified?: boolean | undefined;
+                    };
+                    timestamp: string;
+                    transactionHash: `0x${string}`;
+                }[];
+                meta?: {
+                    totalCountCapped: boolean;
+                    totalCount: number;
+                } | undefined;
+                nextCursor: string | null;
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                query?: {
+                    recipient?: string | string[];
+                    sender?: string | string[];
+                    token?: string | string[];
+                    address?: string | string[];
+                    'blockNumber.from'?: string | string[];
+                    'blockNumber.to'?: string | string[];
+                    chainId?: string | string[];
+                    cursor?: string | string[];
+                    include?: string | string[];
+                    limit?: string | string[];
+                    order?: string | string[];
+                    page?: string | string[];
+                    'timestamp.from'?: string | string[];
+                    'timestamp.to'?: string | string[];
+                } | undefined;
+            };
+        };
+    };
+}, "/", "/">;
+/**
+ * Shared TIP-20 `Transfer` page query. Used by `GET /transfers` and the
+ * webhook poller. Builds the signature-decoded `Transfer` CTE query, applies
+ * opaque keyset pagination on `(block_num, log_idx)`, and decodes rows into a
+ * strongly-typed intermediate shape that each caller maps to its own public
+ * response.
+ *
+ * `eitherSide` (the subject address must appear on _either_ side of the
+ * transfer) is exposed alongside the one-sided `sender`/`recipient` filters
+ * because composing it with the keyset cursor pre-WHERE in SQL is awkward at
+ * the call site; the helper takes the knob directly.
+ *
+ * Memoization lives inside the helper under one canonical `transfers:v1:…`
+ * key derived from every filter — so equivalent filter combinations share a
+ * single cache entry. Callers supply only a `timing` label for Server-Timing.
+ */
+export declare function query(c: Context<App.Environment>, options: query.Options): Promise<{
+    data: query.Row[];
+    nextCursor: string | null;
+}>;
+export declare namespace query {
+    /** Options for the shared TIP-20 `Transfer` page query. */
+    type Options = {
+        chainId: z.output<typeof Schema.ChainId>;
+        /** Opaque keyset cursor anchoring the page; omit for the head page. */
+        cursor?: string | undefined;
+        /** Restrict to rows where this address appears on either side. */
+        eitherSide?: z.output<typeof Schema.Address> | undefined;
+        fromBlock?: number | undefined;
+        fromTimestamp?: string | undefined;
+        limit: number;
+        /** 1-indexed page number (positional pagination; exclusive with `cursor`). */
+        page?: number | undefined;
+        order: 'asc' | 'desc';
+        recipient?: z.output<typeof Schema.Address> | undefined;
+        sender?: z.output<typeof Schema.Address> | undefined;
+        /** Server-Timing label for the caller's surface. */
+        timing: string;
+        toBlock?: number | undefined;
+        toTimestamp?: string | undefined;
+        /** Restrict to a single TIP-20 token contract. */
+        token?: z.output<typeof Schema.Address> | undefined;
+    };
+    /** A decoded `Transfer` row before per-surface shaping. */
+    type Row = {
+        /** Token contract that emitted the event. */
+        address: z.output<typeof Schema.Address>;
+        amount: string;
+        blockNumber: number;
+        logIndex: number;
+        recipient: z.output<typeof Schema.Address>;
+        sender: z.output<typeof Schema.Address>;
+        timestamp: string;
+        transactionHash: z.output<typeof Schema.Hash>;
+    };
+    type Page = {
+        data: readonly Row[];
+        nextCursor: string | null;
+    };
+}
+/**
+ * Context-free core of {@link query}: builds the signature-decoded `Transfer`
+ * CTE query, applies keyset pagination on `(block_num, log_idx)`, and decodes
+ * rows. Used by the Hono routes (via {@link query}, which adds Server-Timing +
+ * memoization) and by the webhook poller (uncached, ascending, per-row cursors).
+ */
+export declare function scan(deps: scan.Deps, options: scan.Options): Promise<scan.Page>;
+export declare namespace scan {
+    /** Dependencies for {@link scan}. */
+    type Deps = {
+        /** TIDX query client for the target chain. */
+        tidx: Tidx.Client;
+    };
+    /** Options for {@link scan} (everything {@link query.Options} has except `timing`). */
+    type Options = Omit<query.Options, 'timing'>;
+    /** A decoded `Transfer` row plus its `(block_num, log_idx)` cursor. */
+    type Item = {
+        /** Keyset position of the row. */
+        cursor: readonly [blockNumber: number, logIndex: number];
+        /** The decoded row before per-surface shaping. */
+        data: query.Row;
+    };
+    /** A page of scanned `Transfer` rows. */
+    type Page = {
+        hasMore: boolean;
+        items: readonly Item[];
+        limit: number;
+        nextCursor: string | null;
+    };
+}
+/**
+ * Builds the shared `WHERE` filter clauses for the `Transfer` feed: contract /
+ * subject / sender / recipient / block / timestamp predicates. Shared verbatim
+ * by the page query ({@link scan}) and the capped count ({@link countScan}) so a
+ * `totalCount` always matches the page it annotates; the keyset cursor clause is
+ * page-only and added by {@link scan} on top of these.
+ */
+declare function filterClauses(options: filterClauses.Options): string[];
+declare namespace filterClauses {
+    /** The non-pagination filter fields of {@link scan.Options}. */
+    type Options = Pick<scan.Options, 'eitherSide' | 'fromBlock' | 'fromTimestamp' | 'recipient' | 'sender' | 'toBlock' | 'toTimestamp' | 'token'>;
+}
+/**
+ * Capped total-row count for the `Transfer` feed, sharing {@link query}'s
+ * filters (minus pagination) so the count matches the page it annotates. Timed
+ * and memoized like {@link query}; the result feeds `meta.totalCount`/`totalCountCapped`
+ * when a caller opts in via `include=totalCount`.
+ */
+export declare function count(c: Context<App.Environment>, options: count.Options): Promise<count.Result>;
+export declare namespace count {
+    /** Options for the capped `Transfer` count: {@link query}'s filters plus `timing`. */
+    type Options = Pick<query.Options, 'chainId' | 'eitherSide' | 'fromBlock' | 'fromTimestamp' | 'recipient' | 'sender' | 'timing' | 'toBlock' | 'toTimestamp' | 'token'> & {
+        /** Count folded cross-token transfers instead of raw `Transfer` logs. */
+        crossToken?: boolean | undefined;
+    };
+    /** A capped count result: `totalCountCapped` is `true` when the count hit `Schema.countCap`. */
+    type Result = {
+        totalCountCapped: boolean;
+        totalCount: number;
+    };
+}
+/**
+ * Context-free core of {@link count}: runs a capped `count(*)` over the
+ * signature-decoded `Transfer` CTE under the shared {@link filterClauses}. The
+ * inner `LIMIT Schema.countCap` bounds the scan so the aggregate can't exceed
+ * the indexer's execution budget on the 10⁹-plus row table (an unbounded count
+ * there blows the 5s `max_execution_time`); a result equal to the cap is a
+ * lower bound, surfaced as `totalCountCapped: true`.
+ */
+export declare function countScan(deps: scan.Deps, options: countScan.Options): Promise<count.Result>;
+export declare namespace countScan {
+    /** Options for {@link countScan}: the shared filters plus the target chain. */
+    type Options = filterClauses.Options & Pick<scan.Options, 'chainId'> & {
+        /** Count folded cross-token transfers instead of raw `Transfer` logs. */
+        crossToken?: boolean | undefined;
+    };
+}
+/**
+ * Attempts to decode a bytes32 memo into a human-readable string. MPP
+ * attribution memos encode a service fingerprint, not text — they are
+ * suppressed from the display memo (and resolved to `attribution` instead).
+ * Shared with the activity feed's transfer entries.
+ */
+export declare function memoToString(memo: Hex.Hex): string | undefined;
+export {};
+//# sourceMappingURL=transfers.d.ts.map

package/dist/apps/transfers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfers.d.ts","sourceRoot":"","sources":["../../src/apps/transfers.ts"],"names":[],"mappings":"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"}