@bounded-sh/core 0.0.53 → 0.0.54

package/dist/client/config.d.ts

@@ -125,6 +125,7 @@ export interface ClientConfig {
         runtimeAddresses?: Record<string, string>;
     };
 }
+export declare const DEFAULT_CLIENT_CONFIG: ClientConfig;
 export declare let clientConfig: ClientConfig;
 type BoundedEndpoints = Pick<ClientConfig, 'wsApiUrl' | 'apiUrl' | 'authApiUrl' | 'humanAuthApiUrl' | 'functionsUrl' | 'devApiUrl'>;
 export declare const BOUNDED_NETWORKS: Record<string, BoundedEndpoints>;
@@ -147,6 +148,21 @@ export declare function getWebhookKeysUrl(): string | undefined;
  * Bounded must use the deterministic server aggregation, not the legacy AI query).
  */
 export declare function isBoundedNetwork(): boolean;
+/**
+ * Config-scoped variant of {@link isBoundedNetwork}: reports whether a SPECIFIC
+ * config (e.g. a scoped `createClient()` instance's) targets a Bounded network,
+ * rather than the module global. Used so a scoped client routes count/aggregate
+ * by its OWN network, not the global one.
+ */
+export declare function isBoundedNetworkConfig(config: ClientConfig): boolean;
+/**
+ * Merge a partial config over a base config, applying the Bounded endpoint
+ * precedence rule used everywhere: defaults (or `base`) < network preset <
+ * explicit fields. Pure - never touches module state. Shared by `init` (base =
+ * the current global) and `createClient` (base = the pristine defaults) so both
+ * resolve endpoints identically. Throws on an unsupported `network`.
+ */
+export declare function resolveClientConfig(base: ClientConfig, newConfig: Partial<ClientConfig>): ClientConfig;
 export declare function init(newConfig: Partial<ClientConfig>): Promise<void>;
 export declare function getConfig(): Promise<ClientConfig>;
 export {};

package/dist/client/create-client.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Scoped multi-app client factory.
+ *
+ * `createClient()` returns an isolated, READ-ONLY client bound to one Bounded
+ * app, independent of the module-global `init()` client. It exists so a single
+ * frontend can hold its normal authenticated client for its own app AND a
+ * read-only client for a SECOND Bounded app (e.g. a shared steward/runtime app),
+ * with live subscriptions on both and zero interference between them.
+ *
+ * Each instance carries its OWN fully-resolved config (endpoints + appId) and
+ * routes through the SAME shared transport/subscription implementation as the
+ * global path - it never forks that code. Isolation comes from threading the
+ * instance config (and a read-only marker) through the existing per-request /
+ * per-subscription override channel, plus the websocket layer already keying
+ * connections by appId.
+ *
+ * ## v1 scope: read-only, unauthenticated
+ *
+ * A scoped instance is UNAUTHENTICATED. It sends no auth, never reads or
+ * refreshes the global session, and connects to its app's realtime endpoint
+ * anonymously. It is therefore only useful against collections a Bounded app
+ * exposes with a public read rule (`read: true`) - private/per-user reads will
+ * be denied by the target app's policy, exactly as an anonymous caller would be.
+ *
+ * Writes and any auth-requiring surface are NOT supported on a scoped instance
+ * and throw a clear error. Per-instance authentication is a planned follow-up.
+ */
+import { type GetOptions, type SearchOptions, type CountOptions, type AggregateOptions, type QueryAggregateOptions, type RunQueryOptions, type AggregateOperation, type AggregateResult, type AggregateRow, type AggregateSpec, type GetManyResult, type RequestOverrides } from './operations';
+import { type ClientConfig } from './config';
+import type { SubscriptionOptions } from '../types';
+/** Config accepted by {@link createClient}. Only `appId` is required; `network`
+ *  (or explicit endpoint fields) selects the target Bounded backend. */
+export type CreateClientConfig = Partial<ClientConfig> & {
+    appId: string;
+};
+/**
+ * A read-only client scoped to a single Bounded app, isolated from the global
+ * `init()` client. Read methods mirror the global surface; writes and auth throw.
+ */
+export interface BoundedClient {
+    /** The app id this instance is bound to. */
+    readonly appId: string;
+    /** A snapshot of this instance's fully-resolved config (endpoints + appId). */
+    getConfig(): ClientConfig;
+    /** Read a document or collection. See the global `get`. */
+    get(path: string, opts?: GetOptions): Promise<any>;
+    /** Batch-read up to 30 documents. See the global `getMany`. */
+    getMany(paths: string[], opts?: {
+        cache?: boolean;
+        bypassCache?: boolean;
+        _overrides?: RequestOverrides;
+    }): Promise<GetManyResult[]>;
+    /** Full-text search a collection declared with `search`. */
+    search(path: string, query: string, opts?: SearchOptions): Promise<any>;
+    /** Structured, grouped aggregation over a collection. */
+    queryAggregate(path: string, spec: AggregateSpec, opts?: QueryAggregateOptions): Promise<AggregateRow[]>;
+    /** Count matching documents (deterministic on Bounded). */
+    count(path: string, opts?: CountOptions): Promise<AggregateResult>;
+    /** Single-scalar aggregate (count/sum/avg/min/max/uniqueCount). */
+    aggregate(path: string, operation: AggregateOperation, opts?: AggregateOptions): Promise<AggregateResult>;
+    /** Run a named/computed query defined by the app's policy. */
+    runQuery(absolutePath: string, queryName: string, queryArgs: any, opts?: RunQueryOptions): Promise<any>;
+    /** Batch variant of {@link runQuery}. */
+    runQueryMany(many: {
+        absolutePath: string;
+        queryName: string;
+        queryArgs: any;
+    }[], opts?: RunQueryOptions): Promise<any[]>;
+    /**
+     * Subscribe to realtime updates for a path on THIS app's realtime endpoint.
+     * Anonymous (read-only): the collection must be publicly readable. Returns an
+     * unsubscribe function. Subscriptions on this instance are fully independent
+     * of the global client and of any other scoped instance.
+     */
+    subscribe(path: string, options: SubscriptionOptions | ((data: any) => void)): Promise<() => Promise<void>>;
+    /** Not supported on a read-only scoped instance - always throws {@link ScopedClientReadOnlyError}. */
+    set(path: string, document: any): Promise<never>;
+    /** Not supported on a read-only scoped instance - always throws {@link ScopedClientReadOnlyError}. */
+    setMany(many: {
+        path: string;
+        document: any;
+    }[]): Promise<never>;
+}
+/** Error thrown when an unsupported (write / auth-requiring) call is made on a
+ *  read-only scoped client. */
+export declare class ScopedClientReadOnlyError extends Error {
+    constructor(operation: string);
+}
+/**
+ * Create a read-only client scoped to a single Bounded app.
+ *
+ * @example
+ * ```ts
+ * // Global client stays the venue's own authenticated app:
+ * await init({ appId: VENUE_APP, network: 'bounded-production', authMethod: 'email' });
+ *
+ * // A second, read-only client for the steward runtime app:
+ * const steward = createClient({ appId: STEWARD_APP, network: 'bounded-production' });
+ * const state = await steward.get('runtime/current');
+ * const stop = await steward.subscribe('runtime/current', (d) => render(d));
+ * ```
+ */
+export declare function createClient(config: CreateClientConfig): BoundedClient;

package/dist/client/operations.d.ts

@@ -1,4 +1,5 @@
 import type { AuthProvider } from '../types';
+import { type ClientConfig } from './config';
 import type { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
 import { type EvmTransactionPolicy } from '../utils/evm/evm-transaction-validation';
 /** Internal overrides for per-request auth and headers. */
@@ -13,6 +14,19 @@ export type RequestOverrides = {
     signal?: AbortSignal;
     /** @internal trusted runtime/chain binding for an explicit wallet client. */
     _evmTransactionPolicy?: EvmTransactionPolicy;
+    /**
+     * @internal Fully-resolved config for a scoped `createClient()` instance. When
+     * present, the request targets THIS config's endpoints + appId instead of the
+     * module-global `init()` config. Threaded internally by the scoped client;
+     * app code never sets it.
+     */
+    _config?: ClientConfig;
+    /**
+     * @internal Read-only scoped instance marker. The request omits auth entirely,
+     * never reads or refreshes the ambient global session, and never populates the
+     * shared read cache. Threaded internally by the scoped read-only client.
+     */
+    _readOnly?: boolean;
 };
 export type SetOptions = {
     shouldSubmitTx?: boolean;
@@ -109,22 +123,6 @@ export type AggregateOptions = {
     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 Bounded 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.