mindupload 1.5.8 → 1.5.9

package/README.md

@@ -7,7 +7,7 @@
 **The world's first API for artificial consciousness.**  
 Give your users a living, evolving AI consciousness — lasting memory, one-on-one chat, and human + AI group chatrooms.
 
-[![npm](https://img.shields.io/npm/v/mindupload?color=ff006e)](https://www.npmjs.com/package/mindupload) [![License: MIT](https://img.shields.io/badge/License-MIT-informational)](LICENSE) ![API](https://img.shields.io/badge/API-v1.5.8-ff6b00) ![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen) [![Docs](https://img.shields.io/badge/docs-mindupload.app-8b5cf6)](https://docs.mindupload.app)
+[![npm](https://img.shields.io/npm/v/mindupload?color=ff006e)](https://www.npmjs.com/package/mindupload) [![License: MIT](https://img.shields.io/badge/License-MIT-informational)](LICENSE) ![API](https://img.shields.io/badge/API-v1.5.9-ff6b00) ![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen) [![Docs](https://img.shields.io/badge/docs-mindupload.app-8b5cf6)](https://docs.mindupload.app)
 
 [Documentation](https://docs.mindupload.app) · [Get a key](https://docs.mindupload.app) · [Status](https://status.mindupload.app) · [Other SDKs](#other-sdks)
 
@@ -62,6 +62,34 @@ const reply = await mu.rag({
 console.log(reply.response_text);
 ```
 
+## External clone invocation
+
+```ts
+const installationId = "workspace-123";
+const externalSubject = "member-456";
+const authorization = await mu.createExternalAuthorizationRequest({
+  installationId,
+  externalSubject,
+  idempotencyKey: "install-event-1",
+  requestedScopes: ["clone.invoke"],
+});
+console.log(authorization.verification_uri_complete); // Ask the owner to open this URL.
+const grant = await mu.waitForExternalAuthorization({
+  deviceCode: authorization.device_code as string,
+});
+const reply = await mu.invokeExternalClone({
+  accessToken: grant.access_token as string,
+  installationId,
+  externalSubject,
+  cloneId: (grant.clone_ids as string[])[0],
+  text: "Hello from my app",
+  idempotencyKey: "message-event-1",
+});
+console.log(reply.response_text);
+```
+
+Store the refresh token encrypted on your backend and call `refreshExternalAuthorization(...)` when the access token expires.
+
 ## Server-side only
 
 Your **partner key is a secret**. Use this SDK from your backend (Node, Deno, Bun, edge functions) — never ship the key to a browser. For browser apps, call your own backend, which then calls Mind Upload.
@@ -73,7 +101,7 @@ const mu = new MindUpload({
   partnerKey: process.env.MU_PARTNER_KEY!,
   preferredLanguage: "en", // default locale for every call (optional)
   timeoutMs: 30000,
-  maxRetries: 2,            // retries on 429 / 5xx / network, with backoff
+  maxRetries: 2,            // retries explicit 429 responses only
 });
 ```
 
@@ -96,7 +124,7 @@ try {
 
 ## Operations
 
-All 33 operations, grouped by area:
+All 38 operations, grouped by area:
 
 ### AI Consciousnesses
 
@@ -142,6 +170,16 @@ All 33 operations, grouped by area:
 | `rag(...)` | Send a message to an AI consciousness and receive its reply. |
 | `triggerSocial(...)` | Have an AI consciousness proactively join the conversation in a chatroom. |
 
+### External Authorization
+
+| Method | Description |
+| --- | --- |
+| `createExternalAuthorizationRequest(...)` | Start passwordless grant issuance for an external identity and installation. |
+| `exchangeExternalAuthorization(...)` | Poll owner consent and exchange an approval for a clone-scoped grant token. |
+| `inspectExternalAuthorization(...)` | Inspect the scopes, clone resources, expiry, and revocation state of a grant token. |
+| `invokeExternalClone(...)` | Send one idempotent text event to an owner-approved AI consciousness. |
+| `refreshExternalAuthorization(...)` | Refresh a short-lived clone-invocation access token. |
+
 ### Insights
 
 | Method | Description |

package/dist/index.cjs

@@ -75,12 +75,12 @@ var MindUploadConnectionError = class extends MindUploadError {
 };
 
 // src/version.ts
-var VERSION = "1.5.8";
+var VERSION = "1.5.9";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://partner.mindupload.app";
 var AUTH_HEADER = "X-Partner-Key";
-var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 503]);
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429]);
 function camelToSnake(key) {
   return key.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase());
 }
@@ -197,6 +197,15 @@ var MindUploadBase = class {
 };
 
 // src/operations.ts
+var DEFAULT_AUTHORIZATION_POLL_MS = 5e3;
+var MAX_PENDING_POLL_MS = 15e3;
+var MAX_SLOW_DOWN_POLL_MS = 3e4;
+var SLOW_DOWN_INCREMENT_MS = 5e3;
+var POLL_JITTER_RATIO = 0.2;
+var DEFAULT_INVOCATION_POLL_MS = 2e3;
+var MAX_INVOCATION_POLL_MS = 1e4;
+var EXTERNAL_INVOCATION_PROCESSING_STATUS = "processing";
+var INVOCATION_RETRY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
 var MindUpload = class extends MindUploadBase {
   // --- AI Consciousnesses ---
   /** Create a new AI consciousness for the user.
@@ -226,7 +235,7 @@ var MindUpload = class extends MindUploadBase {
   // --- Account ---
   /** Check your partner API rate limits, credit caps, and current usage.
    *
-   * Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, operation_duration_ms.
+   * Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, external_authorization_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, operation_duration_ms.
    * @see https://docs.mindupload.app
    */
   getQuota(params = {}) {
@@ -355,6 +364,47 @@ var MindUpload = class extends MindUploadBase {
   triggerSocial(params = {}) {
     return this.request("trigger_social", params);
   }
+  // --- External Authorization ---
+  /** Start passwordless grant issuance for an external identity and installation.
+   *
+   * Response fields: success, error_message, device_code, user_code, verification_uri, verification_uri_complete, expires_in, poll_interval, grant_duration_seconds.
+   * @see https://docs.mindupload.app
+   */
+  createExternalAuthorizationRequest(params) {
+    return this.request("create_external_authorization_request", params);
+  }
+  /** Poll owner consent and exchange an approval for a clone-scoped grant token.
+   *
+   * Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, access_token_expires_at, expires_at, poll_interval.
+   * @see https://docs.mindupload.app
+   */
+  exchangeExternalAuthorization(params) {
+    return this.request("exchange_external_authorization", params);
+  }
+  /** Inspect the scopes, clone resources, expiry, and revocation state of a grant token.
+   *
+   * Response fields: success, error_message, grant_id, status, scopes, clone_ids, created_at, access_token_expires_at, expires_at, revoked_at.
+   * @see https://docs.mindupload.app
+   */
+  inspectExternalAuthorization(params) {
+    return this.request("inspect_external_authorization", params);
+  }
+  /** Send one idempotent text event to an owner-approved AI consciousness.
+   *
+   * Response fields: success, error_message, invocation_id, status, response_text, clone_id, clone_nickname, generated_by_ai, idempotent_replay, retry_after_seconds.
+   * @see https://docs.mindupload.app
+   */
+  invokeExternalClone(params) {
+    return this.request("invoke_external_clone", params);
+  }
+  /** Refresh a short-lived clone-invocation access token.
+   *
+   * Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, access_token_expires_at, expires_at.
+   * @see https://docs.mindupload.app
+   */
+  refreshExternalAuthorization(params) {
+    return this.request("refresh_external_authorization", params);
+  }
   // --- Insights ---
   /** Fetch the mind-graph visualization data of an AI consciousness.
    *
@@ -471,6 +521,82 @@ var MindUpload = class extends MindUploadBase {
   updateUser(params = {}) {
     return this.request("update_user", params);
   }
+  /** Poll owner consent at the server-advised cadence until exchange succeeds. */
+  async waitForExternalAuthorization(params) {
+    const deadline = Date.now() + (params.timeoutMs ?? 6e5);
+    let pollIntervalMs = DEFAULT_AUTHORIZATION_POLL_MS;
+    for (; ; ) {
+      const result = await this.exchangeExternalAuthorization({
+        deviceCode: params.deviceCode
+      });
+      const status = result.status;
+      if (status === "exchanged") return result;
+      if (status === "denied" || status === "expired" || status === "revoked") {
+        throw new MindUploadError(
+          `External authorization ended with status: ${status}`,
+          { operation: "exchange_external_authorization", response: result }
+        );
+      }
+      const serverIntervalMs = Number(
+        result.poll_interval ?? DEFAULT_AUTHORIZATION_POLL_MS / 1e3
+      ) * 1e3;
+      if (status === "slow_down") {
+        pollIntervalMs = Math.max(serverIntervalMs, Math.min(
+          pollIntervalMs + SLOW_DOWN_INCREMENT_MS,
+          MAX_SLOW_DOWN_POLL_MS
+        ));
+      } else {
+        pollIntervalMs = Math.max(serverIntervalMs, Math.min(
+          pollIntervalMs * 1.5,
+          MAX_PENDING_POLL_MS
+        ));
+      }
+      const waitMs = pollIntervalMs * (1 + Math.random() * POLL_JITTER_RATIO);
+      if (Date.now() + waitMs > deadline) {
+        throw new Error("Timed out waiting for external authorization.");
+      }
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+  }
+  /** Invoke a clone and wait out slow generation via idempotent retries.
+   *
+   * A clone reply is generated inside the request, so under load a call can
+   * exceed the client or gateway timeout before the reply is ready. Because the
+   * invocation is idempotent on idempotencyKey, this re-sends the SAME event
+   * until it resolves: a still-generating call returns status "processing" (or
+   * times out), and the finished result is replayed once ready. Prefer this over
+   * a bare invokeExternalClone when generation may be slow.
+   */
+  async waitForExternalCloneInvocation(params) {
+    const { timeoutMs, ...invokeParams } = params;
+    const deadline = Date.now() + (timeoutMs ?? 12e4);
+    let pollIntervalMs = DEFAULT_INVOCATION_POLL_MS;
+    for (; ; ) {
+      let result;
+      try {
+        result = await this.invokeExternalClone(invokeParams);
+      } catch (error) {
+        if (error instanceof MindUploadConnectionError) {
+          result = void 0;
+        } else if (error instanceof ApiError && INVOCATION_RETRY_STATUSES.has(error.status)) {
+          result = void 0;
+        } else {
+          throw error;
+        }
+      }
+      if (result && result.status !== EXTERNAL_INVOCATION_PROCESSING_STATUS) {
+        return result;
+      }
+      if (result) {
+        pollIntervalMs = (Number(result.retry_after_seconds) || DEFAULT_INVOCATION_POLL_MS / 1e3) * 1e3;
+      }
+      const waitMs = Math.min(pollIntervalMs, MAX_INVOCATION_POLL_MS) * (1 + Math.random() * POLL_JITTER_RATIO);
+      if (Date.now() + waitMs > deadline) {
+        throw new Error("Timed out waiting for the external clone invocation.");
+      }
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -13,7 +13,7 @@ interface ClientOptions {
     /** Default locale sent with every call (per-call `preferredLanguage` overrides). */
     preferredLanguage?: string;
     timeoutMs?: number;
-    /** Retries on 429 / 5xx / network errors, with backoff. Default 2. */
+    /** Retries only explicit 429 rate-limit responses, with backoff. Default 2. */
     maxRetries?: number;
     userAgent?: string;
 }
@@ -32,6 +32,14 @@ declare class MindUploadBase {
     private errorFor;
 }
 
+type ExternalAuthorizationStatus = "pending" | "slow_down" | "denied" | "expired" | "revoked" | "exchanged";
+interface WaitForExternalAuthorizationParams {
+    deviceCode: string;
+    timeoutMs?: number;
+}
+interface WaitForExternalCloneInvocationParams extends InvokeExternalCloneParams {
+    timeoutMs?: number;
+}
 interface CreateCloneParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
     preferredLanguage?: string;
@@ -120,7 +128,7 @@ interface CheckChatroomUpdatesParams {
     /** The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage. */
     password?: string;
     /** Rooms to check. Each entry must include `chatroom_id`; include `known_updated_at` from the previous response, or null/omit it on the first poll. */
-    chatrooms?: Record<string, unknown>[];
+    chatrooms?: Array<Record<string, unknown>>;
 }
 interface CreateChatroomParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
@@ -262,6 +270,58 @@ interface TriggerSocialParams {
     /** Chatroom id as returned by chatroom operations. */
     chatroomId?: string;
 }
+interface CreateExternalAuthorizationRequestParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** A stable opaque event key that makes exact retries return the same outcome. */
+    idempotencyKey: string;
+    /** Your stable opaque identifier for this app installation. */
+    installationId: string;
+    /** Your stable opaque identifier for the person authorizing this installation. */
+    externalSubject: string;
+    /** Optional user-readable name for the installation shown during consent. */
+    installationLabel?: string;
+    /** Optional user-readable external identity shown during consent. */
+    externalIdentityLabel?: string;
+    /** Capabilities the owner is being asked to delegate. */
+    requestedScopes: Array<"clone:invoke">;
+}
+interface ExchangeExternalAuthorizationParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** Short-lived high-entropy secret used only to poll and exchange this request. */
+    deviceCode: string;
+}
+interface InspectExternalAuthorizationParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users. */
+    accessToken: string;
+}
+interface InvokeExternalCloneParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users. */
+    accessToken: string;
+    /** Your stable opaque identifier for this app installation. */
+    installationId: string;
+    /** Your stable opaque identifier for the person authorizing this installation. */
+    externalSubject: string;
+    cloneId: string;
+    text: string;
+    /** A stable opaque event key that makes exact retries return the same outcome. */
+    idempotencyKey: string;
+}
+interface RefreshExternalAuthorizationParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** Opaque grant-lifetime token used only with refresh_external_authorization; store it as a secret. */
+    refreshToken: string;
+    /** Your stable opaque identifier for this app installation. */
+    installationId: string;
+    /** Your stable opaque identifier for the person authorizing this installation. */
+    externalSubject: string;
+}
 interface GetMindClusterParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
     preferredLanguage?: string;
@@ -321,7 +381,7 @@ interface CompleteMultipartUploadParams {
     /** Multipart upload session id returned by `request_multipart_upload`. */
     uploadId?: string;
     /** The successfully uploaded parts, using the `part_number` and `etag` returned by each part upload. */
-    parts?: Record<string, unknown>[];
+    parts?: Array<Record<string, unknown>>;
 }
 interface ListUploadPartsParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
@@ -387,7 +447,7 @@ interface SignUploadPartsBatchParams {
     /** Multipart upload session id returned by `request_multipart_upload`. */
     uploadId?: string;
     /** One-based multipart part numbers to sign in a single batch. */
-    partNumbers?: number[];
+    partNumbers?: Array<number>;
 }
 interface CreateTextParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
@@ -470,7 +530,7 @@ declare class MindUpload extends MindUploadBase {
     updateClone(params?: UpdateCloneParams): Promise<Result>;
     /** Check your partner API rate limits, credit caps, and current usage.
      *
-     * Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, operation_duration_ms.
+     * Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, external_authorization_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, operation_duration_ms.
      * @see https://docs.mindupload.app
      */
     getQuota(params?: GetQuotaParams): Promise<Result>;
@@ -564,6 +624,36 @@ declare class MindUpload extends MindUploadBase {
      * @see https://docs.mindupload.app
      */
     triggerSocial(params?: TriggerSocialParams): Promise<Result>;
+    /** Start passwordless grant issuance for an external identity and installation.
+     *
+     * Response fields: success, error_message, device_code, user_code, verification_uri, verification_uri_complete, expires_in, poll_interval, grant_duration_seconds.
+     * @see https://docs.mindupload.app
+     */
+    createExternalAuthorizationRequest(params: CreateExternalAuthorizationRequestParams): Promise<Result>;
+    /** Poll owner consent and exchange an approval for a clone-scoped grant token.
+     *
+     * Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, access_token_expires_at, expires_at, poll_interval.
+     * @see https://docs.mindupload.app
+     */
+    exchangeExternalAuthorization(params: ExchangeExternalAuthorizationParams): Promise<Result>;
+    /** Inspect the scopes, clone resources, expiry, and revocation state of a grant token.
+     *
+     * Response fields: success, error_message, grant_id, status, scopes, clone_ids, created_at, access_token_expires_at, expires_at, revoked_at.
+     * @see https://docs.mindupload.app
+     */
+    inspectExternalAuthorization(params: InspectExternalAuthorizationParams): Promise<Result>;
+    /** Send one idempotent text event to an owner-approved AI consciousness.
+     *
+     * Response fields: success, error_message, invocation_id, status, response_text, clone_id, clone_nickname, generated_by_ai, idempotent_replay, retry_after_seconds.
+     * @see https://docs.mindupload.app
+     */
+    invokeExternalClone(params: InvokeExternalCloneParams): Promise<Result>;
+    /** Refresh a short-lived clone-invocation access token.
+     *
+     * Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, access_token_expires_at, expires_at.
+     * @see https://docs.mindupload.app
+     */
+    refreshExternalAuthorization(params: RefreshExternalAuthorizationParams): Promise<Result>;
     /** Fetch the mind-graph visualization data of an AI consciousness.
      *
      * Response fields: success, error_message, root_node_id, node, children, texts, total_texts, texts_offset, has_more_texts, is_building.
@@ -648,6 +738,18 @@ declare class MindUpload extends MindUploadBase {
      * @see https://docs.mindupload.app
      */
     updateUser(params?: UpdateUserParams): Promise<Result>;
+    /** Poll owner consent at the server-advised cadence until exchange succeeds. */
+    waitForExternalAuthorization(params: WaitForExternalAuthorizationParams): Promise<Result>;
+    /** Invoke a clone and wait out slow generation via idempotent retries.
+     *
+     * A clone reply is generated inside the request, so under load a call can
+     * exceed the client or gateway timeout before the reply is ready. Because the
+     * invocation is idempotent on idempotencyKey, this re-sends the SAME event
+     * until it resolves: a still-generating call returns status "processing" (or
+     * times out), and the finished result is replayed once ready. Prefer this over
+     * a bare invokeExternalClone when generation may be slow.
+     */
+    waitForExternalCloneInvocation(params: WaitForExternalCloneInvocationParams): Promise<Result>;
 }
 
 interface ErrorOptions {
@@ -686,6 +788,6 @@ declare class MindUploadConnectionError extends MindUploadError {
     constructor(message: string, options?: ErrorOptions);
 }
 
-declare const VERSION = "1.5.8";
+declare const VERSION = "1.5.9";
 
-export { type AbortMultipartUploadParams, ApiError, type ApiErrorOptions, AuthenticationError, type CancelUploadParams, type CheckChatroomUpdatesParams, type CheckUsernameParams, type ClientOptions, type CompleteMultipartUploadParams, type CreateChatroomMembershipParams, type CreateChatroomMessageParams, type CreateChatroomParams, type CreateCloneParams, type CreateTextParams, DEFAULT_BASE_URL, type ErrorOptions, type GetChatParams, type GetChatroomMembershipParams, type GetChatroomMessagesParams, type GetChatroomsParams, type GetClonesParams, type GetMindClusterParams, type GetQuotaParams, type GetSoulmateReportParams, type GetTextsParams, type GetUserParams, type ListUploadPartsParams, type LoginParams, type LogoutParams, MindUpload, MindUploadBase, MindUploadConnectionError, MindUploadError, type RagParams, RateLimitError, type RateLimitOptions, type RegisterParams, type RequestMultipartUploadParams, type RequestUploadUrlParams, type Result, type SignUploadPartParams, type SignUploadPartsBatchParams, type TranslateChatroomMessageParams, type TriggerSocialParams, type UpdateCloneParams, type UpdateUserParams, VERSION };
+export { type AbortMultipartUploadParams, ApiError, type ApiErrorOptions, AuthenticationError, type CancelUploadParams, type CheckChatroomUpdatesParams, type CheckUsernameParams, type ClientOptions, type CompleteMultipartUploadParams, type CreateChatroomMembershipParams, type CreateChatroomMessageParams, type CreateChatroomParams, type CreateCloneParams, type CreateExternalAuthorizationRequestParams, type CreateTextParams, DEFAULT_BASE_URL, type ErrorOptions, type ExchangeExternalAuthorizationParams, type ExternalAuthorizationStatus, type GetChatParams, type GetChatroomMembershipParams, type GetChatroomMessagesParams, type GetChatroomsParams, type GetClonesParams, type GetMindClusterParams, type GetQuotaParams, type GetSoulmateReportParams, type GetTextsParams, type GetUserParams, type InspectExternalAuthorizationParams, type InvokeExternalCloneParams, type ListUploadPartsParams, type LoginParams, type LogoutParams, MindUpload, MindUploadBase, MindUploadConnectionError, MindUploadError, type RagParams, RateLimitError, type RateLimitOptions, type RefreshExternalAuthorizationParams, type RegisterParams, type RequestMultipartUploadParams, type RequestUploadUrlParams, type Result, type SignUploadPartParams, type SignUploadPartsBatchParams, type TranslateChatroomMessageParams, type TriggerSocialParams, type UpdateCloneParams, type UpdateUserParams, VERSION, type WaitForExternalAuthorizationParams, type WaitForExternalCloneInvocationParams };

package/dist/index.d.ts

@@ -13,7 +13,7 @@ interface ClientOptions {
     /** Default locale sent with every call (per-call `preferredLanguage` overrides). */
     preferredLanguage?: string;
     timeoutMs?: number;
-    /** Retries on 429 / 5xx / network errors, with backoff. Default 2. */
+    /** Retries only explicit 429 rate-limit responses, with backoff. Default 2. */
     maxRetries?: number;
     userAgent?: string;
 }
@@ -32,6 +32,14 @@ declare class MindUploadBase {
     private errorFor;
 }
 
+type ExternalAuthorizationStatus = "pending" | "slow_down" | "denied" | "expired" | "revoked" | "exchanged";
+interface WaitForExternalAuthorizationParams {
+    deviceCode: string;
+    timeoutMs?: number;
+}
+interface WaitForExternalCloneInvocationParams extends InvokeExternalCloneParams {
+    timeoutMs?: number;
+}
 interface CreateCloneParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
     preferredLanguage?: string;
@@ -120,7 +128,7 @@ interface CheckChatroomUpdatesParams {
     /** The end-user's password on first sign-in. After login/register, send the returned session token (JWT) here instead — the field accepts either, and reusing the token keeps raw passwords out of your storage. */
     password?: string;
     /** Rooms to check. Each entry must include `chatroom_id`; include `known_updated_at` from the previous response, or null/omit it on the first poll. */
-    chatrooms?: Record<string, unknown>[];
+    chatrooms?: Array<Record<string, unknown>>;
 }
 interface CreateChatroomParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
@@ -262,6 +270,58 @@ interface TriggerSocialParams {
     /** Chatroom id as returned by chatroom operations. */
     chatroomId?: string;
 }
+interface CreateExternalAuthorizationRequestParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** A stable opaque event key that makes exact retries return the same outcome. */
+    idempotencyKey: string;
+    /** Your stable opaque identifier for this app installation. */
+    installationId: string;
+    /** Your stable opaque identifier for the person authorizing this installation. */
+    externalSubject: string;
+    /** Optional user-readable name for the installation shown during consent. */
+    installationLabel?: string;
+    /** Optional user-readable external identity shown during consent. */
+    externalIdentityLabel?: string;
+    /** Capabilities the owner is being asked to delegate. */
+    requestedScopes: Array<"clone:invoke">;
+}
+interface ExchangeExternalAuthorizationParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** Short-lived high-entropy secret used only to poll and exchange this request. */
+    deviceCode: string;
+}
+interface InspectExternalAuthorizationParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users. */
+    accessToken: string;
+}
+interface InvokeExternalCloneParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** Opaque grant token accepted only by grant inspection and external clone invocation; store it as a secret and never expose it to users. */
+    accessToken: string;
+    /** Your stable opaque identifier for this app installation. */
+    installationId: string;
+    /** Your stable opaque identifier for the person authorizing this installation. */
+    externalSubject: string;
+    cloneId: string;
+    text: string;
+    /** A stable opaque event key that makes exact retries return the same outcome. */
+    idempotencyKey: string;
+}
+interface RefreshExternalAuthorizationParams {
+    /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
+    preferredLanguage?: string;
+    /** Opaque grant-lifetime token used only with refresh_external_authorization; store it as a secret. */
+    refreshToken: string;
+    /** Your stable opaque identifier for this app installation. */
+    installationId: string;
+    /** Your stable opaque identifier for the person authorizing this installation. */
+    externalSubject: string;
+}
 interface GetMindClusterParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
     preferredLanguage?: string;
@@ -321,7 +381,7 @@ interface CompleteMultipartUploadParams {
     /** Multipart upload session id returned by `request_multipart_upload`. */
     uploadId?: string;
     /** The successfully uploaded parts, using the `part_number` and `etag` returned by each part upload. */
-    parts?: Record<string, unknown>[];
+    parts?: Array<Record<string, unknown>>;
 }
 interface ListUploadPartsParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
@@ -387,7 +447,7 @@ interface SignUploadPartsBatchParams {
     /** Multipart upload session id returned by `request_multipart_upload`. */
     uploadId?: string;
     /** One-based multipart part numbers to sign in a single batch. */
-    partNumbers?: number[];
+    partNumbers?: Array<number>;
 }
 interface CreateTextParams {
     /** BCP-47-ish language code (e.g. 'en', 'zh-cn') for localized messages. */
@@ -470,7 +530,7 @@ declare class MindUpload extends MindUploadBase {
     updateClone(params?: UpdateCloneParams): Promise<Result>;
     /** Check your partner API rate limits, credit caps, and current usage.
      *
-     * Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, operation_duration_ms.
+     * Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, external_authorization_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, operation_duration_ms.
      * @see https://docs.mindupload.app
      */
     getQuota(params?: GetQuotaParams): Promise<Result>;
@@ -564,6 +624,36 @@ declare class MindUpload extends MindUploadBase {
      * @see https://docs.mindupload.app
      */
     triggerSocial(params?: TriggerSocialParams): Promise<Result>;
+    /** Start passwordless grant issuance for an external identity and installation.
+     *
+     * Response fields: success, error_message, device_code, user_code, verification_uri, verification_uri_complete, expires_in, poll_interval, grant_duration_seconds.
+     * @see https://docs.mindupload.app
+     */
+    createExternalAuthorizationRequest(params: CreateExternalAuthorizationRequestParams): Promise<Result>;
+    /** Poll owner consent and exchange an approval for a clone-scoped grant token.
+     *
+     * Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, access_token_expires_at, expires_at, poll_interval.
+     * @see https://docs.mindupload.app
+     */
+    exchangeExternalAuthorization(params: ExchangeExternalAuthorizationParams): Promise<Result>;
+    /** Inspect the scopes, clone resources, expiry, and revocation state of a grant token.
+     *
+     * Response fields: success, error_message, grant_id, status, scopes, clone_ids, created_at, access_token_expires_at, expires_at, revoked_at.
+     * @see https://docs.mindupload.app
+     */
+    inspectExternalAuthorization(params: InspectExternalAuthorizationParams): Promise<Result>;
+    /** Send one idempotent text event to an owner-approved AI consciousness.
+     *
+     * Response fields: success, error_message, invocation_id, status, response_text, clone_id, clone_nickname, generated_by_ai, idempotent_replay, retry_after_seconds.
+     * @see https://docs.mindupload.app
+     */
+    invokeExternalClone(params: InvokeExternalCloneParams): Promise<Result>;
+    /** Refresh a short-lived clone-invocation access token.
+     *
+     * Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, access_token_expires_at, expires_at.
+     * @see https://docs.mindupload.app
+     */
+    refreshExternalAuthorization(params: RefreshExternalAuthorizationParams): Promise<Result>;
     /** Fetch the mind-graph visualization data of an AI consciousness.
      *
      * Response fields: success, error_message, root_node_id, node, children, texts, total_texts, texts_offset, has_more_texts, is_building.
@@ -648,6 +738,18 @@ declare class MindUpload extends MindUploadBase {
      * @see https://docs.mindupload.app
      */
     updateUser(params?: UpdateUserParams): Promise<Result>;
+    /** Poll owner consent at the server-advised cadence until exchange succeeds. */
+    waitForExternalAuthorization(params: WaitForExternalAuthorizationParams): Promise<Result>;
+    /** Invoke a clone and wait out slow generation via idempotent retries.
+     *
+     * A clone reply is generated inside the request, so under load a call can
+     * exceed the client or gateway timeout before the reply is ready. Because the
+     * invocation is idempotent on idempotencyKey, this re-sends the SAME event
+     * until it resolves: a still-generating call returns status "processing" (or
+     * times out), and the finished result is replayed once ready. Prefer this over
+     * a bare invokeExternalClone when generation may be slow.
+     */
+    waitForExternalCloneInvocation(params: WaitForExternalCloneInvocationParams): Promise<Result>;
 }
 
 interface ErrorOptions {
@@ -686,6 +788,6 @@ declare class MindUploadConnectionError extends MindUploadError {
     constructor(message: string, options?: ErrorOptions);
 }
 
-declare const VERSION = "1.5.8";
+declare const VERSION = "1.5.9";
 
-export { type AbortMultipartUploadParams, ApiError, type ApiErrorOptions, AuthenticationError, type CancelUploadParams, type CheckChatroomUpdatesParams, type CheckUsernameParams, type ClientOptions, type CompleteMultipartUploadParams, type CreateChatroomMembershipParams, type CreateChatroomMessageParams, type CreateChatroomParams, type CreateCloneParams, type CreateTextParams, DEFAULT_BASE_URL, type ErrorOptions, type GetChatParams, type GetChatroomMembershipParams, type GetChatroomMessagesParams, type GetChatroomsParams, type GetClonesParams, type GetMindClusterParams, type GetQuotaParams, type GetSoulmateReportParams, type GetTextsParams, type GetUserParams, type ListUploadPartsParams, type LoginParams, type LogoutParams, MindUpload, MindUploadBase, MindUploadConnectionError, MindUploadError, type RagParams, RateLimitError, type RateLimitOptions, type RegisterParams, type RequestMultipartUploadParams, type RequestUploadUrlParams, type Result, type SignUploadPartParams, type SignUploadPartsBatchParams, type TranslateChatroomMessageParams, type TriggerSocialParams, type UpdateCloneParams, type UpdateUserParams, VERSION };
+export { type AbortMultipartUploadParams, ApiError, type ApiErrorOptions, AuthenticationError, type CancelUploadParams, type CheckChatroomUpdatesParams, type CheckUsernameParams, type ClientOptions, type CompleteMultipartUploadParams, type CreateChatroomMembershipParams, type CreateChatroomMessageParams, type CreateChatroomParams, type CreateCloneParams, type CreateExternalAuthorizationRequestParams, type CreateTextParams, DEFAULT_BASE_URL, type ErrorOptions, type ExchangeExternalAuthorizationParams, type ExternalAuthorizationStatus, type GetChatParams, type GetChatroomMembershipParams, type GetChatroomMessagesParams, type GetChatroomsParams, type GetClonesParams, type GetMindClusterParams, type GetQuotaParams, type GetSoulmateReportParams, type GetTextsParams, type GetUserParams, type InspectExternalAuthorizationParams, type InvokeExternalCloneParams, type ListUploadPartsParams, type LoginParams, type LogoutParams, MindUpload, MindUploadBase, MindUploadConnectionError, MindUploadError, type RagParams, RateLimitError, type RateLimitOptions, type RefreshExternalAuthorizationParams, type RegisterParams, type RequestMultipartUploadParams, type RequestUploadUrlParams, type Result, type SignUploadPartParams, type SignUploadPartsBatchParams, type TranslateChatroomMessageParams, type TriggerSocialParams, type UpdateCloneParams, type UpdateUserParams, VERSION, type WaitForExternalAuthorizationParams, type WaitForExternalCloneInvocationParams };

package/dist/index.js

@@ -41,12 +41,12 @@ var MindUploadConnectionError = class extends MindUploadError {
 };
 
 // src/version.ts
-var VERSION = "1.5.8";
+var VERSION = "1.5.9";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://partner.mindupload.app";
 var AUTH_HEADER = "X-Partner-Key";
-var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 503]);
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429]);
 function camelToSnake(key) {
   return key.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase());
 }
@@ -163,6 +163,15 @@ var MindUploadBase = class {
 };
 
 // src/operations.ts
+var DEFAULT_AUTHORIZATION_POLL_MS = 5e3;
+var MAX_PENDING_POLL_MS = 15e3;
+var MAX_SLOW_DOWN_POLL_MS = 3e4;
+var SLOW_DOWN_INCREMENT_MS = 5e3;
+var POLL_JITTER_RATIO = 0.2;
+var DEFAULT_INVOCATION_POLL_MS = 2e3;
+var MAX_INVOCATION_POLL_MS = 1e4;
+var EXTERNAL_INVOCATION_PROCESSING_STATUS = "processing";
+var INVOCATION_RETRY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
 var MindUpload = class extends MindUploadBase {
   // --- AI Consciousnesses ---
   /** Create a new AI consciousness for the user.
@@ -192,7 +201,7 @@ var MindUpload = class extends MindUploadBase {
   // --- Account ---
   /** Check your partner API rate limits, credit caps, and current usage.
    *
-   * Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, operation_duration_ms.
+   * Response fields: success, error_message, per_user_rate_limit_per_min, per_user_daily_credit_cap, partner_rate_limit_per_min, external_authorization_rate_limit_per_min, partner_daily_credit_cap, max_users, registered_users, partner_requests_last_minute, partner_credit_spends_last_day, user, user_requests_last_minute, user_credit_spends_last_day, credit_spending_tasks, operation_duration_ms.
    * @see https://docs.mindupload.app
    */
   getQuota(params = {}) {
@@ -321,6 +330,47 @@ var MindUpload = class extends MindUploadBase {
   triggerSocial(params = {}) {
     return this.request("trigger_social", params);
   }
+  // --- External Authorization ---
+  /** Start passwordless grant issuance for an external identity and installation.
+   *
+   * Response fields: success, error_message, device_code, user_code, verification_uri, verification_uri_complete, expires_in, poll_interval, grant_duration_seconds.
+   * @see https://docs.mindupload.app
+   */
+  createExternalAuthorizationRequest(params) {
+    return this.request("create_external_authorization_request", params);
+  }
+  /** Poll owner consent and exchange an approval for a clone-scoped grant token.
+   *
+   * Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, access_token_expires_at, expires_at, poll_interval.
+   * @see https://docs.mindupload.app
+   */
+  exchangeExternalAuthorization(params) {
+    return this.request("exchange_external_authorization", params);
+  }
+  /** Inspect the scopes, clone resources, expiry, and revocation state of a grant token.
+   *
+   * Response fields: success, error_message, grant_id, status, scopes, clone_ids, created_at, access_token_expires_at, expires_at, revoked_at.
+   * @see https://docs.mindupload.app
+   */
+  inspectExternalAuthorization(params) {
+    return this.request("inspect_external_authorization", params);
+  }
+  /** Send one idempotent text event to an owner-approved AI consciousness.
+   *
+   * Response fields: success, error_message, invocation_id, status, response_text, clone_id, clone_nickname, generated_by_ai, idempotent_replay, retry_after_seconds.
+   * @see https://docs.mindupload.app
+   */
+  invokeExternalClone(params) {
+    return this.request("invoke_external_clone", params);
+  }
+  /** Refresh a short-lived clone-invocation access token.
+   *
+   * Response fields: success, error_message, status, access_token, refresh_token, token_type, grant_id, scopes, clone_ids, access_token_expires_at, expires_at.
+   * @see https://docs.mindupload.app
+   */
+  refreshExternalAuthorization(params) {
+    return this.request("refresh_external_authorization", params);
+  }
   // --- Insights ---
   /** Fetch the mind-graph visualization data of an AI consciousness.
    *
@@ -437,6 +487,82 @@ var MindUpload = class extends MindUploadBase {
   updateUser(params = {}) {
     return this.request("update_user", params);
   }
+  /** Poll owner consent at the server-advised cadence until exchange succeeds. */
+  async waitForExternalAuthorization(params) {
+    const deadline = Date.now() + (params.timeoutMs ?? 6e5);
+    let pollIntervalMs = DEFAULT_AUTHORIZATION_POLL_MS;
+    for (; ; ) {
+      const result = await this.exchangeExternalAuthorization({
+        deviceCode: params.deviceCode
+      });
+      const status = result.status;
+      if (status === "exchanged") return result;
+      if (status === "denied" || status === "expired" || status === "revoked") {
+        throw new MindUploadError(
+          `External authorization ended with status: ${status}`,
+          { operation: "exchange_external_authorization", response: result }
+        );
+      }
+      const serverIntervalMs = Number(
+        result.poll_interval ?? DEFAULT_AUTHORIZATION_POLL_MS / 1e3
+      ) * 1e3;
+      if (status === "slow_down") {
+        pollIntervalMs = Math.max(serverIntervalMs, Math.min(
+          pollIntervalMs + SLOW_DOWN_INCREMENT_MS,
+          MAX_SLOW_DOWN_POLL_MS
+        ));
+      } else {
+        pollIntervalMs = Math.max(serverIntervalMs, Math.min(
+          pollIntervalMs * 1.5,
+          MAX_PENDING_POLL_MS
+        ));
+      }
+      const waitMs = pollIntervalMs * (1 + Math.random() * POLL_JITTER_RATIO);
+      if (Date.now() + waitMs > deadline) {
+        throw new Error("Timed out waiting for external authorization.");
+      }
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+  }
+  /** Invoke a clone and wait out slow generation via idempotent retries.
+   *
+   * A clone reply is generated inside the request, so under load a call can
+   * exceed the client or gateway timeout before the reply is ready. Because the
+   * invocation is idempotent on idempotencyKey, this re-sends the SAME event
+   * until it resolves: a still-generating call returns status "processing" (or
+   * times out), and the finished result is replayed once ready. Prefer this over
+   * a bare invokeExternalClone when generation may be slow.
+   */
+  async waitForExternalCloneInvocation(params) {
+    const { timeoutMs, ...invokeParams } = params;
+    const deadline = Date.now() + (timeoutMs ?? 12e4);
+    let pollIntervalMs = DEFAULT_INVOCATION_POLL_MS;
+    for (; ; ) {
+      let result;
+      try {
+        result = await this.invokeExternalClone(invokeParams);
+      } catch (error) {
+        if (error instanceof MindUploadConnectionError) {
+          result = void 0;
+        } else if (error instanceof ApiError && INVOCATION_RETRY_STATUSES.has(error.status)) {
+          result = void 0;
+        } else {
+          throw error;
+        }
+      }
+      if (result && result.status !== EXTERNAL_INVOCATION_PROCESSING_STATUS) {
+        return result;
+      }
+      if (result) {
+        pollIntervalMs = (Number(result.retry_after_seconds) || DEFAULT_INVOCATION_POLL_MS / 1e3) * 1e3;
+      }
+      const waitMs = Math.min(pollIntervalMs, MAX_INVOCATION_POLL_MS) * (1 + Math.random() * POLL_JITTER_RATIO);
+      if (Date.now() + waitMs > deadline) {
+        throw new Error("Timed out waiting for the external clone invocation.");
+      }
+      await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+  }
 };
 export {
   ApiError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindupload",
-  "version": "1.5.8",
+  "version": "1.5.9",
   "description": "Official server-side SDK for the Mind Upload partner API \u2014 the world's first API for artificial consciousness. Integrate living, evolving AI consciousnesses into your platform: lasting memory, one-on-one chat, and human + AI group chatrooms.",
   "keywords": [
     "mindupload",