@arke-institute/sdk 3.6.0 → 3.6.3

package/dist/generated/index.d.cts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-02-07T17:07:45.355Z
+ * Generated: 2026-02-09T15:17:42.566Z
  */
 type paths = {
     "/ops-reference": {
@@ -160,6 +160,84 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/auth/whoami": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get current identity
+         * @description Returns identity information for the authenticated caller.
+         *
+         *     Accepts any valid credential type:
+         *     - **JWT**: Returns user PI, email, name, and Supabase user ID
+         *     - **User API Key (uk_)**: Returns user PI and key metadata
+         *     - **Agent API Key (ak_)**: Returns agent PI, owner PI, and key metadata
+         *
+         *     Use this endpoint to verify credentials are working or to retrieve the caller's entity PI.
+         *
+         *     ---
+         *     **Permission:** `auth:whoami`
+         *     **Auth:** required
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Identity information */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["WhoamiResponse"];
+                    };
+                };
+                /** @description Unauthorized - Missing or invalid authentication */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Unauthorized: Missing or invalid authentication token"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Internal Server Error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Internal server error"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/alpha/invite": {
         parameters: {
             query?: never;
@@ -9177,6 +9255,84 @@ type components = {
                 [key: string]: unknown;
             };
         };
+        WhoamiUserResponse: {
+            /**
+             * @description Identity type
+             * @enum {string}
+             */
+            type: "user";
+            /**
+             * @description User entity PI (persistent identifier)
+             * @example 01J1SHMAE10000000000000000
+             */
+            pi: string;
+            /**
+             * @description How this identity was authenticated
+             * @example jwt
+             * @enum {string}
+             */
+            auth_method: "jwt" | "api_key";
+            /**
+             * Format: email
+             * @description User email (JWT auth only)
+             * @example ishmael@pequod.ship
+             */
+            email?: string;
+            /**
+             * @description Display name (JWT auth only)
+             * @example Ishmael
+             */
+            name?: string;
+            /**
+             * Format: uuid
+             * @description Supabase Auth user ID (JWT auth only)
+             */
+            supabase_user_id?: string;
+            /**
+             * @description API key prefix (API key auth only)
+             * @example uk_abc1
+             */
+            key_prefix?: string;
+            /**
+             * Format: date-time
+             * @description API key expiration (API key auth only)
+             */
+            key_expires_at?: string;
+        };
+        WhoamiAgentResponse: {
+            /**
+             * @description Identity type
+             * @enum {string}
+             */
+            type: "agent";
+            /**
+             * @description Agent entity PI (persistent identifier)
+             * @example 01J1AGENTID000000000000000
+             */
+            pi: string;
+            /**
+             * @description How this identity was authenticated
+             * @example api_key
+             * @enum {string}
+             */
+            auth_method: "api_key";
+            /**
+             * @description Entity PI of the agent owner
+             * @example 01J1OWNERID0000000000000000
+             */
+            owner_pi: string;
+            /**
+             * @description API key prefix
+             * @example ak_xyz9
+             */
+            key_prefix: string;
+            /**
+             * Format: date-time
+             * @description API key expiration
+             */
+            key_expires_at: string;
+        };
+        WhoamiResponse: components["schemas"]["WhoamiUserResponse"] | components["schemas"]["WhoamiAgentResponse"];
         AlphaInvite: {
             /**
              * Format: uuid

package/dist/generated/index.d.ts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-02-07T17:07:45.355Z
+ * Generated: 2026-02-09T15:17:42.566Z
  */
 type paths = {
     "/ops-reference": {
@@ -160,6 +160,84 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/auth/whoami": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get current identity
+         * @description Returns identity information for the authenticated caller.
+         *
+         *     Accepts any valid credential type:
+         *     - **JWT**: Returns user PI, email, name, and Supabase user ID
+         *     - **User API Key (uk_)**: Returns user PI and key metadata
+         *     - **Agent API Key (ak_)**: Returns agent PI, owner PI, and key metadata
+         *
+         *     Use this endpoint to verify credentials are working or to retrieve the caller's entity PI.
+         *
+         *     ---
+         *     **Permission:** `auth:whoami`
+         *     **Auth:** required
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Identity information */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["WhoamiResponse"];
+                    };
+                };
+                /** @description Unauthorized - Missing or invalid authentication */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Unauthorized: Missing or invalid authentication token"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Internal Server Error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Internal server error"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/alpha/invite": {
         parameters: {
             query?: never;
@@ -9177,6 +9255,84 @@ type components = {
                 [key: string]: unknown;
             };
         };
+        WhoamiUserResponse: {
+            /**
+             * @description Identity type
+             * @enum {string}
+             */
+            type: "user";
+            /**
+             * @description User entity PI (persistent identifier)
+             * @example 01J1SHMAE10000000000000000
+             */
+            pi: string;
+            /**
+             * @description How this identity was authenticated
+             * @example jwt
+             * @enum {string}
+             */
+            auth_method: "jwt" | "api_key";
+            /**
+             * Format: email
+             * @description User email (JWT auth only)
+             * @example ishmael@pequod.ship
+             */
+            email?: string;
+            /**
+             * @description Display name (JWT auth only)
+             * @example Ishmael
+             */
+            name?: string;
+            /**
+             * Format: uuid
+             * @description Supabase Auth user ID (JWT auth only)
+             */
+            supabase_user_id?: string;
+            /**
+             * @description API key prefix (API key auth only)
+             * @example uk_abc1
+             */
+            key_prefix?: string;
+            /**
+             * Format: date-time
+             * @description API key expiration (API key auth only)
+             */
+            key_expires_at?: string;
+        };
+        WhoamiAgentResponse: {
+            /**
+             * @description Identity type
+             * @enum {string}
+             */
+            type: "agent";
+            /**
+             * @description Agent entity PI (persistent identifier)
+             * @example 01J1AGENTID000000000000000
+             */
+            pi: string;
+            /**
+             * @description How this identity was authenticated
+             * @example api_key
+             * @enum {string}
+             */
+            auth_method: "api_key";
+            /**
+             * @description Entity PI of the agent owner
+             * @example 01J1OWNERID0000000000000000
+             */
+            owner_pi: string;
+            /**
+             * @description API key prefix
+             * @example ak_xyz9
+             */
+            key_prefix: string;
+            /**
+             * Format: date-time
+             * @description API key expiration
+             */
+            key_expires_at: string;
+        };
+        WhoamiResponse: components["schemas"]["WhoamiUserResponse"] | components["schemas"]["WhoamiAgentResponse"];
         AlphaInvite: {
             /**
              * Format: uuid

package/dist/operations/index.cjs

@@ -43,6 +43,7 @@ __export(operations_exports, {
   isCasConflictError: () => isCasConflictError,
   scanFileList: () => scanFileList,
   scanFileSystemEntries: () => scanFileSystemEntries,
+  uploadToEntity: () => uploadToEntity,
   uploadTree: () => uploadTree,
   verifyCid: () => verifyCid,
   withCasRetry: () => withCasRetry
@@ -859,6 +860,185 @@ function buildUploadTree(items) {
   return { files, folders };
 }
 
+// src/operations/upload/single.ts
+var MAX_CAS_RETRIES = 3;
+async function uploadToEntity(client, entityId, items, options = {}) {
+  if (items.length === 0) {
+    throw new Error("At least one upload item is required");
+  }
+  const { onProgress } = options;
+  let progressState = {
+    phase: "preparing",
+    totalBytes: 0,
+    uploadedBytes: 0,
+    completedFiles: 0,
+    totalFiles: items.length
+  };
+  const reportProgress = (update) => {
+    progressState = { ...progressState, ...update };
+    onProgress?.(progressState);
+  };
+  reportProgress({ phase: "preparing" });
+  const prepared = await Promise.all(
+    items.map((item) => prepareItem(item))
+  );
+  const keys = prepared.map((p) => p.key);
+  const duplicates = keys.filter((key, i) => keys.indexOf(key) !== i);
+  if (duplicates.length > 0) {
+    const uniqueDupes = [...new Set(duplicates)];
+    throw new Error(
+      `Duplicate content keys detected: ${uniqueDupes.map((k) => `"${k}"`).join(", ")}. Each file must have a unique key. Provide explicit keys to resolve.`
+    );
+  }
+  const totalBytes = prepared.reduce((sum, p) => sum + p.size, 0);
+  reportProgress({ totalBytes });
+  const uploadInfos = await Promise.all(
+    prepared.map(async (item) => {
+      const { data: presigned, error } = await client.api.POST(
+        "/entities/{id}/content/upload-url",
+        {
+          params: { path: { id: entityId } },
+          body: {
+            cid: item.cid,
+            content_type: item.contentType,
+            size: item.size
+          }
+        }
+      );
+      if (error || !presigned) {
+        throw new Error(
+          `Failed to get upload URL for ${item.key}: ${JSON.stringify(error)}`
+        );
+      }
+      return {
+        ...item,
+        uploadUrl: presigned.upload_url
+      };
+    })
+  );
+  reportProgress({ phase: "uploading", uploadedBytes: 0 });
+  let uploadedBytes = 0;
+  await Promise.all(
+    uploadInfos.map(async (item) => {
+      const response = await fetch(item.uploadUrl, {
+        method: "PUT",
+        headers: { "Content-Type": item.contentType },
+        body: item.bytes
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Upload to R2 failed for ${item.key}: ${response.statusText}`
+        );
+      }
+      uploadedBytes += item.size;
+      reportProgress({ uploadedBytes });
+    })
+  );
+  const { data: tipData, error: tipError } = await client.api.GET(
+    "/entities/{id}/tip",
+    { params: { path: { id: entityId } } }
+  );
+  if (tipError || !tipData) {
+    throw new Error(`Failed to get entity tip: ${JSON.stringify(tipError)}`);
+  }
+  const prevCid = tipData.cid;
+  let currentTip = prevCid;
+  reportProgress({ phase: "completing", completedFiles: 0 });
+  const contents = [];
+  let finalCid = currentTip;
+  for (let i = 0; i < uploadInfos.length; i++) {
+    const item = uploadInfos[i];
+    const result = await completeWithRetry(client, entityId, item, currentTip);
+    currentTip = result.cid;
+    finalCid = result.cid;
+    contents.push({
+      key: item.key,
+      cid: result.contentCid,
+      size: item.size,
+      contentType: item.contentType,
+      filename: item.filename
+    });
+    reportProgress({ completedFiles: i + 1 });
+  }
+  return {
+    id: entityId,
+    cid: finalCid,
+    prevCid,
+    contents
+  };
+}
+async function prepareItem(item) {
+  const { data } = item;
+  let bytes;
+  if (data instanceof Blob) {
+    bytes = await data.arrayBuffer();
+  } else if (data instanceof ArrayBuffer) {
+    bytes = data;
+  } else {
+    const buffer = new ArrayBuffer(data.byteLength);
+    new Uint8Array(buffer).set(data);
+    bytes = buffer;
+  }
+  const size = bytes.byteLength;
+  let filename = item.filename;
+  let contentType = item.contentType;
+  if (data instanceof File) {
+    filename = filename ?? data.name;
+    contentType = contentType ?? (data.type || getMimeType(data.name));
+  }
+  contentType = contentType ?? "application/octet-stream";
+  if (contentType === "application/octet-stream" && filename) {
+    contentType = getMimeType(filename);
+  }
+  const cid = await computeCid(new Uint8Array(bytes));
+  let key = item.key;
+  if (!key && filename) {
+    const lastDot = filename.lastIndexOf(".");
+    key = lastDot > 0 ? filename.substring(0, lastDot) : filename;
+  }
+  if (!key) {
+    key = `file_${cid.slice(-8)}`;
+  }
+  return { key, bytes, size, contentType, filename, cid };
+}
+async function completeWithRetry(client, entityId, item, expectTip) {
+  let tip = expectTip;
+  for (let attempt = 0; attempt < MAX_CAS_RETRIES; attempt++) {
+    const { data, error, response } = await client.api.POST(
+      "/entities/{id}/content/complete",
+      {
+        params: { path: { id: entityId } },
+        body: {
+          key: item.key,
+          cid: item.cid,
+          size: item.size,
+          content_type: item.contentType,
+          filename: item.filename,
+          expect_tip: tip
+        }
+      }
+    );
+    if (data) {
+      return { cid: data.cid, contentCid: data.content.cid };
+    }
+    if (response?.status === 409) {
+      const { data: freshTip, error: tipError } = await client.api.GET(
+        "/entities/{id}/tip",
+        { params: { path: { id: entityId } } }
+      );
+      if (tipError || !freshTip) {
+        throw new Error(`Failed to refresh tip: ${JSON.stringify(tipError)}`);
+      }
+      tip = freshTip.cid;
+      continue;
+    }
+    throw new Error(
+      `Failed to complete upload for ${item.key}: ${JSON.stringify(error)}`
+    );
+  }
+  throw new Error(`Max CAS retries exceeded for ${item.key}`);
+}
+
 // src/operations/folders.ts
 var FolderOperations = class {
   constructor(client) {
@@ -1056,6 +1236,7 @@ async function withCasRetry(callbacks, options) {
   isCasConflictError,
   scanFileList,
   scanFileSystemEntries,
+  uploadToEntity,
   uploadTree,
   verifyCid,
   withCasRetry