@arke-institute/sdk 2.5.0 → 2.6.1

package/dist/generated/index.d.ts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-25T03:52:16.348Z
+ * Generated: 2026-01-26T22:08:41.056Z
  */
 type paths = {
     "/ops-reference": {
@@ -2123,6 +2123,9 @@ type paths = {
          *
          *     **Performance:** Preview expansion is recommended for most use cases. Full expansion with many large entities can result in multi-MB payloads.
          *
+         *     **Expansion Limit:**
+         *     Use `?expand_limit=N` to control maximum relationships expanded (1-500, default 100). When truncated, the response includes `_expansion_metadata` with counts.
+         *
          *     ---
          *     **Permission:** `entity:view`
          *     **Auth:** optional
@@ -2132,6 +2135,8 @@ type paths = {
                 query?: {
                     /** @description Comma-separated list of fields to expand. Supports: relationships[:preview|full] */
                     expand?: string;
+                    /** @description Maximum number of relationships to expand (1-500, default 100). When exceeded, relationships beyond the limit are returned without peer data. */
+                    expand_limit?: number;
                 };
                 header?: never;
                 path: {
@@ -6610,7 +6615,7 @@ type paths = {
         patch?: never;
         trace?: never;
     };
-    "/jobs/{id}": {
+    "/agents/{id}/jobs/{job_id}/status": {
         parameters: {
             query?: never;
             header?: never;
@@ -6618,68 +6623,110 @@ type paths = {
             cookie?: never;
         };
         /**
-         * Get job status
-         * @description Returns focused job status and summary. Use this endpoint for quick status polling.
+         * Get job status from agent
+         * @description Proxies to the agent's `/status/:job_id` endpoint and returns the response.
+         *
+         *     Use this endpoint to poll job status after invoking an agent. The `agent_id` and `job_id`
+         *     are both returned in the invoke response.
          *
-         *     Returns 404 if the entity is not a job collection.
+         *     **Query Parameters (passed through to agent):**
+         *     - `detail=full` - Include detailed sub-job/dispatch information (orchestrators/workflows)
+         *     - `errors=N` - Include last N errors (orchestrators only)
          *
-         *     **Response includes:**
-         *     - Current status (running/done/error)
-         *     - Timestamps (started_at, completed_at)
-         *     - Agent references (agent, main_agent, target)
-         *     - Counts (files_count, sub_jobs_count)
+         *     **Response:** Returns the agent's status response directly. Schema varies by agent type
+         *     (service, workflow, orchestrator) but always includes:
+         *     - `job_id` - Job identifier
+         *     - `status` - Current status (pending/running/done/error)
+         *     - `progress` - Progress counters (total/pending/done/error)
+         *     - `started_at` - When the job started
+         *     - `completed_at` - When the job completed (if done/error)
+         *     - `updated_at` - Last state modification
+         *
+         *     Agent-specific fields (phase, stages, sub_jobs, folders, dispatches) are also included
+         *     when applicable.
          *
          *     ---
-         *     **Permission:** `collection:view`
+         *     **Permission:** `agent:view`
          *     **Auth:** optional
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    detail?: "full";
+                    errors?: number | null;
+                };
                 header?: never;
                 path: {
-                    /** @description Entity ID (ULID) */
                     id: string;
+                    job_id: string;
                 };
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Job status */
+                /** @description Job status from agent */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["JobStatusResponse"];
+                        "application/json": {
+                            /**
+                             * @description Unique job identifier
+                             * @example job_01KFXPQ3ABCDEFGHIJKLMN
+                             */
+                            job_id: string;
+                            /**
+                             * @description Current job status
+                             * @example running
+                             * @enum {string}
+                             */
+                            status: "pending" | "running" | "done" | "error";
+                            progress: components["schemas"]["JobProgress"];
+                            /**
+                             * @description When this job started (ISO timestamp)
+                             * @example 2026-01-26T17:48:15.000Z
+                             */
+                            started_at: string;
+                            /**
+                             * @description When this job completed (ISO timestamp)
+                             * @example 2026-01-26T17:49:30.000Z
+                             */
+                            completed_at?: string;
+                            /**
+                             * @description Last state modification (ISO timestamp)
+                             * @example 2026-01-26T17:49:27.000Z
+                             */
+                            updated_at?: string;
+                            /** @description Final result data (only when status is done) */
+                            result?: {
+                                [key: string]: unknown;
+                            };
+                            error?: components["schemas"]["JobError"];
+                        };
                     };
                 };
-                /** @description Forbidden - Insufficient permissions */
-                403: {
+                /** @description Not Found - Resource does not exist */
+                404: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
                         /**
                          * @example {
-                         *       "error": "Forbidden: You do not have permission to perform this action"
+                         *       "error": "Entity not found"
                          *     }
                          */
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description Not Found - Resource does not exist */
-                404: {
+                /** @description Agent unreachable or returned an error */
+                502: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        /**
-                         * @example {
-                         *       "error": "Entity not found"
-                         *     }
-                         */
-                        "application/json": components["schemas"]["ErrorResponse"];
+                        "application/json": components["schemas"]["AgentUnreachableError"];
                     };
                 };
             };
@@ -11416,57 +11463,51 @@ type components = {
              */
             confirm?: boolean;
         };
-        EntityRef: {
+        JobProgress: {
             /**
-             * @description Entity ID (ULID format)
-             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             * @description Total items to process
+             * @example 10
              */
-            pi: string;
-            type?: string;
-            label?: string;
-        };
-        JobStatusResponse: {
+            total: number;
             /**
-             * @description Entity ID (ULID format)
-             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             * @description Items not yet started
+             * @example 3
              */
-            id: string;
+            pending: number;
             /**
-             * @description Content Identifier (CID) - content-addressed hash
-             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             * @description Items dispatched but not complete
+             * @example 2
              */
-            cid: string;
+            dispatched?: number;
             /**
-             * @description Job collection status
-             * @example running
-             * @enum {string}
+             * @description Successfully completed items
+             * @example 4
              */
-            status: "running" | "done" | "error";
+            done: number;
             /**
-             * Format: date-time
-             * @description ISO 8601 datetime
-             * @example 2025-12-26T12:00:00.000Z
+             * @description Failed items
+             * @example 1
              */
-            started_at: string;
+            error: number;
+        };
+        JobError: {
             /**
-             * Format: date-time
-             * @description ISO 8601 datetime
-             * @example 2025-12-26T12:00:00.000Z
+             * @description Error code
+             * @example TIMEOUT
              */
-            completed_at: string | null;
-            agent: components["schemas"]["EntityRef"];
-            target?: components["schemas"]["EntityRef"];
-            main_agent?: components["schemas"]["EntityRef"];
+            code: string;
             /**
-             * @description Number of files contained in this job collection
-             * @example 5
+             * @description Human-readable error message
+             * @example Request timed out after 30 seconds
              */
-            files_count: number;
+            message: string;
+        };
+        AgentUnreachableError: {
             /**
-             * @description Number of sub-job collections
-             * @example 2
+             * @description Error message
+             * @example Failed to reach agent: Connection refused
              */
-            sub_jobs_count: number;
+            error: string;
         };
         Event: {
             /**

package/dist/index.cjs

@@ -57,6 +57,147 @@ var DEFAULT_CONFIG = {
   network: "main"
 };
 
+// src/client/retry.ts
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  initialDelay: 100,
+  maxDelay: 5e3,
+  retryOn5xx: true,
+  retryOnNetworkError: true
+};
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([
+  500,
+  // Internal Server Error
+  502,
+  // Bad Gateway
+  503,
+  // Service Unavailable
+  504,
+  // Gateway Timeout
+  520,
+  // Cloudflare: Unknown Error
+  521,
+  // Cloudflare: Web Server Is Down
+  522,
+  // Cloudflare: Connection Timed Out
+  523,
+  // Cloudflare: Origin Is Unreachable
+  524,
+  // Cloudflare: A Timeout Occurred
+  525,
+  // Cloudflare: SSL Handshake Failed
+  526,
+  // Cloudflare: Invalid SSL Certificate
+  527,
+  // Cloudflare: Railgun Error
+  530
+  // Cloudflare: Origin DNS Error
+]);
+var NON_RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([
+  400,
+  // Bad Request
+  401,
+  // Unauthorized
+  403,
+  // Forbidden
+  404,
+  // Not Found
+  405,
+  // Method Not Allowed
+  409,
+  // Conflict (CAS errors)
+  410,
+  // Gone
+  422,
+  // Unprocessable Entity
+  429
+  // Too Many Requests (should be handled separately with rate limiting)
+]);
+function isRetryableStatus(status) {
+  if (NON_RETRYABLE_STATUS_CODES.has(status)) {
+    return false;
+  }
+  return RETRYABLE_STATUS_CODES.has(status);
+}
+function isNetworkError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  if (error instanceof TypeError) {
+    const message = error.message.toLowerCase();
+    return message.includes("failed to fetch") || message.includes("network") || message.includes("fetch failed") || message.includes("econnrefused") || message.includes("econnreset") || message.includes("etimedout") || message.includes("enotfound") || message.includes("dns") || message.includes("socket");
+  }
+  if (error.name === "AbortError") {
+    return true;
+  }
+  return false;
+}
+function isCloudflareErrorResponse(response) {
+  const contentType = response.headers.get("content-type") || "";
+  if (contentType.includes("text/html") && !response.ok) {
+    return true;
+  }
+  return false;
+}
+function calculateDelay(attempt, initialDelay, maxDelay) {
+  const exponentialDelay = initialDelay * Math.pow(2, attempt);
+  const cappedDelay = Math.min(exponentialDelay, maxDelay);
+  const jitter = Math.random() * cappedDelay;
+  return Math.floor(cappedDelay + jitter);
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function createRetryFetch(config = {}) {
+  const {
+    maxRetries = DEFAULT_RETRY_CONFIG.maxRetries,
+    initialDelay = DEFAULT_RETRY_CONFIG.initialDelay,
+    maxDelay = DEFAULT_RETRY_CONFIG.maxDelay,
+    retryOn5xx = DEFAULT_RETRY_CONFIG.retryOn5xx,
+    retryOnNetworkError = DEFAULT_RETRY_CONFIG.retryOnNetworkError,
+    onRetry
+  } = config;
+  return async function retryFetch(input, init) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const response = await fetch(input, init);
+        if (isCloudflareErrorResponse(response) && attempt < maxRetries) {
+          const error = new Error(
+            `Cloudflare error (status ${response.status})`
+          );
+          lastError = error;
+          const delay = calculateDelay(attempt, initialDelay, maxDelay);
+          onRetry?.(attempt + 1, error, delay);
+          await sleep(delay);
+          continue;
+        }
+        if (retryOn5xx && isRetryableStatus(response.status) && attempt < maxRetries) {
+          const error = new Error(
+            `Server error (status ${response.status})`
+          );
+          lastError = error;
+          const delay = calculateDelay(attempt, initialDelay, maxDelay);
+          onRetry?.(attempt + 1, error, delay);
+          await sleep(delay);
+          continue;
+        }
+        return response;
+      } catch (error) {
+        if (retryOnNetworkError && isNetworkError(error) && attempt < maxRetries) {
+          lastError = error;
+          const delay = calculateDelay(attempt, initialDelay, maxDelay);
+          onRetry?.(attempt + 1, error, delay);
+          await sleep(delay);
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw lastError ?? new Error("Request failed after retries");
+  };
+}
+
 // src/client/errors.ts
 var ArkeError = class extends Error {
   constructor(message, code2, status, details) {
@@ -166,9 +307,11 @@ var ArkeClient = class {
     if (this.config.network === "test") {
       headers["X-Arke-Network"] = "test";
     }
+    const customFetch = this.config.retry === false ? void 0 : createRetryFetch(this.config.retry ?? {});
     return (0, import_openapi_fetch.default)({
       baseUrl: this.config.baseUrl ?? DEFAULT_CONFIG.baseUrl,
-      headers
+      headers,
+      ...customFetch && { fetch: customFetch }
     });
   }
   /**
@@ -269,6 +412,46 @@ var ArkeClient = class {
     });
     return { data, error };
   }
+  /**
+   * Upload file content
+   *
+   * This is a convenience method that handles the binary body serialization
+   * that openapi-fetch doesn't handle automatically for non-JSON bodies.
+   *
+   * @example
+   * ```typescript
+   * // Upload from a Blob
+   * const blob = new Blob(['Hello, world!'], { type: 'text/plain' });
+   * const { data, error } = await arke.uploadFileContent('01ABC...', blob, 'text/plain');
+   *
+   * // Upload from an ArrayBuffer
+   * const buffer = new TextEncoder().encode('Hello, world!').buffer;
+   * const { data, error } = await arke.uploadFileContent('01ABC...', buffer, 'text/plain');
+   *
+   * // Upload from a Uint8Array
+   * const bytes = new TextEncoder().encode('Hello, world!');
+   * const { data, error } = await arke.uploadFileContent('01ABC...', bytes, 'text/plain');
+   * ```
+   */
+  async uploadFileContent(fileId, content, contentType) {
+    let body;
+    if (content instanceof Blob) {
+      body = content;
+    } else if (content instanceof Uint8Array) {
+      const buffer = new ArrayBuffer(content.byteLength);
+      new Uint8Array(buffer).set(content);
+      body = new Blob([buffer], { type: contentType });
+    } else {
+      body = new Blob([content], { type: contentType });
+    }
+    const { data, error } = await this.api.POST("/files/{id}/content", {
+      params: { path: { id: fileId } },
+      body,
+      bodySerializer: (b) => b,
+      headers: { "Content-Type": contentType }
+    });
+    return { data, error };
+  }
 };
 function createArkeClient(config) {
   return new ArkeClient(config);