@mymehq/sdk 3.1.0 → 3.3.0

package/dist/index.d.ts

@@ -1,11 +1,14 @@
-import { ConflictSnapshot, ItemState, CreateItemInput, Item, 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, Metadata, PaginatedResult, SearchResult, TypeSchema, UpdateKeyInput, Version } from '@mymehq/shared';
+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';
+export { ApiKey, ConflictSnapshot, CreateItemInput, CreateKeyInput, Item, ItemState, MergePolicy, MergeStrategy, Metadata, PaginatedResult, SearchResult, TypeSchema, UpdateKeyInput, Version } from '@mymehq/shared';
 
 /**
  * Conflict resolution strategy for item updates.
  *
- * - `"auto"` (default): Non-conflicting field changes merge automatically.
- *   Conflicting fields use the server's current value. Retries up to 3 times.
+ * - `"auto"` (default): policy-aware. Per-field strategies declared on the
+ *   type drive the merge. `last_writer_wins` fields take the server's value;
+ *   `keep_both_copies` fields spawn a sibling item tagged `conflicted-copy`
+ *   with the client's value, leaving the original at the server's value.
+ *   The default for fields not listed in the policy is `last_writer_wins`.
  * - `"manual"`: Throws a `ConflictError` with both versions and the list of
  *   conflicting fields. The caller decides how to resolve.
  * - `"callback"`: Calls a custom `ConflictResolver` function with the conflict
@@ -17,8 +20,32 @@ interface ConflictData {
     ancestor: ConflictSnapshot;
     conflictingFields: string[];
     clientPatch: Record<string, unknown>;
+    /** Resolved per-field merge policy for the conflicting item's type. */
+    mergePolicy: MergePolicy;
 }
 type ConflictResolver = (conflict: ConflictData) => Record<string, unknown> | Promise<Record<string, unknown>>;
+/**
+ * Notification payload emitted by the auto-merge path. Surfaces the per-field
+ * outcome so callers can present an accurate UI affordance (e.g. "your edit
+ * was saved as a conflicted copy").
+ *
+ * - `itemId` — the original item that was being updated.
+ * - `mergedItemId` — the same id; included so listeners that care about
+ *   identity in event streams have a stable field.
+ * - `conflictedCopyId` — present when at least one `keep_both_copies` field
+ *   conflicted; the id of the spawned sibling that carries the client's edit.
+ * - `fields` — the list of fields that conflicted.
+ * - `strategy` — keyed by field name, the strategy applied to each.
+ */
+interface ConflictAutoMergedEvent {
+    itemId: string;
+    mergedItemId: string;
+    conflictedCopyId?: string;
+    fields: string[];
+    strategy: Record<string, MergeStrategy>;
+}
+/** Optional callback fired when the auto-merge path completes successfully. */
+type ConflictAutoMergeListener = (event: ConflictAutoMergedEvent) => void | Promise<void>;
 
 interface ClientConfig {
     url: string;
@@ -31,6 +58,13 @@ interface ClientConfig {
      * use the server's value.
      */
     conflictStrategy?: ConflictStrategy;
+    /**
+     * Default listener invoked after the auto-merge path completes successfully.
+     * Receives a `ConflictAutoMergedEvent` describing the per-field outcome and
+     * any spawned conflicted-copy id. Per-call overridable via
+     * `UpdateOptions.onAutoMerge`.
+     */
+    onConflictAutoMerge?: ConflictAutoMergeListener;
     timeoutMs?: number;
     cdnBaseUrl?: string;
 }
@@ -45,6 +79,19 @@ interface UpdateOptions {
     conflict?: ConflictStrategy;
     /** Custom conflict resolver (required when `conflict` is `"callback"`). */
     resolve?: ConflictResolver;
+    /** Toggle library / ambient state. Independent of the version-merge path
+     *  for `properties`; a library-only update never conflicts. */
+    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.
+     */
+    type?: string;
+    /**
+     * Listener invoked after the auto-merge path completes successfully.
+     * Overrides the client's default `onConflictAutoMerge` for this call.
+     */
+    onAutoMerge?: ConflictAutoMergeListener;
 }
 interface ListFilters {
     type?: string;
@@ -65,12 +112,33 @@ interface ListFilters {
     until?: string;
     limit?: number;
     cursor?: string;
+    /**
+     * Opt-in hydrations on the list response. Comma-separated values; each
+     * value widens the per-item shape. Prefer the typed helpers
+     * (`listWithMetadata`, `listWithExtensions`) over raw strings.
+     *
+     * - `metadata` — wraps each entry as `{ item, metadata }`.
+     * - `edges` — hydrates outbound edges per item grouped by type.
+     * - `extensions` — hydrates extension namespaces (filtered by caller
+     *   permissions, same rule as `GET /items/:id/extensions`).
+     *
+     * Lists are lean by default; opt into extras when the UI needs them
+     * to avoid N+1 per-item round trips.
+     */
+    include?: string;
 }
+/** Item paired with its hydrated extension namespaces. */
+type ItemWithExtensions = Item & {
+    extensions: Record<string, Record<string, unknown>>;
+};
 interface SearchFilters {
     type?: string;
     state?: ItemState;
     /** Tri-value library filter, matching `ListFilters.library`. */
     library?: boolean;
+    /** Items must have ALL specified tags (AND semantics). Matches
+     *  `ListFilters.tags` and `/items?tags=`. */
+    tags?: string[];
     filter?: string;
     limit?: number;
 }
@@ -80,6 +148,7 @@ interface MetadataInput {
 declare class MymeClient {
     private readonly transport;
     private readonly defaultConflictStrategy;
+    private readonly defaultOnConflictAutoMerge?;
     private readonly apiBaseUrl;
     private readonly cdnBaseUrl?;
     constructor(config: ClientConfig);
@@ -92,6 +161,14 @@ declare class MymeClient {
         get: (id: string) => Promise<Item>;
         list: (filters?: ListFilters) => Promise<PaginatedResult<Item>>;
         listWithMetadata: (filters?: Omit<ListFilters, "include">) => Promise<PaginatedResult<ItemWithMetadata>>;
+        /**
+         * List items with their extension namespaces hydrated inline. Avoids
+         * the N+1 pattern of listing then calling `GET /items/:id/extensions`
+         * per item. Extensions are filtered by the caller's permissions —
+         * admins see every namespace, members see what they can read or
+         * write.
+         */
+        listWithExtensions: (filters?: Omit<ListFilters, "include">) => Promise<PaginatedResult<ItemWithExtensions>>;
         update: (id: string, properties: Record<string, unknown>, options?: UpdateOptions) => Promise<Item>;
         delete: (id: string) => Promise<void>;
         /** Permanently delete a trashed item (admin only). Item must already
@@ -120,12 +197,33 @@ declare class MymeClient {
         merge: (itemId: string, input: Partial<MetadataInput>) => Promise<Metadata>;
         addTags: (itemId: string, tags: string[]) => Promise<Metadata>;
         removeTag: (itemId: string, tag: string) => Promise<void>;
+        /**
+         * Enumerate the distinct set of tags in use across items the caller can
+         * read. Tenant-scoped, type-permission scoped, excludes trashed items.
+         * Returns tags with usage counts, sorted by count desc then tag asc.
+         */
+        listTags: () => Promise<{
+            tag: string;
+            count: number;
+        }[]>;
         getExtensions: (itemId: string, namespace?: string) => Promise<Record<string, Record<string, unknown>>>;
         setExtension: (itemId: string, namespace: string, data: Record<string, unknown>) => Promise<Record<string, Record<string, unknown>>>;
         deleteExtension: (itemId: string, namespace: string) => Promise<void>;
     };
     search(query: string, filters?: SearchFilters): Promise<SearchResult[]>;
     readonly edges: {
+        /**
+         * Global edge listing across the tenant, filtered by edge type
+         * (comma-separated string or array of type ids). Use this when you
+         * need "all edges of type X" — replaces the walk-every-item
+         * pattern. Per-target filters live on `listFromSource` /
+         * `listToTarget`.
+         */
+        list: (filters?: {
+            edge_type?: string | string[];
+            limit?: number;
+            cursor?: string;
+        }) => Promise<PaginatedResult<Edge>>;
         /** Create a single edge. Server enforces cardinality / type
          *  constraints / cycle prevention; throws on violation. */
         create: (input: CreateEdgeInput) => Promise<Edge>;
@@ -254,4 +352,4 @@ declare class ConflictError extends MymeError {
     constructor(current: ConflictSnapshot, ancestor: ConflictSnapshot, conflictingFields: string[], clientPatch: Record<string, unknown>);
 }
 
-export { type ClientConfig, type ConflictData, ConflictError, type ConflictResolver, type ConflictStrategy, ForbiddenError, type ListFilters, type MetadataInput, MymeClient, MymeError, NotFoundError, type SearchFilters, UnauthorizedError, type UpdateOptions, ValidationError };
+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 };

package/dist/index.js

@@ -156,14 +156,41 @@ var MAX_RETRIES = 3;
 function isConflictResponse(body) {
   return typeof body === "object" && body !== null && "error" in body && "current" in body && "conflicting_fields" in body;
 }
-function autoMerge(conflict) {
+function strategyFor(field, policy) {
+  return policy?.fields?.[field] ?? policy?.default ?? "last_writer_wins";
+}
+function planAutoMerge(conflict) {
   const merged = { ...conflict.current.properties };
+  const keepBothFields = [];
+  const strategyByField = {};
   for (const [key, value] of Object.entries(conflict.clientPatch)) {
-    if (!conflict.conflictingFields.includes(key)) {
+    const isConflicting = conflict.conflictingFields.includes(key);
+    if (!isConflicting) {
       merged[key] = value;
+      continue;
+    }
+    const strategy = strategyFor(key, conflict.mergePolicy);
+    strategyByField[key] = strategy;
+    if (strategy === "keep_both_copies") {
+      keepBothFields.push(key);
     }
   }
-  return merged;
+  return { merged, keepBothFields, strategyByField };
+}
+async function keepBothFlow(transport, type, current, clientPatch, keepBothFields) {
+  const properties = { ...current };
+  for (const field of keepBothFields) {
+    properties[field] = clientPatch[field];
+  }
+  const input = {
+    type,
+    properties,
+    tags: ["conflicted-copy"]
+  };
+  const res = await transport.request("POST", "/items", {
+    body: input
+  });
+  return res.item;
 }
 function toConflictError(response, clientPatch) {
   return new ConflictError(
@@ -173,17 +200,22 @@ function toConflictError(response, clientPatch) {
     clientPatch
   );
 }
-async function handleConflictUpdate(transport, itemId, clientPatch, version, strategy, resolver) {
+async function handleConflictUpdate(transport, itemId, itemType, clientPatch, version, strategy, resolver, library, onAutoMerge) {
   let properties = clientPatch;
   let currentVersion = version;
+  let pendingAutoMergeEvent;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
     const result = await transport.requestWithConflict("PATCH", `/items/${itemId}`, {
       body: {
         properties,
-        version: currentVersion
+        version: currentVersion,
+        ...library !== void 0 && { library }
       }
     });
     if (!isConflictResponse(result)) {
+      if (pendingAutoMergeEvent && onAutoMerge) {
+        await onAutoMerge(pendingAutoMergeEvent);
+      }
       return result.item;
     }
     if (strategy === "manual") {
@@ -196,10 +228,30 @@ async function handleConflictUpdate(transport, itemId, clientPatch, version, str
       current: result.current,
       ancestor: result.ancestor,
       conflictingFields: result.conflicting_fields,
-      clientPatch
+      clientPatch,
+      mergePolicy: result.merge_policy
     };
     if (strategy === "auto") {
-      properties = autoMerge(conflict);
+      const plan = planAutoMerge(conflict);
+      let conflictedCopyId;
+      if (plan.keepBothFields.length > 0) {
+        const sibling = await keepBothFlow(
+          transport,
+          itemType,
+          result.current.properties,
+          clientPatch,
+          plan.keepBothFields
+        );
+        conflictedCopyId = sibling.id;
+      }
+      properties = plan.merged;
+      pendingAutoMergeEvent = {
+        itemId,
+        mergedItemId: itemId,
+        conflictedCopyId,
+        fields: conflict.conflictingFields,
+        strategy: plan.strategyByField
+      };
     } else {
       if (!resolver) {
         throw toConflictError(result, clientPatch);
@@ -220,6 +272,7 @@ async function handleConflictUpdate(transport, itemId, clientPatch, version, str
 var MymeClient = class {
   transport;
   defaultConflictStrategy;
+  defaultOnConflictAutoMerge;
   apiBaseUrl;
   cdnBaseUrl;
   constructor(config) {
@@ -231,6 +284,7 @@ var MymeClient = class {
       timeoutMs: config.timeoutMs
     });
     this.defaultConflictStrategy = config.conflictStrategy ?? "auto";
+    this.defaultOnConflictAutoMerge = config.onConflictAutoMerge;
     this.cdnBaseUrl = config.cdnBaseUrl;
   }
   // ---- Items ----
@@ -267,20 +321,45 @@ var MymeClient = class {
         }
       );
     },
+    /**
+     * List items with their extension namespaces hydrated inline. Avoids
+     * the N+1 pattern of listing then calling `GET /items/:id/extensions`
+     * per item. Extensions are filtered by the caller's permissions —
+     * admins see every namespace, members see what they can read or
+     * write.
+     */
+    listWithExtensions: async (filters) => {
+      return this.transport.request(
+        "GET",
+        "/items",
+        {
+          query: {
+            ...filters,
+            include: "extensions"
+          }
+        }
+      );
+    },
     update: async (id, properties, options) => {
       let version = options?.version;
-      if (version === void 0) {
+      let type = options?.type;
+      if (version === void 0 || type === void 0) {
         const item = await this.items.get(id);
-        version = item.version;
+        version ??= item.version;
+        type ??= item.type;
       }
       const strategy = options?.conflict ?? this.defaultConflictStrategy;
+      const onAutoMerge = options?.onAutoMerge ?? this.defaultOnConflictAutoMerge;
       return handleConflictUpdate(
         this.transport,
         id,
+        type,
         properties,
         version,
         strategy,
-        options?.resolve
+        options?.resolve,
+        options?.library,
+        onAutoMerge
       );
     },
     delete: async (id) => {
@@ -366,6 +445,15 @@ var MymeClient = class {
         `/items/${itemId}/tags/${encodeURIComponent(tag)}`
       );
     },
+    /**
+     * Enumerate the distinct set of tags in use across items the caller can
+     * read. Tenant-scoped, type-permission scoped, excludes trashed items.
+     * Returns tags with usage counts, sorted by count desc then tag asc.
+     */
+    listTags: async () => {
+      const res = await this.transport.request("GET", "/metadata/tags");
+      return res.tags;
+    },
     getExtensions: async (itemId, namespace) => {
       if (namespace) {
         const res2 = await this.transport.request(
@@ -403,6 +491,23 @@ var MymeClient = class {
   }
   // ---- Edges ----
   edges = {
+    /**
+     * Global edge listing across the tenant, filtered by edge type
+     * (comma-separated string or array of type ids). Use this when you
+     * need "all edges of type X" — replaces the walk-every-item
+     * pattern. Per-target filters live on `listFromSource` /
+     * `listToTarget`.
+     */
+    list: async (filters) => {
+      const edgeType = Array.isArray(filters?.edge_type) ? filters.edge_type.join(",") : filters?.edge_type;
+      return this.transport.request("GET", "/edges", {
+        query: {
+          ...edgeType && { edge_type: edgeType },
+          ...filters?.limit !== void 0 && { limit: filters.limit },
+          ...filters?.cursor && { cursor: filters.cursor }
+        }
+      });
+    },
     /** Create a single edge. Server enforces cardinality / type
      *  constraints / cycle prevention; throws on violation. */
     create: async (input) => {

package/package.json

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