@bounded-sh/core 0.0.1

package/README.md

@@ -0,0 +1,78 @@
+# @tarobase/core
+
+Core functionality for Tarobase SDKs. This package provides the shared functionality used by both the web and server SDKs.
+
+## Installation
+
+```bash
+npm install @tarobase/core
+```
+
+## Usage
+
+This package is typically not used directly, but is instead used as a dependency by `@tarobase/web` and `@tarobase/server`. If you're building a browser application, use `@tarobase/web`. If you're building a server application, use `@tarobase/server`.
+
+## API Reference
+
+### Core Types
+
+```typescript
+export interface ClientConfig {
+  appId: string;
+  apiUrl: string;
+  authMethod: string;
+  privyConfig?: any;
+  chain?: string;
+  useSessionStorage?: boolean;
+}
+
+export interface AuthProvider {
+  login(): Promise<User | null>;
+  runTransaction(evmTransactionData?: EVMTransaction, solTransactionData?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+  signMessage(message: string): Promise<string>;
+  restoreSession(): Promise<User | null>;
+  logout(): Promise<void>;
+  getNativeMethods(): Promise<any>;
+}
+
+export interface User {
+  address: string;
+  provider: AuthProvider;
+}
+
+export interface GetManyResult {
+  path: string;
+  data: any | null;
+  error?: {
+    code: 'NOT_FOUND' | 'UNAUTHORIZED' | 'INVALID_PATH';
+    message: string;
+  };
+}
+```
+
+### Core Operations
+
+```typescript
+// Initialize the SDK
+function configInit(newConfig: Partial<ClientConfig>, options?: SessionOptions): Promise<void>;
+
+// Get the current configuration
+function getConfig(): Promise<ClientConfig>;
+
+// Data operations
+function get(path: string): Promise<any>;
+function getMany(paths: string[], options?: { bypassCache?: boolean }): Promise<GetManyResult[]>;
+function set(path: string, data: any, options?: SetOptions): Promise<any>;
+function setMany(paths: { [key: string]: any }, options?: SetOptions): Promise<any>;
+function setFile(path: string, file: File, metadata?: any): Promise<any>;
+function getFiles(path: string): Promise<any>;
+function runQuery(queryString: string, variables?: any): Promise<any>;
+function runQueryMany(queryString: string, variables?: any): Promise<any>;
+
+// Subscription
+function subscribe(path: string, options?: SubscriptionOptions): Promise<() => void>;
+```
+
+## Contributing
+
+Please see the main repository for contribution guidelines.

package/dist/client/config.d.ts

@@ -0,0 +1,105 @@
+import { AuthProvider } from '../types';
+export interface ClientConfig {
+    name: string;
+    logoUrl: string;
+    apiKey: string;
+    /** Auth method. 'email' = Bounded Better Auth human login (email OTP, inline) —
+     *  the default for most apps. 'phantom' = connect a Solana wallet (Phantom), the
+     *  recommended wallet option (yields a real @user.address). 'guest' = zero-config
+     *  anonymous (device keypair). All coexist; an app can offer email login AND Phantom
+     *  AND `signInAnonymously()` side by side. */
+    authMethod: 'none' | 'email' | 'guest' | 'wallet' | 'rainbowkit' | 'coinbase-smart-wallet' | 'onboard' | 'phantom' | 'mobile-wallet-adapter' | 'privy' | 'privy-expo';
+    wsApiUrl: string;
+    apiUrl: string;
+    /**
+     * Base URL of the Bounded Functions dispatcher (the imperative escape hatch).
+     * Optional and ADDITIVE — when unset, bounded.functions.invoke() throws a
+     * clear "functions not configured" error. Defaults to the staging dispatcher.
+     */
+    functionsUrl?: string;
+    appId: string;
+    /** Wallet/SIWS issuer (wallet + guest providers sign challenges against this). */
+    authApiUrl: string;
+    /** Human-login issuer (Bounded Better Auth — email OTP). The 'email' provider
+     *  calls {humanAuthApiUrl}/email + /verify. Defaults per network. */
+    humanAuthApiUrl?: string;
+    /**
+     * Selects a Bounded backend preset. When set, the endpoint defaults
+     * (apiUrl/wsApiUrl/authApiUrl/functionsUrl) resolve to that network's Bounded
+     * services instead of the legacy defaults — so a Bounded app needs only
+     * `{ appId, network }`. Anything you pass explicitly still wins. Unset =
+     * legacy behavior (unchanged for existing apps).
+     */
+    network?: 'bounded' | 'bounded-staging' | 'bounded-production';
+    chain: string;
+    rpcUrl: string;
+    skipBackendInit: boolean;
+    authProvider: AuthProvider | null;
+    isServer: boolean;
+    phantomConfig?: {
+        appId?: string;
+        providers?: Array<'injected' | 'google' | 'apple' | 'phantom' | 'deeplink'>;
+        redirectUrl?: string;
+        autoConnect?: boolean;
+        /** Theme for the login modal: 'light' or 'dark'. Defaults to 'dark'. */
+        theme?: 'light' | 'dark';
+        appName?: string;
+        appIcon?: string;
+        /** Custom title shown at the top of the login modal. */
+        modalTitle?: string;
+        /** Custom subtitle shown below the title in the login modal. */
+        modalSubtitle?: string;
+        /** When true, the Phantom login modal offers a Privy (email/social) fallback
+         *  route, hot-swapping to the Privy provider on demand. Web only. */
+        enablePrivyFallback?: boolean;
+    };
+    /** Privy (web) configuration — the @privy-io/react-auth app id + its config
+     *  object. Used when authMethod is 'privy' (a co-equal login route alongside
+     *  email/phantom/guest). The Privy embedded/external Solana wallet signs the
+     *  standard SIWS challenge, so the session is minted via the same wallet path
+     *  as Phantom — no Privy-specific backend verification required. */
+    privyConfig?: {
+        appId: string;
+        config: any;
+    };
+    /** React Native (Expo) Privy provider instance, bridged from the host app's
+     *  <PrivyProvider> tree via setPrivyMethods(). Required when authMethod is
+     *  'privy-expo' because @privy-io/expo is hook-based and must be rendered by
+     *  the RN component tree (see PrivyExpoProvider). */
+    privyExpoProvider?: AuthProvider;
+    mobileWalletConfig?: {
+        appIdentity?: {
+            name?: string;
+            uri?: string;
+            icon?: string;
+        };
+        cluster?: string;
+        theme?: 'light' | 'dark';
+    };
+    mockAuth?: boolean;
+}
+export declare let clientConfig: ClientConfig;
+type BoundedEndpoints = Pick<ClientConfig, 'wsApiUrl' | 'apiUrl' | 'authApiUrl' | 'humanAuthApiUrl' | 'functionsUrl'>;
+export declare const BOUNDED_NETWORKS: Record<string, BoundedEndpoints>;
+/**
+ * The hosted `/.well-known/bounded-webhook-keys.json` URL for the configured
+ * Bounded network, or `undefined` when no Bounded network is set. Used by
+ * `verifyWebhook` so a staging receiver that did `init({ network:
+ * 'bounded-staging' })` verifies against the STAGING signing keys instead of
+ * the production default. Synchronous and non-blocking on purpose: a pure
+ * webhook receiver may never call `init()`, so we read the already-applied
+ * config rather than awaiting `getConfig()` (which blocks on initialization).
+ * Returns `undefined` when the network is unknown so the caller keeps its
+ * fail-closed production default (audit SDK LOW-7).
+ */
+export declare function getWebhookKeysUrl(): string | undefined;
+/**
+ * True when init() configured a Bounded network (the Cloudflare-native stack).
+ * Synchronous + non-blocking. Used to route reads/writes that behave differently
+ * on Bounded vs the legacy Tarobase backend (e.g. `count`/`aggregate`, which on
+ * Bounded must use the deterministic server aggregation, not the legacy AI query).
+ */
+export declare function isBoundedNetwork(): boolean;
+export declare function init(newConfig: Partial<ClientConfig>): Promise<void>;
+export declare function getConfig(): Promise<ClientConfig>;
+export {};

package/dist/client/field-values.d.ts

@@ -0,0 +1,24 @@
+/** A server-resolved field operation. Pass as a field value in `set`/`setMany`. */
+export type FieldOperation = {
+    operation: 'increment';
+    value: number;
+} | {
+    operation: 'time';
+    value: 'now';
+};
+/**
+ * Atomically add `value` to a numeric field when the write commits, server-side.
+ * Use a negative `value` to decrement. The field starts from 0 if the document
+ * (or field) does not exist yet. Concurrent increments are race-free.
+ *
+ *   await set("counters/likes", { n: increment(1) });
+ *   await set("scores/p1", { points: increment(-5) });
+ */
+export declare function increment(value: number): FieldOperation;
+/**
+ * Stamp a field with the server's clock (Unix seconds) when the write commits —
+ * the trustworthy "when did this happen" you can't get from a client clock.
+ *
+ *   await set("posts/p1", { createdAt: serverTimestamp() });
+ */
+export declare function serverTimestamp(): FieldOperation;

package/dist/client/functions.d.ts

@@ -0,0 +1,34 @@
+export type InvokeOptions = {
+    /** Per-call timeout (ms) for the HTTP request to the dispatcher. */
+    timeoutMs?: number;
+    /** Extra headers (advanced/testing). */
+    headers?: Record<string, string>;
+    /**
+     * @internal Auth override. The server `WalletClient.invoke` sets this so the
+     * call authenticates as that wallet's session instead of the ambient
+     * `BOUNDED_PRIVATE_KEY` keypair (which would otherwise throw when unset). App
+     * code never sets this.
+     */
+    _overrides?: {
+        _getAuthHeaders?: () => Promise<Record<string, string>>;
+    };
+};
+export declare class FunctionInvokeError extends Error {
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: any | undefined);
+}
+/**
+ * Invoke a deployed Bounded Function by name. Returns the function's JSON.
+ *
+ *   const res = await bounded.functions.invoke('syncStripe', { customerId });
+ *
+ * Throws FunctionInvokeError on 401 (not logged in / bad token), 403 (the
+ * function's auth policy rule denied this caller), 404 (unknown function),
+ * 503 (Workers for Platforms not configured), or any non-2xx / transport error.
+ */
+export declare function invoke<T = any>(name: string, args?: Record<string, any>, opts?: InvokeOptions): Promise<T>;
+/** The `bounded.functions` namespace surface. */
+export declare const functions: {
+    invoke: typeof invoke;
+};

package/dist/client/live-effects.d.ts

@@ -0,0 +1,120 @@
+/**
+ * An effect a tick may emit. Structured-clonable JSON ONLY — no functions/closures.
+ *
+ * `id` is your stable correlation/idempotency key (e.g. `"npc:7:turn-42"`). It is
+ * MANDATORY for charged kinds (ai/function/agent/onchain) so an in-sim retry of the
+ * SAME logical action reuses the SAME id and never double-charges. For the other
+ * kinds the platform assigns a deterministic `${tick}:${seq}` fallback.
+ *
+ * `onBehalfOf` runs the effect AS that player (their auth/rules downstream). It must
+ * be a player whose intent you processed in the SAME tick (no privilege escalation);
+ * omit it to run as the game's own service principal.
+ */
+export type Effect = {
+    kind: "ai";
+    id: string;
+    model: string;
+    input: unknown;
+    onBehalfOf?: string;
+} | {
+    kind: "function";
+    id: string;
+    name: string;
+    args?: Record<string, unknown>;
+    onBehalfOf?: string;
+} | {
+    kind: "agent";
+    id: string;
+    agent: string;
+    message: unknown;
+    onBehalfOf?: string;
+} | {
+    kind: "http";
+    id?: string;
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    /** Secret NAME(s) only — the value is injected host-side on egress, never in your code. */
+    secret?: string | string[];
+    onBehalfOf?: string;
+} | {
+    kind: "onchain";
+    id: string;
+    collection: string;
+    op: "set" | "delete";
+    data?: Record<string, unknown>;
+    onBehalfOf?: string;
+    /** Require the player to co-sign the transaction. */
+    cosign?: boolean;
+} | {
+    kind: "data";
+    id?: string;
+    op: "set" | "delete";
+    path: string;
+    document?: Record<string, unknown>;
+    onBehalfOf?: string;
+} | {
+    kind: "schedule";
+    id?: string;
+    name: string;
+    atMs?: number;
+    everyMs?: number;
+};
+export type EffectKind = Effect["kind"];
+/** Reserved intent address an effect result arrives on. */
+export declare const EFFECT_INTENT_ADDRESS: "@effect";
+/**
+ * The result of an effect, re-entered into your tick as an intent on the reserved
+ * `@effect` address. Match `effectId` to the `id` you emitted; read `result` iff
+ * `ok`, else `error` (an enumerated code).
+ */
+export interface EffectResult<T = unknown> {
+    __effect: true;
+    effectId: string;
+    ok: boolean;
+    result?: T;
+    error?: string;
+}
+/** A per-tick input: a player intent, or an `@effect` result the platform re-injected. */
+export interface LiveIntent {
+    address: string;
+    intent: unknown;
+}
+/**
+ * The tick may return the bare next state, OR `{ state, effects }` to also emit
+ * effects this tick. Use {@link withEffects} to build the wrapper unambiguously.
+ */
+export type LiveTickResult<S> = S | {
+    state: S;
+    effects?: Effect[];
+};
+/** A Bounded live module (game/realtime-room logic) that can emit effects. */
+export interface LiveModule<S = unknown> {
+    init(seed: unknown): S;
+    tick(state: S, intents: LiveIntent[], dt: number): LiveTickResult<S>;
+    views?(state: S): Record<string, unknown>;
+}
+/**
+ * Build the `{ state, effects }` tick return. Always include this (even with an
+ * empty list) when you intend the wrapper, so the runtime never has to guess
+ * whether your state object happens to look like the wrapper.
+ *
+ *   return withEffects(next, [{ kind: "ai", id: `npc:${id}:${next.turn}`, model, input }]);
+ */
+export declare function withEffects<S>(state: S, effects?: Effect[]): {
+    state: S;
+    effects: Effect[];
+};
+/**
+ * Narrow an incoming intent to an effect result inside your tick:
+ *
+ *   for (const i of intents) {
+ *     if (i.address === EFFECT_INTENT_ADDRESS && isEffectResult(i.intent)) {
+ *       applyResult(state, i.intent); // i.intent.effectId / .ok / .result / .error
+ *     } else { applyPlayerIntent(state, i); }
+ *   }
+ */
+export declare function isEffectResult<T = unknown>(intent: unknown): intent is EffectResult<T>;
+/** Identity helper purely for type inference when authoring a module. */
+export declare function defineLiveModule<S>(mod: LiveModule<S>): LiveModule<S>;

package/dist/client/live.d.ts

@@ -0,0 +1,61 @@
+export type LiveIntentOptions = {
+    /** Per-call timeout (ms) for the HTTP request to the realtime worker. */
+    timeoutMs?: number;
+    /** Extra headers (advanced/testing). */
+    headers?: Record<string, string>;
+    /**
+     * Fire-and-forget over the room socket without awaiting a server ack — lowest
+     * latency, but a rejection (auth/policy deny, room gone) is NOT surfaced. Use
+     * for high-frequency, idempotent input (movement/aim). Default (false): the
+     * intent rides the socket but AWAITS the ack, so a denial throws — important
+     * for join/ready/leave and any intent whose failure the player must know about.
+     */
+    fireAndForget?: boolean;
+};
+export declare class LiveIntentError extends Error {
+    statusCode?: number | undefined;
+    details?: any | undefined;
+    constructor(message: string, statusCode?: number | undefined, details?: any | undefined);
+}
+/**
+ * Send a player intent to a running live room. Returns `{ ok: true }`.
+ *
+ *   await bounded.live.intent('rooms/abc', { type: 'move', dir: 'up' });
+ *
+ * `roomPath` is the document path of the room (e.g. `rooms/abc`). The worker
+ * derives the room from this path and reads `intent` as the opaque per-tick
+ * input. The caller's address is taken from the attached session token.
+ *
+ * Throws LiveIntentError on 401 (not logged in / bad token), 404 (room has no
+ * live module), 503 (live runtime/module unavailable), or any non-2xx /
+ * transport error / timeout.
+ */
+export declare function intent(roomPath: string, intent: unknown, opts?: LiveIntentOptions): Promise<{
+    ok: true;
+}>;
+export type SubscribeViewOptions = {
+    /** Address whose view to read. Defaults to the logged-in user's address. */
+    address?: string;
+    /** Called with the latest per-player view document. */
+    onData: (view: any) => void;
+    /** Called on subscription error. */
+    onError?: (error: any) => void;
+};
+/**
+ * Subscribe to YOUR per-player view of a room. Thin sugar over:
+ *
+ *   subscribe('<roomPath>/view/<myAddress>', { onData, onError })
+ *
+ * The address defaults to the logged-in user's address (from the session
+ * token's claims); pass `opts.address` to override. Returns the unsubscribe
+ * function (a Promise<() => Promise<void>>, same as `subscribe`).
+ *
+ * Note: this is a browser-first helper (the WS subscription manager is
+ * browser-oriented). Server consumers should use `live.intent`.
+ */
+export declare function subscribeView(roomPath: string, opts: SubscribeViewOptions): Promise<() => Promise<void>>;
+/** The `bounded.live` namespace surface. */
+export declare const live: {
+    intent: typeof intent;
+    subscribeView: typeof subscribeView;
+};

package/dist/client/operations.d.ts

@@ -0,0 +1,264 @@
+import { AuthProvider } from '../types';
+import { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
+/** Internal overrides for per-request auth and headers. */
+export type RequestOverrides = {
+    headers?: Record<string, string>;
+    authProvider?: AuthProvider;
+    _getAuthHeaders?: () => Promise<Record<string, string>>;
+    _clearAuth?: () => Promise<void>;
+    _walletAddress?: string;
+    timeout?: number;
+};
+export type SetOptions = {
+    shouldSubmitTx?: boolean;
+    _overrides?: RequestOverrides;
+};
+/**
+ * Thrown when a user's wallet doesn't have enough SOL to cover the transaction.
+ * Apps can catch this to trigger an onramp/funding flow.
+ */
+export declare class InsufficientBalanceError extends Error {
+    address: string;
+    balanceLamports: number;
+    estimatedCostLamports: number;
+    deficitLamports: number;
+    deficitSol: number;
+    constructor(address: string, balanceLamports: number, estimatedCostLamports: number, deficitLamports: number, deficitSol: number);
+}
+/**
+ * Options for the get function.
+ */
+export type GetOptions = {
+    /**
+     * Structured MongoDB-style filter for collection reads, e.g.
+     * `{ status: "open", amount: { $gt: 10 } }`. Deterministic (no AI). Supported
+     * operators: $gt $gte $lt $lte $ne $in $nin $exists $regex ($options) $and $or
+     * $nor; a bare value means equality. Read rules still apply on top.
+     */
+    filter?: Record<string, any>;
+    /** Sort spec for collection reads, e.g. `{ createdAt: -1 }` (1 = asc, -1 = desc). */
+    sort?: Record<string, number>;
+    /** Natural language prompt for AI-powered queries (collections only) */
+    prompt?: string | undefined;
+    /** Bypass the local cache and fetch fresh data */
+    bypassCache?: boolean;
+    /** Include documents from sub-paths (nested collections) */
+    includeSubPaths?: boolean;
+    /** Shape object for relationship resolution - specifies which related documents to include */
+    shape?: Record<string, any>;
+    /** Maximum number of items to return (opt-in pagination) */
+    limit?: number;
+    /** Opaque cursor for cursor-based pagination (used with limit) */
+    cursor?: string;
+    _overrides?: RequestOverrides;
+};
+export type RunQueryOptions = {
+    _overrides?: RequestOverrides;
+};
+/**
+ * Supported aggregate operations for count/aggregate queries.
+ */
+export type AggregateOperation = 'count' | 'uniqueCount' | 'sum' | 'avg' | 'min' | 'max';
+/**
+ * Result of a count or aggregate query — always a single numeric value.
+ */
+export type AggregateResult = {
+    value: number;
+};
+/**
+ * Options for the count function.
+ */
+export type CountOptions = {
+    /** Natural language filter prompt (e.g., "posts created in the last 7 days"). Legacy backend only. */
+    prompt?: string;
+    /** Structured filter (same shape as `get`/`queryAggregate`). Preferred on Bounded. */
+    filter?: Record<string, any>;
+    _overrides?: RequestOverrides;
+};
+/**
+ * Options for the aggregate function.
+ */
+export type AggregateOptions = {
+    /** Natural language filter prompt. Legacy backend only. */
+    prompt?: string;
+    /** Structured filter (same shape as `get`/`queryAggregate`). Preferred on Bounded. */
+    filter?: Record<string, any>;
+    /** Field name to aggregate on (required for sum, avg, min, max) */
+    field?: string;
+    _overrides?: RequestOverrides;
+};
+/**
+ * Count items in a collection path. Returns a numeric result.
+ *
+ * This uses the AI query engine with a count-specific prompt prefix,
+ * so TaroBase will generate a $count aggregation pipeline and return
+ * just the count rather than full documents.
+ *
+ * IMPORTANT: This only works for collections where the read policy is "true".
+ * If the read policy requires per-document checks, the server will return
+ * an error because aggregate counts cannot be performed without pulling all
+ * documents for access control evaluation.
+ *
+ * @param path - Collection path (e.g., "posts", "users/abc/comments")
+ * @param opts - Optional filter prompt and overrides
+ * @returns AggregateResult with the count value
+ */
+export declare function count(path: string, opts?: CountOptions): Promise<AggregateResult>;
+/**
+ * Run an aggregate operation on a collection path. Returns a numeric result.
+ *
+ * Supported operations:
+ * - count: Total number of documents
+ * - uniqueCount: Number of distinct values for a field
+ * - sum: Sum of a numeric field
+ * - avg: Average of a numeric field
+ * - min: Minimum value of a numeric field
+ * - max: Maximum value of a numeric field
+ *
+ * IMPORTANT: This only works for collections where the read policy is "true".
+ * If the read policy requires per-document checks, the server will return
+ * an error because aggregate operations cannot be performed without pulling
+ * all documents for access control evaluation.
+ *
+ * @param path - Collection path (e.g., "posts", "users/abc/comments")
+ * @param operation - The aggregate operation to perform
+ * @param opts - Options including optional filter prompt and field name
+ * @returns AggregateResult with the computed numeric value
+ */
+export declare function aggregate(path: string, operation: AggregateOperation, opts?: AggregateOptions): Promise<AggregateResult>;
+/**
+ * Structured aggregation spec — group rows and compute count/sum/avg/min/max.
+ * Unlike `aggregate` (a single scalar via AI prompt), this runs deterministically
+ * server-side and can return MULTIPLE grouped rows.
+ */
+export type AggregateSpec = {
+    /** Group rows by these field values (omit for a single overall row). */
+    groupBy?: string[];
+    /** Include the document count per group. */
+    count?: boolean;
+    /** Sum these numeric fields per group. */
+    sum?: string[];
+    /** Average these numeric fields per group. */
+    avg?: string[];
+    /** Minimum of these fields per group. */
+    min?: string[];
+    /** Maximum of these fields per group. */
+    max?: string[];
+};
+/** One row of a `queryAggregate` result. */
+export type AggregateRow = {
+    group?: Record<string, any>;
+    count?: number;
+    sum?: Record<string, number>;
+    avg?: Record<string, number | null>;
+    min?: Record<string, any>;
+    max?: Record<string, any>;
+};
+/** Options for `queryAggregate`. */
+export type QueryAggregateOptions = {
+    /** Structured MongoDB-style filter applied before grouping (same shape as GetOptions.filter). */
+    filter?: Record<string, any>;
+    _overrides?: RequestOverrides;
+};
+/**
+ * Structured, grouped aggregation over a collection. Returns one row per group
+ * (or a single row when `spec.groupBy` is omitted). Read rules are enforced — the
+ * aggregation only sees documents the caller can read.
+ *
+ * ```ts
+ * const byCat = await queryAggregate("spend", { groupBy: ["category"], count: true, sum: ["amount"] });
+ * // [{ group: { category: "food" }, count: 2, sum: { amount: 70 } }, ...]
+ * ```
+ */
+export declare function queryAggregate(path: string, spec: AggregateSpec, opts?: QueryAggregateOptions): Promise<AggregateRow[]>;
+/**
+ * Options for the full-text `search` function.
+ */
+export type SearchOptions = {
+    /** Restrict the match to these declared search fields (default: all indexed fields). */
+    fields?: string[];
+    /** Maximum number of matches to return. */
+    limit?: number;
+    /** Opaque pagination cursor from a prior page. */
+    cursor?: string;
+    _overrides?: RequestOverrides;
+};
+/**
+ * Full-text search a collection declared with `search: { fields: [...] }`.
+ *
+ * The match runs over the collection's indexed fields (or the subset passed in
+ * `opts.fields`) and respects each document's `read` rule — results the caller
+ * cannot read are omitted. Returns the matching documents (optionally paged via
+ * `opts.limit`/`opts.cursor`).
+ *
+ * @param path  Collection path, e.g. "orgs/o1/docs"
+ * @param query Free-text query string (non-empty)
+ */
+export declare function search(path: string, query: string, opts?: SearchOptions): Promise<any>;
+export declare function get(path: string, opts?: GetOptions): Promise<any>;
+export type GetManyResult = {
+    path: string;
+    data: any | null;
+    error?: {
+        code: 'NOT_FOUND' | 'UNAUTHORIZED' | 'INVALID_PATH';
+        message: string;
+    };
+};
+export declare function getMany(paths: string[], opts?: {
+    bypassCache?: boolean;
+    _overrides?: {
+        headers?: Record<string, string>;
+    };
+}): Promise<GetManyResult[]>;
+export type RunExpressionOptions = {
+    returnType?: 'Bool' | 'String' | 'Int' | 'UInt';
+    _overrides?: RequestOverrides;
+};
+export type RunExpressionResult = {
+    result: any;
+    trace?: {
+        variable: string;
+        resolvedValue: any;
+        operation?: string;
+        result?: any;
+    }[];
+};
+export declare function runQuery(absolutePath: string, queryName: string, queryArgs: any, opts?: RunQueryOptions): Promise<any>;
+export declare function runQueryMany(many: {
+    absolutePath: string;
+    queryName: string;
+    queryArgs: any;
+}[], opts?: RunQueryOptions): Promise<any>;
+export declare function runExpression(expression: string, queryArgs: any, options?: RunExpressionOptions): Promise<RunExpressionResult>;
+export declare function runExpressionMany(many: {
+    expression: string;
+    queryArgs: any;
+    returnType?: 'Bool' | 'String' | 'Int' | 'UInt';
+    _overrides?: RequestOverrides;
+}[]): Promise<RunExpressionResult[]>;
+export declare function set(path: string, document: any, options?: SetOptions): Promise<any>;
+export declare function setMany(many: {
+    path: string;
+    document: any;
+}[], options?: SetOptions): Promise<any>;
+export declare function clearCache(path?: string, opts?: {
+    prompt?: string;
+}): void;
+/**
+ * SECURITY (H1): Wipe ALL HTTP read caches + in-flight reads. Call this whenever
+ * the logged-in identity changes (login / logout / switch identity) so a freshly
+ * authenticated principal can never observe data cached for the previous one.
+ * This is invoked from the WS auth-change path (reconnectWithNewAuthV2).
+ */
+export declare function clearReadCacheForAuthChange(): void;
+export declare function getFiles(path: string, options?: {
+    _overrides?: RequestOverrides;
+}): Promise<any>;
+export declare function setFile(path: string, file: File | null, options?: {
+    _overrides?: RequestOverrides;
+    metadata?: Record<string, any>;
+}): Promise<boolean>;
+export declare function signMessage(message: string): Promise<string>;
+export declare function signTransaction(transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+export declare function signAndSubmitTransaction(transaction: Transaction | VersionedTransaction, feePayer?: PublicKey): Promise<string>;
+export declare function syncItems(paths: string[], options?: SetOptions): Promise<any>;