@masorinho99/statesync-client 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StateSync
+
+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/README.md

@@ -0,0 +1,150 @@
+# @masorinho99/statesync-client
+
+**StateSync — the global state database for AI coding agents.**
+
+Two lines. Any agent. Persistent memory.
+
+📚 **[Full documentation →](https://www.statesync.it/docs)**  ·  🚀 **[Quickstart](https://www.statesync.it/docs/quickstart)**  ·  🔑 **[Get an API key](https://www.statesync.it/dashboard/api-keys)**  ·  💬 **[MCP guide](https://www.statesync.it/docs/cursor)**
+
+---
+
+```bash
+npm install @masorinho99/statesync-client
+```
+
+```ts
+import { StateSync } from "@masorinho99/statesync-client";
+
+const sync = new StateSync({ apiKey: "ss_live_..." });          // 1
+
+await sync.checkpoint({ project: "my-app", messages: history });  // 2a
+const ctx = await sync.pull({ project: "my-app", agent: "windsurf" }); // 2b — 70% smaller
+```
+
+## What it does
+
+StateSync is a middleware layer that gives every AI agent in your stack the same
+long-term memory. It captures each agent's checkpoints (messages, files, decisions,
+test results) and returns a compressed, unified brief when the next agent starts —
+so Windsurf can pick up exactly where Cursor left off, without re-sending 50k tokens.
+
+Under the hood: real semantic embeddings (BAAI/bge-small-en-v1.5) + temporal
+decay + LLM summarization → 70–85% smaller context on every sync.
+
+👉 [Read the concepts guide](https://www.statesync.it/docs/concepts)
+
+## Quickstart
+
+Full walkthrough: **https://www.statesync.it/docs/quickstart**
+
+### OpenAI Agents SDK pattern
+
+```ts
+import OpenAI from "openai";
+import { StateSync } from "@masorinho99/statesync-client";
+
+const openai = new OpenAI();
+const sync = new StateSync({ apiKey: process.env.STATESYNC_API_KEY });
+
+// 1) On every turn, pull the compressed brief instead of the full history:
+const { compressed_context } = await sync.pull({
+  project: "todo-app",
+  agent: "openai-agents",
+  query: userTurn.content,
+});
+
+const messages = [
+  { role: "system", content: compressed_context.summary },
+  ...compressed_context.highlights,
+  ...compressed_context.recent,
+  userTurn,
+];
+
+const resp = await openai.chat.completions.create({
+  model: "gpt-4o-mini",
+  messages,
+});
+
+// 2) After the turn, save the state so the next agent (Cursor, Claude, whatever)
+//    picks up exactly here:
+await sync.checkpoint({
+  project: "todo-app",
+  agent: "openai-agents",
+  messages: [...messages, resp.choices[0].message],
+  files: ["src/App.tsx"],
+});
+```
+
+## API reference
+
+Complete reference with endpoint tables, params, and response examples:
+
+| Topic | Docs link |
+|---|---|
+| Projects API | https://www.statesync.it/docs/api-projects |
+| Snapshots API | https://www.statesync.it/docs/api-snapshots |
+| Sync & Compress | https://www.statesync.it/docs/api-sync |
+| Analytics & Audit | https://www.statesync.it/docs/api-analytics |
+| Rate limits & pricing | https://www.statesync.it/docs/guide-rate-limits |
+
+Node-SDK-specific reference: **https://www.statesync.it/docs/sdk-node**
+
+## Windsurf / Cursor / Claude Desktop (MCP)
+
+`@masorinho99/statesync-client` is the direct HTTP SDK. If you'd rather have your editor
+attach snapshots as native context, StateSync also runs as an MCP server —
+drop this into your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "statesync": {
+      "url": "https://www.statesync.it/api/mcp",
+      "headers": { "Authorization": "Bearer ss_live_..." }
+    }
+  }
+}
+```
+
+Full MCP integration guide: **https://www.statesync.it/docs/cursor**
+Tools exposed: `statesync_list_projects`, `statesync_create_project`,
+`statesync_checkpoint`, `statesync_pull`.
+Resources exposed: `statesync://project/{id}`, `statesync://project/{id}/snapshots`,
+`statesync://snapshot/{id}`, `statesync://audit`.
+
+## API surface
+
+### `new StateSync({ apiKey, baseUrl?, timeoutMs?, fetchImpl? })`
+
+- `apiKey` — required (or set `STATESYNC_API_KEY`).
+- `baseUrl` — defaults to the hosted service.
+- `timeoutMs` — request timeout (default 30 000).
+- `fetchImpl` — custom fetch (Node 18+ has global fetch).
+
+### `sync.checkpoint({ project, messages, files?, decisions?, testsPassed?, testsFailed?, agent?, metadata? })`
+Save an agent state snapshot. `project` accepts either a `proj_...` id or a project name
+(auto-created on first use).
+
+### `sync.pull({ project, agent?, query?, maxTokens? })`
+Return the compressed unified context. See `CompressedContext` in the types.
+
+### `sync.compress({ messages, query?, maxTokens?, projectName? })`
+One-shot compression (no project required) — useful to preview savings.
+
+### `sync.listProjects()` / `sync.createProject(name, description?)`
+
+## Get an API key
+
+Sign up free at https://www.statesync.it — 1,000 syncs/mo, no credit card.
+Create a key from **Dashboard → API Keys**.
+
+## Links
+
+- 📚 Documentation: https://www.statesync.it/docs
+- 🎛️  Dashboard: https://www.statesync.it/dashboard
+- 📖 OpenAPI spec: https://www.statesync.it/openapi.json
+- 📦 Sister SDK (Python): https://pypi.org/project/agent-state-api/
+
+## License
+
+MIT.

package/dist/index.cjs

@@ -0,0 +1,181 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StateSync: () => StateSync,
+  StateSyncError: () => StateSyncError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://www.statesync.it/api";
+var DEFAULT_TIMEOUT = 3e4;
+var StateSyncError = class extends Error {
+  status;
+  payload;
+  constructor(message, status, payload) {
+    super(message);
+    this.name = "StateSyncError";
+    this.status = status;
+    this.payload = payload;
+  }
+};
+function normaliseMessages(input) {
+  if (!input) return [];
+  return input.map((m) => ({
+    role: m.role || "user",
+    content: String(m.content ?? "")
+  }));
+}
+var StateSync = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  fetchImpl;
+  projectCache = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    const apiKey = opts.apiKey || (typeof process !== "undefined" ? process.env.STATESYNC_API_KEY : void 0);
+    if (!apiKey) {
+      throw new StateSyncError(
+        "Missing API key. Pass { apiKey } or set STATESYNC_API_KEY env var."
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (opts.baseUrl || (typeof process !== "undefined" ? process.env.STATESYNC_BASE_URL : void 0) || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
+    if (opts.fetchImpl) {
+      this.fetchImpl = opts.fetchImpl;
+    } else if (typeof fetch !== "undefined") {
+      this.fetchImpl = fetch.bind(globalThis);
+    } else {
+      throw new StateSyncError(
+        "No fetch implementation found. Pass { fetchImpl } (e.g. node-fetch)."
+      );
+    }
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "@masorinho99/statesync-client/0.1.1"
+        },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (e) {
+      throw new StateSyncError(`Network error: ${e?.message || e}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      let payload = void 0;
+      const text = await res.text();
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = text;
+      }
+      const detail = (payload && typeof payload === "object" && "detail" in payload ? payload.detail : void 0) || payload;
+      throw new StateSyncError(
+        `${res.status} ${typeof detail === "string" ? detail : JSON.stringify(detail)}`,
+        res.status,
+        payload
+      );
+    }
+    return await res.json();
+  }
+  async resolveProjectId(project) {
+    if (project.startsWith("proj_")) return project;
+    const cached = this.projectCache.get(project);
+    if (cached) return cached;
+    const items = await this.request("GET", "/projects") || [];
+    for (const p of items) {
+      if (p.name === project) {
+        this.projectCache.set(project, p.project_id);
+        return p.project_id;
+      }
+    }
+    const created = await this.request("POST", "/projects", {
+      name: project,
+      description: ""
+    });
+    this.projectCache.set(project, created.project_id);
+    return created.project_id;
+  }
+  /** List all projects owned by the authenticated user. */
+  listProjects() {
+    return this.request("GET", "/projects");
+  }
+  /** Create a new project explicitly (checkpoint() auto-creates by name too). */
+  createProject(name, description = "") {
+    return this.request("POST", "/projects", { name, description });
+  }
+  /**
+   * Save an agent state snapshot to a project.
+   * `project` may be a project_id (`proj_...`) or a name (auto-created).
+   */
+  async checkpoint(input) {
+    const projectId = await this.resolveProjectId(input.project);
+    return this.request("POST", "/snapshots", {
+      project_id: projectId,
+      agent: input.agent ?? "sdk-js",
+      messages: normaliseMessages(input.messages),
+      files_modified: input.files ?? [],
+      decisions: input.decisions ?? [],
+      tests_passed: input.testsPassed ?? [],
+      tests_failed: input.testsFailed ?? [],
+      metadata: input.metadata ?? {}
+    });
+  }
+  /**
+   * Pull the compressed unified context for a project.
+   */
+  async pull(input) {
+    const projectId = await this.resolveProjectId(input.project);
+    return this.request("POST", "/sync", {
+      project_id: projectId,
+      agent: input.agent ?? "sdk-js",
+      query: input.query ?? "",
+      max_tokens: input.maxTokens ?? 4e3
+    });
+  }
+  /** One-shot compression (no project required) — useful to preview savings. */
+  compress(input) {
+    return this.request("POST", "/compress", {
+      messages: normaliseMessages(input.messages),
+      query: input.query ?? "",
+      max_tokens: input.maxTokens ?? 4e3,
+      project_name: input.projectName ?? ""
+    });
+  }
+};
+var index_default = StateSync;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StateSync,
+  StateSyncError
+});

package/dist/index.d.cts

@@ -0,0 +1,130 @@
+/**
+ * StateSync — the global state database for AI coding agents.
+ *
+ *   npm install @masorinho99/statesync-client
+ *
+ *   import { StateSync } from "@masorinho99/statesync-client";
+ *   const sync = new StateSync({ apiKey: "ss_live_..." });
+ *   await sync.checkpoint({ project: "my-app", messages: history, files: ["App.js"] });
+ *   const ctx = await sync.pull({ project: "my-app", agent: "windsurf" });
+ */
+interface StateSyncOptions {
+    /** Your StateSync API key (starts with `ss_live_`). Falls back to STATESYNC_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL — defaults to the hosted service. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default 30_000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (Node 18+ has global fetch). */
+    fetchImpl?: typeof fetch;
+}
+interface Message {
+    role: "user" | "assistant" | "system" | "tool" | string;
+    content: string;
+}
+interface CheckpointInput {
+    project: string;
+    messages?: (Message | {
+        role?: string;
+        content?: string;
+    })[] | undefined;
+    files?: string[];
+    decisions?: string[];
+    testsPassed?: string[];
+    testsFailed?: string[];
+    agent?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Snapshot {
+    snapshot_id: string;
+    project_id: string;
+    user_id: string;
+    agent: string;
+    messages: Message[];
+    files_modified: string[];
+    decisions: string[];
+    tests_passed: string[];
+    tests_failed: string[];
+    metadata: Record<string, unknown>;
+    original_tokens: number;
+    compressed_tokens: number;
+    savings_pct: number;
+    created_at: string;
+}
+interface CompressedContext {
+    summary: string;
+    recent: Message[];
+    highlights: Message[];
+    original_tokens: number;
+    compressed_tokens: number;
+    savings_pct: number;
+    scoring?: string;
+}
+interface PullResult {
+    project: {
+        project_id: string;
+        name: string;
+        description?: string;
+        created_at: string;
+    };
+    compressed_context: CompressedContext;
+    files_modified: string[];
+    decisions: string[];
+    message_count: number;
+}
+interface Project {
+    project_id: string;
+    user_id: string;
+    name: string;
+    description: string;
+    created_at: string;
+    snapshot_count?: number;
+    last_activity?: string;
+}
+interface PullInput {
+    project: string;
+    agent?: string;
+    query?: string;
+    maxTokens?: number;
+}
+interface CompressInput {
+    messages: (Message | {
+        role?: string;
+        content?: string;
+    })[];
+    query?: string;
+    maxTokens?: number;
+    projectName?: string;
+}
+declare class StateSyncError extends Error {
+    status?: number;
+    payload?: unknown;
+    constructor(message: string, status?: number, payload?: unknown);
+}
+declare class StateSync {
+    private apiKey;
+    private baseUrl;
+    private timeoutMs;
+    private fetchImpl;
+    private projectCache;
+    constructor(opts?: StateSyncOptions);
+    private request;
+    private resolveProjectId;
+    /** List all projects owned by the authenticated user. */
+    listProjects(): Promise<Project[]>;
+    /** Create a new project explicitly (checkpoint() auto-creates by name too). */
+    createProject(name: string, description?: string): Promise<Project>;
+    /**
+     * Save an agent state snapshot to a project.
+     * `project` may be a project_id (`proj_...`) or a name (auto-created).
+     */
+    checkpoint(input: CheckpointInput): Promise<Snapshot>;
+    /**
+     * Pull the compressed unified context for a project.
+     */
+    pull(input: PullInput): Promise<PullResult>;
+    /** One-shot compression (no project required) — useful to preview savings. */
+    compress(input: CompressInput): Promise<CompressedContext>;
+}
+
+export { type CheckpointInput, type CompressInput, type CompressedContext, type Message, type Project, type PullInput, type PullResult, type Snapshot, StateSync, StateSyncError, type StateSyncOptions, StateSync as default };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * StateSync — the global state database for AI coding agents.
+ *
+ *   npm install @masorinho99/statesync-client
+ *
+ *   import { StateSync } from "@masorinho99/statesync-client";
+ *   const sync = new StateSync({ apiKey: "ss_live_..." });
+ *   await sync.checkpoint({ project: "my-app", messages: history, files: ["App.js"] });
+ *   const ctx = await sync.pull({ project: "my-app", agent: "windsurf" });
+ */
+interface StateSyncOptions {
+    /** Your StateSync API key (starts with `ss_live_`). Falls back to STATESYNC_API_KEY env var. */
+    apiKey?: string;
+    /** Base URL — defaults to the hosted service. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default 30_000. */
+    timeoutMs?: number;
+    /** Custom fetch implementation (Node 18+ has global fetch). */
+    fetchImpl?: typeof fetch;
+}
+interface Message {
+    role: "user" | "assistant" | "system" | "tool" | string;
+    content: string;
+}
+interface CheckpointInput {
+    project: string;
+    messages?: (Message | {
+        role?: string;
+        content?: string;
+    })[] | undefined;
+    files?: string[];
+    decisions?: string[];
+    testsPassed?: string[];
+    testsFailed?: string[];
+    agent?: string;
+    metadata?: Record<string, unknown>;
+}
+interface Snapshot {
+    snapshot_id: string;
+    project_id: string;
+    user_id: string;
+    agent: string;
+    messages: Message[];
+    files_modified: string[];
+    decisions: string[];
+    tests_passed: string[];
+    tests_failed: string[];
+    metadata: Record<string, unknown>;
+    original_tokens: number;
+    compressed_tokens: number;
+    savings_pct: number;
+    created_at: string;
+}
+interface CompressedContext {
+    summary: string;
+    recent: Message[];
+    highlights: Message[];
+    original_tokens: number;
+    compressed_tokens: number;
+    savings_pct: number;
+    scoring?: string;
+}
+interface PullResult {
+    project: {
+        project_id: string;
+        name: string;
+        description?: string;
+        created_at: string;
+    };
+    compressed_context: CompressedContext;
+    files_modified: string[];
+    decisions: string[];
+    message_count: number;
+}
+interface Project {
+    project_id: string;
+    user_id: string;
+    name: string;
+    description: string;
+    created_at: string;
+    snapshot_count?: number;
+    last_activity?: string;
+}
+interface PullInput {
+    project: string;
+    agent?: string;
+    query?: string;
+    maxTokens?: number;
+}
+interface CompressInput {
+    messages: (Message | {
+        role?: string;
+        content?: string;
+    })[];
+    query?: string;
+    maxTokens?: number;
+    projectName?: string;
+}
+declare class StateSyncError extends Error {
+    status?: number;
+    payload?: unknown;
+    constructor(message: string, status?: number, payload?: unknown);
+}
+declare class StateSync {
+    private apiKey;
+    private baseUrl;
+    private timeoutMs;
+    private fetchImpl;
+    private projectCache;
+    constructor(opts?: StateSyncOptions);
+    private request;
+    private resolveProjectId;
+    /** List all projects owned by the authenticated user. */
+    listProjects(): Promise<Project[]>;
+    /** Create a new project explicitly (checkpoint() auto-creates by name too). */
+    createProject(name: string, description?: string): Promise<Project>;
+    /**
+     * Save an agent state snapshot to a project.
+     * `project` may be a project_id (`proj_...`) or a name (auto-created).
+     */
+    checkpoint(input: CheckpointInput): Promise<Snapshot>;
+    /**
+     * Pull the compressed unified context for a project.
+     */
+    pull(input: PullInput): Promise<PullResult>;
+    /** One-shot compression (no project required) — useful to preview savings. */
+    compress(input: CompressInput): Promise<CompressedContext>;
+}
+
+export { type CheckpointInput, type CompressInput, type CompressedContext, type Message, type Project, type PullInput, type PullResult, type Snapshot, StateSync, StateSyncError, type StateSyncOptions, StateSync as default };

package/dist/index.js

@@ -0,0 +1,155 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://www.statesync.it/api";
+var DEFAULT_TIMEOUT = 3e4;
+var StateSyncError = class extends Error {
+  status;
+  payload;
+  constructor(message, status, payload) {
+    super(message);
+    this.name = "StateSyncError";
+    this.status = status;
+    this.payload = payload;
+  }
+};
+function normaliseMessages(input) {
+  if (!input) return [];
+  return input.map((m) => ({
+    role: m.role || "user",
+    content: String(m.content ?? "")
+  }));
+}
+var StateSync = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  fetchImpl;
+  projectCache = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    const apiKey = opts.apiKey || (typeof process !== "undefined" ? process.env.STATESYNC_API_KEY : void 0);
+    if (!apiKey) {
+      throw new StateSyncError(
+        "Missing API key. Pass { apiKey } or set STATESYNC_API_KEY env var."
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (opts.baseUrl || (typeof process !== "undefined" ? process.env.STATESYNC_BASE_URL : void 0) || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
+    if (opts.fetchImpl) {
+      this.fetchImpl = opts.fetchImpl;
+    } else if (typeof fetch !== "undefined") {
+      this.fetchImpl = fetch.bind(globalThis);
+    } else {
+      throw new StateSyncError(
+        "No fetch implementation found. Pass { fetchImpl } (e.g. node-fetch)."
+      );
+    }
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "@masorinho99/statesync-client/0.1.1"
+        },
+        body: body === void 0 ? void 0 : JSON.stringify(body),
+        signal: controller.signal
+      });
+    } catch (e) {
+      throw new StateSyncError(`Network error: ${e?.message || e}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      let payload = void 0;
+      const text = await res.text();
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = text;
+      }
+      const detail = (payload && typeof payload === "object" && "detail" in payload ? payload.detail : void 0) || payload;
+      throw new StateSyncError(
+        `${res.status} ${typeof detail === "string" ? detail : JSON.stringify(detail)}`,
+        res.status,
+        payload
+      );
+    }
+    return await res.json();
+  }
+  async resolveProjectId(project) {
+    if (project.startsWith("proj_")) return project;
+    const cached = this.projectCache.get(project);
+    if (cached) return cached;
+    const items = await this.request("GET", "/projects") || [];
+    for (const p of items) {
+      if (p.name === project) {
+        this.projectCache.set(project, p.project_id);
+        return p.project_id;
+      }
+    }
+    const created = await this.request("POST", "/projects", {
+      name: project,
+      description: ""
+    });
+    this.projectCache.set(project, created.project_id);
+    return created.project_id;
+  }
+  /** List all projects owned by the authenticated user. */
+  listProjects() {
+    return this.request("GET", "/projects");
+  }
+  /** Create a new project explicitly (checkpoint() auto-creates by name too). */
+  createProject(name, description = "") {
+    return this.request("POST", "/projects", { name, description });
+  }
+  /**
+   * Save an agent state snapshot to a project.
+   * `project` may be a project_id (`proj_...`) or a name (auto-created).
+   */
+  async checkpoint(input) {
+    const projectId = await this.resolveProjectId(input.project);
+    return this.request("POST", "/snapshots", {
+      project_id: projectId,
+      agent: input.agent ?? "sdk-js",
+      messages: normaliseMessages(input.messages),
+      files_modified: input.files ?? [],
+      decisions: input.decisions ?? [],
+      tests_passed: input.testsPassed ?? [],
+      tests_failed: input.testsFailed ?? [],
+      metadata: input.metadata ?? {}
+    });
+  }
+  /**
+   * Pull the compressed unified context for a project.
+   */
+  async pull(input) {
+    const projectId = await this.resolveProjectId(input.project);
+    return this.request("POST", "/sync", {
+      project_id: projectId,
+      agent: input.agent ?? "sdk-js",
+      query: input.query ?? "",
+      max_tokens: input.maxTokens ?? 4e3
+    });
+  }
+  /** One-shot compression (no project required) — useful to preview savings. */
+  compress(input) {
+    return this.request("POST", "/compress", {
+      messages: normaliseMessages(input.messages),
+      query: input.query ?? "",
+      max_tokens: input.maxTokens ?? 4e3,
+      project_name: input.projectName ?? ""
+    });
+  }
+};
+var index_default = StateSync;
+export {
+  StateSync,
+  StateSyncError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@masorinho99/statesync-client",
+  "version": "0.1.1",
+  "description": "StateSync \u2014 the global state database for AI agents. Two-line SDK to unify memory across Cursor, Claude, OpenAI and Emergent.",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "mcp",
+    "context",
+    "compression",
+    "cursor",
+    "claude",
+    "openai",
+    "state-management"
+  ],
+  "author": "StateSync",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/statesync/client-js"
+  },
+  "homepage": "https://www.statesync.it/docs",
+  "bugs": {
+    "url": "https://www.statesync.it/docs"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.ts

@@ -0,0 +1,278 @@
+/**
+ * StateSync — the global state database for AI coding agents.
+ *
+ *   npm install @masorinho99/statesync-client
+ *
+ *   import { StateSync } from "@masorinho99/statesync-client";
+ *   const sync = new StateSync({ apiKey: "ss_live_..." });
+ *   await sync.checkpoint({ project: "my-app", messages: history, files: ["App.js"] });
+ *   const ctx = await sync.pull({ project: "my-app", agent: "windsurf" });
+ */
+
+export interface StateSyncOptions {
+  /** Your StateSync API key (starts with `ss_live_`). Falls back to STATESYNC_API_KEY env var. */
+  apiKey?: string;
+  /** Base URL — defaults to the hosted service. */
+  baseUrl?: string;
+  /** Request timeout in milliseconds. Default 30_000. */
+  timeoutMs?: number;
+  /** Custom fetch implementation (Node 18+ has global fetch). */
+  fetchImpl?: typeof fetch;
+}
+
+export interface Message {
+  role: "user" | "assistant" | "system" | "tool" | string;
+  content: string;
+}
+
+export interface CheckpointInput {
+  project: string;
+  messages?: (Message | { role?: string; content?: string })[] | undefined;
+  files?: string[];
+  decisions?: string[];
+  testsPassed?: string[];
+  testsFailed?: string[];
+  agent?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface Snapshot {
+  snapshot_id: string;
+  project_id: string;
+  user_id: string;
+  agent: string;
+  messages: Message[];
+  files_modified: string[];
+  decisions: string[];
+  tests_passed: string[];
+  tests_failed: string[];
+  metadata: Record<string, unknown>;
+  original_tokens: number;
+  compressed_tokens: number;
+  savings_pct: number;
+  created_at: string;
+}
+
+export interface CompressedContext {
+  summary: string;
+  recent: Message[];
+  highlights: Message[];
+  original_tokens: number;
+  compressed_tokens: number;
+  savings_pct: number;
+  scoring?: string;
+}
+
+export interface PullResult {
+  project: {
+    project_id: string;
+    name: string;
+    description?: string;
+    created_at: string;
+  };
+  compressed_context: CompressedContext;
+  files_modified: string[];
+  decisions: string[];
+  message_count: number;
+}
+
+export interface Project {
+  project_id: string;
+  user_id: string;
+  name: string;
+  description: string;
+  created_at: string;
+  snapshot_count?: number;
+  last_activity?: string;
+}
+
+export interface PullInput {
+  project: string;
+  agent?: string;
+  query?: string;
+  maxTokens?: number;
+}
+
+export interface CompressInput {
+  messages: (Message | { role?: string; content?: string })[];
+  query?: string;
+  maxTokens?: number;
+  projectName?: string;
+}
+
+const DEFAULT_BASE_URL = "https://www.statesync.it/api";
+const DEFAULT_TIMEOUT = 30_000;
+
+export class StateSyncError extends Error {
+  status?: number;
+  payload?: unknown;
+  constructor(message: string, status?: number, payload?: unknown) {
+    super(message);
+    this.name = "StateSyncError";
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+function normaliseMessages(
+  input?: (Message | { role?: string; content?: string })[]
+): Message[] {
+  if (!input) return [];
+  return input.map((m) => ({
+    role: (m.role as string) || "user",
+    content: String(m.content ?? ""),
+  }));
+}
+
+export class StateSync {
+  private apiKey: string;
+  private baseUrl: string;
+  private timeoutMs: number;
+  private fetchImpl: typeof fetch;
+  private projectCache = new Map<string, string>();
+
+  constructor(opts: StateSyncOptions = {}) {
+    const apiKey =
+      opts.apiKey ||
+      (typeof process !== "undefined" ? process.env.STATESYNC_API_KEY : undefined);
+    if (!apiKey) {
+      throw new StateSyncError(
+        "Missing API key. Pass { apiKey } or set STATESYNC_API_KEY env var."
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (
+      opts.baseUrl ||
+      (typeof process !== "undefined" ? process.env.STATESYNC_BASE_URL : undefined) ||
+      DEFAULT_BASE_URL
+    ).replace(/\/$/, "");
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT;
+    if (opts.fetchImpl) {
+      this.fetchImpl = opts.fetchImpl;
+    } else if (typeof fetch !== "undefined") {
+      this.fetchImpl = fetch.bind(globalThis);
+    } else {
+      throw new StateSyncError(
+        "No fetch implementation found. Pass { fetchImpl } (e.g. node-fetch)."
+      );
+    }
+  }
+
+  private async request<T = unknown>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let res: Response;
+    try {
+      res = await this.fetchImpl(url, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+          "User-Agent": "@masorinho99/statesync-client/0.1.1",
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+      });
+    } catch (e: any) {
+      throw new StateSyncError(`Network error: ${e?.message || e}`);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!res.ok) {
+      let payload: unknown = undefined;
+      const text = await res.text();
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        payload = text;
+      }
+      const detail =
+        (payload && typeof payload === "object" && "detail" in payload
+          ? (payload as any).detail
+          : undefined) || payload;
+      throw new StateSyncError(
+        `${res.status} ${typeof detail === "string" ? detail : JSON.stringify(detail)}`,
+        res.status,
+        payload
+      );
+    }
+    return (await res.json()) as T;
+  }
+
+  private async resolveProjectId(project: string): Promise<string> {
+    if (project.startsWith("proj_")) return project;
+    const cached = this.projectCache.get(project);
+    if (cached) return cached;
+    const items = (await this.request<Project[]>("GET", "/projects")) || [];
+    for (const p of items) {
+      if (p.name === project) {
+        this.projectCache.set(project, p.project_id);
+        return p.project_id;
+      }
+    }
+    const created = await this.request<Project>("POST", "/projects", {
+      name: project,
+      description: "",
+    });
+    this.projectCache.set(project, created.project_id);
+    return created.project_id;
+  }
+
+  /** List all projects owned by the authenticated user. */
+  listProjects(): Promise<Project[]> {
+    return this.request<Project[]>("GET", "/projects");
+  }
+
+  /** Create a new project explicitly (checkpoint() auto-creates by name too). */
+  createProject(name: string, description = ""): Promise<Project> {
+    return this.request<Project>("POST", "/projects", { name, description });
+  }
+
+  /**
+   * Save an agent state snapshot to a project.
+   * `project` may be a project_id (`proj_...`) or a name (auto-created).
+   */
+  async checkpoint(input: CheckpointInput): Promise<Snapshot> {
+    const projectId = await this.resolveProjectId(input.project);
+    return this.request<Snapshot>("POST", "/snapshots", {
+      project_id: projectId,
+      agent: input.agent ?? "sdk-js",
+      messages: normaliseMessages(input.messages),
+      files_modified: input.files ?? [],
+      decisions: input.decisions ?? [],
+      tests_passed: input.testsPassed ?? [],
+      tests_failed: input.testsFailed ?? [],
+      metadata: input.metadata ?? {},
+    });
+  }
+
+  /**
+   * Pull the compressed unified context for a project.
+   */
+  async pull(input: PullInput): Promise<PullResult> {
+    const projectId = await this.resolveProjectId(input.project);
+    return this.request<PullResult>("POST", "/sync", {
+      project_id: projectId,
+      agent: input.agent ?? "sdk-js",
+      query: input.query ?? "",
+      max_tokens: input.maxTokens ?? 4000,
+    });
+  }
+
+  /** One-shot compression (no project required) — useful to preview savings. */
+  compress(input: CompressInput): Promise<CompressedContext> {
+    return this.request<CompressedContext>("POST", "/compress", {
+      messages: normaliseMessages(input.messages),
+      query: input.query ?? "",
+      max_tokens: input.maxTokens ?? 4000,
+      project_name: input.projectName ?? "",
+    });
+  }
+}
+
+export default StateSync;