@arke-institute/sdk 2.3.9 → 2.3.11

package/dist/generated/index.d.cts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-12T23:27:06.100Z
+ * Generated: 2026-01-14T01:00:30.186Z
  */
 type paths = {
     "/auth/register": {
@@ -2484,6 +2484,121 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/entities/{id}/diff": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get diff between entity versions
+         * @description Computes the difference between two versions of an entity.
+         *
+         *     Query parameters:
+         *     - `from`: CID of the "from" version (defaults to prev of "to" version)
+         *     - `to`: CID of the "to" version (defaults to current tip)
+         *     - `format`: Output format - "semantic" (default) or "patch" (RFC 6902)
+         *
+         *     Modes:
+         *     - No params: Compare current tip with its previous version
+         *     - `to` only: Compare that version with its prev
+         *     - `from` only: Compare from that version to current tip
+         *     - Both: Compare any two versions
+         *
+         *     For version 1 entities (no previous version), "from" is null and all content appears as added.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /** @description CID of the "from" version. Defaults to prev of "to" version. */
+                    from?: string;
+                    /** @description CID of the "to" version. Defaults to current tip. */
+                    to?: string;
+                    /** @description Output format: "semantic" (default) or "patch" (RFC 6902) */
+                    format?: "semantic" | "patch";
+                };
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Diff computed */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["DiffResponse"];
+                    };
+                };
+                /** @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 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"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/relationships": {
         parameters: {
             query?: never;
@@ -5838,9 +5953,23 @@ type paths = {
          *     ## Query Syntax
          *
          *     ```
-         *     ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...
+         *     [SCOPE_PREFIX] ENTRY_POINT [ENTRY_FILTER] [-[RELATION]{DEPTH}-> TARGET_FILTER]...
          *     ```
          *
+         *     ## Scope Prefixes
+         *
+         *     Control where semantic search looks for entry points. Default is discovery mode.
+         *
+         *     | Prefix | Description | Example |
+         *     |--------|-------------|---------|
+         *     | (none) | **Discovery mode** (default) - find relevant collections, then search within each | `"medical notes"` |
+         *     | `@:collections` | Search for collections themselves | `@:collections "columbia archives"` |
+         *     | `@:collection(id)` | Search within a specific collection | `@:collection(01JCOLL123) "meeting"` |
+         *     | `@:discover` | Explicit discovery mode | `@:discover "research papers"` |
+         *     | `@:public` | Search public domain only | `@:public "orphaned data"` |
+         *
+         *     **Note:** Graph traversal (hops) is always cross-collection regardless of scope.
+         *
          *     ### Entry Points
          *
          *     | Syntax | Description | Example |
@@ -5862,10 +5991,11 @@ type paths = {
          *     ### Examples
          *
          *     ```
-         *     "george washington"                           # Simple semantic search
-         *     "albert einstein" type:person                 # With type filter
-         *     "medical college" -[*]{,4}-> type:file        # Find files connected to concept
-         *     @01KE4ZY... -[*]{,2}-> type:person            # Find people near entity
+         *     "george washington"                           # Discovery mode (default)
+         *     @:collections "columbia university"           # Find collections
+         *     @:collection(01JCOLL123) "faculty meeting"    # Within specific collection
+         *     @:discover "alice" -[*]{,2}-> type:person     # Discover, then traverse
+         *     @01KE4ZY... -[*]{,2}-> type:person            # From exact entity
          *     ```
          */
         post: {
@@ -6202,6 +6332,364 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/search/collections": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Search collections by text
+         * @description Search for collections using semantic text search.
+         *
+         *     Use this endpoint to discover collections about a topic. Results are ranked by semantic similarity to your query.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /** @description Search query text */
+                        query: string;
+                        /**
+                         * @description Maximum results to return
+                         * @default 10
+                         */
+                        limit?: number;
+                        /** @description Filter by collection types */
+                        types?: string[];
+                    };
+                };
+            };
+            responses: {
+                /** @description Search results */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            results: {
+                                pi: string;
+                                label: string;
+                                type: string;
+                                score: number;
+                                created_at?: string;
+                                updated_at?: string;
+                            }[];
+                            metadata: {
+                                query: string;
+                                result_count: number;
+                            };
+                        };
+                    };
+                };
+                /** @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 Service Unavailable - External service not available */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Service unavailable",
+                         *       "details": {
+                         *         "service": "pinecone"
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/search/entities": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Search entities within collection(s)
+         * @description Search for entities within one or more collections using semantic text search.
+         *
+         *     Provide either `collection_pi` for a single collection or `collection_pis` for multiple collections (searched in parallel).
+         *
+         *     Use `per_collection_limit` to ensure result diversity when searching multiple collections.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /** @description Single collection PI to search within */
+                        collection_pi?: string;
+                        /** @description Multiple collection PIs to search (max 20) */
+                        collection_pis?: string[];
+                        /** @description Search query text */
+                        query: string;
+                        /**
+                         * @description Maximum total results to return
+                         * @default 20
+                         */
+                        limit?: number;
+                        /** @description Filter by entity types */
+                        types?: string[];
+                        /** @description Max results per collection for diversity */
+                        per_collection_limit?: number;
+                    };
+                };
+            };
+            responses: {
+                /** @description Search results */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            results: {
+                                pi: string;
+                                label: string;
+                                type: string;
+                                score: number;
+                                collection_pi: string;
+                                created_at?: string;
+                                updated_at?: string;
+                            }[];
+                            metadata: {
+                                collection_pis: string[];
+                                query: string;
+                                collections_searched: number;
+                                result_count: number;
+                            };
+                        };
+                    };
+                };
+                /** @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 Service Unavailable - External service not available */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Service unavailable",
+                         *       "details": {
+                         *         "service": "pinecone"
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/search/discover": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Discover entities across all collections
+         * @description Two-step discovery search: first finds relevant collections, then searches within them.
+         *
+         *     Use this endpoint when you don't know which collections to search. The system will:
+         *     1. Find collections semantically related to your query
+         *     2. Search within each collection in parallel
+         *     3. Aggregate and rank results across all collections
+         *
+         *     Great for exploration and AI agents navigating the network.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        /** @description Search query text */
+                        query: string;
+                        /**
+                         * @description Maximum total results to return
+                         * @default 20
+                         */
+                        limit?: number;
+                        /** @description Filter by entity types */
+                        types?: string[];
+                        /**
+                         * @description Number of collections to search
+                         * @default 10
+                         */
+                        collection_limit?: number;
+                        /**
+                         * @description Max results per collection
+                         * @default 5
+                         */
+                        per_collection_limit?: number;
+                    };
+                };
+            };
+            responses: {
+                /** @description Discovery results */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            results: {
+                                pi: string;
+                                label: string;
+                                type: string;
+                                score: number;
+                                collection_pi: string;
+                                created_at?: string;
+                                updated_at?: string;
+                            }[];
+                            metadata: {
+                                query: string;
+                                collections_searched: number;
+                                result_count: number;
+                            };
+                        };
+                    };
+                };
+                /** @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 Service Unavailable - External service not available */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        /**
+                         * @example {
+                         *       "error": "Service unavailable",
+                         *       "details": {
+                         *         "service": "pinecone"
+                         *       }
+                         *     }
+                         */
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/entities/{id}/attestation": {
         parameters: {
             query?: never;
@@ -7484,6 +7972,139 @@ type components = {
             /** @description Whether results were truncated due to limit */
             truncated: boolean;
         };
+        /** @description Metadata about the "from" version (null for version 1) */
+        VersionMeta: {
+            /**
+             * @description Content Identifier (CID) - content-addressed hash
+             * @example bafyreibug443cnd4endcwinwttw3c3dzmcl2ikht64xzn5qg56bix3usfy
+             */
+            cid: string;
+            /**
+             * @description Entity version number
+             * @example 1
+             */
+            ver: number;
+            /**
+             * Format: date-time
+             * @description ISO 8601 datetime
+             * @example 2025-12-26T12:00:00.000Z
+             */
+            ts: string;
+        } | null;
+        PropertyChange: {
+            /** @description Previous value */
+            from?: unknown;
+            /** @description New value */
+            to?: unknown;
+        };
+        PropertiesChanges: {
+            /**
+             * @description Properties that were added
+             * @example {
+             *       "email": "new@example.com"
+             *     }
+             */
+            added: {
+                [key: string]: unknown;
+            };
+            /**
+             * @description Properties that were removed (includes old values)
+             * @example {
+             *       "deprecated_field": "old value"
+             *     }
+             */
+            removed: {
+                [key: string]: unknown;
+            };
+            /**
+             * @description Properties that changed
+             * @example {
+             *       "name": {
+             *         "from": "Old Name",
+             *         "to": "New Name"
+             *       }
+             *     }
+             */
+            changed: {
+                [key: string]: components["schemas"]["PropertyChange"];
+            };
+        };
+        RelationshipChange: {
+            predicate: string;
+            peer: string;
+            peer_type?: string;
+            peer_label?: string;
+            properties: components["schemas"]["PropertyChange"];
+        };
+        RelationshipsChanges: {
+            /** @description Relationships that were added */
+            added: {
+                predicate: string;
+                peer: string;
+                peer_type?: string;
+                peer_label?: string;
+                properties?: {
+                    [key: string]: unknown;
+                };
+            }[];
+            /** @description Relationships that were removed */
+            removed: {
+                predicate: string;
+                peer: string;
+                peer_type?: string;
+                peer_label?: string;
+                properties?: {
+                    [key: string]: unknown;
+                };
+            }[];
+            /** @description Relationships with changed properties */
+            changed: components["schemas"]["RelationshipChange"][];
+        };
+        SemanticChanges: {
+            properties: components["schemas"]["PropertiesChanges"];
+            relationships: components["schemas"]["RelationshipsChanges"];
+        };
+        SemanticDiffResponse: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            entity_id: string;
+            from: components["schemas"]["VersionMeta"];
+            to: components["schemas"]["VersionMeta"];
+            /** @enum {string} */
+            format: "semantic";
+            changes: components["schemas"]["SemanticChanges"];
+        };
+        PatchOperation: {
+            /** @enum {string} */
+            op: "add";
+            path: string;
+            value?: unknown;
+        } | {
+            /** @enum {string} */
+            op: "remove";
+            path: string;
+        } | {
+            /** @enum {string} */
+            op: "replace";
+            path: string;
+            value?: unknown;
+        };
+        PatchDiffResponse: {
+            /**
+             * @description Entity ID (ULID format)
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            entity_id: string;
+            from: components["schemas"]["VersionMeta"];
+            to: components["schemas"]["VersionMeta"];
+            /** @enum {string} */
+            format: "patch";
+            /** @description RFC 6902 JSON Patch operations */
+            patch: components["schemas"]["PatchOperation"][];
+        };
+        DiffResponse: components["schemas"]["SemanticDiffResponse"] | components["schemas"]["PatchDiffResponse"];
         AddRelationshipResponse: {
             source: components["schemas"]["EntityResponse"] & unknown;
             target?: components["schemas"]["EntityResponse"] & unknown;