mneme-sdk 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -140,6 +140,25 @@ var Mneme = class {
   from(table) {
     return new Collection(this, table);
   }
+  /**
+   * 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) => {
@@ -220,6 +239,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 +247,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

@@ -112,6 +112,29 @@ declare class Mneme {
     }>;
     stats(): Promise<StatsResponse>;
     from<T = unknown>(table: string): Collection<T>;
+    /**
+     * 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 +206,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

@@ -112,6 +112,29 @@ declare class Mneme {
     }>;
     stats(): Promise<StatsResponse>;
     from<T = unknown>(table: string): Collection<T>;
+    /**
+     * 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 +206,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

@@ -108,6 +108,25 @@ var Mneme = class {
   from(table) {
     return new Collection(this, table);
   }
+  /**
+   * 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) => {
@@ -188,6 +207,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 +215,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.3.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, wallet-bound files with $MNEME burn quota.",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",