@mymehq/sdk 5.1.0 → 5.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
-export { ApiKey, ConflictSnapshot, CreateItemInput, CreateKeyInput, Item, ItemState, MergePolicy, MergeStrategy, Metadata, PaginatedResult, Profile, SearchResult, TypeSchema, UpdateKeyInput, UpdateProfileInput, Version } 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, Tenant, TenantActivityEntry, TenantMetrics, Profile, UpdateProfileInput } from '@mymehq/shared';
+export { ApiKey, ConflictSnapshot, CreateItemInput, CreateKeyInput, Item, ItemState, MergePolicy, MergeStrategy, Metadata, PaginatedResult, Profile, SearchResult, Tenant, TenantActivityEntry, TenantMetrics, TenantQuota, TenantStatus, TypeSchema, UpdateKeyInput, UpdateProfileInput, Version } from '@mymehq/shared';
 
 /**
  * Conflict resolution strategy for item updates.
@@ -178,6 +178,21 @@ interface SearchFilters {
 interface MetadataInput {
     tags?: string[];
 }
+/**
+ * Compact API-key summary returned by the admin keys-list route
+ * (T-117). The full `ApiKey` shape carries permission maps; the
+ * operator surface deliberately surfaces only the identifying fields +
+ * timestamps needed for emergency revocation.
+ */
+interface TenantApiKeySummary {
+    id: string;
+    label: string;
+    source: string;
+    role: string;
+    is_platform: boolean;
+    created_at: string;
+    last_used_at: string | null;
+}
 /** One item to create or upsert in a `POST /items/bulk` call. Shape is
  *  `CreateItemInput` plus compact outbound-only inline `edges`. */
 interface BulkItemInput {
@@ -199,6 +214,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 +470,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
@@ -648,6 +742,54 @@ declare class MymeClient {
             }) => Promise<TenantQuota>;
         };
     };
+    /**
+     * Operator-level admin surface — the `my admin` CLI command tree's
+     * backing endpoints. Every method requires a platform-admin key
+     * (`is_platform: true`). Non-platform credentials get a `403
+     * forbidden`; render `"this command requires a platform-admin key"`
+     * in CLI / UI layers.
+     *
+     * Quota read/write is intentionally NOT duplicated here — it lives on
+     * `client.tenants.quotas.{getById, set}` and is already platform-
+     * admin-gated. The admin namespace mirrors what the CLI's `my admin`
+     * tree exposes; quotas are reached via the existing tenants surface.
+     */
+    readonly admin: {
+        tenants: {
+            /** List every tenant in the instance with current status. */
+            list: () => Promise<Tenant[]>;
+            /**
+             * Single tenant + per-tenant quota overrides + the most-recent
+             * `system.activity` items for the tenant (`null` quotas when no
+             * override is configured; quota fields then resolve to instance
+             * defaults).
+             */
+            show: (tenantId: string) => Promise<{
+                tenant: Tenant;
+                quotas: TenantQuota | null;
+                recent_activity: TenantActivityEntry[];
+            }>;
+            /**
+             * Flip the tenant's status to `'suspended'`. Future non-GET
+             * requests from credentials in the tenant return HTTP 403
+             * `tenant_suspended`. Reads pass through; platform-admin keys
+             * bypass. Idempotent.
+             */
+            suspend: (tenantId: string) => Promise<Tenant>;
+            /** Reverse of `suspend`. Idempotent. */
+            unsuspend: (tenantId: string) => Promise<Tenant>;
+            /**
+             * Per-tenant usage snapshot — item count by state, blob count
+             * and total bytes, custom-type count, plus recent activity.
+             */
+            metrics: (tenantId: string) => Promise<TenantMetrics>;
+        };
+        keys: {
+            /** Active (non-revoked) keys for the named tenant. Operator
+             *  surface for emergency revocation — pair with `client.keys.revoke`. */
+            list: (tenantId: string) => Promise<TenantApiKeySummary[]>;
+        };
+    };
     /**
      * The calling user's profile. `system.profile` is a virtual type —
      * served by a dedicated endpoint over the `users` table joined to
@@ -815,4 +957,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, type TenantApiKeySummary, 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
@@ -1014,6 +1129,77 @@ var MymeClient = class {
       }
     }
   };
+  // ---- Admin (T-117) ----
+  /**
+   * Operator-level admin surface — the `my admin` CLI command tree's
+   * backing endpoints. Every method requires a platform-admin key
+   * (`is_platform: true`). Non-platform credentials get a `403
+   * forbidden`; render `"this command requires a platform-admin key"`
+   * in CLI / UI layers.
+   *
+   * Quota read/write is intentionally NOT duplicated here — it lives on
+   * `client.tenants.quotas.{getById, set}` and is already platform-
+   * admin-gated. The admin namespace mirrors what the CLI's `my admin`
+   * tree exposes; quotas are reached via the existing tenants surface.
+   */
+  admin = {
+    tenants: {
+      /** List every tenant in the instance with current status. */
+      list: async () => {
+        const res = await this.transport.request(
+          "GET",
+          "/admin/tenants"
+        );
+        return res.data;
+      },
+      /**
+       * Single tenant + per-tenant quota overrides + the most-recent
+       * `system.activity` items for the tenant (`null` quotas when no
+       * override is configured; quota fields then resolve to instance
+       * defaults).
+       */
+      show: async (tenantId) => {
+        return this.transport.request("GET", `/admin/tenants/${encodeURIComponent(tenantId)}`);
+      },
+      /**
+       * Flip the tenant's status to `'suspended'`. Future non-GET
+       * requests from credentials in the tenant return HTTP 403
+       * `tenant_suspended`. Reads pass through; platform-admin keys
+       * bypass. Idempotent.
+       */
+      suspend: async (tenantId) => {
+        return this.transport.request(
+          "POST",
+          `/admin/tenants/${encodeURIComponent(tenantId)}/suspend`
+        );
+      },
+      /** Reverse of `suspend`. Idempotent. */
+      unsuspend: async (tenantId) => {
+        return this.transport.request(
+          "POST",
+          `/admin/tenants/${encodeURIComponent(tenantId)}/unsuspend`
+        );
+      },
+      /**
+       * Per-tenant usage snapshot — item count by state, blob count
+       * and total bytes, custom-type count, plus recent activity.
+       */
+      metrics: async (tenantId) => {
+        return this.transport.request(
+          "GET",
+          `/admin/tenants/${encodeURIComponent(tenantId)}/metrics`
+        );
+      }
+    },
+    keys: {
+      /** Active (non-revoked) keys for the named tenant. Operator
+       *  surface for emergency revocation — pair with `client.keys.revoke`. */
+      list: async (tenantId) => {
+        const res = await this.transport.request("GET", `/admin/tenants/${encodeURIComponent(tenantId)}/keys`);
+        return res.data;
+      }
+    }
+  };
   // ---- Profile (T-074) ----
   /**
    * The calling user's profile. `system.profile` is a virtual type —

package/package.json

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