@memrosetta/sync-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 obst
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import Database from 'better-sqlite3';
+import { SyncOp, SyncPulledOp, SyncPushResult } from '@memrosetta/types';
+export { SyncConfig, SyncOp, SyncPullParams, SyncPullResponse, SyncPulledOp, SyncPushRequest, SyncPushResponse, SyncPushResult } from '@memrosetta/types';
+
+declare class Outbox {
+    private readonly db;
+    constructor(db: Database.Database);
+    addOp(op: SyncOp): void;
+    getPending(): readonly SyncOp[];
+    markPushed(opIds: readonly string[]): void;
+}
+
+declare class Inbox {
+    private readonly db;
+    constructor(db: Database.Database);
+    addOps(ops: readonly SyncPulledOp[]): void;
+    getPending(): readonly SyncPulledOp[];
+    markApplied(opIds: readonly string[]): void;
+}
+
+/**
+ * Minimal config required by SyncClient at runtime.
+ * serverUrl and apiKey are required (unlike the optional SyncConfig
+ * from @memrosetta/types which is aimed at feature-flag configuration).
+ */
+interface SyncClientConfig {
+    readonly serverUrl: string;
+    readonly apiKey: string;
+    readonly deviceId: string;
+}
+interface SyncClientPushResponse {
+    readonly pushed: number;
+    readonly results: readonly SyncPushResult[];
+    readonly highWatermark: number;
+}
+declare class SyncClient {
+    private readonly db;
+    private readonly config;
+    private readonly outbox;
+    private readonly inbox;
+    constructor(db: Database.Database, config: SyncClientConfig);
+    initialize(): void;
+    getOutbox(): Outbox;
+    getInbox(): Inbox;
+    push(): Promise<SyncClientPushResponse>;
+    pull(): Promise<number>;
+    getState(key: string): string | null;
+    setState(key: string, value: string): void;
+}
+
+declare function ensureSyncSchema(db: Database.Database): void;
+
+export { Inbox, Outbox, SyncClient, ensureSyncSchema };

package/dist/index.js

@@ -0,0 +1,207 @@
+// src/schema.ts
+var SYNC_SCHEMA = `
+CREATE TABLE IF NOT EXISTS sync_outbox (
+  op_id       TEXT PRIMARY KEY,
+  op_type     TEXT NOT NULL,
+  device_id   TEXT NOT NULL,
+  user_id     TEXT NOT NULL,
+  payload     TEXT NOT NULL,
+  created_at  TEXT NOT NULL,
+  pushed_at   TEXT
+);
+
+CREATE TABLE IF NOT EXISTS sync_inbox (
+  op_id       TEXT PRIMARY KEY,
+  op_type     TEXT NOT NULL,
+  device_id   TEXT NOT NULL,
+  user_id     TEXT NOT NULL,
+  payload     TEXT NOT NULL,
+  created_at  TEXT NOT NULL,
+  applied_at  TEXT
+);
+
+CREATE TABLE IF NOT EXISTS sync_state (
+  key         TEXT PRIMARY KEY,
+  value       TEXT NOT NULL
+);
+`;
+function ensureSyncSchema(db) {
+  db.exec(SYNC_SCHEMA);
+}
+
+// src/outbox.ts
+function rowToSyncOp(row) {
+  return {
+    opId: row.op_id,
+    opType: row.op_type,
+    deviceId: row.device_id,
+    userId: row.user_id,
+    payload: JSON.parse(row.payload),
+    createdAt: row.created_at
+  };
+}
+var Outbox = class {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  addOp(op) {
+    const payloadStr = typeof op.payload === "string" ? op.payload : JSON.stringify(op.payload);
+    this.db.prepare(
+      `INSERT INTO sync_outbox (op_id, op_type, device_id, user_id, payload, created_at, pushed_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`
+    ).run(op.opId, op.opType, op.deviceId, op.userId, payloadStr, op.createdAt, null);
+  }
+  getPending() {
+    const rows = this.db.prepare("SELECT * FROM sync_outbox WHERE pushed_at IS NULL ORDER BY created_at ASC").all();
+    return rows.map(rowToSyncOp);
+  }
+  markPushed(opIds) {
+    if (opIds.length === 0) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const placeholders = opIds.map(() => "?").join(", ");
+    this.db.prepare(`UPDATE sync_outbox SET pushed_at = ? WHERE op_id IN (${placeholders})`).run(now, ...opIds);
+  }
+};
+
+// src/inbox.ts
+function rowToPulledOp(row) {
+  return {
+    opId: row.op_id,
+    opType: row.op_type,
+    deviceId: row.device_id,
+    userId: row.user_id,
+    payload: JSON.parse(row.payload),
+    createdAt: row.created_at,
+    cursor: 0,
+    receivedAt: ""
+  };
+}
+var Inbox = class {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+  addOps(ops) {
+    if (ops.length === 0) return;
+    const stmt = this.db.prepare(
+      `INSERT OR IGNORE INTO sync_inbox (op_id, op_type, device_id, user_id, payload, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`
+    );
+    const insertMany = this.db.transaction((items) => {
+      for (const op of items) {
+        const payloadStr = typeof op.payload === "string" ? op.payload : JSON.stringify(op.payload);
+        stmt.run(op.opId, op.opType, op.deviceId, op.userId, payloadStr, op.createdAt);
+      }
+    });
+    insertMany(ops);
+  }
+  getPending() {
+    const rows = this.db.prepare("SELECT * FROM sync_inbox WHERE applied_at IS NULL ORDER BY created_at ASC").all();
+    return rows.map(rowToPulledOp);
+  }
+  markApplied(opIds) {
+    if (opIds.length === 0) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const placeholders = opIds.map(() => "?").join(", ");
+    this.db.prepare(`UPDATE sync_inbox SET applied_at = ? WHERE op_id IN (${placeholders})`).run(now, ...opIds);
+  }
+};
+
+// src/sync-client.ts
+var SyncClient = class {
+  db;
+  config;
+  outbox;
+  inbox;
+  constructor(db, config) {
+    this.db = db;
+    this.config = config;
+    this.outbox = new Outbox(db);
+    this.inbox = new Inbox(db);
+  }
+  initialize() {
+    ensureSyncSchema(this.db);
+  }
+  getOutbox() {
+    return this.outbox;
+  }
+  getInbox() {
+    return this.inbox;
+  }
+  async push() {
+    const pending = this.outbox.getPending();
+    if (pending.length === 0) {
+      return { pushed: 0, results: [], highWatermark: 0 };
+    }
+    const baseCursorStr = this.getState("pull_cursor");
+    const baseCursor = baseCursorStr ? parseInt(baseCursorStr, 10) : 0;
+    const wireOps = pending.map((op) => ({
+      ...op,
+      payload: typeof op.payload === "string" ? JSON.parse(op.payload) : op.payload
+    }));
+    const url = `${this.config.serverUrl}/sync/push`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.config.apiKey}`
+      },
+      body: JSON.stringify({
+        deviceId: this.config.deviceId,
+        baseCursor,
+        ops: wireOps
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Push failed: ${response.status} ${response.statusText}`);
+    }
+    const body = await response.json();
+    const { results, highWatermark } = body.data;
+    const pushedIds = results.filter((r) => r.status === "accepted" || r.status === "duplicate").map((r) => r.opId);
+    this.outbox.markPushed(pushedIds);
+    this.setState("pull_cursor", String(highWatermark));
+    return {
+      pushed: pushedIds.length,
+      results,
+      highWatermark
+    };
+  }
+  async pull() {
+    const cursorStr = this.getState("pull_cursor");
+    const since = cursorStr ? parseInt(cursorStr, 10) : 0;
+    const params = new URLSearchParams({
+      since: String(since)
+    });
+    const url = `${this.config.serverUrl}/sync/pull?${params.toString()}`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`Pull failed: ${response.status} ${response.statusText}`);
+    }
+    const body = await response.json();
+    const { ops, nextCursor, hasMore } = body.data;
+    if (ops.length > 0) {
+      this.inbox.addOps(ops);
+    }
+    this.setState("pull_cursor", String(nextCursor));
+    return ops.length;
+  }
+  getState(key) {
+    const row = this.db.prepare("SELECT value FROM sync_state WHERE key = ?").get(key);
+    return row?.value ?? null;
+  }
+  setState(key, value) {
+    this.db.prepare("INSERT OR REPLACE INTO sync_state (key, value) VALUES (?, ?)").run(key, value);
+  }
+};
+export {
+  Inbox,
+  Outbox,
+  SyncClient,
+  ensureSyncSchema
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@memrosetta/sync-client",
+  "version": "0.1.0",
+  "description": "Local-first sync client for MemRosetta (outbox/inbox, push/pull)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "@memrosetta/types": "0.4.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}