@exposify/firebase 0.0.0-stage → 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,178 @@
+import { AuthResolver, WebMcpHandler } from '@exposify/core';
+export { HostedAuthResolverConfig, completeMcpLogin, createHostedAuthResolver, hostedBroker } from '@exposify/core';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** What `onRequest` hands its handler: Express's req/res, with the body already read. */
+type FirebaseRequest = IncomingMessage & {
+    body?: unknown;
+    rawBody?: Buffer;
+    originalUrl?: string;
+};
+type NodeHandler = (req: FirebaseRequest, res: ServerResponse) => Promise<void>;
+/**
+ * Adapts a web-standard handler to Node's `(req, res)`. Cloud Functions has
+ * already drained the request stream by the time the handler runs (it sets
+ * `rawBody` and a parsed `body`), so the body comes from those; a plain Node
+ * server's untouched stream is read directly. The response body is streamed
+ * chunk by chunk, since MCP answers over SSE.
+ */
+declare function toNodeHandler(handle: (req: Request) => Promise<Response>): NodeHandler;
+
+/**
+ * The JSON Schema subset accepted for `fields` and `functions[].input`
+ * (same as `@exposify/supabase`'s), plus `format: "date-time"`, which makes
+ * a string field a Firestore timestamp on writes and in filters.
+ */
+interface JsonSchemaProperty {
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+    description?: string;
+    format?: "date-time";
+    enum?: unknown[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface JsonSchemaObject {
+    type?: "object";
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface CollectionConfig {
+    /** Becomes the tools' description. Say what a document is, for the agent. */
+    description?: string;
+    /**
+     * The document's fields. Optional: without it, filters accept any field
+     * name and writes accept any object. With it, filters and `select` are
+     * limited to these names and writes are typed.
+     */
+    fields?: Record<string, JsonSchemaProperty>;
+    /** Field names a `create_*` call must include. */
+    required?: string[];
+    /**
+     * The field holding the owning user's uid, for the common
+     * `resource.data.<owner> == request.auth.uid` rule: `list_*` filters on
+     * it, `create_*` sets it, `update_*` refuses to change it. A convenience,
+     * not a security boundary: your rules still decide.
+     */
+    owner?: string;
+}
+/** A registered callable function (`onCall`), invoked with the caller's ID token. */
+interface FunctionToolConfig {
+    description: string;
+    input?: JsonSchemaObject;
+    /** Full URL override, e.g. a custom domain or a run.app URL. */
+    url?: string;
+}
+type WriteOp = "create" | "update" | "delete";
+interface ExposifyFirebaseOptions {
+    /**
+     * The Firestore collections agents can use, keyed by collection path.
+     * Subcollections use `{param}` placeholders: `"users/{userId}/notes"`.
+     * A plain array is shorthand for `{ name: {} }` each.
+     */
+    collections?: Record<string, CollectionConfig> | string[];
+    /** `"<collection>.create"` / `.update` / `.delete` / `.*`. Reads need no opt-in. */
+    writes?: string[];
+    /** Callable functions (`onCall`) exposed as `call_<name>` tools. */
+    functions?: Record<string, FunctionToolConfig>;
+    /** Doc globs, relative to the functions source directory. Default: `["docs/**\/*.md"]`. */
+    docs?: string[];
+    /** Default `"public"`. `"required"` hides `search_docs` from callers with no token. */
+    docsAuth?: "public" | "required";
+    /** Cap on documents per `list_*` call regardless of the caller's `limit`. Default 100. */
+    maxDocs?: number;
+    /** Default: `GCLOUD_PROJECT` / `GOOGLE_CLOUD_PROJECT` / `FIREBASE_CONFIG.projectId`, set in every deployed function. */
+    projectId?: string;
+    /** Firestore database id. Default `"(default)"`. */
+    databaseId?: string;
+    /** Region of the callable functions in `functions`. Default `"us-central1"`. */
+    functionsRegion?: string;
+    /**
+     * Resolves the caller's headers into the headers used for Firestore and
+     * callable calls, e.g. `hostedBroker()` (Exposify's hosted broker, from `EXPOSIFY_KEY`).
+     * Only `authorization` from the result is used.
+     */
+    auth?: AuthResolver;
+    /**
+     * With `auth` set: 401 when the resolver returns no `authorization`, instead
+     * of running unauthenticated. Default true with the hosted broker (`EXPOSIFY_KEY`
+     * set, or `auth: hostedBroker()`), which also answers tokenless requests with
+     * Connect's sign-in challenge; false otherwise.
+     */
+    authRequired?: boolean;
+    /** The cold-start "MCP ready" line. Default: on, except under `NODE_ENV=test`. Failures always log. */
+    startupLog?: boolean;
+    /** Injectable for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Overrides `process.env` (tests). */
+    env?: Record<string, string | undefined>;
+    /** Directory doc globs resolve against. Default `process.cwd()` (the functions source directory when deployed). */
+    docsRoot?: string;
+    rateLimit?: number;
+    rateWindowMs?: number;
+}
+interface ResolvedCollection {
+    /** The configured key, e.g. `"users/{userId}/notes"`. */
+    key: string;
+    /** Path segments; odd positions are collection ids, even positions are `{param}` or literal doc ids. */
+    segments: string[];
+    /** `{param}` names in order. */
+    params: string[];
+    /** Tool-name suffix, e.g. `"users_notes"`. */
+    suffix: string;
+    config: CollectionConfig;
+    writes: Set<WriteOp>;
+}
+interface ResolvedFirebaseConfig {
+    collections: ResolvedCollection[];
+    functions: Record<string, FunctionToolConfig>;
+    docs: string[];
+    docsAuth: "public" | "required";
+    maxDocs: number;
+    databaseId: string;
+    functionsRegion: string;
+    rateLimit?: number;
+    rateWindowMs?: number;
+}
+
+/**
+ * Collection keys are Firestore collection paths with `{param}` placeholders
+ * in document positions: `"todos"`, `"users/{userId}/notes"`. A key has an
+ * odd number of segments (it names a collection, not a document); collection
+ * ids (even indexes) must be literal.
+ */
+interface ParsedKey {
+    segments: string[];
+    params: string[];
+    suffix: string;
+}
+/** Throws with a message naming the problem; config.ts turns that into a warning. */
+declare function parseCollectionKey(key: string): ParsedKey;
+
+/**
+ * The MCP endpoint for `onRequest`:
+ *
+ * ```ts
+ * export const mcp = onRequest(aiReady({ collections: { todos: { owner: "uid" } } }));
+ * ```
+ */
+declare function aiReady(options?: ExposifyFirebaseOptions): NodeHandler;
+/**
+ * The same endpoint as a web-standard `Request → Response` handler, for
+ * runtimes other than `onRequest` and for tests. Docs are read and indexed
+ * on the first request and cached for the instance's lifetime.
+ */
+declare function createFirebaseMcpHandler(options?: ExposifyFirebaseOptions): WebMcpHandler;
+/**
+ * The function's public URL from the URL a request arrived at. Behind
+ * `<region>-<project>.cloudfunctions.net/<name>` the function sees the path
+ * without its own name, so the name goes back in; a `run.app` URL already is
+ * the function's root.
+ */
+declare function functionPublicUrl(own: string, functionName: string | undefined): string;
+/** `https://<region>-<project>.cloudfunctions.net/<name>`, or the Functions emulator's URL. */
+declare function callableUrl(name: string, projectId: string, region: string, env: Record<string, string | undefined>): string;
+/** "7 tools (2 list, 2 get, 2 write, 1 callable)": only the kinds present. */
+declare function firebaseToolsPhrase(cfg: ResolvedFirebaseConfig, hasDocs: boolean): string;
+
+export { type CollectionConfig, type ExposifyFirebaseOptions, type FirebaseRequest, type FunctionToolConfig, type JsonSchemaObject, type JsonSchemaProperty, type NodeHandler, aiReady, callableUrl, createFirebaseMcpHandler, firebaseToolsPhrase, functionPublicUrl, parseCollectionKey, toNodeHandler };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import { AuthResolver, WebMcpHandler } from '@exposify/core';
+export { HostedAuthResolverConfig, completeMcpLogin, createHostedAuthResolver, hostedBroker } from '@exposify/core';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** What `onRequest` hands its handler: Express's req/res, with the body already read. */
+type FirebaseRequest = IncomingMessage & {
+    body?: unknown;
+    rawBody?: Buffer;
+    originalUrl?: string;
+};
+type NodeHandler = (req: FirebaseRequest, res: ServerResponse) => Promise<void>;
+/**
+ * Adapts a web-standard handler to Node's `(req, res)`. Cloud Functions has
+ * already drained the request stream by the time the handler runs (it sets
+ * `rawBody` and a parsed `body`), so the body comes from those; a plain Node
+ * server's untouched stream is read directly. The response body is streamed
+ * chunk by chunk, since MCP answers over SSE.
+ */
+declare function toNodeHandler(handle: (req: Request) => Promise<Response>): NodeHandler;
+
+/**
+ * The JSON Schema subset accepted for `fields` and `functions[].input`
+ * (same as `@exposify/supabase`'s), plus `format: "date-time"`, which makes
+ * a string field a Firestore timestamp on writes and in filters.
+ */
+interface JsonSchemaProperty {
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+    description?: string;
+    format?: "date-time";
+    enum?: unknown[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface JsonSchemaObject {
+    type?: "object";
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface CollectionConfig {
+    /** Becomes the tools' description. Say what a document is, for the agent. */
+    description?: string;
+    /**
+     * The document's fields. Optional: without it, filters accept any field
+     * name and writes accept any object. With it, filters and `select` are
+     * limited to these names and writes are typed.
+     */
+    fields?: Record<string, JsonSchemaProperty>;
+    /** Field names a `create_*` call must include. */
+    required?: string[];
+    /**
+     * The field holding the owning user's uid, for the common
+     * `resource.data.<owner> == request.auth.uid` rule: `list_*` filters on
+     * it, `create_*` sets it, `update_*` refuses to change it. A convenience,
+     * not a security boundary: your rules still decide.
+     */
+    owner?: string;
+}
+/** A registered callable function (`onCall`), invoked with the caller's ID token. */
+interface FunctionToolConfig {
+    description: string;
+    input?: JsonSchemaObject;
+    /** Full URL override, e.g. a custom domain or a run.app URL. */
+    url?: string;
+}
+type WriteOp = "create" | "update" | "delete";
+interface ExposifyFirebaseOptions {
+    /**
+     * The Firestore collections agents can use, keyed by collection path.
+     * Subcollections use `{param}` placeholders: `"users/{userId}/notes"`.
+     * A plain array is shorthand for `{ name: {} }` each.
+     */
+    collections?: Record<string, CollectionConfig> | string[];
+    /** `"<collection>.create"` / `.update` / `.delete` / `.*`. Reads need no opt-in. */
+    writes?: string[];
+    /** Callable functions (`onCall`) exposed as `call_<name>` tools. */
+    functions?: Record<string, FunctionToolConfig>;
+    /** Doc globs, relative to the functions source directory. Default: `["docs/**\/*.md"]`. */
+    docs?: string[];
+    /** Default `"public"`. `"required"` hides `search_docs` from callers with no token. */
+    docsAuth?: "public" | "required";
+    /** Cap on documents per `list_*` call regardless of the caller's `limit`. Default 100. */
+    maxDocs?: number;
+    /** Default: `GCLOUD_PROJECT` / `GOOGLE_CLOUD_PROJECT` / `FIREBASE_CONFIG.projectId`, set in every deployed function. */
+    projectId?: string;
+    /** Firestore database id. Default `"(default)"`. */
+    databaseId?: string;
+    /** Region of the callable functions in `functions`. Default `"us-central1"`. */
+    functionsRegion?: string;
+    /**
+     * Resolves the caller's headers into the headers used for Firestore and
+     * callable calls, e.g. `hostedBroker()` (Exposify's hosted broker, from `EXPOSIFY_KEY`).
+     * Only `authorization` from the result is used.
+     */
+    auth?: AuthResolver;
+    /**
+     * With `auth` set: 401 when the resolver returns no `authorization`, instead
+     * of running unauthenticated. Default true with the hosted broker (`EXPOSIFY_KEY`
+     * set, or `auth: hostedBroker()`), which also answers tokenless requests with
+     * Connect's sign-in challenge; false otherwise.
+     */
+    authRequired?: boolean;
+    /** The cold-start "MCP ready" line. Default: on, except under `NODE_ENV=test`. Failures always log. */
+    startupLog?: boolean;
+    /** Injectable for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Overrides `process.env` (tests). */
+    env?: Record<string, string | undefined>;
+    /** Directory doc globs resolve against. Default `process.cwd()` (the functions source directory when deployed). */
+    docsRoot?: string;
+    rateLimit?: number;
+    rateWindowMs?: number;
+}
+interface ResolvedCollection {
+    /** The configured key, e.g. `"users/{userId}/notes"`. */
+    key: string;
+    /** Path segments; odd positions are collection ids, even positions are `{param}` or literal doc ids. */
+    segments: string[];
+    /** `{param}` names in order. */
+    params: string[];
+    /** Tool-name suffix, e.g. `"users_notes"`. */
+    suffix: string;
+    config: CollectionConfig;
+    writes: Set<WriteOp>;
+}
+interface ResolvedFirebaseConfig {
+    collections: ResolvedCollection[];
+    functions: Record<string, FunctionToolConfig>;
+    docs: string[];
+    docsAuth: "public" | "required";
+    maxDocs: number;
+    databaseId: string;
+    functionsRegion: string;
+    rateLimit?: number;
+    rateWindowMs?: number;
+}
+
+/**
+ * Collection keys are Firestore collection paths with `{param}` placeholders
+ * in document positions: `"todos"`, `"users/{userId}/notes"`. A key has an
+ * odd number of segments (it names a collection, not a document); collection
+ * ids (even indexes) must be literal.
+ */
+interface ParsedKey {
+    segments: string[];
+    params: string[];
+    suffix: string;
+}
+/** Throws with a message naming the problem; config.ts turns that into a warning. */
+declare function parseCollectionKey(key: string): ParsedKey;
+
+/**
+ * The MCP endpoint for `onRequest`:
+ *
+ * ```ts
+ * export const mcp = onRequest(aiReady({ collections: { todos: { owner: "uid" } } }));
+ * ```
+ */
+declare function aiReady(options?: ExposifyFirebaseOptions): NodeHandler;
+/**
+ * The same endpoint as a web-standard `Request → Response` handler, for
+ * runtimes other than `onRequest` and for tests. Docs are read and indexed
+ * on the first request and cached for the instance's lifetime.
+ */
+declare function createFirebaseMcpHandler(options?: ExposifyFirebaseOptions): WebMcpHandler;
+/**
+ * The function's public URL from the URL a request arrived at. Behind
+ * `<region>-<project>.cloudfunctions.net/<name>` the function sees the path
+ * without its own name, so the name goes back in; a `run.app` URL already is
+ * the function's root.
+ */
+declare function functionPublicUrl(own: string, functionName: string | undefined): string;
+/** `https://<region>-<project>.cloudfunctions.net/<name>`, or the Functions emulator's URL. */
+declare function callableUrl(name: string, projectId: string, region: string, env: Record<string, string | undefined>): string;
+/** "7 tools (2 list, 2 get, 2 write, 1 callable)": only the kinds present. */
+declare function firebaseToolsPhrase(cfg: ResolvedFirebaseConfig, hasDocs: boolean): string;
+
+export { type CollectionConfig, type ExposifyFirebaseOptions, type FirebaseRequest, type FunctionToolConfig, type JsonSchemaObject, type JsonSchemaProperty, type NodeHandler, aiReady, callableUrl, createFirebaseMcpHandler, firebaseToolsPhrase, functionPublicUrl, parseCollectionKey, toNodeHandler };