@mymehq/sdk 5.1.0 → 5.2.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { MergeStrategy, ConflictSnapshot, MergePolicy, ItemState, Tier, Item, CreateItemInput, PaginatedResult, ItemWithMetadata, Version, Edge, Metadata, SearchResult, CreateEdgeInput, EdgeTypeSchema, TypeSchema, CreateKeyInput, ApiKey, UpdateKeyInput, CreateWebhookInput, Webhook, UpdateWebhookInput, WebhookDelivery, ConnectionInstallResult, ConnectionUninstallResult, PreviewEventRequest, PreviewEventResult, TenantConfig, TenantQuota, Profile, UpdateProfileInput } from '@mymehq/shared';
+import { MergeStrategy, ConflictSnapshot, MergePolicy, ItemState, Tier, CreateItemInput, Item, PaginatedResult, ItemWithMetadata, Version, Edge, Metadata, SearchResult, CreateEdgeInput, EdgeTypeSchema, TypeSchema, CreateKeyInput, ApiKey, UpdateKeyInput, CreateWebhookInput, Webhook, UpdateWebhookInput, WebhookDelivery, ConnectionInstallResult, ConnectionUninstallResult, PreviewEventRequest, PreviewEventResult, TenantConfig, TenantQuota, Profile, UpdateProfileInput } from '@mymehq/shared';
 export { ApiKey, ConflictSnapshot, CreateItemInput, CreateKeyInput, Item, ItemState, MergePolicy, MergeStrategy, Metadata, PaginatedResult, Profile, SearchResult, TypeSchema, UpdateKeyInput, UpdateProfileInput, Version } from '@mymehq/shared';
 
 /**
@@ -199,6 +199,57 @@ interface BulkItemInput {
     edges?: Record<string, string[]>;
 }
 type BulkMode = "upsert" | "create_only";
+/**
+ * Input to `client.items.createWithAttachments(...)` (T-100). Wraps the
+ * existing blob-upload + `items.bulk` pattern: upload each attachment's
+ * blob, then issue one atomic bulk call containing the host item and the
+ * `core.file.*` items with inline `attached-to` edges from each
+ * attachment back to the host.
+ */
+interface CreateWithAttachmentsInput {
+    /** The host item — the thing the attachments are attached *to* (note,
+     *  message, etc.). May carry an explicit `id` for client-minted UUIDs
+     *  and arbitrary `edges` of its own (passed through unchanged into the
+     *  bulk payload). */
+    item: CreateItemInput & {
+        id?: string;
+        edges?: Record<string, string[]>;
+    };
+    /** Attachments in caller-passed order. The returned `attachments`
+     *  array preserves the same order. Empty arrays are valid: the helper
+     *  still issues one `items.bulk` call with just the host item. */
+    attachments: CreateWithAttachmentsAttachment[];
+    /** Edge type from each attachment back to the host. Defaults to
+     *  `"attached-to"` (the canonical attachment edge — T-108). Override
+     *  for app-specific semantics like `"cover-image"`. */
+    edgeType?: string;
+}
+interface CreateWithAttachmentsAttachment {
+    /** Type id, e.g. `"core.file.image"`. */
+    type: string;
+    /** Raw blob bytes. Uploaded via `POST /blobs`. */
+    blob: Uint8Array | ArrayBuffer;
+    /** Sent as the `Content-Type` of the blob upload. Stamped onto the
+     *  attachment item's `mime_type` property automatically. */
+    mimeType: string;
+    /** Caller-supplied properties for this attachment item (e.g. `width`
+     *  and `height` for `core.file.image`). The helper auto-fills
+     *  `blob_ref` (= upload hash) and `mime_type` after upload; do not
+     *  pre-populate them. */
+    properties?: Record<string, unknown>;
+    /** Optional additional edges on the attachment item. The helper
+     *  appends its own `[edgeType]: [hostId]` entry; if you pass a value
+     *  for the same `edgeType`, your ids are merged with the host id
+     *  (helper-added edges are additive, never stripping). */
+    edges?: Record<string, string[]>;
+    /** Explicit attachment id (defaults to a client-minted UUIDv7). */
+    id?: string;
+}
+interface CreateWithAttachmentsResult {
+    host: Item;
+    /** Attachment items in the same order as `input.attachments`. */
+    attachments: Item[];
+}
 interface BulkInput {
     items: BulkItemInput[];
     /** Default: `"upsert"`. */
@@ -404,6 +455,34 @@ declare class MymeClient {
          * `atomic: true` (default) rolls back the whole batch on any failure.
          */
         bulk: (input: BulkInput) => Promise<BulkResult>;
+        /**
+         * Create a host item plus a set of attached `core.file.*` items in
+         * one call (T-100). Wraps the existing `blobs.upload` + `items.bulk`
+         * primitives: each attachment's blob is uploaded concurrently, then a
+         * single atomic bulk call writes the host and the attachments
+         * together with inline `attached-to` edges from each attachment back
+         * to the host (matching T-108's spec direction).
+         *
+         * **Partial-failure contract.** Blob uploads run concurrently via
+         * `Promise.all`. On upload failure, throws with the failing
+         * attachment's index in the message. Successfully-uploaded blobs are
+         * not cleaned up; the server's CAS dedupe (`blob_ref` is the
+         * content hash) makes orphaned uploads cost-trivial — the same bytes
+         * uploaded later resolve to the same hash. Callers are expected to
+         * retry the whole call rather than reason about partial state.
+         *
+         * **Empty `attachments`** is valid and supported: the helper still
+         * issues one `items.bulk` call with just the host item, no blob
+         * uploads, no auto-edges. Lets callers use this method as a uniform
+         * entry point regardless of whether attachments are present.
+         *
+         * **Caller-provided edges co-exist with the auto-`attached-to`
+         * edges.** If the caller passes edges on the host item, they're
+         * passed through unchanged. If the caller passes edges on an
+         * attachment item with the same `edgeType` key, the helper's host id
+         * is appended to that array (additive, never strip-and-replace).
+         */
+        createWithAttachments: (input: CreateWithAttachmentsInput) => Promise<CreateWithAttachmentsResult>;
         /**
          * Apply one action to every item matching a filter. Six actions
          * discriminated on `action`. Purge is admin-only and requires
@@ -815,4 +894,4 @@ interface VerifyWebhookSignatureInput {
  */
 declare function verifyWebhookSignature(input: VerifyWebhookSignatureInput): WebhookVerifyResult;
 
-export { type BulkActionErrorEntry, type BulkActionFilter, type BulkActionInput, type BulkActionResult, type BulkEdgeInput, type BulkEdgeInputItem, type BulkEdgeResult, type BulkEdgeResultEntry, 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, defineType, verifyWebhookSignature };
+export { type BulkActionErrorEntry, type BulkActionFilter, type BulkActionInput, type BulkActionResult, type BulkEdgeInput, type BulkEdgeInputItem, type BulkEdgeResult, type BulkEdgeResultEntry, 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, type CreateWithAttachmentsAttachment, type CreateWithAttachmentsInput, type CreateWithAttachmentsResult, ForbiddenError, type ItemWithExtensions, type ListFilters, type MetadataInput, MymeClient, MymeError, NotFoundError, type SearchFilters, UnauthorizedError, type UpdateOptions, ValidationError, type VerifyWebhookSignatureInput, type WebhookVerifyReason, type WebhookVerifyResult, defineType, verifyWebhookSignature };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/client.ts
+import { generateId } from "@mymehq/shared";
+
 // src/errors.ts
 var MymeError = class extends Error {
   code;
@@ -525,6 +528,118 @@ var MymeClient = class {
         body: input
       });
     },
+    /**
+     * Create a host item plus a set of attached `core.file.*` items in
+     * one call (T-100). Wraps the existing `blobs.upload` + `items.bulk`
+     * primitives: each attachment's blob is uploaded concurrently, then a
+     * single atomic bulk call writes the host and the attachments
+     * together with inline `attached-to` edges from each attachment back
+     * to the host (matching T-108's spec direction).
+     *
+     * **Partial-failure contract.** Blob uploads run concurrently via
+     * `Promise.all`. On upload failure, throws with the failing
+     * attachment's index in the message. Successfully-uploaded blobs are
+     * not cleaned up; the server's CAS dedupe (`blob_ref` is the
+     * content hash) makes orphaned uploads cost-trivial — the same bytes
+     * uploaded later resolve to the same hash. Callers are expected to
+     * retry the whole call rather than reason about partial state.
+     *
+     * **Empty `attachments`** is valid and supported: the helper still
+     * issues one `items.bulk` call with just the host item, no blob
+     * uploads, no auto-edges. Lets callers use this method as a uniform
+     * entry point regardless of whether attachments are present.
+     *
+     * **Caller-provided edges co-exist with the auto-`attached-to`
+     * edges.** If the caller passes edges on the host item, they're
+     * passed through unchanged. If the caller passes edges on an
+     * attachment item with the same `edgeType` key, the helper's host id
+     * is appended to that array (additive, never strip-and-replace).
+     */
+    createWithAttachments: async (input) => {
+      const edgeType = input.edgeType ?? "attached-to";
+      const hostId = input.item.id ?? generateId();
+      const uploadResults = await Promise.all(
+        input.attachments.map(async (att, idx) => {
+          try {
+            return await this.blobs.upload(att.blob, att.mimeType);
+          } catch (err) {
+            throw new MymeError(
+              "blob_upload_failed",
+              `createWithAttachments: blob upload failed for attachments[${String(idx)}] (type=${att.type}): ${err instanceof Error ? err.message : String(err)}`,
+              502
+            );
+          }
+        })
+      );
+      const hostBulkItem = {
+        ...input.item,
+        id: hostId
+      };
+      const attachmentIds = [];
+      const attachmentBulkItems = input.attachments.map(
+        (att, idx) => {
+          const attachmentId = att.id ?? generateId();
+          attachmentIds.push(attachmentId);
+          const upload = uploadResults[idx];
+          if (!upload) {
+            throw new MymeError(
+              "internal_error",
+              `createWithAttachments: upload result missing for attachments[${String(idx)}]`,
+              500
+            );
+          }
+          const callerEdges = att.edges ?? {};
+          const callerSameType = callerEdges[edgeType] ?? [];
+          const mergedEdges = {
+            ...callerEdges,
+            [edgeType]: [...callerSameType, hostId]
+          };
+          return {
+            id: attachmentId,
+            type: att.type,
+            properties: {
+              ...att.properties ?? {},
+              blob_ref: upload.hash,
+              mime_type: att.mimeType
+            },
+            edges: mergedEdges
+          };
+        }
+      );
+      const bulkResult = await this.items.bulk({
+        items: [hostBulkItem, ...attachmentBulkItems],
+        mode: "create_only",
+        atomic: true
+      });
+      const errored = bulkResult.results.find((r) => r.outcome === "errored");
+      if (errored) {
+        throw new MymeError(
+          errored.error?.code ?? "bulk_failed",
+          `createWithAttachments: bulk write failed at index ${String(errored.index)}: ${errored.error?.message ?? errored.reason ?? "unknown"}`,
+          400
+        );
+      }
+      const skipped = bulkResult.results.find((r) => r.outcome === "skipped");
+      if (skipped) {
+        throw new MymeError(
+          "duplicate_id",
+          `createWithAttachments: bulk write skipped at index ${String(skipped.index)} (reason: ${skipped.reason ?? "unknown"}). The helper requires fresh ids \u2014 if you passed an explicit \`item.id\`, it must not already exist.`,
+          409
+        );
+      }
+      const hydrated = await Promise.all(
+        [hostId, ...attachmentIds].map((id) => this.items.get(id))
+      );
+      const [host, ...attachments] = hydrated;
+      if (!host) {
+        throw new MymeError(
+          "internal_error",
+          "createWithAttachments: host hydration returned no item",
+          500
+        );
+      }
+      return { host, attachments };
+    },
     /**
      * Apply one action to every item matching a filter. Six actions
      * discriminated on `action`. Purge is admin-only and requires

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mymehq/sdk",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",