@arke-institute/sdk 2.1.0 → 2.3.0

package/dist/generated/index.d.ts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2025-12-30T18:35:49.017Z
+ * Generated: 2026-01-01T18:48:14.305Z
  */
 type paths = {
     "/auth/register": {
@@ -2069,9 +2069,9 @@ type paths = {
          *
          *     ## Flow
          *     1. Call this endpoint with file metadata (key, filename, content_type, size)
-         *     2. Receive entity data + presigned S3 upload URL
+         *     2. Receive entity data + presigned S3 upload URL (uploaded: false)
          *     3. PUT the file content to the upload URL
-         *     4. File is now stored and accessible
+         *     4. Call POST /{id}/confirm-upload to verify and set uploaded: true
          *
          *     ## Key Best Practice
          *     Use the file's CID as the key for content-addressable storage.
@@ -2454,9 +2454,10 @@ type paths = {
          *
          *     ## Flow
          *     1. Call this endpoint with new key and file metadata
-         *     2. Receive updated entity + presigned upload URL
+         *     2. Receive updated entity + presigned upload URL (uploaded: false)
          *     3. PUT the new file content to the upload URL
-         *     4. Old file versions remain accessible via manifest history
+         *     4. Call POST /{id}/confirm-upload to verify and set uploaded: true
+         *     5. Old file versions remain accessible via manifest history
          *
          *     ## Key Requirement
          *     The new key must NOT already exist in S3 (no overwrites).
@@ -2580,6 +2581,149 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/files/{id}/confirm-upload": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Confirm upload completed
+         * @description Confirms that file content has been uploaded to S3.
+         *
+         *     ## Flow
+         *     1. Create file entity (POST /files) - sets uploaded: false
+         *     2. PUT file content to the presigned upload URL
+         *     3. Call this endpoint to confirm - verifies file exists in S3, sets uploaded: true
+         *
+         *     ## Verification
+         *     The server verifies the file exists in S3 before setting uploaded: true.
+         *     If the file doesn't exist, returns 400 error.
+         *
+         *     ## Idempotency
+         *     If already uploaded: true, returns success without modification.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["ConfirmUploadRequest"];
+                };
+            };
+            responses: {
+                /** @description Upload confirmed */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ConfirmUploadResponse"];
+                    };
+                };
+                /** @description Bad Request - Invalid input */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Validation failed",
+                         *       "details": {
+                         *         "issues": [
+                         *           {
+                         *             "path": [
+                         *               "properties",
+                         *               "label"
+                         *             ],
+                         *             "message": "Required"
+                         *           }
+                         *         ]
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ValidationErrorResponse"];
+                    };
+                };
+                /** @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 Forbidden - Insufficient permissions */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Forbidden: You do not have permission to perform this action"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Not Found - Resource does not exist */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Entity not found"
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Conflict - CAS validation failed (entity was modified) */
+                409: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Conflict: entity was modified",
+                         *       "details": {
+                         *         "expected": "bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy",
+                         *         "actual": "bafyreinewabc123456789defghijklmnopqrstuvwxyz"
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["CASErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/folders": {
         parameters: {
             query?: never;
@@ -3148,6 +3292,9 @@ type paths = {
          * Bulk add children to folder
          * @description Efficiently adds multiple children to a folder.
          *
+         *     **Limit**: Maximum 50 children per request. For larger batches, make multiple
+         *     requests, refetching the folder's CID between each to satisfy the CAS guard.
+         *
          *     **Strategy**:
          *     1. Updates folder once with all 'contains' relationships
          *     2. Updates each child in parallel with 'in' back-link
@@ -4446,6 +4593,59 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List events
+         * @description Returns entity change events in reverse chronological order (newest first).
+         *
+         *     Each event represents a create or update operation on an entity. Use cursor-based pagination to walk through the event history.
+         *
+         *     **Use cases:**
+         *     - Syncing entity changes to external systems
+         *     - Building search indexes
+         *     - Change tracking and audit logs
+         *
+         *     **Note:** This endpoint is public. Access control is enforced at the entity level - if you don't have permission to view an entity, you won't be able to fetch its manifest even if you see an event for it.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description Maximum events to return (1-100, default 50) */
+                    limit?: number;
+                    /** @description Event CID to continue from (for pagination) */
+                    cursor?: string;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Event list */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["EventsListResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 };
 type components = {
     schemas: {
@@ -4586,21 +4786,15 @@ type components = {
              * @example Added Chapter 42: The Whiteness of the Whale
              */
             note?: string;
-            /**
-             * @description Updated display name
-             * @example Captain Ahab
-             */
-            label?: string;
-            /**
-             * @description Properties to merge with existing (partial update)
-             * @example {
-             *       "bio": "Commander of the Pequod, hunter of the white whale"
-             *     }
-             */
+            /** @description Properties to add or update (deep merged) */
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Relationships to add or update */
+            /** @description Properties to remove */
+            properties_remove?: string[] | {
+                [key: string]: unknown;
+            };
+            /** @description Relationships to add or update (upsert semantics) */
             relationships_add?: {
                 /**
                  * @description Relationship predicate (e.g., "admin", "contains", "collection")
@@ -4649,6 +4843,11 @@ type components = {
                  */
                 peer?: string;
             }[];
+            /**
+             * @description Updated display name
+             * @example Captain Ahab
+             */
+            label?: string;
         };
         CreateApiKeyResponse: {
             /**
@@ -4801,20 +5000,15 @@ type components = {
              * @example Added Chapter 42: The Whiteness of the Whale
              */
             note?: string;
-            /** @description Updated collection display name */
-            label?: string;
-            /** @description Updated collection description */
-            description?: string;
-            /**
-             * Format: uri
-             * @description Updated display image URL
-             */
-            display_image_url?: string;
-            /** @description Additional properties to merge */
+            /** @description Properties to add or update (deep merged) */
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Relationships to add or update */
+            /** @description Properties to remove */
+            properties_remove?: string[] | {
+                [key: string]: unknown;
+            };
+            /** @description Relationships to add or update (upsert semantics) */
             relationships_add?: {
                 /**
                  * @description Relationship predicate (e.g., "admin", "contains", "collection")
@@ -4863,6 +5057,15 @@ type components = {
                  */
                 peer?: string;
             }[];
+            /** @description Updated collection display name */
+            label?: string;
+            /** @description Updated collection description */
+            description?: string;
+            /**
+             * Format: uri
+             * @description Updated display image URL
+             */
+            display_image_url?: string;
         };
         RoleResponse: {
             /**
@@ -5186,24 +5389,11 @@ type components = {
              * @example Added Chapter 42: The Whiteness of the Whale
              */
             note?: string;
-            /**
-             * @description Properties to add or update (deep merged with existing)
-             * @example {
-             *       "label": "Chapter 1: Loomings (Revised)",
-             *       "metadata": {
-             *         "status": "reviewed"
-             *       }
-             *     }
-             */
+            /** @description Properties to add or update (deep merged) */
             properties?: {
                 [key: string]: unknown;
             };
-            /**
-             * @description Properties to remove (string array or nested object)
-             * @example [
-             *       "deprecated_field"
-             *     ]
-             */
+            /** @description Properties to remove */
             properties_remove?: string[] | {
                 [key: string]: unknown;
             };
@@ -5256,22 +5446,6 @@ type components = {
                  */
                 peer?: string;
             }[];
-            /**
-             * @description Components to add or update (key → CID)
-             * @example {
-             *       "transcript.txt": "bafyrei..."
-             *     }
-             */
-            components?: {
-                [key: string]: string;
-            };
-            /**
-             * @description Component keys to remove
-             * @example [
-             *       "old_version.txt"
-             *     ]
-             */
-            components_remove?: string[];
         };
         AddRelationshipResponse: {
             source: components["schemas"]["EntityResponse"] & unknown;
@@ -5523,31 +5697,15 @@ type components = {
              * @example Added Chapter 42: The Whiteness of the Whale
              */
             note?: string;
-            /** @description New storage key. Must already exist in S3 (for regression to old version). */
-            key?: string;
-            /** @description New filename */
-            filename?: string;
-            /** @description New MIME type */
-            content_type?: string;
-            /** @description New file size in bytes */
-            size?: number;
-            /** @description New content identifier */
-            cid?: string;
-            /** @description New description */
-            description?: string;
-            /**
-             * @description Additional properties to merge into the file metadata
-             * @example {
-             *       "log_data": {
-             *         "status": "done",
-             *         "entries": []
-             *       }
-             *     }
-             */
+            /** @description Properties to add or update (deep merged) */
             properties?: {
                 [key: string]: unknown;
             };
-            /** @description Relationships to add or update */
+            /** @description Properties to remove */
+            properties_remove?: string[] | {
+                [key: string]: unknown;
+            };
+            /** @description Relationships to add or update (upsert semantics) */
             relationships_add?: {
                 /**
                  * @description Relationship predicate (e.g., "admin", "contains", "collection")
@@ -5596,6 +5754,18 @@ type components = {
                  */
                 peer?: string;
             }[];
+            /** @description New storage key. Must already exist in S3 (for regression to old version). */
+            key?: string;
+            /** @description New filename */
+            filename?: string;
+            /** @description New MIME type */
+            content_type?: string;
+            /** @description New file size in bytes */
+            size?: number;
+            /** @description New content identifier */
+            cid?: string;
+            /** @description New description */
+            description?: string;
         };
         ReuploadFileResponse: components["schemas"]["UpdateFileResponse"] & {
             /**
@@ -5643,6 +5813,30 @@ type components = {
             /** @description New description */
             description?: string;
         };
+        ConfirmUploadResponse: components["schemas"]["FileResponse"] & {
+            /**
+             * @description Previous version CID. Not present if upload was already confirmed.
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            prev_cid?: string;
+            /**
+             * @description True if upload was already confirmed. Entity was not modified.
+             * @example false
+             */
+            already_confirmed: boolean;
+        };
+        ConfirmUploadRequest: {
+            /**
+             * @description Current tip CID for CAS validation. Request fails with 409 if this does not match.
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            expect_tip: string;
+            /**
+             * @description Optional note describing this change
+             * @example Added Chapter 42: The Whiteness of the Whale
+             */
+            note?: string;
+        };
         CreateFolderResponse: {
             /**
              * @description Entity ID (ULID format)
@@ -5757,21 +5951,15 @@ type components = {
              * @example Added Chapter 42: The Whiteness of the Whale
              */
             note?: string;
-            /** @description New display name */
-            label?: string;
-            /** @description New description */
-            description?: string;
-            /** @description New rich description */
-            rich_description?: string;
-            /** @description New metadata (deep merged) */
-            metadata?: {
+            /** @description Properties to add or update (deep merged) */
+            properties?: {
                 [key: string]: unknown;
             };
-            /** @description Additional properties to merge */
-            properties?: {
+            /** @description Properties to remove */
+            properties_remove?: string[] | {
                 [key: string]: unknown;
             };
-            /** @description Relationships to add or update */
+            /** @description Relationships to add or update (upsert semantics) */
             relationships_add?: {
                 /**
                  * @description Relationship predicate (e.g., "admin", "contains", "collection")
@@ -5820,6 +6008,16 @@ type components = {
                  */
                 peer?: string;
             }[];
+            /** @description New display name */
+            label?: string;
+            /** @description New description */
+            description?: string;
+            /** @description New rich description */
+            rich_description?: string;
+            /** @description New metadata (deep merged) */
+            metadata?: {
+                [key: string]: unknown;
+            };
         };
         AddChildResponse: {
             folder: components["schemas"]["FolderResponse"] & unknown;
@@ -5922,7 +6120,7 @@ type components = {
              */
             note?: string;
             /**
-             * @description Children to add
+             * @description Children to add (max 50 per request)
              * @example [
              *       {
              *         "id": "01JFILE123ABCDEFGHJKMNPQRS"
@@ -6094,12 +6292,6 @@ type components = {
                         [key: string]: unknown;
                     };
                 }[];
-                /** @description IPLD links to components (files, chunks, etc.) */
-                components?: {
-                    [key: string]: {
-                        "/": string;
-                    };
-                };
                 /**
                  * @description Audit trail for edits
                  * @example {
@@ -6303,45 +6495,15 @@ type components = {
              * @example Added Chapter 42: The Whiteness of the Whale
              */
             note?: string;
-            /** @description Updated agent display name */
-            label?: string;
-            /** @description Updated agent description */
-            description?: string;
-            /**
-             * Format: uri
-             * @description Updated agent service URL
-             */
-            endpoint?: string;
-            /**
-             * @description Actions this agent requires on target collections
-             * @example [
-             *       "entity:view",
-             *       "entity:update",
-             *       "file:create"
-             *     ]
-             */
-            actions_required?: string[];
-            /**
-             * @description Agent status
-             * @example development
-             * @enum {string}
-             */
-            status?: "development" | "active" | "disabled";
-            /** @description Updated sub-agents */
-            uses_agents?: components["schemas"]["SubAgentRef"][];
-            /** @description Updated input schema */
-            input_schema?: {
-                [key: string]: unknown;
-            };
-            /** @description Updated output schema */
-            output_schema?: {
+            /** @description Properties to add or update (deep merged) */
+            properties?: {
                 [key: string]: unknown;
             };
-            /** @description Additional properties to merge */
-            properties?: {
+            /** @description Properties to remove */
+            properties_remove?: string[] | {
                 [key: string]: unknown;
             };
-            /** @description Relationships to add or update */
+            /** @description Relationships to add or update (upsert semantics) */
             relationships_add?: {
                 /**
                  * @description Relationship predicate (e.g., "admin", "contains", "collection")
@@ -6390,6 +6552,40 @@ type components = {
                  */
                 peer?: string;
             }[];
+            /** @description Updated agent display name */
+            label?: string;
+            /** @description Updated agent description */
+            description?: string;
+            /**
+             * Format: uri
+             * @description Updated agent service URL
+             */
+            endpoint?: string;
+            /**
+             * @description Actions this agent requires on target collections
+             * @example [
+             *       "entity:view",
+             *       "entity:update",
+             *       "file:create"
+             *     ]
+             */
+            actions_required?: string[];
+            /**
+             * @description Agent status
+             * @example development
+             * @enum {string}
+             */
+            status?: "development" | "active" | "disabled";
+            /** @description Updated sub-agents */
+            uses_agents?: components["schemas"]["SubAgentRef"][];
+            /** @description Updated input schema */
+            input_schema?: {
+                [key: string]: unknown;
+            };
+            /** @description Updated output schema */
+            output_schema?: {
+                [key: string]: unknown;
+            };
         };
         InvokeGrant: {
             agent: {
@@ -6419,11 +6615,6 @@ type components = {
             /** @description True if some agents need permission grants */
             grants_needed: boolean;
         };
-        AgentLogRef: {
-            pi: string;
-            /** @enum {string} */
-            type: "file";
-        };
         InvokeGrantResult: {
             agent_id: string;
             role: string;
@@ -6439,7 +6630,8 @@ type components = {
              * @example job_01JEXAMPLEID12345678901
              */
             job_id: string;
-            log: components["schemas"]["AgentLogRef"];
+            /** @description The job collection where agent writes logs */
+            job_collection: string;
             grants: components["schemas"]["InvokeGrantResult"][];
             /**
              * @description IPFS Content Identifier (CID)
@@ -6469,6 +6661,8 @@ type components = {
         InvokeAgentRequest: {
             /** @description Target collection ID to operate on */
             target: string;
+            /** @description Job collection where agent should write logs. If not provided, creates new root collection. */
+            job_collection?: string;
             /** @description Input data for the agent (validated against agent input_schema) */
             input?: {
                 [key: string]: unknown;
@@ -6533,6 +6727,61 @@ type components = {
         ListAgentApiKeysResponse: {
             keys: components["schemas"]["AgentApiKeyInfo"][];
         };
+        EventItem: {
+            /**
+             * @description CID of this event in the event chain
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            event_cid: string;
+            /**
+             * @description Type of entity change event
+             * @example create
+             * @enum {string}
+             */
+            type: "create" | "update";
+            /**
+             * @description Entity ID that was created or updated
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            pi: string;
+            /**
+             * @description Entity version number
+             * @example 1
+             */
+            ver: number;
+            /**
+             * @description CID of the entity manifest at this version
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            tip_cid: string;
+            /**
+             * Format: date-time
+             * @description When the event was recorded
+             * @example 2025-12-26T12:00:00.000Z
+             */
+            ts: string;
+        };
+        EventsListResponse: {
+            /** @description Events in reverse chronological order */
+            items: components["schemas"]["EventItem"][];
+            /**
+             * @description Total events in the event chain
+             * @example 1542
+             */
+            total_events: number;
+            /**
+             * @description Total unique entity IDs across all events
+             * @example 987
+             */
+            total_pis: number;
+            /** @description Whether more events exist beyond this page */
+            has_more: boolean;
+            /**
+             * @description CID to use as "cursor" parameter for next page
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            next_cursor: string | null;
+        };
     };
     responses: never;
     parameters: never;