mneme-sdk 0.0.1 → 0.3.0

package/dist/index.cjs

@@ -74,6 +74,24 @@ function randomNonce() {
 }
 
 // src/client.ts
+async function toUint8Array(input) {
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    return new Uint8Array(await input.arrayBuffer());
+  }
+  if (typeof input === "string") return new TextEncoder().encode(input);
+  throw new Error("unsupported file type for storage.upload");
+}
+function uint8ToBase64(bytes) {
+  const CHUNK = 32768;
+  const parts = [];
+  for (let i = 0; i < bytes.byteLength; i += CHUNK) {
+    parts.push(String.fromCharCode(...bytes.subarray(i, i + CHUNK)));
+  }
+  if (typeof btoa !== "undefined") return btoa(parts.join(""));
+  return Buffer.from(parts.join(""), "binary").toString("base64");
+}
 var MnemeError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -122,6 +140,69 @@ 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) => {
+      const bytes = await toUint8Array(args.file);
+      const content_base64 = uint8ToBase64(bytes);
+      return this.request("POST", "/v1/storage/upload", {
+        key: args.key,
+        visibility: args.visibility ?? "private",
+        content_type: args.contentType ?? "application/octet-stream",
+        content_base64
+      });
+    },
+    list: (args) => {
+      const q = new URLSearchParams();
+      if (args?.visibility) q.set("visibility", args.visibility);
+      if (args?.prefix) q.set("prefix", args.prefix);
+      return this.request("GET", `/v1/storage/list${q.toString() ? `?${q}` : ""}`);
+    },
+    delete: (args) => {
+      const q = new URLSearchParams({ key: args.key });
+      if (args.visibility) q.set("visibility", args.visibility);
+      return this.request(
+        "DELETE",
+        `/v1/storage/object?${q}`
+      );
+    },
+    url: (args) => {
+      const q = new URLSearchParams({ key: args.key });
+      if (args.visibility) q.set("visibility", args.visibility);
+      if (args.expiresIn != null) q.set("expires_in", String(args.expiresIn));
+      return this.request(
+        "GET",
+        `/v1/storage/url?${q}`
+      );
+    },
+    quota: () => this.request("GET", "/v1/storage/quota"),
+    /**
+     * Credit a $MNEME burn tx → extend storage capacity.
+     *   100 $MNEME →   1 GB / 30d
+     *   1000 $MNEME →  10 GB / 30d
+     *  10000 $MNEME → 100 GB / 30d
+     */
+    burn: (args) => this.request("POST", "/v1/storage/burn", { tx_hash: args.tx_hash })
+  };
   async request(method, path, body) {
     const bodyText = body === void 0 ? "" : JSON.stringify(body);
     const headers = { "Content-Type": "application/json" };
@@ -158,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",
@@ -165,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,22 +112,143 @@ 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;
+            file: Blob | Uint8Array | ArrayBuffer | string;
+            visibility?: "public" | "private";
+            contentType?: string;
+        }) => Promise<{
+            ok: true;
+            key: string;
+            visibility: "public" | "private";
+            size: number;
+            content_type: string;
+            public_url?: string;
+        }>;
+        list: (args?: {
+            visibility?: "public" | "private";
+            prefix?: string;
+        }) => Promise<{
+            visibility: "public" | "private";
+            count: number;
+            objects: Array<{
+                key: string;
+                size: number;
+                last_modified: string;
+                public_url?: string;
+            }>;
+        }>;
+        delete: (args: {
+            key: string;
+            visibility?: "public" | "private";
+        }) => Promise<{
+            ok: true;
+            key: string;
+            freed_bytes: number;
+        }>;
+        url: (args: {
+            key: string;
+            visibility?: "public" | "private";
+            expiresIn?: number;
+        }) => Promise<{
+            url: string;
+            expires_in: number;
+        }>;
+        quota: () => Promise<{
+            wallet: string;
+            bytes_used: number;
+            bytes_limit: number;
+            bytes_available: number;
+            free_tier_bytes: number;
+            bonus_expires_at: string | null;
+        }>;
+        /**
+         * Credit a $MNEME burn tx → extend storage capacity.
+         *   100 $MNEME →   1 GB / 30d
+         *   1000 $MNEME →  10 GB / 30d
+         *  10000 $MNEME → 100 GB / 30d
+         */
+        burn: (args: {
+            tx_hash: string;
+        }) => Promise<{
+            ok: true;
+            tx_hash: string;
+            burned_tokens: number;
+            tier: string;
+            bytes_added: number;
+            days_added: number;
+            new_expires_at: string;
+        }>;
+    };
     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,22 +112,143 @@ 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;
+            file: Blob | Uint8Array | ArrayBuffer | string;
+            visibility?: "public" | "private";
+            contentType?: string;
+        }) => Promise<{
+            ok: true;
+            key: string;
+            visibility: "public" | "private";
+            size: number;
+            content_type: string;
+            public_url?: string;
+        }>;
+        list: (args?: {
+            visibility?: "public" | "private";
+            prefix?: string;
+        }) => Promise<{
+            visibility: "public" | "private";
+            count: number;
+            objects: Array<{
+                key: string;
+                size: number;
+                last_modified: string;
+                public_url?: string;
+            }>;
+        }>;
+        delete: (args: {
+            key: string;
+            visibility?: "public" | "private";
+        }) => Promise<{
+            ok: true;
+            key: string;
+            freed_bytes: number;
+        }>;
+        url: (args: {
+            key: string;
+            visibility?: "public" | "private";
+            expiresIn?: number;
+        }) => Promise<{
+            url: string;
+            expires_in: number;
+        }>;
+        quota: () => Promise<{
+            wallet: string;
+            bytes_used: number;
+            bytes_limit: number;
+            bytes_available: number;
+            free_tier_bytes: number;
+            bonus_expires_at: string | null;
+        }>;
+        /**
+         * Credit a $MNEME burn tx → extend storage capacity.
+         *   100 $MNEME →   1 GB / 30d
+         *   1000 $MNEME →  10 GB / 30d
+         *  10000 $MNEME → 100 GB / 30d
+         */
+        burn: (args: {
+            tx_hash: string;
+        }) => Promise<{
+            ok: true;
+            tx_hash: string;
+            burned_tokens: number;
+            tier: string;
+            bytes_added: number;
+            days_added: number;
+            new_expires_at: string;
+        }>;
+    };
     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

@@ -42,6 +42,24 @@ function randomNonce() {
 }
 
 // src/client.ts
+async function toUint8Array(input) {
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  if (typeof Blob !== "undefined" && input instanceof Blob) {
+    return new Uint8Array(await input.arrayBuffer());
+  }
+  if (typeof input === "string") return new TextEncoder().encode(input);
+  throw new Error("unsupported file type for storage.upload");
+}
+function uint8ToBase64(bytes) {
+  const CHUNK = 32768;
+  const parts = [];
+  for (let i = 0; i < bytes.byteLength; i += CHUNK) {
+    parts.push(String.fromCharCode(...bytes.subarray(i, i + CHUNK)));
+  }
+  if (typeof btoa !== "undefined") return btoa(parts.join(""));
+  return Buffer.from(parts.join(""), "binary").toString("base64");
+}
 var MnemeError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -90,6 +108,69 @@ 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) => {
+      const bytes = await toUint8Array(args.file);
+      const content_base64 = uint8ToBase64(bytes);
+      return this.request("POST", "/v1/storage/upload", {
+        key: args.key,
+        visibility: args.visibility ?? "private",
+        content_type: args.contentType ?? "application/octet-stream",
+        content_base64
+      });
+    },
+    list: (args) => {
+      const q = new URLSearchParams();
+      if (args?.visibility) q.set("visibility", args.visibility);
+      if (args?.prefix) q.set("prefix", args.prefix);
+      return this.request("GET", `/v1/storage/list${q.toString() ? `?${q}` : ""}`);
+    },
+    delete: (args) => {
+      const q = new URLSearchParams({ key: args.key });
+      if (args.visibility) q.set("visibility", args.visibility);
+      return this.request(
+        "DELETE",
+        `/v1/storage/object?${q}`
+      );
+    },
+    url: (args) => {
+      const q = new URLSearchParams({ key: args.key });
+      if (args.visibility) q.set("visibility", args.visibility);
+      if (args.expiresIn != null) q.set("expires_in", String(args.expiresIn));
+      return this.request(
+        "GET",
+        `/v1/storage/url?${q}`
+      );
+    },
+    quota: () => this.request("GET", "/v1/storage/quota"),
+    /**
+     * Credit a $MNEME burn tx → extend storage capacity.
+     *   100 $MNEME →   1 GB / 30d
+     *   1000 $MNEME →  10 GB / 30d
+     *  10000 $MNEME → 100 GB / 30d
+     */
+    burn: (args) => this.request("POST", "/v1/storage/burn", { tx_hash: args.tx_hash })
+  };
   async request(method, path, body) {
     const bodyText = body === void 0 ? "" : JSON.stringify(body);
     const headers = { "Content-Type": "application/json" };
@@ -126,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",
@@ -133,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.0.1",
-  "description": "TypeScript SDK for Mneme — agent-native Postgres database platform on Base. Wallet-auth, runtime DDL, pgvector built-in.",
+  "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",