@arke-institute/sdk 2.3.2 → 2.3.4

package/dist/generated/index.d.cts

@@ -6,7 +6,7 @@
  *
  * Source: Arke v1 API
  * Version: 1.0.0
- * Generated: 2026-01-04T16:48:55.356Z
+ * Generated: 2026-01-05T14:48:23.714Z
  */
 type paths = {
     "/auth/register": {
@@ -1497,6 +1497,89 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/collections/{id}/entities": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List entities in a collection
+         * @description Returns entities belonging to this collection from the graph database.
+         *
+         *     Supports pagination and optional type filtering. Results are ordered by creation date (newest first).
+         */
+        get: {
+            parameters: {
+                query?: {
+                    type?: string;
+                    limit?: number;
+                    offset?: number | null;
+                };
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Entities in collection */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CollectionEntitiesResponse"];
+                    };
+                };
+                /** @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 GraphDB service unavailable */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/entities": {
         parameters: {
             query?: never;
@@ -4936,12 +5019,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
@@ -4951,8 +5039,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) */
@@ -5613,6 +5701,45 @@ type components = {
              */
             entity_id: string;
         };
+        CollectionEntitySummary: {
+            /** @description Entity persistent identifier */
+            pi: string;
+            /**
+             * @description Entity type
+             * @example document
+             */
+            type: string;
+            /**
+             * @description Entity display label
+             * @example My Document
+             */
+            label: string;
+            /**
+             * Format: date-time
+             * @description When the entity was created
+             */
+            created_at: string;
+            /**
+             * Format: date-time
+             * @description When the entity was last updated
+             */
+            updated_at: string;
+        };
+        CollectionEntitiesResponse: {
+            /** @description Collection ID */
+            collection_id: string;
+            /** @description Entities in this collection */
+            entities: components["schemas"]["CollectionEntitySummary"][];
+            /** @description Pagination info */
+            pagination: {
+                /** @description Current offset */
+                offset: number;
+                /** @description Requested limit */
+                limit: number;
+                /** @description Number of entities returned */
+                count: number;
+            };
+        };
         EntityCreatedResponse: {
             /**
              * @description Entity ID (ULID format)
@@ -7093,16 +7220,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-04T16:48:55.356Z
+ * Generated: 2026-01-05T14:48:23.714Z
  */
 type paths = {
     "/auth/register": {
@@ -1497,6 +1497,89 @@ type paths = {
         patch?: never;
         trace?: never;
     };
+    "/collections/{id}/entities": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List entities in a collection
+         * @description Returns entities belonging to this collection from the graph database.
+         *
+         *     Supports pagination and optional type filtering. Results are ordered by creation date (newest first).
+         */
+        get: {
+            parameters: {
+                query?: {
+                    type?: string;
+                    limit?: number;
+                    offset?: number | null;
+                };
+                header?: never;
+                path: {
+                    /** @description Entity ID (ULID) */
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Entities in collection */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CollectionEntitiesResponse"];
+                    };
+                };
+                /** @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 GraphDB service unavailable */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/entities": {
         parameters: {
             query?: never;
@@ -4936,12 +5019,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
@@ -4951,8 +5039,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) */
@@ -5613,6 +5701,45 @@ type components = {
              */
             entity_id: string;
         };
+        CollectionEntitySummary: {
+            /** @description Entity persistent identifier */
+            pi: string;
+            /**
+             * @description Entity type
+             * @example document
+             */
+            type: string;
+            /**
+             * @description Entity display label
+             * @example My Document
+             */
+            label: string;
+            /**
+             * Format: date-time
+             * @description When the entity was created
+             */
+            created_at: string;
+            /**
+             * Format: date-time
+             * @description When the entity was last updated
+             */
+            updated_at: string;
+        };
+        CollectionEntitiesResponse: {
+            /** @description Collection ID */
+            collection_id: string;
+            /** @description Entities in this collection */
+            entities: components["schemas"]["CollectionEntitySummary"][];
+            /** @description Pagination info */
+            pagination: {
+                /** @description Current offset */
+                offset: number;
+                /** @description Requested limit */
+                limit: number;
+                /** @description Number of entities returned */
+                count: number;
+            };
+        };
         EntityCreatedResponse: {
             /**
              * @description Entity ID (ULID format)
@@ -7093,16 +7220,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

@@ -1329,6 +1329,88 @@
           "entity_id"
         ]
       },
+      "CollectionEntitySummary": {
+        "type": "object",
+        "properties": {
+          "pi": {
+            "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 persistent identifier"
+          },
+          "type": {
+            "type": "string",
+            "description": "Entity type",
+            "example": "document"
+          },
+          "label": {
+            "type": "string",
+            "description": "Entity display label",
+            "example": "My Document"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the entity was created"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the entity was last updated"
+          }
+        },
+        "required": [
+          "pi",
+          "type",
+          "label",
+          "created_at",
+          "updated_at"
+        ]
+      },
+      "CollectionEntitiesResponse": {
+        "type": "object",
+        "properties": {
+          "collection_id": {
+            "type": "string",
+            "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
+            "description": "Collection ID"
+          },
+          "entities": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CollectionEntitySummary"
+            },
+            "description": "Entities in this collection"
+          },
+          "pagination": {
+            "type": "object",
+            "properties": {
+              "offset": {
+                "type": "integer",
+                "description": "Current offset"
+              },
+              "limit": {
+                "type": "integer",
+                "description": "Requested limit"
+              },
+              "count": {
+                "type": "integer",
+                "description": "Number of entities returned"
+              }
+            },
+            "required": [
+              "offset",
+              "limit",
+              "count"
+            ],
+            "description": "Pagination info"
+          }
+        },
+        "required": [
+          "collection_id",
+          "entities",
+          "pagination"
+        ]
+      },
       "EntityCreatedResponse": {
         "type": "object",
         "properties": {
@@ -4448,17 +4530,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": [
@@ -5983,6 +6065,108 @@
         }
       }
     },
+    "/collections/{id}/entities": {
+      "get": {
+        "tags": [
+          "Collections"
+        ],
+        "summary": "List entities in a collection",
+        "description": "Returns entities belonging to this collection from the graph database.\n\nSupports pagination and optional type filtering. Results are ordered by creation date (newest first).",
+        "x-arke-action": "collection: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"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Filter entities by type",
+              "example": "document"
+            },
+            "required": false,
+            "name": "type",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10000,
+              "default": 1000,
+              "description": "Maximum number of entities to return",
+              "example": 100
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "nullable": true,
+              "minimum": 0,
+              "default": 0,
+              "description": "Number of entities to skip",
+              "example": 0
+            },
+            "required": false,
+            "name": "offset",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Entities in collection",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CollectionEntitiesResponse"
+                }
+              }
+            }
+          },
+          "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"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "GraphDB service unavailable"
+          }
+        }
+      }
+    },
     "/entities": {
       "post": {
         "tags": [
@@ -9325,20 +9509,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-04T16:48:54.559Z",
+  "fetchedAt": "2026-01-05T14:48:22.954Z",
   "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.2",
+  "version": "2.3.4",
   "description": "TypeScript SDK for the Arke API - auto-generated from OpenAPI spec",
   "type": "module",
   "main": "dist/index.cjs",