@functional-systems/lambdadb 0.3.0-dev.1 → 0.3.0-dev.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/README.md +149 -38
  2. package/dist/commonjs/client.d.ts +108 -18
  3. package/dist/commonjs/client.d.ts.map +1 -1
  4. package/dist/commonjs/client.js +220 -2
  5. package/dist/commonjs/client.js.map +1 -1
  6. package/dist/commonjs/index.d.ts +16 -1
  7. package/dist/commonjs/index.d.ts.map +1 -1
  8. package/dist/commonjs/index.js +10 -2
  9. package/dist/commonjs/index.js.map +1 -1
  10. package/dist/commonjs/lib/config.d.ts +4 -2
  11. package/dist/commonjs/lib/config.d.ts.map +1 -1
  12. package/dist/commonjs/lib/config.js.map +1 -1
  13. package/dist/commonjs/lib/queryInput.d.ts +30 -0
  14. package/dist/commonjs/lib/queryInput.d.ts.map +1 -0
  15. package/dist/commonjs/lib/queryInput.js +18 -0
  16. package/dist/commonjs/lib/queryInput.js.map +1 -0
  17. package/dist/commonjs/sdk/collections.d.ts +3 -0
  18. package/dist/commonjs/sdk/collections.d.ts.map +1 -1
  19. package/dist/commonjs/sdk/collections.js +3 -0
  20. package/dist/commonjs/sdk/collections.js.map +1 -1
  21. package/dist/commonjs/sdk/docs.d.ts +3 -0
  22. package/dist/commonjs/sdk/docs.d.ts.map +1 -1
  23. package/dist/commonjs/sdk/docs.js +3 -0
  24. package/dist/commonjs/sdk/docs.js.map +1 -1
  25. package/dist/commonjs/sdk/sdk.d.ts +3 -0
  26. package/dist/commonjs/sdk/sdk.d.ts.map +1 -1
  27. package/dist/commonjs/sdk/sdk.js +3 -0
  28. package/dist/commonjs/sdk/sdk.js.map +1 -1
  29. package/dist/commonjs/types/errors.d.ts +34 -0
  30. package/dist/commonjs/types/errors.d.ts.map +1 -0
  31. package/dist/commonjs/types/errors.js +27 -0
  32. package/dist/commonjs/types/errors.js.map +1 -0
  33. package/dist/commonjs/types/public.d.ts +26 -0
  34. package/dist/commonjs/types/public.d.ts.map +1 -0
  35. package/dist/commonjs/types/public.js +7 -0
  36. package/dist/commonjs/types/public.js.map +1 -0
  37. package/dist/esm/client.d.ts +108 -18
  38. package/dist/esm/client.d.ts.map +1 -1
  39. package/dist/esm/client.js +221 -3
  40. package/dist/esm/client.js.map +1 -1
  41. package/dist/esm/index.d.ts +16 -1
  42. package/dist/esm/index.d.ts.map +1 -1
  43. package/dist/esm/index.js +6 -1
  44. package/dist/esm/index.js.map +1 -1
  45. package/dist/esm/lib/config.d.ts +4 -2
  46. package/dist/esm/lib/config.d.ts.map +1 -1
  47. package/dist/esm/lib/config.js.map +1 -1
  48. package/dist/esm/lib/queryInput.d.ts +30 -0
  49. package/dist/esm/lib/queryInput.d.ts.map +1 -0
  50. package/dist/esm/lib/queryInput.js +15 -0
  51. package/dist/esm/lib/queryInput.js.map +1 -0
  52. package/dist/esm/sdk/collections.d.ts +3 -0
  53. package/dist/esm/sdk/collections.d.ts.map +1 -1
  54. package/dist/esm/sdk/collections.js +3 -0
  55. package/dist/esm/sdk/collections.js.map +1 -1
  56. package/dist/esm/sdk/docs.d.ts +3 -0
  57. package/dist/esm/sdk/docs.d.ts.map +1 -1
  58. package/dist/esm/sdk/docs.js +3 -0
  59. package/dist/esm/sdk/docs.js.map +1 -1
  60. package/dist/esm/sdk/sdk.d.ts +3 -0
  61. package/dist/esm/sdk/sdk.d.ts.map +1 -1
  62. package/dist/esm/sdk/sdk.js +3 -0
  63. package/dist/esm/sdk/sdk.js.map +1 -1
  64. package/dist/esm/types/errors.d.ts +34 -0
  65. package/dist/esm/types/errors.d.ts.map +1 -0
  66. package/dist/esm/types/errors.js +8 -0
  67. package/dist/esm/types/errors.js.map +1 -0
  68. package/dist/esm/types/public.d.ts +26 -0
  69. package/dist/esm/types/public.d.ts.map +1 -0
  70. package/dist/esm/types/public.js +6 -0
  71. package/dist/esm/types/public.js.map +1 -0
  72. package/examples/collectionScoped.example.ts +9 -3
  73. package/examples/collectionsList.example.ts +5 -2
  74. package/package.json +1 -1
  75. package/src/client.ts +410 -19
  76. package/src/index.ts +25 -1
  77. package/src/lib/config.ts +4 -2
  78. package/src/lib/queryInput.ts +33 -0
  79. package/src/sdk/collections.ts +3 -0
  80. package/src/sdk/docs.ts +3 -0
  81. package/src/sdk/sdk.ts +3 -0
  82. package/src/types/errors.ts +97 -0
  83. package/src/types/public.ts +45 -0
package/README.md CHANGED
@@ -83,11 +83,14 @@ We recommend the **collection-scoped client** (`LambdaDBClient`): you get a hand
83
83
 
84
84
  ### Recommended: LambdaDBClient (collection-scoped)
85
85
 
86
+ The client connects to `{baseUrl}/projects/{projectName}`. Defaults: **baseUrl** `https://api.lambdadb.ai`, **projectName** `playground`. Override with `baseUrl` and `projectName` when creating the client.
87
+
86
88
  ```typescript
87
89
  import { LambdaDBClient } from "@functional-systems/lambdadb";
88
90
 
89
91
  const client = new LambdaDBClient({
90
92
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
93
+ // Optional: baseUrl (default "https://api.lambdadb.ai"), projectName (default "playground")
91
94
  });
92
95
 
93
96
  async function run() {
@@ -100,10 +103,78 @@ async function run() {
100
103
  await collection.get();
101
104
  await collection.docs.list({ size: 20 });
102
105
  await collection.docs.upsert({ docs: [{ id: "1", text: "hello" }] });
106
+ // For large document sets (up to 200MB), use bulkUpsertDocs for a single-call flow
107
+ // await collection.docs.bulkUpsertDocs({ docs: largeDocArray });
103
108
  }
104
109
 
105
110
  run();
106
111
  ```
112
+
113
+ ### TypeScript types
114
+
115
+ Import request and response types from the package for type-safe usage. Use the **input** types for method arguments and the **response** types for return values.
116
+
117
+ ```typescript
118
+ import {
119
+ LambdaDBClient,
120
+ type CreateCollectionInput,
121
+ type QueryCollectionInput,
122
+ type QueryCollectionResponse,
123
+ type ListDocsInput,
124
+ type ListDocsResponse,
125
+ } from "@functional-systems/lambdadb";
126
+
127
+ const client = new LambdaDBClient({ projectApiKey: "..." });
128
+ const collection = client.collection("my-collection");
129
+
130
+ // Typed list params
131
+ const params: ListDocsInput = { size: 20, pageToken: undefined };
132
+ const listResult: ListDocsResponse = await collection.docs.list(params);
133
+
134
+ // Typed query body and response (or use createQueryInput helper)
135
+ const queryBody: QueryCollectionInput = {
136
+ query: { text: "hello" },
137
+ size: 10,
138
+ };
139
+ const queryResult: QueryCollectionResponse = await collection.query(queryBody);
140
+ ```
141
+
142
+ Common types: `CreateCollectionInput`, `UpdateCollectionInput`, `QueryCollectionInput`, `ListDocsInput`, `UpsertDocsInput`, `DeleteDocsInput`, `FetchDocsInput`, `BulkUpsertInput`; response types such as `QueryCollectionResponse`, `ListDocsResponse`, `FetchDocsResponse`, `MessageResponse`; and model types like `IndexConfigsUnion`, `PartitionConfig`, `FieldsSelectorUnion`. All are exported from the main package.
143
+
144
+ ### Pagination
145
+
146
+ Use `listPages()` to iterate over all pages without loading everything into memory, or `listAll()` to fetch all docs into a single list. Each page is one API response; the API limits response size by **payload**, not by document count, so the number of docs per page may be less than the requested `size` and can vary from page to page.
147
+
148
+ ```typescript
149
+ import { LambdaDBClient } from "@functional-systems/lambdadb";
150
+
151
+ const client = new LambdaDBClient({ projectApiKey: "..." });
152
+ const collection = client.collection("my-collection");
153
+
154
+ // Page-by-page (memory efficient)
155
+ for await (const page of collection.docs.listPages({ size: 50 })) {
156
+ console.log(page.docs.length, page.nextPageToken ?? "last page");
157
+ }
158
+
159
+ // Or load all docs (for small/medium collections)
160
+ const { docs, total } = await collection.docs.listAll({ size: 100 });
161
+ console.log(docs.length, total);
162
+ ```
163
+
164
+ ### Query helper
165
+
166
+ Use `createQueryInput()` to build query parameters for `collection.query()` or `collection.querySafe()`:
167
+
168
+ ```typescript
169
+ import { LambdaDBClient, createQueryInput } from "@functional-systems/lambdadb";
170
+
171
+ const client = new LambdaDBClient({ projectApiKey: "..." });
172
+ const collection = client.collection("my-collection");
173
+
174
+ const input = createQueryInput({ text: "hello" }, { size: 10 });
175
+ const result = await collection.query(input);
176
+ ```
177
+
107
178
  <!-- End SDK Example Usage [usage] -->
108
179
 
109
180
  <!-- Start Authentication [security] -->
@@ -153,6 +224,7 @@ run();
153
224
 
154
225
  * [listDocs](docs/sdks/docs/README.md#listdocs) - List documents in a collection.
155
226
  * [upsert](docs/sdks/docs/README.md#upsert) - Upsert documents into a collection. Note that the maximum supported payload size is 6MB.
227
+ * [bulkUpsertDocs](docs/sdks/docs/README.md#bulkupsertdocs) - Bulk upsert documents in one call (up to 200MB); use this for best DX when you have a document list.
156
228
  * [getBulkUpsert](docs/sdks/docs/README.md#getbulkupsert) - Request required info to upload documents.
157
229
  * [bulkUpsert](docs/sdks/docs/README.md#bulkupsert) - Bulk upsert documents into a collection. Note that the maximum supported object size is 200MB.
158
230
  * [update](docs/sdks/docs/README.md#update) - Update documents in a collection. Note that the maximum supported payload size is 6MB.
@@ -266,6 +338,22 @@ async function run() {
266
338
  run();
267
339
 
268
340
  ```
341
+
342
+ **Timeout and request-level options:** You can set a request timeout (ms) and retry behavior when creating the client or per call. If not set, there is no request timeout. The `RetryConfig` type is exported from the package for typing your options.
343
+
344
+ ```typescript
345
+ import { LambdaDBClient, type RetryConfig } from "@functional-systems/lambdadb";
346
+
347
+ const client = new LambdaDBClient({
348
+ projectApiKey: "...",
349
+ timeoutMs: 30_000, // 30s timeout for all requests
350
+ retryConfig: { strategy: "backoff", retryConnectionErrors: true },
351
+ });
352
+
353
+ // Override per request
354
+ await client.listCollections({ timeoutMs: 10_000, retries: { strategy: "none" } });
355
+ ```
356
+
269
357
  <!-- End Retries [retries] -->
270
358
 
271
359
  <!-- Start Error Handling [errors] -->
@@ -282,10 +370,17 @@ run();
282
370
  | `error.rawResponse` | `Response` | Raw HTTP response |
283
371
  | `error.data$` | | Optional. Some errors may contain structured data. [See Error Classes](#error-classes). |
284
372
 
285
- ### Example
373
+ ### Default methods (throw on error)
374
+
375
+ Regular methods throw on failure. Catch errors and use `instanceof` to narrow types. Error classes are exported from the main package:
376
+
286
377
  ```typescript
287
- import { LambdaDBClient } from "@functional-systems/lambdadb";
288
- import * as errors from "@functional-systems/lambdadb/models/errors";
378
+ import {
379
+ LambdaDBClient,
380
+ LambdaDBError,
381
+ UnauthenticatedError,
382
+ ResourceNotFoundError,
383
+ } from "@functional-systems/lambdadb";
289
384
 
290
385
  const client = new LambdaDBClient({
291
386
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
@@ -296,25 +391,49 @@ async function run() {
296
391
  const result = await client.listCollections();
297
392
  console.log(result);
298
393
  } catch (error) {
299
- // The base class for HTTP error responses
300
- if (error instanceof errors.LambdaDBError) {
301
- console.log(error.message);
302
- console.log(error.statusCode);
303
- console.log(error.body);
304
- console.log(error.headers);
305
-
306
- // Depending on the method different errors may be thrown
307
- if (error instanceof errors.UnauthenticatedError) {
308
- console.log(error.data$.message); // string
394
+ if (error instanceof LambdaDBError) {
395
+ console.log(error.message, error.statusCode, error.body);
396
+ if (error instanceof UnauthenticatedError) {
397
+ console.log(error.data$.message);
398
+ }
399
+ if (error instanceof ResourceNotFoundError) {
400
+ console.log("Not found:", error.data$);
309
401
  }
310
402
  }
311
403
  }
312
404
  }
313
405
 
314
406
  run();
407
+ ```
408
+
409
+ ### Safe methods (return Result)
315
410
 
411
+ Use `*Safe` methods to get a `Result<T, E>` instead of throwing. You can handle errors without try/catch and narrow with type guards:
412
+
413
+ ```typescript
414
+ import {
415
+ LambdaDBClient,
416
+ Result,
417
+ ResourceNotFoundError,
418
+ } from "@functional-systems/lambdadb";
419
+
420
+ const client = new LambdaDBClient({ projectApiKey: "..." });
421
+
422
+ const result = await client.listCollectionsSafe();
423
+ if (result.ok) {
424
+ console.log(result.value.collections);
425
+ } else {
426
+ const err = result.error;
427
+ if (err instanceof ResourceNotFoundError) {
428
+ console.log("Not found:", err.data$);
429
+ } else {
430
+ console.error(err);
431
+ }
432
+ }
316
433
  ```
317
434
 
435
+ Available Safe methods: `listCollectionsSafe`, `createCollectionSafe`, `collection.getSafe`, `collection.updateSafe`, `collection.deleteSafe`, `collection.querySafe`, `collection.docs.listSafe`, `collection.docs.upsertSafe`, `collection.docs.updateSafe`, `collection.docs.deleteSafe`, `collection.docs.fetchSafe`, `collection.docs.getBulkUpsertSafe`, `collection.docs.bulkUpsertSafe`, `collection.docs.bulkUpsertDocsSafe`. The `Result` type and `OK` / `ERR` helpers are exported from the package.
436
+
318
437
  ### Error Classes
319
438
  **Primary errors:**
320
439
  * [`LambdaDBError`](./src/models/errors/lambdadberror.ts): The base class for HTTP error responses.
@@ -346,52 +465,44 @@ run();
346
465
  <!-- End Error Handling [errors] -->
347
466
 
348
467
  <!-- Start Server Selection [server] -->
349
- ## Server Selection
468
+ ## Server Selection (API base URL)
350
469
 
351
- ### Server Variables
470
+ `LambdaDBClient` builds the API base as **`{baseUrl}/projects/{projectName}`**. You can override the defaults when creating the client.
352
471
 
353
- The default server `https://{projectHost}` contains variables and is set to `https://api.lambdadb.com/projects/default` by default. To override default values, the following parameters are available when initializing the SDK client instance:
472
+ | Option | Type | Default | Description |
473
+ | -------------- | -------- | --------------------------- | ------------------------------------ |
474
+ | `baseUrl` | `string` | `"https://api.lambdadb.ai"` | API base URL (no trailing slash). |
475
+ | `projectName` | `string` | `"playground"` | Project name (path segment). |
476
+ | `serverURL` | `string` | — | Full base URL (overrides baseUrl + projectName). |
477
+ | `projectHost` | `string` | — | Legacy: host path for URL (e.g. `api.lambdadb.ai/projects/my-project`). |
354
478
 
355
- | Variable | Parameter | Default | Description |
356
- | ------------- | --------------------- | ------------------------------------- | -------------------------- |
357
- | `projectHost` | `projectHost: string` | `"api.lambdadb.com/projects/default"` | The project URL of the API |
358
-
359
- #### Example
479
+ ### Using baseUrl and projectName (recommended)
360
480
 
361
481
  ```typescript
362
482
  import { LambdaDBClient } from "@functional-systems/lambdadb";
363
483
 
364
484
  const client = new LambdaDBClient({
365
- serverIdx: 0,
366
- projectHost: "api.lambdadb.com/projects/default",
367
485
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
486
+ baseUrl: "https://api.lambdadb.ai",
487
+ projectName: "my-project",
368
488
  });
369
489
 
370
- async function run() {
371
- const result = await client.listCollections();
372
- console.log(result);
373
- }
374
-
375
- run();
490
+ const result = await client.listCollections();
376
491
  ```
377
492
 
378
- ### Override Server URL Per-Client
493
+ ### Override with full server URL
494
+
495
+ To set the base URL in one go, use `serverURL`:
379
496
 
380
- The default server can be overridden globally by passing a URL to the `serverURL: string` optional parameter when initializing the SDK client instance. For example:
381
497
  ```typescript
382
498
  import { LambdaDBClient } from "@functional-systems/lambdadb";
383
499
 
384
500
  const client = new LambdaDBClient({
385
- serverURL: "https://api.lambdadb.com/projects/default",
501
+ serverURL: "https://api.lambdadb.ai/projects/my-project",
386
502
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
387
503
  });
388
504
 
389
- async function run() {
390
- const result = await client.listCollections();
391
- console.log(result);
392
- }
393
-
394
- run();
505
+ const result = await client.listCollections();
395
506
  ```
396
507
  <!-- End Server Selection [server] -->
397
508
 
@@ -12,9 +12,16 @@
12
12
  import { LambdaDBCore } from "./core.js";
13
13
  import type { SDKOptions } from "./lib/config.js";
14
14
  import type { RequestOptions } from "./lib/sdks.js";
15
+ import type { Result } from "./types/fp.js";
15
16
  import type * as operations from "./models/operations/index.js";
16
17
  import type * as models from "./models/index.js";
18
+ import type { CreateCollectionInput, UpdateCollectionInput, QueryCollectionInput, QueryCollectionResponse, ListDocsInput, ListDocsResponse, UpsertDocsInput, UpdateDocsInput, DeleteDocsInput, FetchDocsInput, FetchDocsResponse, BulkUpsertInput, MessageResponse, ListCollectionsResponse, CreateCollectionResponse, GetCollectionResponse, UpdateCollectionResponse, GetBulkUpsertDocsResponse } from "./types/public.js";
19
+ import type { ListCollectionsError, CreateCollectionError, GetCollectionError, UpdateCollectionError, DeleteCollectionError, QueryCollectionError, ListDocsError, UpsertDocsError, UpdateDocsError, DeleteDocsError, FetchDocsError, GetBulkUpsertDocsError, BulkUpsertDocsError } from "./types/errors.js";
17
20
  export type { RequestOptions };
21
+ export type * from "./types/public.js";
22
+ /**
23
+ * @deprecated Use types from the package root (e.g. CreateCollectionInput, QueryCollectionResponse, ListDocsInput). Will be removed in the next major version.
24
+ */
18
25
  export type { operations, models };
19
26
  /** Default base URL for the LambdaDB API. */
20
27
  export declare const DEFAULT_BASE_URL = "https://api.lambdadb.ai";
@@ -50,10 +57,18 @@ export declare class LambdaDBClient extends LambdaDBCore {
50
57
  * List all collections in the project.
51
58
  */
52
59
  listCollections(options?: RequestOptions): Promise<operations.ListCollectionsResponse>;
60
+ /**
61
+ * List all collections (Safe: returns Result instead of throwing).
62
+ */
63
+ listCollectionsSafe(options?: RequestOptions): Promise<Result<ListCollectionsResponse, ListCollectionsError>>;
53
64
  /**
54
65
  * Create a new collection.
55
66
  */
56
- createCollection(request: operations.CreateCollectionRequest, options?: RequestOptions): Promise<operations.CreateCollectionResponse>;
67
+ createCollection(request: CreateCollectionInput, options?: RequestOptions): Promise<operations.CreateCollectionResponse>;
68
+ /**
69
+ * Create a new collection (Safe: returns Result instead of throwing).
70
+ */
71
+ createCollectionSafe(request: CreateCollectionInput, options?: RequestOptions): Promise<Result<CreateCollectionResponse, CreateCollectionError>>;
57
72
  }
58
73
  /**
59
74
  * Handle for a single collection. All methods operate on this collection.
@@ -66,18 +81,37 @@ export declare class CollectionHandle {
66
81
  * Get metadata of this collection.
67
82
  */
68
83
  get(options?: RequestOptions): Promise<operations.GetCollectionResponse>;
84
+ /**
85
+ * Get metadata of this collection (Safe: returns Result instead of throwing).
86
+ */
87
+ getSafe(options?: RequestOptions): Promise<Result<GetCollectionResponse, GetCollectionError>>;
69
88
  /**
70
89
  * Configure (update) this collection.
71
90
  */
72
- update(requestBody: operations.UpdateCollectionRequestBody, options?: RequestOptions): Promise<operations.UpdateCollectionResponse>;
91
+ update(requestBody: UpdateCollectionInput, options?: RequestOptions): Promise<operations.UpdateCollectionResponse>;
92
+ /**
93
+ * Configure (update) this collection (Safe: returns Result instead of throwing).
94
+ */
95
+ updateSafe(requestBody: UpdateCollectionInput, options?: RequestOptions): Promise<Result<UpdateCollectionResponse, UpdateCollectionError>>;
73
96
  /**
74
97
  * Delete this collection.
75
98
  */
76
99
  delete(options?: RequestOptions): Promise<models.MessageResponse>;
100
+ /**
101
+ * Delete this collection (Safe: returns Result instead of throwing).
102
+ */
103
+ deleteSafe(options?: RequestOptions): Promise<Result<MessageResponse, DeleteCollectionError>>;
77
104
  /**
78
105
  * Search this collection with a query.
106
+ * When the API returns docs via docsUrl (isDocsInline false), documents are
107
+ * fetched from the presigned URL automatically so the response always has docs.
79
108
  */
80
- query(requestBody: operations.QueryCollectionRequestBody, options?: RequestOptions): Promise<operations.QueryCollectionResponse>;
109
+ query(requestBody: QueryCollectionInput, options?: RequestOptions): Promise<QueryCollectionResponse>;
110
+ /**
111
+ * Search this collection with a query (Safe: returns Result instead of throwing).
112
+ * When the API returns docs via docsUrl, documents are fetched from the presigned URL automatically.
113
+ */
114
+ querySafe(requestBody: QueryCollectionInput, options?: RequestOptions): Promise<Result<QueryCollectionResponse, QueryCollectionError>>;
81
115
  readonly docs: CollectionDocs;
82
116
  }
83
117
  /**
@@ -90,39 +124,95 @@ declare class CollectionDocs {
90
124
  /**
91
125
  * List documents in the collection.
92
126
  */
93
- list(params?: {
94
- size?: number;
95
- pageToken?: string;
96
- }, options?: RequestOptions): Promise<operations.ListDocsResponse>;
127
+ list(params?: ListDocsInput, options?: RequestOptions): Promise<operations.ListDocsResponse>;
97
128
  /**
98
- * Upsert documents. Max payload 6MB.
129
+ * List documents in the collection (Safe: returns Result instead of throwing).
99
130
  */
100
- upsert(body: {
131
+ listSafe(params?: ListDocsInput, options?: RequestOptions): Promise<Result<ListDocsResponse, ListDocsError>>;
132
+ /**
133
+ * Iterate over all pages of documents. Yields one page per API response (with docs and nextPageToken).
134
+ * Use this to process large result sets without loading everything into memory.
135
+ *
136
+ * Note: The API limits response size by payload, not by document count. The number of docs per page
137
+ * may be less than the requested `size` and can vary from page to page.
138
+ *
139
+ * @example
140
+ * for await (const page of collection.docs.listPages({ size: 50 })) {
141
+ * console.log(page.docs.length, page.nextPageToken ?? "last page");
142
+ * }
143
+ */
144
+ listPages(params?: ListDocsInput, options?: RequestOptions): AsyncGenerator<ListDocsResponse>;
145
+ /**
146
+ * Fetch all documents across pages and return a single list. Uses listPages internally.
147
+ * For large collections, prefer listPages() to avoid high memory use.
148
+ *
149
+ * Note: Page size is constrained by API payload limits, so the number of docs per page may vary.
150
+ */
151
+ listAll(params?: ListDocsInput, options?: RequestOptions): Promise<{
101
152
  docs: Array<Record<string, unknown>>;
102
- }, options?: RequestOptions): Promise<models.MessageResponse>;
153
+ total: number;
154
+ }>;
155
+ /**
156
+ * Upsert documents. Max payload 6MB.
157
+ */
158
+ upsert(body: UpsertDocsInput, options?: RequestOptions): Promise<MessageResponse>;
159
+ /**
160
+ * Upsert documents (Safe: returns Result instead of throwing). Max payload 6MB.
161
+ */
162
+ upsertSafe(body: UpsertDocsInput, options?: RequestOptions): Promise<Result<MessageResponse, UpsertDocsError>>;
103
163
  /**
104
164
  * Update documents (each doc must have id). Max payload 6MB.
105
165
  */
106
- update(body: {
107
- docs: Array<Record<string, unknown>>;
108
- }, options?: RequestOptions): Promise<models.MessageResponse>;
166
+ update(body: UpdateDocsInput, options?: RequestOptions): Promise<MessageResponse>;
167
+ /**
168
+ * Update documents (Safe: returns Result instead of throwing). Max payload 6MB.
169
+ */
170
+ updateSafe(body: UpdateDocsInput, options?: RequestOptions): Promise<Result<MessageResponse, UpdateDocsError>>;
109
171
  /**
110
172
  * Delete documents by ids and/or filter.
111
173
  */
112
- delete(body: operations.DeleteDocsRequestBody, options?: RequestOptions): Promise<models.MessageResponse>;
174
+ delete(body: DeleteDocsInput, options?: RequestOptions): Promise<MessageResponse>;
175
+ /**
176
+ * Delete documents by ids and/or filter (Safe: returns Result instead of throwing).
177
+ */
178
+ deleteSafe(body: DeleteDocsInput, options?: RequestOptions): Promise<Result<MessageResponse, DeleteDocsError>>;
113
179
  /**
114
180
  * Fetch documents by IDs (max 100).
181
+ * When the API returns docs via docsUrl (isDocsInline false), documents are
182
+ * fetched from the presigned URL automatically so the response always has docs.
115
183
  */
116
- fetch(body: operations.FetchDocsRequestBody, options?: RequestOptions): Promise<operations.FetchDocsResponse>;
184
+ fetch(body: FetchDocsInput, options?: RequestOptions): Promise<FetchDocsResponse>;
185
+ /**
186
+ * Fetch documents by IDs (Safe: returns Result instead of throwing).
187
+ * When the API returns docs via docsUrl, documents are fetched from the presigned URL automatically.
188
+ */
189
+ fetchSafe(body: FetchDocsInput, options?: RequestOptions): Promise<Result<FetchDocsResponse, FetchDocsError>>;
117
190
  /**
118
191
  * Get presigned URL and metadata for bulk upload (up to 200MB).
119
192
  */
120
193
  getBulkUpsert(options?: RequestOptions): Promise<operations.GetBulkUpsertDocsResponse>;
194
+ /**
195
+ * Get presigned URL and metadata for bulk upload (Safe: returns Result instead of throwing).
196
+ */
197
+ getBulkUpsertSafe(options?: RequestOptions): Promise<Result<GetBulkUpsertDocsResponse, GetBulkUpsertDocsError>>;
121
198
  /**
122
199
  * Trigger bulk upsert with an object key from getBulkUpsert().
123
200
  */
124
- bulkUpsert(body: {
125
- objectKey: string;
126
- }, options?: RequestOptions): Promise<models.MessageResponse>;
201
+ bulkUpsert(body: BulkUpsertInput, options?: RequestOptions): Promise<MessageResponse>;
202
+ /**
203
+ * Trigger bulk upsert (Safe: returns Result instead of throwing).
204
+ */
205
+ bulkUpsertSafe(body: BulkUpsertInput, options?: RequestOptions): Promise<Result<MessageResponse, BulkUpsertDocsError>>;
206
+ /**
207
+ * Bulk upsert documents in one call (up to 200MB). Abstracts getBulkUpsert,
208
+ * S3 upload via presigned URL, and bulkUpsert. Use this for better DX when
209
+ * you have a document list; use getBulkUpsert + bulkUpsert for low-level control.
210
+ */
211
+ bulkUpsertDocs(body: UpsertDocsInput, options?: RequestOptions): Promise<MessageResponse>;
212
+ /**
213
+ * Bulk upsert documents in one call (Safe: returns Result instead of throwing).
214
+ * May return Error for local failures (payload size, upload). API errors use GetBulkUpsertDocsError or BulkUpsertDocsError.
215
+ */
216
+ bulkUpsertDocsSafe(body: UpsertDocsInput, options?: RequestOptions): Promise<Result<MessageResponse, GetBulkUpsertDocsError | BulkUpsertDocsError | Error>>;
127
217
  }
128
218
  //# sourceMappingURL=client.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}