memorysync-sdk 1.7.3 → 1.9.0

package/dist/index.d.mts

@@ -807,6 +807,17 @@ interface AddRequest {
     sessionId?: string;
     metadata?: Record<string, unknown>;
     endUserId?: string;
+    /**
+     * Your own identifier for this record, at most 128 characters.
+     *
+     * Send it and re-sending the record is recognised rather than stored a second
+     * time: the call resolves to an {@link AddSkippedResponse} with reason
+     * `already_ingested` and the ids the first write produced. That makes an
+     * interrupted write safe to retry without first checking whether it landed.
+     * Near-duplicate detection is always on but compares *meaning*, so it is a
+     * filter and not a guarantee.
+     */
+    clientRef?: string;
 }
 interface MemoryRecord {
     id: number;
@@ -832,6 +843,16 @@ interface AddSkippedResponse {
 type AddResponse = MemoryRecord | AddSkippedResponse;
 interface BulkAddItem {
     text: string;
+    /**
+     * Your own identifier for this record, at most 128 characters.
+     *
+     * Send it and re-submitting the record is recognised rather than stored a
+     * second time: the item comes back `skipped` with reason `already_ingested`
+     * and the ids the first submission produced. This is what makes a large import
+     * safe to re-run. Near-duplicate detection is always on but compares
+     * *meaning*, so it is a filter and not a guarantee.
+     */
+    clientRef?: string;
     source?: string;
     eventType?: string;
     tags?: string[];
@@ -1093,6 +1114,46 @@ declare class MemorySyncClient {
     bulkAdd(items: BulkAddItem[], opts?: {
         deduplicate?: boolean;
     }): Promise<BulkAddResponse>;
+    /**
+     * Upload a payload and get an import job back, without waiting for it.
+     *
+     * `bulkAdd` accepts fifty records per call because each one runs the extraction
+     * pipeline. For a migration out of another system, upload the whole file here
+     * and poll {@link getImport}.
+     *
+     * `resume` requires `clientRef` on every record and is what makes re-running the
+     * same file safe: records a previous run already stored come back counted as
+     * `alreadyImported` rather than stored again.
+     *
+     * The payload is JSONL, or JSON when `filename` ends in `.json`. The extension
+     * is how the server picks the reader, so it is required.
+     */
+    createImport(req: {
+        file: Blob | Uint8Array | string;
+        filename: string;
+        endUserId?: string;
+        resume?: boolean;
+        continueOnError?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * One import job's status, progress and per-outcome counters.
+     *
+     * `progress_percentage` stays below 100 until the job is genuinely finished, so
+     * reaching 100 means done.
+     */
+    getImport(jobId: string): Promise<Record<string, unknown>>;
+    /** Recent import jobs, newest first. */
+    listImports(opts?: {
+        status?: string;
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Ask the worker to stop between batches.
+     *
+     * Records already imported stay imported, and the counters report how far it
+     * reached. Cancelling a finished job is a no-op rather than an error.
+     */
+    cancelImport(jobId: string): Promise<Record<string, unknown>>;
     query(req: QueryRequest): Promise<QueryResponse>;
     get(memoryId: number): Promise<MemoryRecord>;
     update(memoryId: number, req: UpdateRequest): Promise<MemoryRecord>;

package/dist/index.d.ts

@@ -807,6 +807,17 @@ interface AddRequest {
     sessionId?: string;
     metadata?: Record<string, unknown>;
     endUserId?: string;
+    /**
+     * Your own identifier for this record, at most 128 characters.
+     *
+     * Send it and re-sending the record is recognised rather than stored a second
+     * time: the call resolves to an {@link AddSkippedResponse} with reason
+     * `already_ingested` and the ids the first write produced. That makes an
+     * interrupted write safe to retry without first checking whether it landed.
+     * Near-duplicate detection is always on but compares *meaning*, so it is a
+     * filter and not a guarantee.
+     */
+    clientRef?: string;
 }
 interface MemoryRecord {
     id: number;
@@ -832,6 +843,16 @@ interface AddSkippedResponse {
 type AddResponse = MemoryRecord | AddSkippedResponse;
 interface BulkAddItem {
     text: string;
+    /**
+     * Your own identifier for this record, at most 128 characters.
+     *
+     * Send it and re-submitting the record is recognised rather than stored a
+     * second time: the item comes back `skipped` with reason `already_ingested`
+     * and the ids the first submission produced. This is what makes a large import
+     * safe to re-run. Near-duplicate detection is always on but compares
+     * *meaning*, so it is a filter and not a guarantee.
+     */
+    clientRef?: string;
     source?: string;
     eventType?: string;
     tags?: string[];
@@ -1093,6 +1114,46 @@ declare class MemorySyncClient {
     bulkAdd(items: BulkAddItem[], opts?: {
         deduplicate?: boolean;
     }): Promise<BulkAddResponse>;
+    /**
+     * Upload a payload and get an import job back, without waiting for it.
+     *
+     * `bulkAdd` accepts fifty records per call because each one runs the extraction
+     * pipeline. For a migration out of another system, upload the whole file here
+     * and poll {@link getImport}.
+     *
+     * `resume` requires `clientRef` on every record and is what makes re-running the
+     * same file safe: records a previous run already stored come back counted as
+     * `alreadyImported` rather than stored again.
+     *
+     * The payload is JSONL, or JSON when `filename` ends in `.json`. The extension
+     * is how the server picks the reader, so it is required.
+     */
+    createImport(req: {
+        file: Blob | Uint8Array | string;
+        filename: string;
+        endUserId?: string;
+        resume?: boolean;
+        continueOnError?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * One import job's status, progress and per-outcome counters.
+     *
+     * `progress_percentage` stays below 100 until the job is genuinely finished, so
+     * reaching 100 means done.
+     */
+    getImport(jobId: string): Promise<Record<string, unknown>>;
+    /** Recent import jobs, newest first. */
+    listImports(opts?: {
+        status?: string;
+        limit?: number;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * Ask the worker to stop between batches.
+     *
+     * Records already imported stay imported, and the counters report how far it
+     * reached. Cancelling a finished job is a no-op rather than an error.
+     */
+    cancelImport(jobId: string): Promise<Record<string, unknown>>;
     query(req: QueryRequest): Promise<QueryResponse>;
     get(memoryId: number): Promise<MemoryRecord>;
     update(memoryId: number, req: UpdateRequest): Promise<MemoryRecord>;

package/dist/index.js

@@ -576,7 +576,7 @@ var IntegrationsNamespace = class extends Namespace {
 };
 
 // src/control-plane.ts
-var SDK_VERSION = "1.7.3";
+var SDK_VERSION = "1.9.0";
 function safeJson(text) {
   try {
     return JSON.parse(text);
@@ -1148,7 +1148,7 @@ function asSkipped(raw, defaultReason) {
   }
   return null;
 }
-var SDK_VERSION2 = "1.7.3";
+var SDK_VERSION2 = "1.9.0";
 function camelToSnakeKey(key) {
   return key.replace(/([A-Z])/g, "_$1").toLowerCase();
 }
@@ -1315,6 +1315,7 @@ var MemorySyncClient = class {
     if (req.sessionId !== void 0) body.session_id = req.sessionId;
     if (req.metadata !== void 0) body.metadata = req.metadata;
     if (req.endUserId !== void 0) body.end_user_id = req.endUserId;
+    if (req.clientRef !== void 0) body.client_ref = req.clientRef;
     const raw = await this.request("POST", "/memory/add", {
       body,
       endUserOverride: req.endUserId
@@ -1335,6 +1336,7 @@ var MemorySyncClient = class {
         if (i.metadata !== void 0) o.metadata = i.metadata;
         if (i.importance !== void 0) o.importance = i.importance;
         if (i.endUserId !== void 0) o.end_user_id = i.endUserId;
+        if (i.clientRef !== void 0) o.client_ref = i.clientRef;
         return o;
       }),
       deduplicate: opts.deduplicate ?? true
@@ -1364,6 +1366,63 @@ var MemorySyncClient = class {
       }))
     };
   }
+  // ── Bulk import ────────────────────────────────────────────────────
+  /**
+   * Upload a payload and get an import job back, without waiting for it.
+   *
+   * `bulkAdd` accepts fifty records per call because each one runs the extraction
+   * pipeline. For a migration out of another system, upload the whole file here
+   * and poll {@link getImport}.
+   *
+   * `resume` requires `clientRef` on every record and is what makes re-running the
+   * same file safe: records a previous run already stored come back counted as
+   * `alreadyImported` rather than stored again.
+   *
+   * The payload is JSONL, or JSON when `filename` ends in `.json`. The extension
+   * is how the server picks the reader, so it is required.
+   */
+  async createImport(req) {
+    if (!req.filename?.trim()) {
+      throw new ValidationError("filename is required so the server can pick a reader");
+    }
+    const form = new FormData();
+    form.set("resume", req.resume ? "true" : "false");
+    form.set("continue_on_error", req.continueOnError ? "true" : "false");
+    if (req.endUserId !== void 0) form.set("end_user_id", req.endUserId);
+    const blob = req.file instanceof Blob ? req.file : new Blob([req.file], { type: "application/octet-stream" });
+    form.set("file", blob, req.filename);
+    return this.request("POST", "/imports", {
+      form,
+      endUserOverride: req.endUserId
+    });
+  }
+  /**
+   * One import job's status, progress and per-outcome counters.
+   *
+   * `progress_percentage` stays below 100 until the job is genuinely finished, so
+   * reaching 100 means done.
+   */
+  async getImport(jobId) {
+    if (!jobId?.trim()) throw new ValidationError("jobId is required");
+    return this.request("GET", `/imports/${encodeURIComponent(jobId)}`);
+  }
+  /** Recent import jobs, newest first. */
+  async listImports(opts = {}) {
+    return this.request("GET", "/imports", { query: opts });
+  }
+  /**
+   * Ask the worker to stop between batches.
+   *
+   * Records already imported stay imported, and the counters report how far it
+   * reached. Cancelling a finished job is a no-op rather than an error.
+   */
+  async cancelImport(jobId) {
+    if (!jobId?.trim()) throw new ValidationError("jobId is required");
+    return this.request(
+      "POST",
+      `/imports/${encodeURIComponent(jobId)}/cancel`
+    );
+  }
   async query(req) {
     const body = { query: req.query };
     if (req.k !== void 0) body.k = req.k;