@mymehq/sdk 3.4.0 → 3.6.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { MergeStrategy, ConflictSnapshot, MergePolicy, Item, ItemState, CreateItemInput, PaginatedResult, ItemWithMetadata, Version, Edge, Metadata, SearchResult, CreateEdgeInput, EdgeTypeSchema, TypeSchema, CreateKeyInput, ApiKey, UpdateKeyInput, CreateWebhookInput, Webhook, UpdateWebhookInput, WebhookDelivery, TenantConfig } from '@mymehq/shared';
+import { MergeStrategy, ConflictSnapshot, MergePolicy, ItemState, Item, CreateItemInput, PaginatedResult, ItemWithMetadata, Version, Edge, Metadata, SearchResult, CreateEdgeInput, EdgeTypeSchema, TypeSchema, CreateKeyInput, ApiKey, UpdateKeyInput, CreateWebhookInput, Webhook, UpdateWebhookInput, WebhookDelivery, TenantConfig } from '@mymehq/shared';
 export { ApiKey, ConflictSnapshot, CreateItemInput, CreateKeyInput, Item, ItemState, MergePolicy, MergeStrategy, Metadata, PaginatedResult, SearchResult, TypeSchema, UpdateKeyInput, Version } from '@mymehq/shared';
 
 /**
@@ -69,6 +69,21 @@ interface ClientConfig {
     cdnBaseUrl?: string;
 }
 interface UpdateOptions {
+    /**
+     * Version the caller expects the item to currently be at. When provided,
+     * the SDK skips the upfront `GET /items/:id` and PATCHes directly. If the
+     * server's actual version differs, the update 409s through the usual
+     * conflict path — the caller's retry policy is out of scope here.
+     *
+     * Prefer `expectedVersion` for bulk importers and sync loops that already
+     * know the version locally; one request instead of two.
+     */
+    expectedVersion?: number;
+    /**
+     * Legacy alias for `expectedVersion`. Kept for backwards compatibility;
+     * new code should use `expectedVersion`.
+     * @deprecated Use `expectedVersion`.
+     */
     version?: number;
     /**
      * Override the client's default conflict strategy for this update.
@@ -84,7 +99,10 @@ interface UpdateOptions {
     library?: boolean;
     /**
      * Item type. Required by the `auto` strategy when a `keep_both_copies`
-     * conflict spawns a sibling item. Omit to let the SDK pre-fetch it.
+     * conflict spawns a sibling item. Omit to let the SDK pre-fetch it —
+     * when `expectedVersion` is also omitted the pre-fetch happens upfront;
+     * when `expectedVersion` is provided the fetch is deferred until a
+     * `keep_both_copies` conflict actually needs it.
      */
     type?: string;
     /**
@@ -145,6 +163,126 @@ interface SearchFilters {
 interface MetadataInput {
     tags?: string[];
 }
+/** One item to create or upsert in a `POST /items/bulk` call. Shape is
+ *  `CreateItemInput` plus compact outbound-only inline `edges`. */
+interface BulkItemInput {
+    id?: string;
+    type: string;
+    properties?: Record<string, unknown>;
+    state?: ItemState;
+    library?: boolean;
+    timestamp?: string;
+    /** Ignored on the wire — server stamps `source` from the credential.
+     *  Kept on the input shape for round-trip parity with /export output. */
+    source?: string;
+    source_id?: string;
+    origin?: "user" | "ai" | "worker";
+    device?: string;
+    tags?: string[];
+    /** Outbound edges to reconcile in the same transaction as the item
+     *  write. Replace-all semantics per edge_type. Absent = untouched. */
+    edges?: Record<string, string[]>;
+}
+type BulkMode = "upsert" | "create_only";
+interface BulkInput {
+    items: BulkItemInput[];
+    /** Default: `"upsert"`. */
+    mode?: BulkMode;
+    /** Default: `true`. When false, errors are collected per item and the
+     *  batch continues past failures. */
+    atomic?: boolean;
+    /** Default: `false`. Per-item events are suppressed on bulk writes
+     *  unless the caller opts in. */
+    emit_events?: boolean;
+}
+type BulkOutcome = "created" | "updated" | "skipped" | "errored";
+interface BulkResultEntry {
+    index: number;
+    outcome: BulkOutcome;
+    id?: string;
+    reason?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+interface BulkResult {
+    counts: {
+        created: number;
+        updated: number;
+        skipped: number;
+        errored: number;
+    };
+    results: BulkResultEntry[];
+    /** Present only on archive-restore paths. */
+    blobs_imported?: number;
+}
+/** Filter shape for `POST /items/bulk_action`. Mirrors the `GET /items`
+ *  query grammar — every field is AND-composed, `filter` accepts the
+ *  full filter-SQL DSL. */
+interface BulkActionFilter {
+    type?: string;
+    state?: ItemState;
+    source?: string;
+    library?: boolean;
+    tags?: string[];
+    since?: string;
+    until?: string;
+    /** Same grammar as `GET /items?filter=`. `edge[type]=id` shorthand
+     *  becomes `edge[type] eq "id"` here. */
+    filter?: string;
+}
+/** Shared knobs every bulk action accepts. */
+interface BulkActionBase {
+    filter?: BulkActionFilter;
+    dry_run?: boolean;
+    max_items?: number;
+    emit_events?: boolean;
+}
+/** Discriminated union over the six bulk actions. The compiler pins the
+ *  per-case parameters at the call site — no runtime string fiddling. */
+type BulkActionInput = (BulkActionBase & {
+    action: "transition";
+    state: "active" | "archived" | "trashed";
+}) | (BulkActionBase & {
+    action: "purge";
+    /** Required literal. The server returns `400 bulk_confirmation_required`
+     *  without it; the SDK throws the same shape before sending. */
+    confirm: "PURGE";
+}) | (BulkActionBase & {
+    action: "update_tags";
+    add?: string[];
+    remove?: string[];
+}) | (BulkActionBase & {
+    action: "update_library";
+    library: boolean;
+}) | (BulkActionBase & {
+    action: "update_properties";
+    patch: Record<string, unknown>;
+}) | (BulkActionBase & {
+    action: "update_timestamp";
+    timestamp: string;
+});
+interface BulkActionErrorEntry {
+    id: string;
+    code: string;
+    message: string;
+}
+interface BulkActionResult {
+    action: string;
+    matched: number;
+    succeeded: number;
+    errored: number;
+    dry_run: boolean;
+    /** Present when matched / succeeded is small enough to be useful
+     *  (dry-run always, otherwise when succeeded ≤ 100). */
+    ids?: string[];
+    errors?: BulkActionErrorEntry[];
+    /** Unique blob hashes referenced by items in a `purge` action. Not a
+     *  strict orphan count — callers that need that should wait for blob
+     *  GC to land. Omitted for non-purge actions. */
+    blob_hashes_referenced?: number;
+}
 declare class MymeClient {
     private readonly transport;
     private readonly defaultConflictStrategy;
@@ -178,6 +316,25 @@ declare class MymeClient {
         transition: (id: string, state: string) => Promise<Item>;
         versions: (id: string) => Promise<Version[]>;
         stats: () => Promise<Record<string, number>>;
+        /**
+         * Create or upsert many items in one call (admin-only). Replaces the
+         * historical `/import` endpoint. Up to 5000 items per call.
+         *
+         * Modes: `"upsert"` (default) updates matching `(source, source_id)`
+         * rows in place; `"create_only"` surfaces matches as `skipped`.
+         * `atomic: true` (default) rolls back the whole batch on any failure.
+         */
+        bulk: (input: BulkInput) => Promise<BulkResult>;
+        /**
+         * Apply one action to every item matching a filter. Six actions
+         * discriminated on `action`. Purge is admin-only and requires
+         * `confirm: "PURGE"` — the SDK throws a `bulk_confirmation_required`
+         * `MymeError` client-side if you forget, matching the server's 400.
+         *
+         * Non-admin callers see their match set narrowed to writable types
+         * for every action except `purge`, which hard-403s.
+         */
+        bulkAction: (input: BulkActionInput) => Promise<BulkActionResult>;
         /** Outbound edges from this item. Shortcut for edges.listFromSource. */
         edges: (itemId: string, filters?: {
             edge_type?: string | string[];
@@ -330,7 +487,7 @@ declare class MymeError extends Error {
     readonly code: string;
     readonly status: number;
     readonly details?: Record<string, unknown>;
-    constructor(code: string, message: string, status: number, details?: Record<string, unknown>);
+    constructor(code: string, message: string, status: number, details?: Record<string, unknown>, cause?: unknown);
 }
 declare class NotFoundError extends MymeError {
     constructor(message: string, details?: Record<string, unknown>);
@@ -404,4 +561,4 @@ interface VerifyWebhookSignatureInput {
  */
 declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): WebhookVerifyResult;
 
-export { type ClientConfig, type ConflictAutoMergeListener, type ConflictAutoMergedEvent, type ConflictData, ConflictError, type ConflictResolver, type ConflictStrategy, ForbiddenError, type ItemWithExtensions, type ListFilters, type MetadataInput, MymeClient, MymeError, NotFoundError, type SearchFilters, UnauthorizedError, type UpdateOptions, ValidationError, type VerifyWebhookSignatureInput, type WebhookVerifyReason, type WebhookVerifyResult, verifyWebhookSignature };
+export { type BulkActionErrorEntry, type BulkActionFilter, type BulkActionInput, type BulkActionResult, type BulkInput, type BulkItemInput, type BulkMode, type BulkOutcome, type BulkResult, type BulkResultEntry, type ClientConfig, type ConflictAutoMergeListener, type ConflictAutoMergedEvent, type ConflictData, ConflictError, type ConflictResolver, type ConflictStrategy, ForbiddenError, type ItemWithExtensions, type ListFilters, type MetadataInput, MymeClient, MymeError, NotFoundError, type SearchFilters, UnauthorizedError, type UpdateOptions, ValidationError, type VerifyWebhookSignatureInput, type WebhookVerifyReason, type WebhookVerifyResult, verifyWebhookSignature };

package/dist/index.js

@@ -3,8 +3,8 @@ var MymeError = class extends Error {
   code;
   status;
   details;
-  constructor(code, message, status, details) {
-    super(message);
+  constructor(code, message, status, details, cause) {
+    super(message, cause !== void 0 ? { cause } : void 0);
     this.name = "MymeError";
     this.code = code;
     this.status = status;
@@ -68,7 +68,7 @@ var HttpTransport = class {
     if (response.status === 204) {
       return void 0;
     }
-    const body = await response.json();
+    const body = await this.parseJson(response);
     if (!response.ok) {
       this.throwForError(response.status, body);
     }
@@ -81,7 +81,7 @@ var HttpTransport = class {
    */
   async requestWithConflict(method, path, options) {
     const response = await this.rawRequest(method, path, options);
-    const body = await response.json();
+    const body = await this.parseJson(response);
     if (response.status === 409) {
       return body;
     }
@@ -109,10 +109,42 @@ var HttpTransport = class {
     }
     try {
       return await this.fetch(url, init);
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "AbortError") {
+        throw new MymeError(
+          "timeout",
+          `Request to ${path} timed out after ${String(this.timeoutMs)}ms`,
+          0,
+          { path, timeoutMs: this.timeoutMs },
+          err
+        );
+      }
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new MymeError(
+        "network_error",
+        `Network request to ${path} failed: ${reason}`,
+        0,
+        { path },
+        err
+      );
     } finally {
       clearTimeout(timeout);
     }
   }
+  async parseJson(response) {
+    try {
+      return await response.json();
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      throw new MymeError(
+        "parse_error",
+        `Failed to parse response body as JSON (HTTP ${String(response.status)}): ${reason}`,
+        0,
+        { httpStatus: response.status },
+        err
+      );
+    }
+  }
   buildUrl(path, query) {
     const url = `${this.baseUrl}${path}`;
     if (!query) return url;
@@ -152,6 +184,13 @@ var HttpTransport = class {
 };
 
 // src/conflict.ts
+async function fetchItemType(transport, itemId) {
+  const res = await transport.request(
+    "GET",
+    `/items/${itemId}`
+  );
+  return res.item.type;
+}
 var MAX_RETRIES = 3;
 function isConflictResponse(body) {
   return typeof body === "object" && body !== null && "error" in body && "current" in body && "conflicting_fields" in body;
@@ -235,9 +274,10 @@ async function handleConflictUpdate(transport, itemId, itemType, clientPatch, ve
       const plan = planAutoMerge(conflict);
       let conflictedCopyId;
       if (plan.keepBothFields.length > 0) {
+        const effectiveType = itemType ?? await fetchItemType(transport, itemId);
         const sibling = await keepBothFlow(
           transport,
-          itemType,
+          effectiveType,
           result.current.properties,
           clientPatch,
           plan.keepBothFields
@@ -341,11 +381,14 @@ var MymeClient = class {
       );
     },
     update: async (id, properties, options) => {
-      let version = options?.version;
+      const expected = options?.expectedVersion ?? options?.version;
+      let version;
       let type = options?.type;
-      if (version === void 0 || type === void 0) {
+      if (expected !== void 0) {
+        version = expected;
+      } else {
         const item = await this.items.get(id);
-        version ??= item.version;
+        version = item.version;
         type ??= item.type;
       }
       const strategy = options?.conflict ?? this.defaultConflictStrategy;
@@ -401,6 +444,45 @@ var MymeClient = class {
         "/items/stats"
       );
     },
+    /**
+     * Create or upsert many items in one call (admin-only). Replaces the
+     * historical `/import` endpoint. Up to 5000 items per call.
+     *
+     * Modes: `"upsert"` (default) updates matching `(source, source_id)`
+     * rows in place; `"create_only"` surfaces matches as `skipped`.
+     * `atomic: true` (default) rolls back the whole batch on any failure.
+     */
+    bulk: async (input) => {
+      return this.transport.request("POST", "/items/bulk", {
+        body: input
+      });
+    },
+    /**
+     * Apply one action to every item matching a filter. Six actions
+     * discriminated on `action`. Purge is admin-only and requires
+     * `confirm: "PURGE"` — the SDK throws a `bulk_confirmation_required`
+     * `MymeError` client-side if you forget, matching the server's 400.
+     *
+     * Non-admin callers see their match set narrowed to writable types
+     * for every action except `purge`, which hard-403s.
+     */
+    bulkAction: async (input) => {
+      if (input.action === "purge") {
+        const confirm = input.confirm;
+        if (confirm !== "PURGE") {
+          throw new MymeError(
+            "bulk_confirmation_required",
+            "bulkAction({ action: 'purge' }) requires confirm: 'PURGE'",
+            400
+          );
+        }
+      }
+      return this.transport.request(
+        "POST",
+        "/items/bulk_action",
+        { body: input }
+      );
+    },
     /** Outbound edges from this item. Shortcut for edges.listFromSource. */
     edges: (itemId, filters) => this.edges.listFromSource(itemId, filters),
     /** Inbound edges targeting this item. Shortcut for edges.listToTarget. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mymehq/sdk",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@mymehq/shared": "3.4.0"
+    "@mymehq/shared": "3.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",