cabalspy-id 0.0.0-stage → 0.5.2

package/dist/users-B4r33i4O.d.ts

@@ -0,0 +1,767 @@
+import { d as Chain, S as Scope, ab as Trade, I as ThesisLiveItem, Z as ThesisReactionUpdate, a0 as ThesisRemoved, a as ApiResponse, H as HealthResponse, M as MeResponse, v as Profile, ag as WalletLookupResponse, p as Period, a9 as TrackerResponse, f as HistoryResponse, h as HistoryTrade, j as HoldingsResponse, t as PnlCalendarResponse, m as LeaderboardSort, l as LeaderboardResponse, k as LeaderboardEntry, a3 as ThesisSort, a4 as ThesisStance, y as Thesis, a5 as ThesisSummary, F as ThesisEligibility, G as ThesisEmoji, _ as ThesisReactions, a2 as ThesisReportReason, Q as ThesisNotifications, ah as WebhookEvent } from './types-UZeY9n1e.js';
+
+interface RateLimitInfo {
+    /** Requests per second allowed by the plan. `null` when the header is absent. */
+    limit: number | null;
+    remaining: number | null;
+    /** Seconds until the current one-second window resets. */
+    reset: number | null;
+}
+/** Error body of the Data API: `{"success": false, "error": {...}}`. */
+interface ApiErrorBody {
+    code: string;
+    message: string;
+    request_id: string;
+    /** Link to the error's documentation, e.g. https://docs.cabalspy.xyz/cabalspy-id/errors#wallet_not_found */
+    docs: string;
+    parameter?: string;
+    allowed?: unknown[];
+    /** Set on `plan_user_limit`. */
+    limited?: boolean;
+    [key: string]: unknown;
+}
+interface CabalSpyIDErrorOptions {
+    status?: number;
+    code?: string;
+    requestId?: string;
+    docs?: string;
+    parameter?: string;
+    allowed?: unknown[];
+    rateLimit?: RateLimitInfo;
+    body?: unknown;
+}
+/** Base class for every error thrown by this SDK. */
+declare class CabalSpyIDError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly docs?: string;
+    readonly parameter?: string;
+    readonly allowed?: unknown[];
+    readonly rateLimit: RateLimitInfo;
+    /** The parsed response body, when there was one. */
+    readonly body?: unknown;
+    constructor(message: string, opts?: CabalSpyIDErrorOptions);
+}
+/** 400 — missing_parameter, invalid_parameter, instance_required */
+declare class BadRequestError extends CabalSpyIDError {
+}
+/** 401 — missing_api_key; thesis API: client_id_required, invalid_client */
+declare class AuthenticationError extends CabalSpyIDError {
+}
+/** 403 — invalid_api_key, product_not_enabled, no_instance, scope_not_allowed; thesis API: origin_not_allowed */
+declare class PermissionError extends CabalSpyIDError {
+}
+/**
+ * 403 — plan_user_limit. The person signed in beyond the plan's user limit:
+ * the platform receives no data for them until it upgrades.
+ */
+declare class PlanUserLimitError extends PermissionError {
+    readonly limited: true;
+}
+/** 404 — profile_not_found, wallet_not_found, instance_not_found */
+declare class NotFoundError extends CabalSpyIDError {
+}
+/** 429 — rate_limit_exceeded; thesis API: rate_limited (Retry-After 60) */
+declare class RateLimitError extends CabalSpyIDError {
+    /** Seconds until the next request is allowed, taken from Retry-After. */
+    readonly retryAfter: number | null;
+    constructor(message: string, opts?: CabalSpyIDErrorOptions & {
+        retryAfter?: number | null;
+    });
+}
+/** 5xx — internal_error, service_unavailable */
+declare class ServerError extends CabalSpyIDError {
+}
+/** Network failure, timeout or aborted connection. */
+declare class ConnectionError extends CabalSpyIDError {
+}
+/** Response was not valid JSON, or did not have the expected envelope. */
+declare class InvalidResponseError extends CabalSpyIDError {
+}
+/**
+ * An error from the OpenID Connect endpoints (`/oauth/token`, `/oauth/userinfo`,
+ * `/oauth/revoke`) or from the authorization redirect, in OAuth's own format:
+ * `code` is the OAuth `error` (invalid_grant, invalid_client, access_denied …).
+ */
+declare class OAuthError extends CabalSpyIDError {
+    readonly error: string;
+    readonly errorDescription?: string;
+    constructor(error: string, description?: string, opts?: CabalSpyIDErrorOptions);
+}
+/** An ID or access token failed verification (signature, iss, aud, exp, nonce …). */
+declare class TokenVerificationError extends CabalSpyIDError {
+}
+/** A webhook failed signature or timestamp verification. */
+declare class WebhookVerificationError extends CabalSpyIDError {
+}
+
+/** `trades`: your users' trades. `theses`: new theses, replies, reactions and removals (public, all users). */
+type StreamTopic = 'trades' | 'theses';
+interface StreamOptions {
+    /** What to receive. Default: ['trades'] */
+    events?: StreamTopic[];
+    /** Only this chain. Default: every chain. */
+    blockchain?: Chain;
+    /** Theses of one token only (needs `blockchain`). */
+    mint?: string;
+    /** `global` (every CabalSpy ID user) is Enterprise only. Default: instance */
+    scope?: Scope;
+    /** Instance client_id, when your account has several. */
+    instance?: string;
+    /** Reconnect automatically after a dropped connection. Default: true */
+    reconnect?: boolean;
+    /** Initial reconnect delay in ms, doubling up to maxReconnectDelay. Default: 1000 */
+    reconnectDelay?: number;
+    /** Default: 30_000 */
+    maxReconnectDelay?: number;
+    /**
+     * The server sends a heartbeat every 30 s. When nothing at all arrives for
+     * this many ms, the connection is treated as dead and reopened.
+     * 0 disables the check. Default: 75_000
+     */
+    heartbeatTimeout?: number;
+    /**
+     * WebSocket implementation. Browsers, Deno, Bun and Node 22+ have a global
+     * WebSocket. On Node 18-21, `npm i ws` and pass `{ WebSocketImpl: WebSocket }`.
+     */
+    WebSocketImpl?: unknown;
+}
+interface SubscribedEvent {
+    blockchain: Chain | 'all';
+    scope: Scope;
+    events?: StreamTopic[];
+    mint?: string | null;
+}
+interface HeartbeatEvent {
+    ts: number;
+}
+interface CloseEvent {
+    code?: number;
+    reason?: string;
+}
+interface ReconnectEvent {
+    attempt: number;
+    delay: number;
+}
+interface StreamEventMap {
+    trade: Trade;
+    /** A new thesis (events: theses). */
+    thesis: ThesisLiveItem;
+    /** A new reply to a thesis. */
+    'thesis.reply': ThesisLiveItem;
+    /** Reaction counts of a thesis or reply changed. */
+    'thesis.reaction': ThesisReactionUpdate;
+    /** A thesis or reply was deleted or hidden. */
+    'thesis.removed': ThesisRemoved;
+    subscribed: SubscribedEvent;
+    heartbeat: HeartbeatEvent;
+    pong: Record<string, never>;
+    open: undefined;
+    close: CloseEvent;
+    reconnecting: ReconnectEvent;
+    error: CabalSpyIDError;
+    /** Every parsed message, before dispatch. */
+    message: Record<string, unknown>;
+}
+type StreamEvent = keyof StreamEventMap;
+type Handler$1<T> = (payload: T) => void;
+/**
+ * WebSocket client for the live trade stream.
+ *
+ *   const stream = csid.stream({ blockchain: 'solana' });
+ *   stream.on('trade', (t) => console.log(t.trader?.username, t.transaction_type, t.value_usd));
+ *   await stream.connect();          // resolves once the server confirmed the subscription
+ *
+ * or as an async iterator:
+ *
+ *   for await (const trade of csid.stream()) { … }
+ *
+ * Reconnects with exponential backoff after a dropped connection or a missed
+ * heartbeat. Configuration errors from the server (invalid key, plan without
+ * the stream, …) are fatal: they are emitted as 'error' and stop reconnecting.
+ */
+declare class CabalSpyIDStream {
+    private readonly url;
+    private readonly apiKey;
+    private readonly options;
+    private ws;
+    private readonly opts;
+    private readonly handlers;
+    private reconnectAttempt;
+    private reconnectTimer;
+    private watchdog;
+    private closedByUser;
+    private fatal;
+    constructor(url: string, apiKey: string, options?: StreamOptions);
+    /** True while the socket is open. */
+    get connected(): boolean;
+    /** The stream URL including query parameters, with the key masked. */
+    get safeUrl(): string;
+    private buildUrl;
+    on<E extends StreamEvent>(event: E, handler: Handler$1<StreamEventMap[E]>): this;
+    off<E extends StreamEvent>(event: E, handler: Handler$1<StreamEventMap[E]>): this;
+    private emit;
+    /** Opens the socket. Resolves once the server sent `subscribed`. */
+    connect(): Promise<SubscribedEvent>;
+    private scheduleReconnect;
+    private armWatchdog;
+    private clearWatchdog;
+    /**
+     * Sends a ping; the server answers with 'pong'. Not needed to keep the
+     * connection alive (the server sends heartbeats), and pinging more often
+     * than every 30 s suppresses those heartbeats.
+     */
+    ping(): void;
+    /** Closes the connection and stops reconnecting. */
+    close(): void;
+    /**
+     * Iterates over trades. Connects if needed; ends when close() is called or
+     * a fatal error occurs (which is thrown). Breaking out of the loop closes a
+     * connection the iterator opened.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<Trade, void, void>;
+    /**
+     * Iterates over thesis events (`thesis`, `thesis.reply`, `thesis.reaction`,
+     * `thesis.removed`). Open the stream with `events: ['theses']`.
+     *
+     *   for await (const { event, data } of csid.stream({ events: ['theses'] }).theses()) { … }
+     */
+    theses(): AsyncGenerator<ThesisStreamEvent, void, void>;
+    private iterate;
+}
+/** One thesis event from `stream.theses()`. */
+type ThesisStreamEvent = {
+    event: 'thesis';
+    data: ThesisLiveItem;
+} | {
+    event: 'thesis.reply';
+    data: ThesisLiveItem;
+} | {
+    event: 'thesis.reaction';
+    data: ThesisReactionUpdate;
+} | {
+    event: 'thesis.removed';
+    data: ThesisRemoved;
+};
+
+/** Tokens per connection. */
+declare const MAX_THESES_STREAM_TOKENS = 200;
+interface ThesisTokenRef {
+    blockchain: Chain;
+    mint: string;
+}
+interface ThesesStreamOptions {
+    /** `global` (default): theses from every platform. `instance`: only the ones written on your instance. */
+    scope?: 'global' | 'instance';
+    /** Instance client_id, when your account has several. */
+    instance?: string;
+    /** Default: true */
+    reconnect?: boolean;
+    /** Default: 1000 */
+    reconnectDelay?: number;
+    /** Default: 30_000 */
+    maxReconnectDelay?: number;
+    /** The server sends a heartbeat every 30 s; silence this long reopens the socket. 0 disables. Default: 75_000 */
+    heartbeatTimeout?: number;
+    /** WebSocket implementation for Node < 22 (the `ws` package). */
+    WebSocketImpl?: unknown;
+}
+interface ThesesReadyEvent {
+    scope: 'global' | 'instance';
+    max_tokens: number;
+}
+interface ThesesSubscribedEvent {
+    all: boolean;
+    tokens: ThesisTokenRef[];
+}
+interface ThesesStreamEventMap {
+    ready: ThesesReadyEvent;
+    subscribed: ThesesSubscribedEvent;
+    thesis: ThesisLiveItem;
+    'thesis.reply': ThesisLiveItem;
+    'thesis.reaction': ThesisReactionUpdate;
+    'thesis.removed': ThesisRemoved;
+    heartbeat: {
+        ts: number;
+    };
+    pong: Record<string, never>;
+    open: undefined;
+    close: {
+        code?: number;
+        reason?: string;
+    };
+    reconnecting: {
+        attempt: number;
+        delay: number;
+    };
+    error: CabalSpyIDError;
+}
+type Handler<T> = (payload: T) => void;
+/**
+ * Live theses for the tokens you choose. Subscriptions are remembered and sent
+ * again after every reconnect.
+ *
+ *   const ts = csid.thesesStream();
+ *   ts.on('thesis', (t) => addMarker(t.blockchain, t.mint, t));
+ *   await ts.connect();
+ *   ts.subscribe([{ blockchain: 'solana', mint: MINT_A }, { blockchain: 'base', mint: TOKEN_B }]);
+ *
+ *   for await (const { event, data } of ts) { … }
+ */
+declare class ThesesStream {
+    private readonly url;
+    private readonly apiKey;
+    private readonly options;
+    private ws;
+    private readonly handlers;
+    private readonly tokens;
+    private all;
+    private attempt;
+    private closedByUser;
+    private fatal;
+    private ready;
+    private reconnectTimer;
+    private watchdog;
+    private readonly opts;
+    constructor(url: string, apiKey: string, options?: ThesesStreamOptions);
+    private buildUrl;
+    /** The URL with the key masked, safe to log. */
+    get safeUrl(): string;
+    get connected(): boolean;
+    /** The tokens currently subscribed (kept across reconnects). */
+    get subscriptions(): {
+        all: boolean;
+        tokens: ThesisTokenRef[];
+    };
+    on<E extends keyof ThesesStreamEventMap>(event: E, handler: Handler<ThesesStreamEventMap[E]>): this;
+    off<E extends keyof ThesesStreamEventMap>(event: E, handler: Handler<ThesesStreamEventMap[E]>): this;
+    private emit;
+    private send;
+    /** Adds tokens (at most 200 per connection). Sent now if connected, and after every reconnect. */
+    subscribe(tokens: ThesisTokenRef[]): this;
+    /** Removes tokens. */
+    unsubscribe(tokens: ThesisTokenRef[]): this;
+    /** Every token (all theses). */
+    subscribeAll(): this;
+    /** Drops every subscription, including subscribeAll(). */
+    unsubscribeAll(): this;
+    private resubscribe;
+    /** Opens the socket; resolves on `ready` (after sending the remembered subscriptions). */
+    connect(): Promise<ThesesReadyEvent>;
+    private scheduleReconnect;
+    private arm;
+    private disarm;
+    /** Sends a ping (answered with `pong`). Pinging more often than every 30 s suppresses heartbeats. */
+    ping(): void;
+    /** Closes the socket and stops reconnecting. Subscriptions are kept for a later connect(). */
+    close(): void;
+    /**
+     * Iterates over thesis events as `{ event, data }`. Connects if needed;
+     * breaking out closes a connection the iterator opened.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<ThesisStreamEvent, void, void>;
+}
+
+/**
+ * CabalSpy ID Data API client — https://api-id.cabalspy.xyz/v1
+ *
+ * Auth: Authorization: Bearer <API_KEY>. The same key as the CabalSpy API, with
+ * the "CabalSpy ID" toggle enabled on the API keys page of
+ * https://apidashboard.cabalspy.xyz.
+ */
+
+declare const DEFAULT_BASE_URL = "https://api-id.cabalspy.xyz/v1";
+declare const DEFAULT_STREAM_URL = "wss://api-id.cabalspy.xyz/v1/stream";
+declare const DEFAULT_THESES_STREAM_URL = "wss://api-id.cabalspy.xyz/v1/theses/stream";
+interface CabalSpyIDOptions {
+    /**
+     * API key. Falls back to CABALSPY_ID_API_KEY, then CABALSPY_API_KEY.
+     * Only `health()` works without one.
+     */
+    apiKey?: string;
+    /**
+     * Your instance's client_id (`csid_…`). Only needed when your account has
+     * several CabalSpy ID instances. Falls back to CABALSPY_ID_INSTANCE.
+     */
+    instance?: string;
+    /** REST base URL including /v1. Falls back to CABALSPY_ID_BASE_URL, then the default. */
+    baseUrl?: string;
+    /** Stream URL. Falls back to CABALSPY_ID_STREAM_URL, then the default. */
+    streamUrl?: string;
+    /** Theses stream URL. Default: wss://api-id.cabalspy.xyz/v1/theses/stream */
+    thesesStreamUrl?: string;
+    /** Per-request timeout in milliseconds. Default: 30_000 */
+    timeout?: number;
+    /** Retries on 429, 5xx and network errors. Default: 2 */
+    maxRetries?: number;
+    /** Extra headers added to every request. */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation, for tests or proxies. */
+    fetch?: typeof globalThis.fetch;
+}
+/** Response body plus the metadata carried in HTTP headers. */
+interface Envelope<T> extends ApiResponse<T> {
+    rateLimit: RateLimitInfo;
+    status: number;
+}
+type QueryValue = string | number | boolean | undefined | null;
+type Query = Record<string, QueryValue>;
+interface ScopedParams {
+    /** `global` (every CabalSpy ID user) is Enterprise only. Default: instance */
+    scope?: Scope;
+}
+interface UsersParams extends ScopedParams {
+    /** 1-100. Default: 50 */
+    limit?: number;
+    /** Only users with the KOL badge. */
+    kol?: boolean;
+    cursor?: string;
+}
+/** Exactly one of username, csid_id or address. */
+type ProfileParams = ScopedParams & ({
+    username: string;
+    csid_id?: never;
+    address?: never;
+} | {
+    csid_id: string;
+    username?: never;
+    address?: never;
+} | {
+    address: string;
+    username?: never;
+    csid_id?: never;
+});
+interface WalletParams extends ScopedParams {
+    blockchain: Chain;
+    address: string;
+}
+interface TrackerParams extends WalletParams {
+    /** Default: 1d */
+    period?: Period;
+}
+interface HistoryParams extends WalletParams {
+    /** 1-1000. Default: 500 */
+    limit?: number;
+    cursor?: string;
+}
+interface LeaderboardParams extends ScopedParams {
+    blockchain: Chain;
+    /** Default: 1d */
+    period?: Period;
+    /** Default: volume */
+    sort?: LeaderboardSort;
+    /** 1-500. Default: 100 */
+    limit?: number;
+    /** The `next_cursor` of the previous page (a wallet address). */
+    cursor?: string;
+}
+interface LatestTransactionsParams extends ScopedParams {
+    /** Omit for every chain. */
+    blockchain?: Chain;
+    /** 1-100. Default: 50 */
+    limit?: number;
+}
+interface ThesisTokenParams {
+    blockchain: Chain;
+    /** Token mint / contract address. */
+    mint: string;
+}
+/**
+ * `global` (default): theses written on every platform. `instance`: only the
+ * ones written on your instance (your apps). Same for every plan.
+ */
+interface ThesisScopeParam {
+    scope?: Scope;
+}
+interface ListThesesParams extends ThesisTokenParams, ThesisScopeParam {
+    /** Default: new */
+    sort?: ThesisSort;
+    stance?: ThesisStance;
+    /** 1-50. Default: 20 */
+    limit?: number;
+    cursor?: string;
+    /** Viewer: fills `my_reactions` and `is_mine` for this user. */
+    csid_id?: string;
+}
+interface ThesisRepliesParams {
+    /** The thesis id. */
+    id: string;
+    /** 1-100. Default: 50 */
+    limit?: number;
+    cursor?: string;
+    csid_id?: string;
+}
+interface LatestThesesParams extends ThesisScopeParam {
+    /** Omit for every chain. */
+    blockchain?: Chain;
+    /** `instance`: only theses of your instance's users. Default: all */
+    users?: 'all' | 'instance';
+    /** 1-50. Default: 20 */
+    limit?: number;
+    cursor?: string;
+    csid_id?: string;
+}
+/** Exactly one of csid_id or username. */
+type UserThesesParams = {
+    limit?: number;
+    cursor?: string;
+} & ({
+    csid_id: string;
+    username?: never;
+} | {
+    username: string;
+    csid_id?: never;
+});
+/**
+ * Writes happen in the name of one of your users: `csid_id` is the `sub` of
+ * their ID token. They must have signed in to your app with the scope
+ * `thesis` and be within your plan's user limit.
+ */
+interface ThesisWriter {
+    csid_id: string;
+}
+interface PostThesisParams extends ThesisTokenParams, ThesisWriter {
+    /** Up to 1000 characters. Only holders of the token can post. */
+    body: string;
+    stance?: ThesisStance;
+}
+interface ReplyToThesisParams extends ThesisWriter {
+    thesis_id: string;
+    body: string;
+}
+interface ReactToThesisParams extends ThesisWriter {
+    thesis_id: string;
+    emoji: ThesisEmoji;
+    /** false removes the reaction. Default: true */
+    on?: boolean;
+}
+interface ReportThesisParams extends ThesisWriter {
+    thesis_id: string;
+    reason: ThesisReportReason;
+    note?: string;
+}
+interface DeleteThesisParams extends ThesisWriter {
+    thesis_id: string;
+}
+/**
+ * Data API client.
+ *
+ *   const csid = new CabalSpyID({ apiKey: process.env.CABALSPY_API_KEY });
+ *   const me = await csid.me();
+ *   const user = await csid.profile({ csid_id: idToken.sub });
+ */
+declare class CabalSpyID {
+    readonly baseUrl: string;
+    readonly streamUrl: string;
+    readonly thesesStreamUrl: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly instance?: string;
+    private readonly apiKey;
+    private readonly extraHeaders;
+    private readonly fetchImpl;
+    /** Rate limit state from the most recent request. */
+    lastRateLimit: RateLimitInfo;
+    constructor(options?: CabalSpyIDOptions);
+    private authedQuery;
+    /** GET returning the full envelope: data, pagination, meta and rate limit. */
+    getRaw<T>(path: string, query?: Query, opts?: {
+        auth?: boolean;
+    }): Promise<Envelope<T>>;
+    /** GET returning only the data payload. */
+    get<T>(path: string, query?: Query): Promise<T>;
+    /**
+     * POST with a JSON body, returning the full envelope. POSTs are not retried
+     * after a server or network error (the write may have happened); only the
+     * API's own rate limit (429 rate_limit_exceeded) is retried.
+     */
+    postRaw<T>(path: string, body: Record<string, unknown>): Promise<Envelope<T>>;
+    /** POST returning only the data payload. */
+    post<T>(path: string, body: Record<string, unknown>): Promise<T>;
+    private request;
+    /**
+     * Walks a cursor-paginated route and yields whole pages.
+     *
+     *   for await (const page of csid.pages((cursor) => csid.usersRaw({ cursor }))) …
+     *
+     * Reads `pagination` from the envelope or, for the leaderboard, from `data`.
+     */
+    pages<T>(fetchPage: (cursor: string | undefined) => Promise<Envelope<T>>, opts?: {
+        cursor?: string;
+        maxPages?: number;
+    }): AsyncGenerator<Envelope<T>, void, void>;
+    /** GET /v1/health — service health and trade sync freshness. No API key required. */
+    health(): Promise<HealthResponse>;
+    /** GET /v1/me — the key's instance, plan, request rate and number of users with data. */
+    me(): Promise<MeResponse>;
+    /** GET /v1/users — users of your instance (within the plan's user limit), newest first. */
+    users(params?: UsersParams): Promise<Profile[]>;
+    usersRaw(params?: UsersParams): Promise<Envelope<Profile[]>>;
+    /** Iterates over every user, following `next_cursor`. */
+    iterUsers(params?: Omit<UsersParams, 'cursor'> & {
+        cursor?: string;
+    }): AsyncGenerator<Profile, void, void>;
+    /**
+     * GET /v1/profile — one user by X username, by `csid_id` (the `sub` of their
+     * ID token) or by a verified wallet address. Pass exactly one.
+     *
+     * An anonymous `anon_…` sub throws PlanUserLimitError.
+     */
+    profile(params: ProfileParams): Promise<Profile>;
+    /** GET /v1/wallets/lookup — which of your users verified this wallet (by an on-chain payment). */
+    walletLookup(address: string, params?: ScopedParams): Promise<WalletLookupResponse>;
+    /**
+     * GET /v1/wallets/tracker — stats, realized PnL, win-rate distribution,
+     * tokens, PnL chart (cumulative from 0) and trades of a verified wallet for a
+     * period. Same numbers as the CabalSpy API.
+     */
+    tracker(params: TrackerParams): Promise<TrackerResponse>;
+    /** GET /v1/wallets/history — lifetime stats, token overview and one page of trades. */
+    history(params: HistoryParams): Promise<HistoryResponse>;
+    historyRaw(params: HistoryParams): Promise<Envelope<HistoryResponse>>;
+    /** Iterates over every trade of a wallet, newest first, following `next_cursor`. */
+    iterHistory(params: HistoryParams): AsyncGenerator<HistoryTrade, void, void>;
+    /** GET /v1/wallets/holdings — current token balances with USD value (dust under $0.01 hidden). */
+    holdings(params: WalletParams): Promise<HoldingsResponse>;
+    /** GET /v1/wallets/pnl_calendar — realized PnL per UTC day, grouped by month. */
+    pnlCalendar(params: WalletParams): Promise<PnlCalendarResponse>;
+    /** GET /v1/wallets/leaderboard — your users ranked by volume, PnL, win rate or trades. */
+    leaderboard(params: LeaderboardParams): Promise<LeaderboardResponse>;
+    leaderboardRaw(params: LeaderboardParams): Promise<Envelope<LeaderboardResponse>>;
+    /** Iterates over every leaderboard entry, following `next_cursor`. */
+    iterLeaderboard(params: LeaderboardParams): AsyncGenerator<LeaderboardEntry, void, void>;
+    /** GET /v1/transactions/latest — the newest trades of your users, each with the trader. */
+    latestTransactions(params?: LatestTransactionsParams): Promise<Trade[]>;
+    /** GET /v1/theses — theses on a token, newest or top first. */
+    listTheses(params: ListThesesParams): Promise<Thesis[]>;
+    listThesesRaw(params: ListThesesParams): Promise<Envelope<Thesis[]>>;
+    /** Iterates over every thesis on a token, following `next_cursor`. */
+    iterTheses(params: ListThesesParams): AsyncGenerator<Thesis, void, void>;
+    /** GET /v1/theses/summary — counts (theses, bull, bear, authors) and token info. */
+    thesisSummary(params: ThesisTokenParams & ThesisScopeParam): Promise<ThesisSummary>;
+    /** GET /v1/theses/item — one thesis or reply. */
+    thesis(id: string, params?: {
+        csid_id?: string;
+    }): Promise<Thesis>;
+    /** GET /v1/theses/replies — replies to a thesis. */
+    thesisReplies(params: ThesisRepliesParams): Promise<Thesis[]>;
+    thesisRepliesRaw(params: ThesisRepliesParams): Promise<Envelope<Thesis[]>>;
+    /** Iterates over every reply of a thesis. */
+    iterThesisReplies(params: ThesisRepliesParams): AsyncGenerator<Thesis, void, void>;
+    /** GET /v1/theses/latest — newest theses on every token (or only your users'). */
+    latestTheses(params?: LatestThesesParams): Promise<Thesis[]>;
+    latestThesesRaw(params?: LatestThesesParams): Promise<Envelope<Thesis[]>>;
+    /** GET /v1/theses/user — theses of one user, by csid_id or X username. */
+    userTheses(params: UserThesesParams): Promise<Thesis[]>;
+    userThesesRaw(params: UserThesesParams): Promise<Envelope<Thesis[]>>;
+    /**
+     * GET /v1/theses/eligibility — may this user post (holder, not paused) and
+     * reply on this token through your app? `reason` says why not
+     * (consent_required, plan_user_limit, sandbox_user).
+     */
+    thesisEligibility(params: ThesisTokenParams & ThesisWriter): Promise<ThesisEligibility>;
+    /** POST /v1/theses — posts a thesis. Holders only (`not_a_holder` otherwise). */
+    postThesis(params: PostThesisParams): Promise<Thesis>;
+    /** POST /v1/theses/replies — replies to a thesis. */
+    replyToThesis(params: ReplyToThesisParams): Promise<Thesis>;
+    /** POST /v1/theses/reactions — adds (or with `on: false` removes) a reaction. */
+    reactToThesis(params: ReactToThesisParams): Promise<ThesisReactions>;
+    /** POST /v1/theses/report — reports a post (hidden for review after 3 reports). */
+    reportThesis(params: ReportThesisParams): Promise<{
+        reported: true;
+    }>;
+    /**
+     * GET /v1/theses/notifications — moderation notifications of one of your users
+     * (warnings, hidden posts, pauses, appeal results), with the unread count.
+     */
+    thesisNotifications(csidId: string): Promise<ThesisNotifications>;
+    /**
+     * POST /v1/theses/appeal — appeals a moderation decision in the user's name
+     * (an `appealable` notification, within 30 days; message 10-1000 characters).
+     */
+    appealThesisDecision(csidId: string, notificationId: number, message: string): Promise<{
+        appealed: true;
+    }>;
+    /** POST /v1/theses/delete — deletes the user's own thesis or reply. */
+    deleteThesis(params: DeleteThesisParams): Promise<{
+        deleted: true;
+    }>;
+    /**
+     * Live trades of your users over WebSocket (Pro plan and up).
+     *
+     *   const stream = csid.stream({ blockchain: 'solana' });
+     *   stream.on('trade', (trade) => console.log(trade));
+     *   await stream.connect();
+     */
+    stream(options?: StreamOptions): CabalSpyIDStream;
+    /**
+     * Live theses for the tokens you subscribe to (every plan), e.g. for a chart.
+     *
+     *   const ts = csid.thesesStream();
+     *   ts.on('thesis', (t) => addMarker(t));
+     *   await ts.connect();
+     *   ts.subscribe([{ blockchain: 'solana', mint }]);
+     */
+    thesesStream(options?: ThesesStreamOptions): ThesesStream;
+}
+
+type HeaderSource = Headers | Record<string, string | string[] | undefined> | {
+    get(name: string): string | null | undefined;
+};
+interface VerifyWebhookOptions {
+    /** The raw request body, exactly as received (do not re-serialize parsed JSON). */
+    payload: string | Uint8Array | ArrayBuffer;
+    /** Request headers (Fetch Headers, Node's IncomingHttpHeaders or a plain object). */
+    headers: HeaderSource;
+    /** Signing secret from the dashboard, `whsec_…`. */
+    secret: string;
+    /** Maximum age (and future skew) of webhook-timestamp in seconds. Default: 300 */
+    toleranceSeconds?: number;
+    /** Current time in seconds; for tests. */
+    now?: number;
+}
+/**
+ * Computes the `webhook-signature` header value for a payload. Useful to
+ * build test requests for your receiver.
+ */
+declare function signWebhook(secret: string, id: string, timestamp: number, payload: string | Uint8Array): Promise<string>;
+/**
+ * Verifies a webhook and returns the parsed event. Throws
+ * WebhookVerificationError when a header is missing, the timestamp is outside
+ * the tolerance or no signature matches.
+ *
+ *   const event = await verifyWebhook({ payload: rawBody, headers: req.headers, secret: process.env.CSID_WEBHOOK_SECRET });
+ */
+declare function verifyWebhook<D = Record<string, unknown>>(options: VerifyWebhookOptions): Promise<WebhookEvent<D>>;
+
+/** Internal helpers: encoding, WebCrypto access, environment. */
+declare const SDK_VERSION = "0.5.2";
+
+/**
+ * People can sign in with X, Telegram or Google. Accounts without X have no
+ * X profile: `x` is null, `twitter` is null and the handle is `tg.<name>`
+ * (Telegram) or `id.<hex>` (Google). X handles never contain a dot.
+ */
+/** Anything that describes a CabalSpy ID user: claims, a Data API profile, a trader or thesis author. */
+interface UserLike {
+    x?: unknown;
+    twitter?: string | null;
+    preferred_username?: string | null;
+    username?: string | null;
+}
+/** The sign-in identity a handle belongs to. */
+type HandleKind = 'x' | 'telegram' | 'google';
+/** Which identity a CabalSpy ID handle comes from: `tg.` = Telegram, `id.` = Google, else X. */
+declare function handleKind(handle: string): HandleKind;
+/**
+ * True when the user has an X account connected.
+ *
+ * Uses the most reliable field available: `x` (userinfo claims, Data API
+ * profiles), then `twitter` (trading profiles, leaderboards), then the handle
+ * (ID token claims, thesis authors). Returns false for null/undefined. The ID
+ * token carries no `x` claim, so there the handle decides.
+ */
+declare function hasX(user: UserLike | null | undefined): boolean;
+
+export { type ThesisStreamEvent as $, type ApiErrorBody as A, BadRequestError as B, CabalSpyID as C, DEFAULT_BASE_URL as D, type Envelope as E, type StreamEvent as F, type StreamEventMap as G, type HandleKind as H, InvalidResponseError as I, type StreamOptions as J, type StreamTopic as K, type LatestThesesParams as L, MAX_THESES_STREAM_TOKENS as M, NotFoundError as N, OAuthError as O, PermissionError as P, type Query as Q, RateLimitError as R, SDK_VERSION as S, type SubscribedEvent as T, type ThesesReadyEvent as U, ThesesStream as V, type ThesesStreamEventMap as W, type ThesesStreamOptions as X, type ThesesSubscribedEvent as Y, type ThesisRepliesParams as Z, type ThesisScopeParam as _, AuthenticationError as a, type ThesisTokenParams as a0, type ThesisTokenRef as a1, type ThesisWriter as a2, TokenVerificationError as a3, type TrackerParams as a4, type UserLike as a5, type UserThesesParams as a6, type UsersParams as a7, type VerifyWebhookOptions as a8, type WalletParams as a9, WebhookVerificationError as aa, handleKind as ab, hasX as ac, signWebhook as ad, verifyWebhook as ae, CabalSpyIDError as b, type CabalSpyIDErrorOptions as c, type CabalSpyIDOptions as d, CabalSpyIDStream as e, type CloseEvent as f, ConnectionError as g, DEFAULT_STREAM_URL as h, DEFAULT_THESES_STREAM_URL as i, type DeleteThesisParams as j, type HeaderSource as k, type HeartbeatEvent as l, type HistoryParams as m, type LatestTransactionsParams as n, type LeaderboardParams as o, type ListThesesParams as p, PlanUserLimitError as q, type PostThesisParams as r, type ProfileParams as s, type RateLimitInfo as t, type ReactToThesisParams as u, type ReconnectEvent as v, type ReplyToThesisParams as w, type ReportThesisParams as x, type ScopedParams as y, ServerError as z };