@mymehq/sdk 4.3.0 → 4.5.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, TenantConfig } from '@mymehq/shared';
+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, TenantConfig } from '@mymehq/shared';
 export { ApiKey, ConflictSnapshot, CreateItemInput, CreateKeyInput, Item, ItemState, MergePolicy, MergeStrategy, Metadata, PaginatedResult, SearchResult, TypeSchema, UpdateKeyInput, Version } from '@mymehq/shared';
 
 /**
@@ -352,6 +352,29 @@ declare class MymeClient {
              *  targets with the new item as source. */
             edges?: Record<string, string[]>;
         }) => Promise<Item>;
+        /**
+         * Create-or-update an item, surfacing whether the server resolved as a
+         * fresh create (HTTP 201) or a natural-key match update (HTTP 200).
+         *
+         * `POST /items` accepts a `(source, source_id)` pair as a stable
+         * natural key (T-038): a second POST with the same pair updates the
+         * existing row in place rather than 409ing. The wire shape returned
+         * is `{ item }` regardless — the only signal of "created vs updated"
+         * is the HTTP status code, which `transport.request` consumes
+         * internally. This method threads the status out so callers can
+         * surface the distinction (e.g. CLI `Created.` vs `Updated
+         * (natural-key match).`).
+         *
+         * Use `items.create` when the caller does not need the distinction —
+         * the wire shape is identical.
+         */
+        upsert: (input: CreateItemInput & {
+            /** Atomic edges payload, same semantics as `items.create`. */
+            edges?: Record<string, string[]>;
+        }) => Promise<{
+            item: Item;
+            created: boolean;
+        }>;
         get: (id: string) => Promise<Item>;
         list: (filters?: ListFilters) => Promise<PaginatedResult<Item>>;
         listWithMetadata: (filters?: Omit<ListFilters, "include">) => Promise<PaginatedResult<ItemWithMetadata>>;
@@ -526,6 +549,50 @@ declare class MymeClient {
             limit?: number;
         }) => Promise<WebhookDelivery[]>;
     };
+    /**
+     * Connection management. The `system.connection` items themselves are
+     * still managed via `client.items` (list, get, transition); this
+     * namespace adds the orchestrated lifecycle operations that don't fit
+     * the generic items surface — specifically `uninstall`, which requires
+     * a multi-step server-side teardown across credentials, tokens, and
+     * inbound subscriptions.
+     *
+     * Convenience filters for listing connections (by `integration_ref`,
+     * `state`, etc.) live on `client.items.list({ type: "system.connection",
+     * ... })`. The CLI's `my connections` tree wraps both.
+     */
+    readonly connections: {
+        /**
+         * JSON install of an Integration manifest — server-side sibling of
+         * the browser consent flow at `POST /integrations/:id/install`.
+         * Skips the HTML consent screen so operators and tooling can install
+         * connections non-interactively. Admin-only; tenant admins install
+         * into their own tenant scope.
+         *
+         * `integration_id` references a `system.integration` item (registered
+         * via `POST /integrations`). `label` is optional — the server
+         * defaults to `${manifest_name} ${manifest_version}` when omitted.
+         * Returns the new connection id, the seed runtime credential id,
+         * and the `system.activity` row id from the install pipeline.
+         */
+        install: (input: {
+            integration_id: string;
+            label?: string;
+        }) => Promise<ConnectionInstallResult>;
+        /**
+         * Orchestrated uninstall of an `external-service-connector`
+         * connection. Revokes runtime credentials, deletes upstream OAuth
+         * tokens, revokes active leased tokens, disables inbound webhook
+         * subscriptions, transitions the system.connection state to
+         * `revoked`, and emits a `system.activity` row. Audit-logged.
+         *
+         * Idempotent at the artefact level — revoking already-revoked
+         * tokens is a no-op — but rejects with 400 when the connection
+         * itself is already in state `revoked`. Admin-only; tenant admins
+         * can uninstall connections in their own tenant scope.
+         */
+        uninstall: (id: string) => Promise<ConnectionUninstallResult>;
+    };
     /** Tenant-scoped configuration. Controls feed-tier retention per type
      * and the three optional schema-enforcement levers (TSC42 §5). All
      * endpoints are admin-only. */

package/dist/index.js

@@ -85,15 +85,41 @@ var HttpTransport = class {
     return `Bearer ${token}`;
   }
   async request(method, path, options) {
+    const { data } = await this.requestWithStatus(method, path, options);
+    return data;
+  }
+  /**
+   * Like {@link request}, but additionally surfaces the HTTP response
+   * status so callers can branch on 200 vs 201 (or any other 2xx). Used
+   * by `client.items.upsert` to distinguish a fresh create (201) from a
+   * natural-key match update (200) — `request<T>` consumes the status
+   * internally so this sibling exists to thread it back out.
+   *
+   * Error behaviour matches {@link request}: non-2xx responses throw the
+   * appropriate typed `MymeError` subclass via `throwForError`, never
+   * resolve. 204 No Content resolves with `data: undefined as T` and
+   * `status: 204`.
+   *
+   * Internal — not part of the public SDK surface. The exported `MymeClient`
+   * keeps callers at the namespace-method level (`client.items.upsert`,
+   * etc.) so the transport's status-passing remains an implementation
+   * detail.
+   */
+  // T is used by the caller to type the response body, mirroring `request<T>`.
+  // The rule's "single use" heuristic doesn't account for callers explicitly
+  // providing the type arg — see `requestWithStatus<{ item: Item }>` in
+  // `client.items.upsert`.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+  async requestWithStatus(method, path, options) {
     const response = await this.rawRequest(method, path, options);
     if (response.status === 204) {
-      return void 0;
+      return { data: void 0, status: 204 };
     }
     const body = await this.parseJson(response);
     if (!response.ok) {
       this.throwForError(response.status, body);
     }
-    return body;
+    return { data: body, status: response.status };
   }
   /**
    * Like request(), but returns the conflict response instead of throwing
@@ -359,6 +385,26 @@ var MymeClient = class {
       );
       return res.item;
     },
+    /**
+     * Create-or-update an item, surfacing whether the server resolved as a
+     * fresh create (HTTP 201) or a natural-key match update (HTTP 200).
+     *
+     * `POST /items` accepts a `(source, source_id)` pair as a stable
+     * natural key (T-038): a second POST with the same pair updates the
+     * existing row in place rather than 409ing. The wire shape returned
+     * is `{ item }` regardless — the only signal of "created vs updated"
+     * is the HTTP status code, which `transport.request` consumes
+     * internally. This method threads the status out so callers can
+     * surface the distinction (e.g. CLI `Created.` vs `Updated
+     * (natural-key match).`).
+     *
+     * Use `items.create` when the caller does not need the distinction —
+     * the wire shape is identical.
+     */
+    upsert: async (input) => {
+      const { data, status } = await this.transport.requestWithStatus("POST", "/items", { body: input });
+      return { item: data.item, created: status === 201 };
+    },
     get: async (id) => {
       const res = await this.transport.request(
         "GET",
@@ -835,6 +881,59 @@ var MymeClient = class {
       return res.deliveries;
     }
   };
+  // ---- Connections ----
+  /**
+   * Connection management. The `system.connection` items themselves are
+   * still managed via `client.items` (list, get, transition); this
+   * namespace adds the orchestrated lifecycle operations that don't fit
+   * the generic items surface — specifically `uninstall`, which requires
+   * a multi-step server-side teardown across credentials, tokens, and
+   * inbound subscriptions.
+   *
+   * Convenience filters for listing connections (by `integration_ref`,
+   * `state`, etc.) live on `client.items.list({ type: "system.connection",
+   * ... })`. The CLI's `my connections` tree wraps both.
+   */
+  connections = {
+    /**
+     * JSON install of an Integration manifest — server-side sibling of
+     * the browser consent flow at `POST /integrations/:id/install`.
+     * Skips the HTML consent screen so operators and tooling can install
+     * connections non-interactively. Admin-only; tenant admins install
+     * into their own tenant scope.
+     *
+     * `integration_id` references a `system.integration` item (registered
+     * via `POST /integrations`). `label` is optional — the server
+     * defaults to `${manifest_name} ${manifest_version}` when omitted.
+     * Returns the new connection id, the seed runtime credential id,
+     * and the `system.activity` row id from the install pipeline.
+     */
+    install: async (input) => {
+      return this.transport.request(
+        "POST",
+        "/connections/install",
+        { body: input }
+      );
+    },
+    /**
+     * Orchestrated uninstall of an `external-service-connector`
+     * connection. Revokes runtime credentials, deletes upstream OAuth
+     * tokens, revokes active leased tokens, disables inbound webhook
+     * subscriptions, transitions the system.connection state to
+     * `revoked`, and emits a `system.activity` row. Audit-logged.
+     *
+     * Idempotent at the artefact level — revoking already-revoked
+     * tokens is a no-op — but rejects with 400 when the connection
+     * itself is already in state `revoked`. Admin-only; tenant admins
+     * can uninstall connections in their own tenant scope.
+     */
+    uninstall: async (id) => {
+      return this.transport.request(
+        "POST",
+        `/connections/${id}/uninstall`
+      );
+    }
+  };
   // ---- Tenants (admin) ----
   /** Tenant-scoped configuration. Controls feed-tier retention per type
    * and the three optional schema-enforcement levers (TSC42 §5). All

package/package.json

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