@exposify/supabase 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,171 @@
+import { WebMcpHandler } from '@exposify/core';
+
+type ColumnType = "string" | "number" | "integer" | "boolean" | "object" | "array";
+interface ColumnSchema {
+    name: string;
+    type: ColumnType;
+    /** OpenAPI `format`, e.g. "uuid", "timestamp with time zone", "bigint". */
+    format?: string;
+    required: boolean;
+    /** From `agentify_meta()`'s `column_comment` (a `COMMENT ON COLUMN`), not OpenAPI. */
+    description?: string;
+    isPrimaryKey?: boolean;
+}
+interface TableSchema {
+    name: string;
+    rlsEnabled: boolean;
+    /** From `agentify_meta()`'s `table_comment` (a `COMMENT ON TABLE`). */
+    description?: string;
+    columns: ColumnSchema[];
+}
+/** One row of `agentify_meta()` -- the migration returns one row per column. */
+interface MetaRow {
+    table_name: string;
+    rls_enabled: boolean;
+    table_comment: string | null;
+    column_name: string;
+    column_comment: string | null;
+}
+/** Registered sibling edge function exposed as a tool. */
+interface FunctionToolConfig {
+    description: string;
+    /** A pragmatic JSON Schema subset -- see jsonschema-to-zod.ts. */
+    input?: JsonSchemaObject;
+}
+interface JsonSchemaProperty {
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+    description?: string;
+    enum?: unknown[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface JsonSchemaObject {
+    type?: "object";
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface AgentifySupabaseOptions {
+    /** `"<table>.insert"` / `"<table>.update"` / `"<table>.delete"` / `"<table>.*"`. */
+    writes?: string[];
+    /** Postgres function names exposed as `rpc_<fn>` tools. */
+    rpc?: string[];
+    /** Sibling edge functions, invoked via fetch with the caller's forwarded JWT. */
+    functions?: Record<string, FunctionToolConfig>;
+    /** Doc globs bundled in the function directory. Default: `["docs/**\/*.md"]`. */
+    docs?: string[];
+    docsAuth?: "public" | "required";
+    /** Row cap applied to every `query_<table>` call regardless of caller-supplied `limit`. Default 100. */
+    maxRows?: number;
+    /** Overrides for local/CI use -- production reads these from the Deno env automatically. */
+    supabaseUrl?: string;
+    anonKey?: string;
+    /** Injectable for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Bundled fallback manifest (from `agentify-supabase generate`), used when runtime introspection fails. */
+    manifest?: unknown;
+    rateLimit?: number;
+    rateWindowMs?: number;
+}
+
+/** Subset of PostgREST's generated OpenAPI (Swagger 2.0) document that we read. */
+interface PostgrestOpenApiDoc {
+    definitions?: Record<string, PostgrestTableDefinition>;
+    paths?: Record<string, PostgrestPathItem>;
+}
+interface PostgrestPathItem {
+    post?: {
+        parameters?: PostgrestParameter[];
+    };
+}
+interface PostgrestParameter {
+    in?: string;
+    schema?: {
+        type?: string;
+        properties?: Record<string, PostgrestColumnProperty>;
+        required?: string[];
+    };
+}
+interface PostgrestTableDefinition {
+    properties?: Record<string, PostgrestColumnProperty>;
+    required?: string[];
+}
+interface PostgrestColumnProperty {
+    type?: string;
+    format?: string;
+    description?: string;
+}
+/**
+ * Extracts column schemas for one table from a PostgREST OpenAPI document.
+ * Returns `[]` for a table PostgREST never exposed (not in `definitions` --
+ * e.g. it exists at the catalog level per `agentify_meta()` but PostgREST's
+ * role lacks USAGE/SELECT grants on it), which the caller treats the same as
+ * "RLS-less": never shown to the agent.
+ */
+declare function columnsFromOpenApi(doc: PostgrestOpenApiDoc, table: string): ColumnSchema[];
+/**
+ * Best-effort extraction of an `rpc_<fn>` tool's argument schema from
+ * PostgREST's OpenAPI doc (Swagger 2.0 body parameter on `POST /rpc/<fn>`).
+ * Returns `null` when the shape isn't there or isn't the expected object
+ * schema -- the caller falls back to a permissive `args` record (see
+ * server.ts), never throws.
+ */
+declare function rpcArgSchema(doc: PostgrestOpenApiDoc, fn: string): JsonSchemaObject | null;
+
+declare const MANIFEST_VERSION = 1;
+interface AgentifyManifest {
+    version: typeof MANIFEST_VERSION;
+    generatedAt: string;
+    tables: TableSchema[];
+}
+/** Built by `npx agentify-supabase generate` against a local/linked project. */
+declare function buildManifest(openapi: PostgrestOpenApiDoc, metaRows: MetaRow[], generatedAt: string): AgentifyManifest;
+/**
+ * Defensive load: a manifest is bundled JSON shipped alongside the function
+ * and can go stale relative to the deployed schema, or simply be malformed
+ * (hand-edited, wrong version). Returns `null` -- never throws -- so the
+ * degradation ladder can fall through to the next rung instead of crashing.
+ */
+declare function loadManifest(raw: unknown): AgentifyManifest | null;
+
+/**
+ * Merges PostgREST's OpenAPI document (column types) with `agentify_meta()`
+ * rows (RLS status + comments) into the DB tool surface.
+ *
+ * DB exposure policy (spec, locked): RLS-gated, reads auto. A table only
+ * appears here if `agentify_meta()` reports `rls_enabled: true` for it AND
+ * PostgREST actually exposes it in its OpenAPI `definitions` (the role
+ * calling this has grants on it) -- a table failing either check never
+ * appears, silently, exactly like a table PostgREST doesn't know about at
+ * all. There is no override: an RLS-less table is invisible even if the
+ * owner explicitly lists it in `writes`.
+ */
+declare function introspectTables(openapi: PostgrestOpenApiDoc, metaRows: MetaRow[]): TableSchema[];
+
+declare class MissingAgentifyMetaError extends Error {
+    constructor(cause: string);
+}
+/**
+ * Calls the `agentify_meta()` Postgres function via PostgREST's RPC
+ * endpoint. Requires the migration from `sql/agentify_meta.sql` to have been
+ * applied; a 404 (unknown route) or PostgREST's `PGRST202` (function not
+ * found in schema cache) both mean "migration missing" and are translated
+ * into a self-diagnosing error (spec: "a missing `agentify_meta()` migration
+ * produces a self-diagnosing message naming the exact fix").
+ */
+declare function fetchAgentifyMeta(postgrestUrl: string, headers: Headers, fetchImpl: typeof fetch): Promise<MetaRow[]>;
+
+/** PostgREST serves its OpenAPI document at the API root when asked for it explicitly. */
+declare function fetchOpenApi(postgrestUrl: string, headers: Headers, fetchImpl: typeof fetch): Promise<PostgrestOpenApiDoc>;
+
+/**
+ * Builds the `Deno.serve`-compatible MCP handler. Everything expensive
+ * (OpenAPI fetch, `agentify_meta()` call, doc loading/chunking) happens
+ * lazily on first request and is cached in-memory for the life of the edge
+ * instance -- "cold start" in the spec's sense, not literally module load,
+ * since env vars and the incoming JWT aren't available before the first
+ * request lands anyway.
+ */
+declare function aiReady(options?: AgentifySupabaseOptions): WebMcpHandler;
+
+export { type AgentifyManifest, type AgentifySupabaseOptions, MANIFEST_VERSION, MissingAgentifyMetaError, type PostgrestOpenApiDoc, aiReady, buildManifest, columnsFromOpenApi, fetchAgentifyMeta, fetchOpenApi, introspectTables, loadManifest, rpcArgSchema };

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+import { WebMcpHandler } from '@exposify/core';
+
+type ColumnType = "string" | "number" | "integer" | "boolean" | "object" | "array";
+interface ColumnSchema {
+    name: string;
+    type: ColumnType;
+    /** OpenAPI `format`, e.g. "uuid", "timestamp with time zone", "bigint". */
+    format?: string;
+    required: boolean;
+    /** From `agentify_meta()`'s `column_comment` (a `COMMENT ON COLUMN`), not OpenAPI. */
+    description?: string;
+    isPrimaryKey?: boolean;
+}
+interface TableSchema {
+    name: string;
+    rlsEnabled: boolean;
+    /** From `agentify_meta()`'s `table_comment` (a `COMMENT ON TABLE`). */
+    description?: string;
+    columns: ColumnSchema[];
+}
+/** One row of `agentify_meta()` -- the migration returns one row per column. */
+interface MetaRow {
+    table_name: string;
+    rls_enabled: boolean;
+    table_comment: string | null;
+    column_name: string;
+    column_comment: string | null;
+}
+/** Registered sibling edge function exposed as a tool. */
+interface FunctionToolConfig {
+    description: string;
+    /** A pragmatic JSON Schema subset -- see jsonschema-to-zod.ts. */
+    input?: JsonSchemaObject;
+}
+interface JsonSchemaProperty {
+    type: "string" | "number" | "integer" | "boolean" | "array" | "object";
+    description?: string;
+    enum?: unknown[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface JsonSchemaObject {
+    type?: "object";
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+interface AgentifySupabaseOptions {
+    /** `"<table>.insert"` / `"<table>.update"` / `"<table>.delete"` / `"<table>.*"`. */
+    writes?: string[];
+    /** Postgres function names exposed as `rpc_<fn>` tools. */
+    rpc?: string[];
+    /** Sibling edge functions, invoked via fetch with the caller's forwarded JWT. */
+    functions?: Record<string, FunctionToolConfig>;
+    /** Doc globs bundled in the function directory. Default: `["docs/**\/*.md"]`. */
+    docs?: string[];
+    docsAuth?: "public" | "required";
+    /** Row cap applied to every `query_<table>` call regardless of caller-supplied `limit`. Default 100. */
+    maxRows?: number;
+    /** Overrides for local/CI use -- production reads these from the Deno env automatically. */
+    supabaseUrl?: string;
+    anonKey?: string;
+    /** Injectable for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Bundled fallback manifest (from `agentify-supabase generate`), used when runtime introspection fails. */
+    manifest?: unknown;
+    rateLimit?: number;
+    rateWindowMs?: number;
+}
+
+/** Subset of PostgREST's generated OpenAPI (Swagger 2.0) document that we read. */
+interface PostgrestOpenApiDoc {
+    definitions?: Record<string, PostgrestTableDefinition>;
+    paths?: Record<string, PostgrestPathItem>;
+}
+interface PostgrestPathItem {
+    post?: {
+        parameters?: PostgrestParameter[];
+    };
+}
+interface PostgrestParameter {
+    in?: string;
+    schema?: {
+        type?: string;
+        properties?: Record<string, PostgrestColumnProperty>;
+        required?: string[];
+    };
+}
+interface PostgrestTableDefinition {
+    properties?: Record<string, PostgrestColumnProperty>;
+    required?: string[];
+}
+interface PostgrestColumnProperty {
+    type?: string;
+    format?: string;
+    description?: string;
+}
+/**
+ * Extracts column schemas for one table from a PostgREST OpenAPI document.
+ * Returns `[]` for a table PostgREST never exposed (not in `definitions` --
+ * e.g. it exists at the catalog level per `agentify_meta()` but PostgREST's
+ * role lacks USAGE/SELECT grants on it), which the caller treats the same as
+ * "RLS-less": never shown to the agent.
+ */
+declare function columnsFromOpenApi(doc: PostgrestOpenApiDoc, table: string): ColumnSchema[];
+/**
+ * Best-effort extraction of an `rpc_<fn>` tool's argument schema from
+ * PostgREST's OpenAPI doc (Swagger 2.0 body parameter on `POST /rpc/<fn>`).
+ * Returns `null` when the shape isn't there or isn't the expected object
+ * schema -- the caller falls back to a permissive `args` record (see
+ * server.ts), never throws.
+ */
+declare function rpcArgSchema(doc: PostgrestOpenApiDoc, fn: string): JsonSchemaObject | null;
+
+declare const MANIFEST_VERSION = 1;
+interface AgentifyManifest {
+    version: typeof MANIFEST_VERSION;
+    generatedAt: string;
+    tables: TableSchema[];
+}
+/** Built by `npx agentify-supabase generate` against a local/linked project. */
+declare function buildManifest(openapi: PostgrestOpenApiDoc, metaRows: MetaRow[], generatedAt: string): AgentifyManifest;
+/**
+ * Defensive load: a manifest is bundled JSON shipped alongside the function
+ * and can go stale relative to the deployed schema, or simply be malformed
+ * (hand-edited, wrong version). Returns `null` -- never throws -- so the
+ * degradation ladder can fall through to the next rung instead of crashing.
+ */
+declare function loadManifest(raw: unknown): AgentifyManifest | null;
+
+/**
+ * Merges PostgREST's OpenAPI document (column types) with `agentify_meta()`
+ * rows (RLS status + comments) into the DB tool surface.
+ *
+ * DB exposure policy (spec, locked): RLS-gated, reads auto. A table only
+ * appears here if `agentify_meta()` reports `rls_enabled: true` for it AND
+ * PostgREST actually exposes it in its OpenAPI `definitions` (the role
+ * calling this has grants on it) -- a table failing either check never
+ * appears, silently, exactly like a table PostgREST doesn't know about at
+ * all. There is no override: an RLS-less table is invisible even if the
+ * owner explicitly lists it in `writes`.
+ */
+declare function introspectTables(openapi: PostgrestOpenApiDoc, metaRows: MetaRow[]): TableSchema[];
+
+declare class MissingAgentifyMetaError extends Error {
+    constructor(cause: string);
+}
+/**
+ * Calls the `agentify_meta()` Postgres function via PostgREST's RPC
+ * endpoint. Requires the migration from `sql/agentify_meta.sql` to have been
+ * applied; a 404 (unknown route) or PostgREST's `PGRST202` (function not
+ * found in schema cache) both mean "migration missing" and are translated
+ * into a self-diagnosing error (spec: "a missing `agentify_meta()` migration
+ * produces a self-diagnosing message naming the exact fix").
+ */
+declare function fetchAgentifyMeta(postgrestUrl: string, headers: Headers, fetchImpl: typeof fetch): Promise<MetaRow[]>;
+
+/** PostgREST serves its OpenAPI document at the API root when asked for it explicitly. */
+declare function fetchOpenApi(postgrestUrl: string, headers: Headers, fetchImpl: typeof fetch): Promise<PostgrestOpenApiDoc>;
+
+/**
+ * Builds the `Deno.serve`-compatible MCP handler. Everything expensive
+ * (OpenAPI fetch, `agentify_meta()` call, doc loading/chunking) happens
+ * lazily on first request and is cached in-memory for the life of the edge
+ * instance -- "cold start" in the spec's sense, not literally module load,
+ * since env vars and the incoming JWT aren't available before the first
+ * request lands anyway.
+ */
+declare function aiReady(options?: AgentifySupabaseOptions): WebMcpHandler;
+
+export { type AgentifyManifest, type AgentifySupabaseOptions, MANIFEST_VERSION, MissingAgentifyMetaError, type PostgrestOpenApiDoc, aiReady, buildManifest, columnsFromOpenApi, fetchAgentifyMeta, fetchOpenApi, introspectTables, loadManifest, rpcArgSchema };