@poa-box/core 0.1.0

package/dist/graph/client.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Subgraph Client — tiered transport (browser-pure port of src/lib/subgraph.ts)
+ *
+ * Two transports can serve the same subgraph:
+ *
+ *   FREE ("Studio")   `api.studio.thegraph.com/...` — no key, capped at
+ *                     3K queries/day (rolling window, see x-ratelimit-reset).
+ *   PAID ("gateway")  `gateway.thegraph.com/api/subgraphs/id/<ID>` — billed
+ *                     against GRAPH_API_KEY, sent as an Authorization header.
+ *
+ * Routing is by AVAILABILITY, controlled by POP_SUBGRAPH_TIER=free|paid|auto
+ * (default `auto`):
+ *
+ *   both      free first, switch to paid when free is exhausted, and REMEMBER
+ *             the switch via the injected TierStateStore so the next process
+ *             does not repeat the doomed free round-trip
+ *   paid only straight to the gateway, never probe Studio
+ *   free only Studio; on exhaustion, fail with an actionable error naming
+ *             GRAPH_API_KEY and the gateway URL to set
+ *   neither   PRECONDITION error (this chain has no POP subgraph)
+ *
+ * ## Injection seams (what differs from the CLI original)
+ *
+ * The logic is identical to the CLI's src/lib/subgraph.ts; only the
+ * environment touchpoints are injected:
+ *
+ *   env         EnvSource instead of process.env (POP_SUBGRAPH_TIER,
+ *               GRAPH_API_KEY, POP_<NET>_* endpoint overrides)
+ *   stateStore  TierStateStore instead of ~/.pop/subgraph-tier-state.json —
+ *               in-memory by default; the CLI injects a file-backed store,
+ *               a browser host can inject localStorage
+ *   fetch       transport (defaults to globalThis.fetch)
+ *   onWarn      per-chain sweep failures (the CLI injects process.stderr)
+ *   now         clock, for tests
+ *
+ * The transport is plain fetch rather than graphql-request, but thrown errors
+ * carry the same observable shape (`.response.{status,headers,errors,error}`,
+ * `GraphQL Error (Code: NNN)` messages for non-JSON bodies) so the error
+ * classifiers below behave identically.
+ *
+ * ## Why exhaustion is persisted
+ *
+ * The CLI is a fresh process per command. A per-process flag meant that once
+ * Studio's daily quota was gone EVERY command burned a doomed Studio
+ * round-trip first, and queryWithFieldFallback repeated that once per tier.
+ *
+ * ## Why the pin is SHORT
+ *
+ * A burst limit and a spent daily quota look identical from a single 429, so
+ * exhaustion is pinned for FREE_BACKOFF_SECONDS (15 min) and no longer — never
+ * "until UTC midnight". Worst case we re-probe Studio ~96 times a day instead
+ * of thousands of times; best case a transient burst limit does not push a
+ * whole day of traffic onto the paid key. A `x-ratelimit-reset` sooner than the
+ * backoff shortens the pin but never extends it.
+ *
+ * The state store is advisory: a corrupt or unreadable one is ignored, never
+ * fatal.
+ */
+import type { EnvSource } from '../env';
+/** How long a free-tier quota/rate error suppresses the free transport. */
+export declare const FREE_BACKOFF_SECONDS: number;
+export type SubgraphTierName = 'free' | 'paid';
+export type SubgraphTierMode = 'auto' | 'free' | 'paid';
+export type TransportAvailability = 'both' | 'paid-only' | 'free-only' | 'none';
+export interface TransportAttempt {
+    tier: SubgraphTierName;
+    url: string;
+}
+export interface TransportPlan {
+    chainId: number;
+    /** Human network name, for error messages. */
+    networkName: string;
+    /** Effective POP_SUBGRAPH_TIER. */
+    mode: SubgraphTierMode;
+    /** Set when POP_SUBGRAPH_TIER held an unrecognised value (we fell back to auto). */
+    modeOverrideIgnored?: string;
+    availability: TransportAvailability;
+    hasApiKey: boolean;
+    /** A gateway URL is configured but GRAPH_API_KEY is missing, so it is unusable. */
+    paidKeyMissing: boolean;
+    freeUrl?: string;
+    paidUrl?: string;
+    /** Transports to try, in order. Empty means "nothing usable" — see planError(). */
+    attempts: TransportAttempt[];
+    /** unix-seconds; while in the future the free transport is skipped. */
+    freeExhaustedUntil?: number;
+}
+export interface TierState {
+    version: 1;
+    chains: Record<string, {
+        freeExhaustedUntil: number;
+        recordedAt: number;
+        reason?: string;
+    }>;
+}
+/**
+ * Where the free-tier exhaustion pin lives between queries. Implementations
+ * must never throw from load() or save(): a broken store degrades routing to
+ * per-call behaviour, it must not fail a read command.
+ */
+export interface TierStateStore {
+    load(): TierState | undefined;
+    save(state: TierState): void;
+}
+export declare function emptyTierState(): TierState;
+/** Default store: per-client-instance memory. */
+export declare class InMemoryTierStateStore implements TierStateStore {
+    private state;
+    load(): TierState | undefined;
+    save(state: TierState): void;
+    clear(): void;
+}
+export interface GraphErrorResponse {
+    status?: number;
+    headers?: any;
+    errors?: Array<{
+        message?: string;
+        extensions?: {
+            code?: string;
+        };
+    }>;
+    error?: any;
+    data?: any;
+}
+export declare class GraphRequestError extends Error {
+    response: GraphErrorResponse;
+    status?: number;
+    constructor(message: string, response: GraphErrorResponse);
+}
+export declare function redactSubgraphUrl(url: string | undefined): string | undefined;
+/**
+ * Quota/rate exhaustion, in whatever shape the host actually uses.
+ *
+ * Confirmed live (2026-07): Studio answers a healthy query HTTP 200 with
+ * `x-ratelimit-limit: 3000` / `-remaining` / `-reset`, and the gateway answers
+ * an unauthenticated query HTTP **200** with `{"errors":[{"message":"auth
+ * error: ..."}]}` — i.e. HTTP status alone is not sufficient in either
+ * direction. So: match the status when it is one of the unambiguous
+ * exhaustion codes, otherwise match only the SERVER's message text.
+ */
+export declare function isQuotaError(error: any): boolean;
+/** Missing/invalid/unauthorised API key on the paid transport. */
+export declare function isAuthError(error: any): boolean;
+/**
+ * Detect a GraphQL validation error caused by querying a field the
+ * deployed schema doesn't have (older subgraph version). Network/HTTP
+ * failures deliberately do NOT match — those should propagate.
+ */
+export declare function isUnknownFieldError(error: any): boolean;
+/**
+ * One tier of a field-fallback query. Tier 0 is the richest query
+ * (newest schema fields); later tiers progressively drop fields for
+ * older subgraph deployments.
+ */
+export interface FieldFallbackTier {
+    query: string;
+    variables?: Record<string, any>;
+}
+export interface ChainQueryResult<T> {
+    chainId: number;
+    name: string;
+    /** null when the chain returned nothing OR when the query failed — check `error`. */
+    data: T | null;
+    /**
+     * Present only when the query FAILED. `data: null` with no `error` means the
+     * chain answered and simply had no matching rows. Without this a
+     * rate-limited sweep looked identical to an empty ecosystem.
+     */
+    error?: string;
+}
+export interface TransportStatus {
+    mode: SubgraphTierMode;
+    availability: TransportAvailability;
+    /** Transport that WILL serve the next query, or null if none is usable. */
+    activeTier: SubgraphTierName | null;
+    hasApiKey: boolean;
+    paidKeyMissing: boolean;
+    freeUrl?: string;
+    paidUrl?: string;
+    freeExhaustedUntil?: number;
+    /** One-line human summary, safe to print. Never contains the API key. */
+    summary: string;
+}
+export interface GraphClientOptions {
+    /** POP_SUBGRAPH_TIER, GRAPH_API_KEY, POP_<NET>_* endpoint overrides. */
+    env?: EnvSource;
+    /**
+     * Chain served when a call passes no chainId. Without it, per-call chainId
+     * (or env POP_DEFAULT_CHAIN) is required — createPopContext({ chainId })
+     * sets this so documented reads work with zero further configuration.
+     */
+    defaultChainId?: number;
+    /** Free-tier exhaustion memory. Default: in-memory (per client instance). */
+    stateStore?: TierStateStore;
+    /** Transport. Default: globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Per-chain sweep failure reporter (CLI: stderr). Default: silent. */
+    onWarn?: (message: string) => void;
+    /** Clock (unix ms), for tests. */
+    now?: () => number;
+}
+export declare class GraphClient {
+    private env;
+    private defaultChainId?;
+    private store;
+    private providedFetch?;
+    private onWarn;
+    private nowMs;
+    constructor(options?: GraphClientOptions);
+    /**
+     * Resolve the transport LAZILY, per request. Capturing globalThis.fetch at
+     * construction would freeze whatever implementation existed then — test
+     * stubs and framework fetch-patchers (Next.js, MSW) replace it later.
+     * Bind: a bare `fetch` reference loses `this` in browsers ("Illegal
+     * invocation").
+     */
+    private resolveFetch;
+    private nowSeconds;
+    /**
+     * Never throws. A missing or hand-mangled state entry is treated as "no
+     * knowledge" — the cost is one wasted free-tier probe, which is strictly
+     * better than failing a read command over advisory cache state.
+     */
+    private loadState;
+    private saveState;
+    /** unix-seconds until which the free transport is considered spent, or undefined. */
+    getFreeExhaustedUntil(chainId: number): number | undefined;
+    /**
+     * Record that the free transport is spent. `resetAtSeconds` (from
+     * x-ratelimit-reset) may SHORTEN the pin but never extend it past
+     * FREE_BACKOFF_SECONDS — see the module header on why the pin stays short.
+     */
+    private markFreeExhausted;
+    private clearFreeExhausted;
+    /**
+     * Proactive exhaustion: Studio tells us how much of the free quota is left on
+     * every response, so record "spent" at remaining === 0 rather than waiting for
+     * the next command to eat a 429.
+     */
+    private observeRateLimit;
+    private getApiKey;
+    /**
+     * One GraphQL POST. Errors carry `.response.{status,headers,errors,error}`
+     * and graphql-request-style messages so the classifiers above keep working.
+     */
+    private request;
+    private resolveMode;
+    /**
+     * Work out which transports exist for a chain and in what order to try them.
+     * Pure w.r.t. the network: reads env + config + the injected state store only.
+     */
+    resolveTransportPlan(chainId?: number): TransportPlan;
+    private gatewayEnvHint;
+    /** The error to raise when a plan has no usable transport at all. */
+    private planError;
+    /** Free quota gone and there is no paid transport to fall back to. */
+    private freeExhaustedError;
+    private paidAuthError;
+    private paidQuotaError;
+    private executePlan;
+    /**
+     * Query a subgraph on the specified chain, routed through the tier plan
+     * (see the module header).
+     */
+    query<T = any>(gqlQuery: string, variables?: Record<string, any>, chainId?: number): Promise<T>;
+    /**
+     * Try query tiers in order, falling through to the next tier when the
+     * deployed schema rejects a field (validation error). Any other error
+     * (network, HTTP, rate limit without fallback) is rethrown immediately.
+     * Returns the first successful result plus the tier index that served it.
+     *
+     * Each tier re-plans, so once tier 0 has recorded free-tier exhaustion the
+     * remaining tiers go straight to the gateway instead of repeating the probe.
+     */
+    queryWithFieldFallback<T = any>(tiers: Array<FieldFallbackTier>, opts?: {
+        chainId?: number;
+    }): Promise<{
+        data: T;
+        tierIndex: number;
+    }>;
+    /**
+     * Query a specific subgraph URL directly, still tier-aware: if `url` is a free
+     * (Studio) endpoint belonging to a known chain and it rate-limits, the request
+     * is retried against that chain's gateway rather than simply failing.
+     */
+    queryUrl<T = any>(url: string, gqlQuery: string, variables?: Record<string, any>): Promise<T>;
+    /**
+     * Query all non-testnet subgraphs in parallel, each through its own tier plan.
+     * Returns results keyed by chainId. Failures are reported per-chain rather
+     * than swallowed: see ChainQueryResult.error.
+     */
+    queryAllChains<T = any>(gqlQuery: string, variables?: Record<string, any>): Promise<Array<ChainQueryResult<T>>>;
+    /**
+     * Describe the transport that will serve the next query on `chainId`.
+     * Purely local — issues no network request. URLs are redacted.
+     */
+    getTransportStatus(chainId?: number): TransportStatus;
+}