memorysync-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MemorySync
+
+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,105 @@
+# memorysync-sdk
+
+Official JavaScript / TypeScript client for the MemorySync API.
+
+```bash
+npm install memorysync-sdk
+```
+
+## Quick start
+
+```ts
+import { MemorySyncClient } from "memorysync-sdk";
+
+const ms = new MemorySyncClient({
+  apiKey: process.env.MEMORYSYNC_API_KEY!,
+  baseUrl: "https://api.memorysync.dev",
+  // optional:
+  projectId: "proj_xxxxxxxxxxxxxxxx",
+  endUserId: "user_42",
+});
+
+await ms.add({ text: "User prefers dark mode." });
+
+const { memories } = await ms.query({ query: "ui preferences", k: 5 });
+for (const m of memories) console.log(m.id, m.text);
+```
+
+## Configuration
+
+| Field        | Required | Description                                                                                  |
+| ------------ | -------- | -------------------------------------------------------------------------------------------- |
+| `apiKey`     | yes      | Sent as `X-API-Key`. Provision in your MemorySync dashboard.                                 |
+| `baseUrl`    | yes      | The deployment URL of your MemorySync instance.                                              |
+| `projectId`  | no       | Pin the client to a single project (`X-Project-ID`). Format: `proj_` + 16 hex chars.         |
+| `endUserId`  | no       | Identify which of *your* users this client speaks for (`X-End-User-ID`).                     |
+| `timeoutMs`  | no       | Per-request timeout. Default `30000`.                                                        |
+| `fetch`      | no       | Inject a custom fetch (tests, Node 16). Defaults to global `fetch` (Node 18+, all browsers). |
+
+`endUserId` can also be passed per-call on `add()` to override the client default.
+
+## Methods
+
+Every method is a thin wrapper over a real HTTP route. There are no hidden side effects.
+
+| Method                                | Route                                  |
+| ------------------------------------- | -------------------------------------- |
+| `add(req)`                            | `POST /memory/add`                     |
+| `bulkAdd(items, { deduplicate? })`    | `POST /memory/bulk-add`                |
+| `query(req)`                          | `POST /memory/query`                   |
+| `get(memoryId)`                       | `GET /memory/{id}`                     |
+| `update(memoryId, req)`               | `PATCH /memory/{id}`                   |
+| `forget(memoryIds, reason?)`          | `DELETE /memory/forget`                |
+| `summarize(req)`                      | `POST /memory/summarize`               |
+| `compose(req)`                        | `POST /memory/compose`                 |
+| `exportAll()`                         | `GET /memory/export`                   |
+| `createRelation(fromId, req)`         | `POST /memory/{id}/relations`          |
+
+### `add` returns one of two shapes
+
+`add()` is routed through MemorySync's extraction pipeline. Inputs that carry no
+high-value content are intentionally skipped. The discriminator is the `status`
+field on the skipped envelope:
+
+```ts
+const result = await ms.add({ text: "User prefers dark mode." });
+if ("status" in result && result.status === "skipped") {
+  // result.reason, result.candidatesExtracted, result.candidatesStored
+} else {
+  // result is a MemoryRecord — result.id, result.text, result.createdAt, ...
+}
+```
+
+## Errors
+
+Every non-2xx response throws a typed subclass of `MemorySyncError`:
+
+| Class             | When                                        |
+| ----------------- | ------------------------------------------- |
+| `AuthError`       | `401` / `403` — bad key, missing scope.     |
+| `ValidationError` | `400` / `409` / `422`.                      |
+| `NotFoundError`   | `404` — record not visible to the caller.   |
+| `RateLimitError`  | `429` — read `err.retryAfterSeconds`.       |
+| `ServerError`     | `5xx`.                                      |
+| `MemorySyncError` | Network errors, timeouts, anything else.    |
+
+Every error carries `statusCode`, `response`, and the server-issued `requestId`
+(when present) for support escalation.
+
+```ts
+import { RateLimitError } from "memorysync-sdk";
+
+try {
+  await ms.add({ text });
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    await new Promise((r) => setTimeout(r, err.retryAfterSeconds * 1000));
+  } else {
+    throw err;
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,188 @@
+/**
+ * MemorySync SDK — JavaScript / TypeScript client.
+ *
+ * Wraps the public REST surface of MemorySync. Every method here maps 1:1
+ * to a route that exists in the backend; field names mirror the on-the-wire
+ * JSON exactly (snake_case is preserved on payloads, camelCase is exposed
+ * on the public TypeScript API).
+ */
+interface MemorySyncConfig {
+    apiKey: string;
+    baseUrl: string;
+    projectId?: string;
+    endUserId?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+interface AddRequest {
+    text: string;
+    source?: string;
+    tags?: string[];
+    importance?: number;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+    endUserId?: string;
+}
+interface MemoryRecord {
+    id: number;
+    text: string;
+    summary?: string | null;
+    tags?: string[] | null;
+    source?: string | null;
+    eventType?: string | null;
+    importance?: number | null;
+    metadata?: Record<string, unknown> | null;
+    isSummary: boolean;
+    createdAt: string;
+    updatedAt?: string | null;
+    score?: number | null;
+}
+interface AddSkippedResponse {
+    status: "skipped";
+    reason: string;
+    memoryIds: number[];
+    candidatesExtracted: number;
+    candidatesStored: number;
+}
+type AddResponse = MemoryRecord | AddSkippedResponse;
+interface BulkAddItem {
+    text: string;
+    source?: string;
+    eventType?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    importance?: number;
+    endUserId?: string;
+}
+interface BulkAddItemResult {
+    index: number;
+    status: "created" | "skipped" | "rejected";
+    memoryIds: number[];
+    reason: string | null;
+}
+interface BulkAddResponse {
+    total: number;
+    created: number;
+    skipped: number;
+    rejected: number;
+    results: BulkAddItemResult[];
+}
+interface QueryFilters {
+    memoryType?: string;
+    source?: string;
+    tags?: string[];
+    since?: string;
+    until?: string;
+    includeSummaries?: boolean;
+    tier?: "hot" | "warm" | "cold";
+}
+interface QueryRequest {
+    query: string;
+    k?: number;
+    filters?: QueryFilters;
+    sessionId?: string;
+    traversalDepth?: number;
+}
+interface QueryResponse {
+    memories: MemoryRecord[];
+    context?: string | null;
+    latencyMs?: number | null;
+    sessionId?: string | null;
+    queryIntent?: string | null;
+}
+interface UpdateRequest {
+    tags?: string[];
+    importance?: number;
+    metadata?: Record<string, unknown>;
+    source?: string;
+    eventType?: string;
+}
+interface SummarizeRequest {
+    memoryIds: number[];
+    lossless?: boolean;
+}
+interface ComposeRequest {
+    promptTemplate: string;
+    recallK?: number;
+    maxTokens?: number;
+}
+interface ComposeResponse {
+    composedPrompt: string;
+    memoriesUsed: number;
+    tokenCount: number;
+    truncated: boolean;
+}
+type RelationshipType = "similar" | "derived_from" | "continuation" | "contradiction" | "summary_of" | "detail_of" | "caused_by" | "references" | "supports" | "extends";
+interface RelationCreateRequest {
+    toMemoryId: number;
+    relationshipType: RelationshipType;
+    confidence?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RelationRecord {
+    id: number;
+    fromMemoryId: number;
+    toMemoryId: number;
+    relationshipType: RelationshipType;
+    confidence: number;
+    metadata?: Record<string, unknown> | null;
+    createdAt: string;
+}
+interface ExportResponse {
+    userId: number;
+    memories: Array<Record<string, unknown>>;
+    generatedAt: string;
+}
+interface ErrorOpts {
+    statusCode?: number;
+    response?: unknown;
+    requestId?: string;
+}
+declare class MemorySyncError extends Error {
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    readonly requestId?: string;
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class AuthError extends MemorySyncError {
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class ValidationError extends MemorySyncError {
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class NotFoundError extends MemorySyncError {
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class RateLimitError extends MemorySyncError {
+    readonly retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number, opts?: ErrorOpts);
+}
+declare class ServerError extends MemorySyncError {
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class MemorySyncClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly projectId?;
+    private readonly endUserId?;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(config: MemorySyncConfig);
+    private headers;
+    private request;
+    private throwForStatus;
+    add(req: AddRequest): Promise<AddResponse>;
+    bulkAdd(items: BulkAddItem[], opts?: {
+        deduplicate?: boolean;
+    }): Promise<BulkAddResponse>;
+    query(req: QueryRequest): Promise<QueryResponse>;
+    get(memoryId: number): Promise<MemoryRecord>;
+    update(memoryId: number, req: UpdateRequest): Promise<MemoryRecord>;
+    forget(memoryIds: number[], reason?: string): Promise<number[]>;
+    summarize(req: SummarizeRequest): Promise<MemoryRecord>;
+    compose(req: ComposeRequest): Promise<ComposeResponse>;
+    exportAll(): Promise<ExportResponse>;
+    createRelation(fromMemoryId: number, req: RelationCreateRequest): Promise<RelationRecord>;
+}
+
+export { type AddRequest, type AddResponse, type AddSkippedResponse, AuthError, type BulkAddItem, type BulkAddItemResult, type BulkAddResponse, type ComposeRequest, type ComposeResponse, type ExportResponse, type MemoryRecord, MemorySyncClient, type MemorySyncConfig, MemorySyncError, NotFoundError, type QueryFilters, type QueryRequest, type QueryResponse, RateLimitError, type RelationCreateRequest, type RelationRecord, type RelationshipType, ServerError, type SummarizeRequest, type UpdateRequest, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,188 @@
+/**
+ * MemorySync SDK — JavaScript / TypeScript client.
+ *
+ * Wraps the public REST surface of MemorySync. Every method here maps 1:1
+ * to a route that exists in the backend; field names mirror the on-the-wire
+ * JSON exactly (snake_case is preserved on payloads, camelCase is exposed
+ * on the public TypeScript API).
+ */
+interface MemorySyncConfig {
+    apiKey: string;
+    baseUrl: string;
+    projectId?: string;
+    endUserId?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+interface AddRequest {
+    text: string;
+    source?: string;
+    tags?: string[];
+    importance?: number;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+    endUserId?: string;
+}
+interface MemoryRecord {
+    id: number;
+    text: string;
+    summary?: string | null;
+    tags?: string[] | null;
+    source?: string | null;
+    eventType?: string | null;
+    importance?: number | null;
+    metadata?: Record<string, unknown> | null;
+    isSummary: boolean;
+    createdAt: string;
+    updatedAt?: string | null;
+    score?: number | null;
+}
+interface AddSkippedResponse {
+    status: "skipped";
+    reason: string;
+    memoryIds: number[];
+    candidatesExtracted: number;
+    candidatesStored: number;
+}
+type AddResponse = MemoryRecord | AddSkippedResponse;
+interface BulkAddItem {
+    text: string;
+    source?: string;
+    eventType?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    importance?: number;
+    endUserId?: string;
+}
+interface BulkAddItemResult {
+    index: number;
+    status: "created" | "skipped" | "rejected";
+    memoryIds: number[];
+    reason: string | null;
+}
+interface BulkAddResponse {
+    total: number;
+    created: number;
+    skipped: number;
+    rejected: number;
+    results: BulkAddItemResult[];
+}
+interface QueryFilters {
+    memoryType?: string;
+    source?: string;
+    tags?: string[];
+    since?: string;
+    until?: string;
+    includeSummaries?: boolean;
+    tier?: "hot" | "warm" | "cold";
+}
+interface QueryRequest {
+    query: string;
+    k?: number;
+    filters?: QueryFilters;
+    sessionId?: string;
+    traversalDepth?: number;
+}
+interface QueryResponse {
+    memories: MemoryRecord[];
+    context?: string | null;
+    latencyMs?: number | null;
+    sessionId?: string | null;
+    queryIntent?: string | null;
+}
+interface UpdateRequest {
+    tags?: string[];
+    importance?: number;
+    metadata?: Record<string, unknown>;
+    source?: string;
+    eventType?: string;
+}
+interface SummarizeRequest {
+    memoryIds: number[];
+    lossless?: boolean;
+}
+interface ComposeRequest {
+    promptTemplate: string;
+    recallK?: number;
+    maxTokens?: number;
+}
+interface ComposeResponse {
+    composedPrompt: string;
+    memoriesUsed: number;
+    tokenCount: number;
+    truncated: boolean;
+}
+type RelationshipType = "similar" | "derived_from" | "continuation" | "contradiction" | "summary_of" | "detail_of" | "caused_by" | "references" | "supports" | "extends";
+interface RelationCreateRequest {
+    toMemoryId: number;
+    relationshipType: RelationshipType;
+    confidence?: number;
+    metadata?: Record<string, unknown>;
+}
+interface RelationRecord {
+    id: number;
+    fromMemoryId: number;
+    toMemoryId: number;
+    relationshipType: RelationshipType;
+    confidence: number;
+    metadata?: Record<string, unknown> | null;
+    createdAt: string;
+}
+interface ExportResponse {
+    userId: number;
+    memories: Array<Record<string, unknown>>;
+    generatedAt: string;
+}
+interface ErrorOpts {
+    statusCode?: number;
+    response?: unknown;
+    requestId?: string;
+}
+declare class MemorySyncError extends Error {
+    readonly statusCode?: number;
+    readonly response?: unknown;
+    readonly requestId?: string;
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class AuthError extends MemorySyncError {
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class ValidationError extends MemorySyncError {
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class NotFoundError extends MemorySyncError {
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class RateLimitError extends MemorySyncError {
+    readonly retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number, opts?: ErrorOpts);
+}
+declare class ServerError extends MemorySyncError {
+    constructor(message: string, opts?: ErrorOpts);
+}
+declare class MemorySyncClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly projectId?;
+    private readonly endUserId?;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(config: MemorySyncConfig);
+    private headers;
+    private request;
+    private throwForStatus;
+    add(req: AddRequest): Promise<AddResponse>;
+    bulkAdd(items: BulkAddItem[], opts?: {
+        deduplicate?: boolean;
+    }): Promise<BulkAddResponse>;
+    query(req: QueryRequest): Promise<QueryResponse>;
+    get(memoryId: number): Promise<MemoryRecord>;
+    update(memoryId: number, req: UpdateRequest): Promise<MemoryRecord>;
+    forget(memoryIds: number[], reason?: string): Promise<number[]>;
+    summarize(req: SummarizeRequest): Promise<MemoryRecord>;
+    compose(req: ComposeRequest): Promise<ComposeResponse>;
+    exportAll(): Promise<ExportResponse>;
+    createRelation(fromMemoryId: number, req: RelationCreateRequest): Promise<RelationRecord>;
+}
+
+export { type AddRequest, type AddResponse, type AddSkippedResponse, AuthError, type BulkAddItem, type BulkAddItemResult, type BulkAddResponse, type ComposeRequest, type ComposeResponse, type ExportResponse, type MemoryRecord, MemorySyncClient, type MemorySyncConfig, MemorySyncError, NotFoundError, type QueryFilters, type QueryRequest, type QueryResponse, RateLimitError, type RelationCreateRequest, type RelationRecord, type RelationshipType, ServerError, type SummarizeRequest, type UpdateRequest, ValidationError };