@mymehq/sdk 3.5.0 → 3.7.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';
 
 /**
@@ -163,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;
@@ -196,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[];
@@ -348,19 +487,28 @@ 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);
 }
+/**
+ * Status-coded subclasses preserve the server-supplied `code` so callers
+ * can branch on specific codes (`bulk_cap_exceeded`, `edge_not_found`,
+ * `reset_disabled`, …) while still matching `instanceof NotFoundError`
+ * etc. for generic handling. The status family (4xx bucket) is
+ * communicated by the class; the specific code is communicated by the
+ * `code` field. When the server omits a code, the canonical value for
+ * the status family is used as a fallback.
+ */
 declare class NotFoundError extends MymeError {
-    constructor(message: string, details?: Record<string, unknown>);
+    constructor(message: string, details?: Record<string, unknown>, code?: string);
 }
 declare class ValidationError extends MymeError {
-    constructor(message: string, details?: Record<string, unknown>);
+    constructor(message: string, details?: Record<string, unknown>, code?: string);
 }
 declare class UnauthorizedError extends MymeError {
-    constructor(message: string, details?: Record<string, unknown>);
+    constructor(message: string, details?: Record<string, unknown>, code?: string);
 }
 declare class ForbiddenError extends MymeError {
-    constructor(message: string, details?: Record<string, unknown>);
+    constructor(message: string, details?: Record<string, unknown>, code?: string);
 }
 declare class ConflictError extends MymeError {
     readonly current: ConflictSnapshot;
@@ -422,4 +570,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;
@@ -12,26 +12,26 @@ var MymeError = class extends Error {
   }
 };
 var NotFoundError = class extends MymeError {
-  constructor(message, details) {
-    super("not_found", message, 404, details);
+  constructor(message, details, code) {
+    super(code ?? "not_found", message, 404, details);
     this.name = "NotFoundError";
   }
 };
 var ValidationError = class extends MymeError {
-  constructor(message, details) {
-    super("validation_error", message, 400, details);
+  constructor(message, details, code) {
+    super(code ?? "validation_error", message, 400, details);
     this.name = "ValidationError";
   }
 };
 var UnauthorizedError = class extends MymeError {
-  constructor(message, details) {
-    super("unauthorized", message, 401, details);
+  constructor(message, details, code) {
+    super(code ?? "unauthorized", message, 401, details);
     this.name = "UnauthorizedError";
   }
 };
 var ForbiddenError = class extends MymeError {
-  constructor(message, details) {
-    super("forbidden", message, 403, details);
+  constructor(message, details, code) {
+    super(code ?? "forbidden", message, 403, details);
     this.name = "ForbiddenError";
   }
 };
@@ -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;
@@ -135,18 +167,18 @@ var HttpTransport = class {
     const errObj = parsed?.error;
     const message = errObj?.message ?? `HTTP ${String(status)}`;
     const details = errObj?.details;
-    const code = errObj?.code ?? "unknown";
+    const serverCode = errObj?.code;
     switch (status) {
       case 400:
-        throw new ValidationError(message, details);
+        throw new ValidationError(message, details, serverCode);
       case 401:
-        throw new UnauthorizedError(message, details);
+        throw new UnauthorizedError(message, details, serverCode);
       case 403:
-        throw new ForbiddenError(message, details);
+        throw new ForbiddenError(message, details, serverCode);
       case 404:
-        throw new NotFoundError(message, details);
+        throw new NotFoundError(message, details, serverCode);
       default:
-        throw new MymeError(code, message, status, details);
+        throw new MymeError(serverCode ?? "unknown", message, status, details);
     }
   }
 };
@@ -412,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.5.0",
+  "version": "3.7.0",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@mymehq/shared": "3.4.1"
+    "@mymehq/shared": "3.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",