@proveanything/smartlinks 1.5.3 → 1.5.4

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.5.3  |  Generated: 2026-02-25T13:03:38.388Z
+Version: 1.5.4  |  Generated: 2026-02-26T07:46:52.121Z
 
 This is a concise summary of all available API functions and types.
 

package/dist/docs/app-objects.md

@@ -130,6 +130,92 @@ await app.records.create(collectionId, appId, {
 
 ---
 
+## Paginated List Responses
+
+Every `.list()` call returns a **`PaginatedResponse<T>`** object. The items are in the `data` array and all page-level metadata lives in a nested `pagination` object:
+
+```json
+{
+  "data": [
+    {
+      "id": "7ac44316-c227-4c39-bf99-a287bc08c6f5",
+      "collectionId": "veho-demo",
+      "appId": "knowledgeBase",
+      "visibility": "public",
+      "recordType": "article",
+      "status": "published",
+      "createdAt": "2026-02-25T22:13:14.310Z",
+      "updatedAt": "2026-02-25T22:47:36.712Z",
+      "data": {
+        "title": "Getting Started",
+        "slug": "getting-started",
+        "body": "..."
+      }
+    }
+  ],
+  "pagination": {
+    "total": 42,
+    "limit": 10,
+    "offset": 0,
+    "hasMore": true
+  }
+}
+```
+
+### Pagination fields
+
+| Field | Type | Description |
+|---|---|---|
+| `data` | `T[]` | The page of items returned |
+| `pagination.total` | `number` | Total number of matching records across **all** pages |
+| `pagination.limit` | `number` | The `limit` that was applied to this request (default `50`, max `500`) |
+| `pagination.offset` | `number` | The `offset` that was applied to this request |
+| `pagination.hasMore` | `boolean` | `true` when more pages exist — use this instead of computing `offset + limit < total` yourself |
+
+> **Note:** The items are always in `response.data`, **not** at the top level. A common mistake is reading `response.total` — the correct path is `response.pagination.total`.
+
+### Fetching all pages
+
+```typescript
+import { app, PaginatedResponse, AppRecord } from '@proveanything/smartlinks';
+
+async function fetchAllRecords(collectionId: string, appId: string) {
+  const results: AppRecord[] = [];
+  let offset = 0;
+  const limit = 100;
+
+  while (true) {
+    const page: PaginatedResponse<AppRecord> = await app.records.list(
+      collectionId,
+      appId,
+      { limit, offset, sort: 'createdAt:desc' }
+    );
+
+    results.push(...page.data);
+
+    if (!page.pagination.hasMore) break;  // no more pages
+    offset += limit;
+  }
+
+  console.log(`Fetched ${results.length} of ${/* saved from first page */ 0} total`);
+  return results;
+}
+```
+
+### Reading the count and checking for more
+
+```typescript
+const page = await app.cases.list(collectionId, appId, { status: 'open', limit: 10 });
+
+console.log(page.data);                   // array of AppCase objects
+console.log(page.pagination.total);       // e.g. 142  — total open cases
+console.log(page.pagination.hasMore);     // true / false
+console.log(page.pagination.offset);      // current page start
+console.log(page.pagination.limit);       // items per page
+```
+
+---
+
 ## Cases
 
 **Cases** represent trackable issues, requests, or tasks that move through states and require resolution.

package/dist/types/appObjects.d.ts

@@ -7,13 +7,33 @@ export type Visibility = 'public' | 'owner' | 'admin';
  */
 export type CallerRole = 'admin' | 'owner' | 'public';
 /**
- * Paginated response wrapper for list endpoints
+ * Paginated response wrapper for list endpoints.
+ *
+ * All list endpoints return this shape:
+ * ```json
+ * {
+ *   "data": [ ...items ],
+ *   "pagination": {
+ *     "total":   142,
+ *     "limit":   10,
+ *     "offset":  0,
+ *     "hasMore": true
+ *   }
+ * }
+ * ```
  */
 export interface PaginatedResponse<T> {
     data: T[];
-    total: number;
-    limit: number;
-    offset: number;
+    pagination: {
+        /** Total number of matching records in the collection */
+        total: number;
+        /** Maximum number of items returned in this page */
+        limit: number;
+        /** Number of items skipped before this page */
+        offset: number;
+        /** `true` when more pages are available (offset + limit < total) */
+        hasMore: boolean;
+    };
 }
 /**
  * Request body for aggregate endpoints

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.5.3  |  Generated: 2026-02-25T13:03:38.388Z
+Version: 1.5.4  |  Generated: 2026-02-26T07:46:52.121Z
 
 This is a concise summary of all available API functions and types.
 

package/docs/app-objects.md

@@ -130,6 +130,92 @@ await app.records.create(collectionId, appId, {
 
 ---
 
+## Paginated List Responses
+
+Every `.list()` call returns a **`PaginatedResponse<T>`** object. The items are in the `data` array and all page-level metadata lives in a nested `pagination` object:
+
+```json
+{
+  "data": [
+    {
+      "id": "7ac44316-c227-4c39-bf99-a287bc08c6f5",
+      "collectionId": "veho-demo",
+      "appId": "knowledgeBase",
+      "visibility": "public",
+      "recordType": "article",
+      "status": "published",
+      "createdAt": "2026-02-25T22:13:14.310Z",
+      "updatedAt": "2026-02-25T22:47:36.712Z",
+      "data": {
+        "title": "Getting Started",
+        "slug": "getting-started",
+        "body": "..."
+      }
+    }
+  ],
+  "pagination": {
+    "total": 42,
+    "limit": 10,
+    "offset": 0,
+    "hasMore": true
+  }
+}
+```
+
+### Pagination fields
+
+| Field | Type | Description |
+|---|---|---|
+| `data` | `T[]` | The page of items returned |
+| `pagination.total` | `number` | Total number of matching records across **all** pages |
+| `pagination.limit` | `number` | The `limit` that was applied to this request (default `50`, max `500`) |
+| `pagination.offset` | `number` | The `offset` that was applied to this request |
+| `pagination.hasMore` | `boolean` | `true` when more pages exist — use this instead of computing `offset + limit < total` yourself |
+
+> **Note:** The items are always in `response.data`, **not** at the top level. A common mistake is reading `response.total` — the correct path is `response.pagination.total`.
+
+### Fetching all pages
+
+```typescript
+import { app, PaginatedResponse, AppRecord } from '@proveanything/smartlinks';
+
+async function fetchAllRecords(collectionId: string, appId: string) {
+  const results: AppRecord[] = [];
+  let offset = 0;
+  const limit = 100;
+
+  while (true) {
+    const page: PaginatedResponse<AppRecord> = await app.records.list(
+      collectionId,
+      appId,
+      { limit, offset, sort: 'createdAt:desc' }
+    );
+
+    results.push(...page.data);
+
+    if (!page.pagination.hasMore) break;  // no more pages
+    offset += limit;
+  }
+
+  console.log(`Fetched ${results.length} of ${/* saved from first page */ 0} total`);
+  return results;
+}
+```
+
+### Reading the count and checking for more
+
+```typescript
+const page = await app.cases.list(collectionId, appId, { status: 'open', limit: 10 });
+
+console.log(page.data);                   // array of AppCase objects
+console.log(page.pagination.total);       // e.g. 142  — total open cases
+console.log(page.pagination.hasMore);     // true / false
+console.log(page.pagination.offset);      // current page start
+console.log(page.pagination.limit);       // items per page
+```
+
+---
+
 ## Cases
 
 **Cases** represent trackable issues, requests, or tasks that move through states and require resolution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",