mneme-sdk 0.1.0 → 0.4.0

package/dist/index.cjs

@@ -112,7 +112,13 @@ var Mneme = class {
   events;
   kvs;
   constructor(opts) {
-    this.auth = "accessToken" in opts && opts.accessToken ? { accessToken: opts.accessToken } : { account: opts.account };
+    if ("apiKey" in opts && opts.apiKey) {
+      this.auth = { apiKey: opts.apiKey };
+    } else if ("accessToken" in opts && opts.accessToken) {
+      this.auth = { accessToken: opts.accessToken };
+    } else {
+      this.auth = { account: opts.account };
+    }
     this.gatewayUrl = opts.gatewayUrl.replace(/\/$/, "");
     this.chainId = opts.chainId ?? 8453;
     this.domainName = opts.domainName ?? "Mneme";
@@ -140,6 +146,50 @@ var Mneme = class {
   from(table) {
     return new Collection(this, table);
   }
+  /**
+   * Natural-language → SQL via the gateway's LLM proxy.
+   * Use the returned SQL with `m.sql(...)` to execute it.
+   */
+  llm = {
+    sql: (args) => this.request(
+      "POST",
+      "/v1/llm/sql",
+      args
+    )
+  };
+  /**
+   * Service-account API keys — for B2B2C integrators (e.g. Gitlawb) that
+   * distribute scoped keys to end-users who don't have wallets.
+   *
+   * Only callable by wallet-authed clients (keys cannot mint more keys).
+   */
+  serviceKeys = {
+    /** Mint a new scoped key. Returns the raw key value ONCE. */
+    create: (args) => this.request("POST", "/v1/service/keys", args),
+    /** List all keys you've created (no raw values — only metadata). */
+    list: () => this.request("GET", "/v1/service/keys"),
+    /** Revoke a key by id. */
+    revoke: (id) => this.request("DELETE", `/v1/service/keys/${id}`)
+  };
+  /**
+   * Run raw SQL against your project's Postgres schema.
+   *
+   * Safety guards (server-side):
+   *   - 5-second statement timeout
+   *   - search_path pinned to your schema (unqualified table refs resolve to YOUR schema)
+   *   - cross-tenant schema references are blocked
+   *   - 1000-row result cap
+   *   - single statement only
+   *
+   * Returns rows, column metadata, and elapsed time.
+   *
+   * @example
+   * await m.sql("SELECT count(*) FROM memories");
+   * await m.sql("CREATE INDEX ON books (rating)");
+   */
+  sql(query) {
+    return this.request("POST", "/v1/sql", { query });
+  }
   // ─── Storage (Cloudflare R2 backend, $MNEME burn quota) ──────────────────
   storage = {
     upload: async (args) => {
@@ -187,7 +237,9 @@ var Mneme = class {
   async request(method, path, body) {
     const bodyText = body === void 0 ? "" : JSON.stringify(body);
     const headers = { "Content-Type": "application/json" };
-    if ("accessToken" in this.auth && this.auth.accessToken) {
+    if ("apiKey" in this.auth && this.auth.apiKey) {
+      headers["Authorization"] = `ApiKey ${this.auth.apiKey}`;
+    } else if ("accessToken" in this.auth && this.auth.accessToken) {
       headers["Authorization"] = `Bearer ${this.auth.accessToken}`;
     } else if ("account" in this.auth && this.auth.account) {
       const signed = await signRequest({
@@ -201,7 +253,7 @@ var Mneme = class {
       });
       Object.assign(headers, signed);
     } else {
-      throw new Error("Mneme: either { account } or { accessToken } is required");
+      throw new Error("Mneme: one of { account }, { accessToken }, or { apiKey } is required");
     }
     const res = await fetch(`${this.gatewayUrl}${path}`, {
       method,
@@ -220,6 +272,7 @@ var Collection = class {
   }
   mneme;
   table;
+  /** Insert one row or an array of rows. Returns the inserted rows. */
   insert(rows) {
     return this.mneme.request(
       "POST",
@@ -227,14 +280,54 @@ var Collection = class {
       rows
     );
   }
+  /**
+   * List rows. Supports filtering with `where` (PostgREST-style col.op.value),
+   * ordering with `order` (e.g. "created_at.desc"), and pagination.
+   *
+   * Ops: eq, neq, gt, gte, lt, lte, like, ilike, in, is.
+   * Example: `m.from("todos").list({ where: ["done.eq.false"], order: "created_at.desc" })`
+   */
   list(opts) {
     const q = new URLSearchParams();
     if (opts?.limit != null) q.set("limit", String(opts.limit));
     if (opts?.offset != null) q.set("offset", String(opts.offset));
     if (opts?.order) q.set("order", opts.order);
+    if (opts?.where) {
+      const ws = Array.isArray(opts.where) ? opts.where : [opts.where];
+      for (const w of ws) q.append("where", w);
+    }
     const qs = q.toString() ? `?${q}` : "";
     return this.mneme.request("GET", `/v1/rows/${this.table}${qs}`);
   }
+  /** Update one row by id. Returns the updated row. */
+  update(id, updates) {
+    return this.mneme.request(
+      "PATCH",
+      `/v1/rows/${this.table}/${id}`,
+      updates
+    );
+  }
+  /** Delete one row by id. */
+  delete(id) {
+    return this.mneme.request(
+      "DELETE",
+      `/v1/rows/${this.table}/${id}`
+    );
+  }
+  /**
+   * Bulk delete by filter. Refuses to delete the whole table — at least one
+   * where clause is required. Returns the count of deleted rows.
+   */
+  deleteWhere(where) {
+    const ws = Array.isArray(where) ? where : [where];
+    if (ws.length === 0) throw new Error("deleteWhere requires at least one filter");
+    const q = new URLSearchParams();
+    for (const w of ws) q.append("where", w);
+    return this.mneme.request(
+      "DELETE",
+      `/v1/rows/${this.table}?${q}`
+    );
+  }
 };
 
 // src/types.ts

package/dist/index.d.cts

@@ -64,9 +64,15 @@ interface KvRow {
 type MnemeAuth = {
     account: Account;
     accessToken?: never;
+    apiKey?: never;
 } | {
     accessToken: string;
     account?: never;
+    apiKey?: never;
+} | {
+    apiKey: string;
+    account?: never;
+    accessToken?: never;
 };
 type MnemeOptions = MnemeAuth & {
     gatewayUrl: string;
@@ -112,6 +118,86 @@ declare class Mneme {
     }>;
     stats(): Promise<StatsResponse>;
     from<T = unknown>(table: string): Collection<T>;
+    /**
+     * Natural-language → SQL via the gateway's LLM proxy.
+     * Use the returned SQL with `m.sql(...)` to execute it.
+     */
+    llm: {
+        sql: (args: {
+            prompt: string;
+            schema?: string;
+        }) => Promise<{
+            sql: string;
+            model: string;
+            elapsed_ms: number;
+        }>;
+    };
+    /**
+     * Service-account API keys — for B2B2C integrators (e.g. Gitlawb) that
+     * distribute scoped keys to end-users who don't have wallets.
+     *
+     * Only callable by wallet-authed clients (keys cannot mint more keys).
+     */
+    readonly serviceKeys: {
+        /** Mint a new scoped key. Returns the raw key value ONCE. */
+        create: (args: {
+            scope: string;
+            label?: string;
+            rpm_limit?: number;
+        }) => Promise<{
+            ok: true;
+            id: number;
+            key: string;
+            key_prefix: string;
+            scope: string;
+            label: string | null;
+            rpm_limit: number;
+            created_at: string;
+            warning: string;
+        }>;
+        /** List all keys you've created (no raw values — only metadata). */
+        list: () => Promise<{
+            keys: Array<{
+                id: number;
+                key_prefix: string;
+                scope: string;
+                label: string | null;
+                rpm_limit: number;
+                revoked: boolean;
+                revoked_at: string | null;
+                last_used_at: string | null;
+                created_at: string;
+            }>;
+        }>;
+        /** Revoke a key by id. */
+        revoke: (id: number) => Promise<{
+            ok: true;
+            id: number;
+        }>;
+    };
+    /**
+     * Run raw SQL against your project's Postgres schema.
+     *
+     * Safety guards (server-side):
+     *   - 5-second statement timeout
+     *   - search_path pinned to your schema (unqualified table refs resolve to YOUR schema)
+     *   - cross-tenant schema references are blocked
+     *   - 1000-row result cap
+     *   - single statement only
+     *
+     * Returns rows, column metadata, and elapsed time.
+     *
+     * @example
+     * await m.sql("SELECT count(*) FROM memories");
+     * await m.sql("CREATE INDEX ON books (rating)");
+     */
+    sql<T = Record<string, unknown>>(query: string): Promise<{
+        rows: T[];
+        row_count: number;
+        columns: string[];
+        truncated: boolean;
+        elapsed_ms: number;
+    }>;
     readonly storage: {
         upload: (args: {
             key: string;
@@ -183,20 +269,49 @@ declare class Mneme {
     };
     request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
 }
+/** PostgREST-ish where clause. e.g. `["status.eq.done", "score.gt.10"]`. */
+type WhereClause = string;
 declare class Collection<T = unknown> {
     private mneme;
     readonly table: string;
     constructor(mneme: Mneme, table: string);
+    /** Insert one row or an array of rows. Returns the inserted rows. */
     insert(rows: T | T[]): Promise<{
         inserted: number;
         rows: T[];
     }>;
+    /**
+     * List rows. Supports filtering with `where` (PostgREST-style col.op.value),
+     * ordering with `order` (e.g. "created_at.desc"), and pagination.
+     *
+     * Ops: eq, neq, gt, gte, lt, lte, like, ilike, in, is.
+     * Example: `m.from("todos").list({ where: ["done.eq.false"], order: "created_at.desc" })`
+     */
     list(opts?: {
         limit?: number;
         offset?: number;
         order?: string;
+        where?: WhereClause | WhereClause[];
     }): Promise<{
         rows: T[];
+        count: number;
+    }>;
+    /** Update one row by id. Returns the updated row. */
+    update(id: string | number, updates: Partial<T>): Promise<{
+        updated: 1;
+        row: T;
+    }>;
+    /** Delete one row by id. */
+    delete(id: string | number): Promise<{
+        deleted: 1;
+        id: number | string;
+    }>;
+    /**
+     * Bulk delete by filter. Refuses to delete the whole table — at least one
+     * where clause is required. Returns the count of deleted rows.
+     */
+    deleteWhere(where: WhereClause | WhereClause[]): Promise<{
+        deleted: number;
     }>;
 }
 

package/dist/index.d.ts

@@ -64,9 +64,15 @@ interface KvRow {
 type MnemeAuth = {
     account: Account;
     accessToken?: never;
+    apiKey?: never;
 } | {
     accessToken: string;
     account?: never;
+    apiKey?: never;
+} | {
+    apiKey: string;
+    account?: never;
+    accessToken?: never;
 };
 type MnemeOptions = MnemeAuth & {
     gatewayUrl: string;
@@ -112,6 +118,86 @@ declare class Mneme {
     }>;
     stats(): Promise<StatsResponse>;
     from<T = unknown>(table: string): Collection<T>;
+    /**
+     * Natural-language → SQL via the gateway's LLM proxy.
+     * Use the returned SQL with `m.sql(...)` to execute it.
+     */
+    llm: {
+        sql: (args: {
+            prompt: string;
+            schema?: string;
+        }) => Promise<{
+            sql: string;
+            model: string;
+            elapsed_ms: number;
+        }>;
+    };
+    /**
+     * Service-account API keys — for B2B2C integrators (e.g. Gitlawb) that
+     * distribute scoped keys to end-users who don't have wallets.
+     *
+     * Only callable by wallet-authed clients (keys cannot mint more keys).
+     */
+    readonly serviceKeys: {
+        /** Mint a new scoped key. Returns the raw key value ONCE. */
+        create: (args: {
+            scope: string;
+            label?: string;
+            rpm_limit?: number;
+        }) => Promise<{
+            ok: true;
+            id: number;
+            key: string;
+            key_prefix: string;
+            scope: string;
+            label: string | null;
+            rpm_limit: number;
+            created_at: string;
+            warning: string;
+        }>;
+        /** List all keys you've created (no raw values — only metadata). */
+        list: () => Promise<{
+            keys: Array<{
+                id: number;
+                key_prefix: string;
+                scope: string;
+                label: string | null;
+                rpm_limit: number;
+                revoked: boolean;
+                revoked_at: string | null;
+                last_used_at: string | null;
+                created_at: string;
+            }>;
+        }>;
+        /** Revoke a key by id. */
+        revoke: (id: number) => Promise<{
+            ok: true;
+            id: number;
+        }>;
+    };
+    /**
+     * Run raw SQL against your project's Postgres schema.
+     *
+     * Safety guards (server-side):
+     *   - 5-second statement timeout
+     *   - search_path pinned to your schema (unqualified table refs resolve to YOUR schema)
+     *   - cross-tenant schema references are blocked
+     *   - 1000-row result cap
+     *   - single statement only
+     *
+     * Returns rows, column metadata, and elapsed time.
+     *
+     * @example
+     * await m.sql("SELECT count(*) FROM memories");
+     * await m.sql("CREATE INDEX ON books (rating)");
+     */
+    sql<T = Record<string, unknown>>(query: string): Promise<{
+        rows: T[];
+        row_count: number;
+        columns: string[];
+        truncated: boolean;
+        elapsed_ms: number;
+    }>;
     readonly storage: {
         upload: (args: {
             key: string;
@@ -183,20 +269,49 @@ declare class Mneme {
     };
     request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
 }
+/** PostgREST-ish where clause. e.g. `["status.eq.done", "score.gt.10"]`. */
+type WhereClause = string;
 declare class Collection<T = unknown> {
     private mneme;
     readonly table: string;
     constructor(mneme: Mneme, table: string);
+    /** Insert one row or an array of rows. Returns the inserted rows. */
     insert(rows: T | T[]): Promise<{
         inserted: number;
         rows: T[];
     }>;
+    /**
+     * List rows. Supports filtering with `where` (PostgREST-style col.op.value),
+     * ordering with `order` (e.g. "created_at.desc"), and pagination.
+     *
+     * Ops: eq, neq, gt, gte, lt, lte, like, ilike, in, is.
+     * Example: `m.from("todos").list({ where: ["done.eq.false"], order: "created_at.desc" })`
+     */
     list(opts?: {
         limit?: number;
         offset?: number;
         order?: string;
+        where?: WhereClause | WhereClause[];
     }): Promise<{
         rows: T[];
+        count: number;
+    }>;
+    /** Update one row by id. Returns the updated row. */
+    update(id: string | number, updates: Partial<T>): Promise<{
+        updated: 1;
+        row: T;
+    }>;
+    /** Delete one row by id. */
+    delete(id: string | number): Promise<{
+        deleted: 1;
+        id: number | string;
+    }>;
+    /**
+     * Bulk delete by filter. Refuses to delete the whole table — at least one
+     * where clause is required. Returns the count of deleted rows.
+     */
+    deleteWhere(where: WhereClause | WhereClause[]): Promise<{
+        deleted: number;
     }>;
 }
 

package/dist/index.js

@@ -80,7 +80,13 @@ var Mneme = class {
   events;
   kvs;
   constructor(opts) {
-    this.auth = "accessToken" in opts && opts.accessToken ? { accessToken: opts.accessToken } : { account: opts.account };
+    if ("apiKey" in opts && opts.apiKey) {
+      this.auth = { apiKey: opts.apiKey };
+    } else if ("accessToken" in opts && opts.accessToken) {
+      this.auth = { accessToken: opts.accessToken };
+    } else {
+      this.auth = { account: opts.account };
+    }
     this.gatewayUrl = opts.gatewayUrl.replace(/\/$/, "");
     this.chainId = opts.chainId ?? 8453;
     this.domainName = opts.domainName ?? "Mneme";
@@ -108,6 +114,50 @@ var Mneme = class {
   from(table) {
     return new Collection(this, table);
   }
+  /**
+   * Natural-language → SQL via the gateway's LLM proxy.
+   * Use the returned SQL with `m.sql(...)` to execute it.
+   */
+  llm = {
+    sql: (args) => this.request(
+      "POST",
+      "/v1/llm/sql",
+      args
+    )
+  };
+  /**
+   * Service-account API keys — for B2B2C integrators (e.g. Gitlawb) that
+   * distribute scoped keys to end-users who don't have wallets.
+   *
+   * Only callable by wallet-authed clients (keys cannot mint more keys).
+   */
+  serviceKeys = {
+    /** Mint a new scoped key. Returns the raw key value ONCE. */
+    create: (args) => this.request("POST", "/v1/service/keys", args),
+    /** List all keys you've created (no raw values — only metadata). */
+    list: () => this.request("GET", "/v1/service/keys"),
+    /** Revoke a key by id. */
+    revoke: (id) => this.request("DELETE", `/v1/service/keys/${id}`)
+  };
+  /**
+   * Run raw SQL against your project's Postgres schema.
+   *
+   * Safety guards (server-side):
+   *   - 5-second statement timeout
+   *   - search_path pinned to your schema (unqualified table refs resolve to YOUR schema)
+   *   - cross-tenant schema references are blocked
+   *   - 1000-row result cap
+   *   - single statement only
+   *
+   * Returns rows, column metadata, and elapsed time.
+   *
+   * @example
+   * await m.sql("SELECT count(*) FROM memories");
+   * await m.sql("CREATE INDEX ON books (rating)");
+   */
+  sql(query) {
+    return this.request("POST", "/v1/sql", { query });
+  }
   // ─── Storage (Cloudflare R2 backend, $MNEME burn quota) ──────────────────
   storage = {
     upload: async (args) => {
@@ -155,7 +205,9 @@ var Mneme = class {
   async request(method, path, body) {
     const bodyText = body === void 0 ? "" : JSON.stringify(body);
     const headers = { "Content-Type": "application/json" };
-    if ("accessToken" in this.auth && this.auth.accessToken) {
+    if ("apiKey" in this.auth && this.auth.apiKey) {
+      headers["Authorization"] = `ApiKey ${this.auth.apiKey}`;
+    } else if ("accessToken" in this.auth && this.auth.accessToken) {
       headers["Authorization"] = `Bearer ${this.auth.accessToken}`;
     } else if ("account" in this.auth && this.auth.account) {
       const signed = await signRequest({
@@ -169,7 +221,7 @@ var Mneme = class {
       });
       Object.assign(headers, signed);
     } else {
-      throw new Error("Mneme: either { account } or { accessToken } is required");
+      throw new Error("Mneme: one of { account }, { accessToken }, or { apiKey } is required");
     }
     const res = await fetch(`${this.gatewayUrl}${path}`, {
       method,
@@ -188,6 +240,7 @@ var Collection = class {
   }
   mneme;
   table;
+  /** Insert one row or an array of rows. Returns the inserted rows. */
   insert(rows) {
     return this.mneme.request(
       "POST",
@@ -195,14 +248,54 @@ var Collection = class {
       rows
     );
   }
+  /**
+   * List rows. Supports filtering with `where` (PostgREST-style col.op.value),
+   * ordering with `order` (e.g. "created_at.desc"), and pagination.
+   *
+   * Ops: eq, neq, gt, gte, lt, lte, like, ilike, in, is.
+   * Example: `m.from("todos").list({ where: ["done.eq.false"], order: "created_at.desc" })`
+   */
   list(opts) {
     const q = new URLSearchParams();
     if (opts?.limit != null) q.set("limit", String(opts.limit));
     if (opts?.offset != null) q.set("offset", String(opts.offset));
     if (opts?.order) q.set("order", opts.order);
+    if (opts?.where) {
+      const ws = Array.isArray(opts.where) ? opts.where : [opts.where];
+      for (const w of ws) q.append("where", w);
+    }
     const qs = q.toString() ? `?${q}` : "";
     return this.mneme.request("GET", `/v1/rows/${this.table}${qs}`);
   }
+  /** Update one row by id. Returns the updated row. */
+  update(id, updates) {
+    return this.mneme.request(
+      "PATCH",
+      `/v1/rows/${this.table}/${id}`,
+      updates
+    );
+  }
+  /** Delete one row by id. */
+  delete(id) {
+    return this.mneme.request(
+      "DELETE",
+      `/v1/rows/${this.table}/${id}`
+    );
+  }
+  /**
+   * Bulk delete by filter. Refuses to delete the whole table — at least one
+   * where clause is required. Returns the count of deleted rows.
+   */
+  deleteWhere(where) {
+    const ws = Array.isArray(where) ? where : [where];
+    if (ws.length === 0) throw new Error("deleteWhere requires at least one filter");
+    const q = new URLSearchParams();
+    for (const w of ws) q.append("where", w);
+    return this.mneme.request(
+      "DELETE",
+      `/v1/rows/${this.table}?${q}`
+    );
+  }
 };
 
 // src/types.ts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mneme-sdk",
-  "version": "0.1.0",
-  "description": "TypeScript SDK for Mneme — agent-native Postgres + R2 storage on Base. Wallet-auth, runtime DDL, pgvector, wallet-bound files with $MNEME burn quota.",
+  "version": "0.4.0",
+  "description": "TypeScript SDK for Mneme — agent-native Postgres + R2 storage on Base. Wallet-auth, runtime DDL, full CRUD with WHERE filters, raw SQL, pgvector, service-account API keys for B2B2C integrations, wallet-bound files with $MNEME burn quota.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",