Skip to content

Commit 33a6c3d

Browse files
hotlonghotlong
authored
Merge pull request #380 from objectstack-ai/copilot/add-batch-update-api
2 parents b192b05 + 62a621d commit 33a6c3d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

62 files changed

+11028
-14
lines changed

‎content/docs/references/api/batch.mdx‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: Batch
3+
description: Batch protocol schemas
4+
---
5+
6+
# Batch
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/api/batch.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { BatchOperationResultSchema, BatchOperationTypeSchema, BatchOptionsSchema, BatchRecordSchema, BatchUpdateRequestSchema, BatchUpdateResponseSchema, DeleteManyRequestSchema, UpdateManyRequestSchema } from '@objectstack/spec/api';
16+
import type { BatchOperationResult, BatchOperationType, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, UpdateManyRequest } from '@objectstack/spec/api';
17+
18+
// Validate data
19+
const result = BatchOperationResultSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## BatchOperationResult
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **id** | `string` | optional | Record ID if operation succeeded |
31+
| **success** | `boolean` | ✅ | Whether this record was processed successfully |
32+
| **errors** | `object[]` | optional | Array of errors if operation failed |
33+
| **data** | `Record<string, any>` | optional | Full record data (if returnRecords=true) |
34+
| **index** | `number` | optional | Index of the record in the request array |
35+
36+
---
37+
38+
## BatchOperationType
39+
40+
### Allowed Values
41+
42+
* `create`
43+
* `update`
44+
* `upsert`
45+
* `delete`
46+
47+
---
48+
49+
## BatchOptions
50+
51+
### Properties
52+
53+
| Property | Type | Required | Description |
54+
| :--- | :--- | :--- | :--- |
55+
| **atomic** | `boolean` | optional | If true, rollback entire batch on any failure (transaction mode) |
56+
| **returnRecords** | `boolean` | optional | If true, return full record data in response |
57+
| **continueOnError** | `boolean` | optional | If true (and atomic=false), continue processing remaining records after errors |
58+
| **validateOnly** | `boolean` | optional | If true, validate records without persisting changes (dry-run mode) |
59+
60+
---
61+
62+
## BatchRecord
63+
64+
### Properties
65+
66+
| Property | Type | Required | Description |
67+
| :--- | :--- | :--- | :--- |
68+
| **id** | `string` | optional | Record ID (required for update/delete) |
69+
| **data** | `Record<string, any>` | optional | Record data (required for create/update/upsert) |
70+
| **externalId** | `string` | optional | External ID for upsert matching |
71+
72+
---
73+
74+
## BatchUpdateRequest
75+
76+
### Properties
77+
78+
| Property | Type | Required | Description |
79+
| :--- | :--- | :--- | :--- |
80+
| **operation** | `Enum<'create' \| 'update' \| 'upsert' \| 'delete'>` | ✅ | Type of batch operation |
81+
| **records** | `object[]` | ✅ | Array of records to process (max 200 per batch) |
82+
| **options** | `object` | optional | Batch operation options |
83+
84+
---
85+
86+
## BatchUpdateResponse
87+
88+
### Properties
89+
90+
| Property | Type | Required | Description |
91+
| :--- | :--- | :--- | :--- |
92+
| **success** | `boolean` | ✅ | Operation success status |
93+
| **error** | `object` | optional | Error details if success is false |
94+
| **meta** | `object` | optional | Response metadata |
95+
| **operation** | `Enum<'create' \| 'update' \| 'upsert' \| 'delete'>` | optional | Operation type that was performed |
96+
| **total** | `number` | ✅ | Total number of records in the batch |
97+
| **succeeded** | `number` | ✅ | Number of records that succeeded |
98+
| **failed** | `number` | ✅ | Number of records that failed |
99+
| **results** | `object[]` | ✅ | Detailed results for each record |
100+
101+
---
102+
103+
## DeleteManyRequest
104+
105+
### Properties
106+
107+
| Property | Type | Required | Description |
108+
| :--- | :--- | :--- | :--- |
109+
| **ids** | `string[]` | ✅ | Array of record IDs to delete (max 200) |
110+
| **options** | `object` | optional | Delete options |
111+
112+
---
113+
114+
## UpdateManyRequest
115+
116+
### Properties
117+
118+
| Property | Type | Required | Description |
119+
| :--- | :--- | :--- | :--- |
120+
| **records** | `object[]` | ✅ | Array of records to update (max 200 per batch) |
121+
| **options** | `object` | optional | Update options |
122+

‎content/docs/references/api/cache.mdx‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Cache
3+
description: Cache protocol schemas
4+
---
5+
6+
# Cache
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/api/cache.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { CacheControlSchema, CacheDirectiveSchema, CacheInvalidationRequestSchema, CacheInvalidationResponseSchema, CacheInvalidationTargetSchema, ETagSchema, MetadataCacheRequestSchema, MetadataCacheResponseSchema } from '@objectstack/spec/api';
16+
import type { CacheControl, CacheDirective, CacheInvalidationRequest, CacheInvalidationResponse, CacheInvalidationTarget, ETag, MetadataCacheRequest, MetadataCacheResponse } from '@objectstack/spec/api';
17+
18+
// Validate data
19+
const result = CacheControlSchema.parse(data);
20+
```
21+
22+
---
23+
24+
## CacheControl
25+
26+
### Properties
27+
28+
| Property | Type | Required | Description |
29+
| :--- | :--- | :--- | :--- |
30+
| **directives** | `Enum<'public' \| 'private' \| 'no-cache' \| 'no-store' \| 'must-revalidate' \| 'max-age'>[]` | ✅ | Cache control directives |
31+
| **maxAge** | `number` | optional | Maximum cache age in seconds |
32+
| **staleWhileRevalidate** | `number` | optional | Allow serving stale content while revalidating (seconds) |
33+
| **staleIfError** | `number` | optional | Allow serving stale content on error (seconds) |
34+
35+
---
36+
37+
## CacheDirective
38+
39+
### Allowed Values
40+
41+
* `public`
42+
* `private`
43+
* `no-cache`
44+
* `no-store`
45+
* `must-revalidate`
46+
* `max-age`
47+
48+
---
49+
50+
## CacheInvalidationRequest
51+
52+
### Properties
53+
54+
| Property | Type | Required | Description |
55+
| :--- | :--- | :--- | :--- |
56+
| **target** | `Enum<'all' \| 'object' \| 'field' \| 'permission' \| 'layout' \| 'custom'>` | ✅ | What to invalidate |
57+
| **identifiers** | `string[]` | optional | Specific resources to invalidate (e.g., object names) |
58+
| **cascade** | `boolean` | optional | If true, invalidate dependent resources |
59+
| **pattern** | `string` | optional | Pattern for custom invalidation (supports wildcards) |
60+
61+
---
62+
63+
## CacheInvalidationResponse
64+
65+
### Properties
66+
67+
| Property | Type | Required | Description |
68+
| :--- | :--- | :--- | :--- |
69+
| **success** | `boolean` | ✅ | Whether invalidation succeeded |
70+
| **invalidated** | `number` | ✅ | Number of cache entries invalidated |
71+
| **targets** | `string[]` | optional | List of invalidated resources |
72+
73+
---
74+
75+
## CacheInvalidationTarget
76+
77+
### Allowed Values
78+
79+
* `all`
80+
* `object`
81+
* `field`
82+
* `permission`
83+
* `layout`
84+
* `custom`
85+
86+
---
87+
88+
## ETag
89+
90+
### Properties
91+
92+
| Property | Type | Required | Description |
93+
| :--- | :--- | :--- | :--- |
94+
| **value** | `string` | ✅ | ETag value (hash or version identifier) |
95+
| **weak** | `boolean` | optional | Whether this is a weak ETag |
96+
97+
---
98+
99+
## MetadataCacheRequest
100+
101+
### Properties
102+
103+
| Property | Type | Required | Description |
104+
| :--- | :--- | :--- | :--- |
105+
| **ifNoneMatch** | `string` | optional | ETag value for conditional request (If-None-Match header) |
106+
| **ifModifiedSince** | `string` | optional | Timestamp for conditional request (If-Modified-Since header) |
107+
| **cacheControl** | `object` | optional | Client cache control preferences |
108+
109+
---
110+
111+
## MetadataCacheResponse
112+
113+
### Properties
114+
115+
| Property | Type | Required | Description |
116+
| :--- | :--- | :--- | :--- |
117+
| **data** | `any` | optional | Metadata payload (omitted for 304 Not Modified) |
118+
| **etag** | `object` | optional | ETag for this resource version |
119+
| **lastModified** | `string` | optional | Last modification timestamp |
120+
| **cacheControl** | `object` | optional | Cache control directives |
121+
| **notModified** | `boolean` | optional | True if resource has not been modified (304 response) |
122+
| **version** | `string` | optional | Metadata version identifier |
123+

‎content/docs/references/api/connector.mdx‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Connector
3+
description: Connector protocol schemas
4+
---
5+
6+
# Connector
7+
8+
<Callout type="info">
9+
**Source:** `packages/spec/src/api/connector.zod.ts`
10+
</Callout>
11+
12+
## TypeScript Usage
13+
14+
```typescript
15+
import { RetryStrategySchema } from '@objectstack/spec/api';
16+
import type { RetryStrategy } from '@objectstack/spec/api';
17+
18+
// Validate data
19+
const result = RetryStrategySchema.parse(data);
20+
```
21+
22+
---
23+
24+
## RetryStrategy
25+
26+
### Allowed Values
27+
28+
* `no_retry`
29+
* `retry_immediate`
30+
* `retry_backoff`
31+
* `retry_after`
32+

‎content/docs/references/api/contract.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ const result = ApiErrorSchema.parse(data);
101101
| **object** | `string` | ✅ | Object name (e.g. account) |
102102
| **fields** | `string \| object[]` | optional | Fields to retrieve |
103103
| **where** | `any` | optional | Filtering criteria (WHERE) |
104+
| **search** | `object` | optional | Full-text search configuration ($search parameter) |
104105
| **orderBy** | `object[]` | optional | Sorting instructions (ORDER BY) |
105106
| **limit** | `number` | optional | Max records to return (LIMIT) |
106107
| **offset** | `number` | optional | Records to skip (OFFSET) |

0 commit comments

Comments
 (0)