@arke-institute/sdk 2.3.1 → 2.3.3

package/dist/generated/index.d.cts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-04T14:33:00.781Z
+ * Generated: 2026-01-04T18:00:08.698Z
  */
 type paths = {
     "/auth/register": {
@@ -2042,6 +2042,76 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/entities/{id}/collection": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get entity collection
+         * @description Returns the collection ID that this entity belongs to. Returns null if the entity is not in any collection. If the entity IS a collection, returns its own ID.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Collection lookup result */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["EntityCollectionResponse"];
+                    };
+                };
+                /** @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;
@@ -4866,12 +4936,17 @@ type paths = {
          * @description Returns a cursor-based list of entity change events for client synchronization.
          *
          *     **Usage:**
-         *     - Start with `?after=0` to get all events
-         *     - Use the returned `cursor` as `?after=` for the next page
-         *     - Poll periodically (e.g., every 10s) to stay in sync
+         *     - Call without cursor to get newest events
+         *     - Use returned `cursor` as `?cursor=` to get older events
+         *     - Poll without cursor periodically to check for new events
+         *
+         *     **Sync flow:**
+         *     1. Initial: `GET /events` → get newest, save highest `id` as high-water mark
+         *     2. Paginate: `GET /events?cursor=X` → get older events until `has_more=false`
+         *     3. Poll: `GET /events` → if newest `id` > high-water mark, process new events
          *
          *     **Event data:**
-         *     - `id`: Auto-increment ID (use as cursor)
+         *     - `id`: Auto-increment ID
          *     - `pi`: Entity ID that changed
          *     - `cid`: New manifest CID
          *     - `ts`: ISO timestamp
@@ -4881,8 +4956,8 @@ type paths = {
         get: {
             parameters: {
                 query?: {
-                    /** @description Return events with id > after (cursor for pagination) */
-                    after?: number | null;
+                    /** @description Return events older than this id (from previous response cursor) */
+                    cursor?: number;
                     /** @description Maximum number of events to return (default: 100, max: 1000) */
                     limit?: number;
                     /** @description Network to query (default: main) */
@@ -5784,6 +5859,13 @@ type components = {
              */
             note?: string;
         };
+        EntityCollectionResponse: {
+            /**
+             * @description The collection ID this entity belongs to, or null if not in any collection
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            collection_id: string | null;
+        };
         AddRelationshipResponse: {
             source: components["schemas"]["EntityResponse"] & unknown;
             target?: components["schemas"]["EntityResponse"] & unknown;
@@ -7016,16 +7098,16 @@ type components = {
             ts: string;
         };
         EventsListResponse: {
-            /** @description List of events */
+            /** @description List of events (newest first) */
             events: components["schemas"]["Event"][];
             /**
-             * @description Whether there are more events available
+             * @description Whether there are more (older) events available
              * @example true
              */
             has_more: boolean;
             /**
-             * @description Cursor for the next page (pass as ?after= parameter)
-             * @example 12347
+             * @description Cursor for the next page (oldest id in batch, pass as ?cursor= for older events)
+             * @example 12340
              */
             cursor: number;
         };

package/dist/generated/index.d.ts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-04T14:33:00.781Z
+ * Generated: 2026-01-04T18:00:08.698Z
  */
 type paths = {
     "/auth/register": {
@@ -2042,6 +2042,76 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/entities/{id}/collection": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get entity collection
+         * @description Returns the collection ID that this entity belongs to. Returns null if the entity is not in any collection. If the entity IS a collection, returns its own ID.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Collection lookup result */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["EntityCollectionResponse"];
+                    };
+                };
+                /** @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;
@@ -4866,12 +4936,17 @@ type paths = {
          * @description Returns a cursor-based list of entity change events for client synchronization.
          *
          *     **Usage:**
-         *     - Start with `?after=0` to get all events
-         *     - Use the returned `cursor` as `?after=` for the next page
-         *     - Poll periodically (e.g., every 10s) to stay in sync
+         *     - Call without cursor to get newest events
+         *     - Use returned `cursor` as `?cursor=` to get older events
+         *     - Poll without cursor periodically to check for new events
+         *
+         *     **Sync flow:**
+         *     1. Initial: `GET /events` → get newest, save highest `id` as high-water mark
+         *     2. Paginate: `GET /events?cursor=X` → get older events until `has_more=false`
+         *     3. Poll: `GET /events` → if newest `id` > high-water mark, process new events
          *
          *     **Event data:**
-         *     - `id`: Auto-increment ID (use as cursor)
+         *     - `id`: Auto-increment ID
          *     - `pi`: Entity ID that changed
          *     - `cid`: New manifest CID
          *     - `ts`: ISO timestamp
@@ -4881,8 +4956,8 @@ type paths = {
         get: {
             parameters: {
                 query?: {
-                    /** @description Return events with id > after (cursor for pagination) */
-                    after?: number | null;
+                    /** @description Return events older than this id (from previous response cursor) */
+                    cursor?: number;
                     /** @description Maximum number of events to return (default: 100, max: 1000) */
                     limit?: number;
                     /** @description Network to query (default: main) */
@@ -5784,6 +5859,13 @@ type components = {
              */
             note?: string;
         };
+        EntityCollectionResponse: {
+            /**
+             * @description The collection ID this entity belongs to, or null if not in any collection
+             * @example 01KDETYWYWM0MJVKM8DK3AEXPY
+             */
+            collection_id: string | null;
+        };
         AddRelationshipResponse: {
             source: components["schemas"]["EntityResponse"] & unknown;
             target?: components["schemas"]["EntityResponse"] & unknown;
@@ -7016,16 +7098,16 @@ type components = {
             ts: string;
         };
         EventsListResponse: {
-            /** @description List of events */
+            /** @description List of events (newest first) */
             events: components["schemas"]["Event"][];
             /**
-             * @description Whether there are more events available
+             * @description Whether there are more (older) events available
              * @example true
              */
             has_more: boolean;
             /**
-             * @description Cursor for the next page (pass as ?after= parameter)
-             * @example 12347
+             * @description Cursor for the next page (oldest id in batch, pass as ?cursor= for older events)
+             * @example 12340
              */
             cursor: number;
         };

package/openapi/spec.json

@@ -1802,6 +1802,20 @@
           "expect_tip"
         ]
       },
+      "EntityCollectionResponse": {
+        "type": "object",
+        "properties": {
+          "collection_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "The collection ID this entity belongs to, or null if not in any collection",
+            "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+          }
+        },
+        "required": [
+          "collection_id"
+        ]
+      },
       "AddRelationshipResponse": {
         "type": "object",
         "properties": {
@@ -4434,17 +4448,17 @@
             "items": {
               "$ref": "#/components/schemas/Event"
             },
-            "description": "List of events"
+            "description": "List of events (newest first)"
           },
           "has_more": {
             "type": "boolean",
-            "description": "Whether there are more events available",
+            "description": "Whether there are more (older) events available",
             "example": true
           },
           "cursor": {
             "type": "integer",
-            "description": "Cursor for the next page (pass as ?after= parameter)",
-            "example": 12347
+            "description": "Cursor for the next page (oldest id in batch, pass as ?cursor= for older events)",
+            "example": 12340
           }
         },
         "required": [
@@ -6525,6 +6539,69 @@
         }
       }
     },
+    "/entities/{id}/collection": {
+      "get": {
+        "tags": [
+          "Entities"
+        ],
+        "summary": "Get entity collection",
+        "description": "Returns the collection ID that this entity belongs to. Returns null if the entity is not in any collection. If the entity IS a collection, returns its own ID.",
+        "x-arke-action": "entity:view",
+        "x-arke-auth": "optional",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
+              "description": "Entity ID (ULID format)",
+              "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+            },
+            "required": true,
+            "description": "Entity ID (ULID)",
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Collection lookup result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/EntityCollectionResponse"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden - Insufficient permissions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "error": "Forbidden: You do not have permission to perform this action"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not Found - Resource does not exist",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "example": {
+                  "error": "Entity not found"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/relationships": {
       "post": {
         "tags": [
@@ -9248,20 +9325,19 @@
           "Events"
         ],
         "summary": "List entity change events",
-        "description": "Returns a cursor-based list of entity change events for client synchronization.\n\n**Usage:**\n- Start with `?after=0` to get all events\n- Use the returned `cursor` as `?after=` for the next page\n- Poll periodically (e.g., every 10s) to stay in sync\n\n**Event data:**\n- `id`: Auto-increment ID (use as cursor)\n- `pi`: Entity ID that changed\n- `cid`: New manifest CID\n- `ts`: ISO timestamp\n\nEvents are ephemeral (30-day rolling window) - for full sync, use snapshots.",
+        "description": "Returns a cursor-based list of entity change events for client synchronization.\n\n**Usage:**\n- Call without cursor to get newest events\n- Use returned `cursor` as `?cursor=` to get older events\n- Poll without cursor periodically to check for new events\n\n**Sync flow:**\n1. Initial: `GET /events` → get newest, save highest `id` as high-water mark\n2. Paginate: `GET /events?cursor=X` → get older events until `has_more=false`\n3. Poll: `GET /events` → if newest `id` > high-water mark, process new events\n\n**Event data:**\n- `id`: Auto-increment ID\n- `pi`: Entity ID that changed\n- `cid`: New manifest CID\n- `ts`: ISO timestamp\n\nEvents are ephemeral (30-day rolling window) - for full sync, use snapshots.",
         "x-arke-action": "events:list",
         "x-arke-auth": "none",
         "parameters": [
           {
             "schema": {
               "type": "integer",
-              "nullable": true,
-              "minimum": 0,
+              "minimum": 1,
               "example": 12345
             },
             "required": false,
-            "description": "Return events with id > after (cursor for pagination)",
-            "name": "after",
+            "description": "Return events older than this id (from previous response cursor)",
+            "name": "cursor",
             "in": "query"
           },
           {

package/openapi/version.json

@@ -1,7 +1,7 @@
 {
   "specVersion": "1.0.0",
   "apiVersion": "1.0.0",
-  "fetchedAt": "2026-01-04T14:32:59.979Z",
+  "fetchedAt": "2026-01-04T18:00:07.945Z",
   "sourceUrl": "https://arke-v1.arke.institute/openapi.json",
   "openApiVersion": "3.1.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arke-institute/sdk",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "TypeScript SDK for the Arke API - auto-generated from OpenAPI spec",
   "type": "module",
   "main": "dist/index.cjs",