@veroxm/sdk 1.11.0 → 1.12.0

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.12.0
4
+
5
+ - Safe retries for writes: `content(slug).create()`, `update()`, `delete()` and `functions.call()` take an
6
+ `idempotencyKey` (any text, 1 to 255 visible characters; a new UUID per write). It is sent as `Idempotency-Key`,
7
+ and the server does the write once for that key: a repeat within 24 hours gets the first answer back. With a key, the
8
+ write is retried like a read, with the app's `retries` or the call's own `retries`, including while the first
9
+ attempt is still running (409 `idempotency_in_progress`). Without a key, writes are never retried, as before. Needs a
10
+ VeroXM server with Idempotency-Key support; an older one ignores the header.
11
+
3
12
  ## 1.11.0
4
13
 
5
14
  - Query text: `content(slug).list({ q })`, `search({ q })` and `count({ q })` take one readable line instead of `where`
package/dist/content.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { VeroXMApp } from './client.js';
2
- import type { RequestControl } from './http.js';
2
+ import type { RequestControl, WriteControl } from './http.js';
3
3
  export interface ListOptions extends RequestControl {
4
4
  /** Field-value filter -- an array of `{field: value}` clauses (AND'ed together), each value either a scalar or an operator object like `{like: '...'}`, `{gte: '...'}`, `{in: 'a,b,c'}`, etc. See the project's SDK Docs tab for the full operator list. */
5
5
  where?: unknown;
@@ -80,7 +80,7 @@ export declare class ContentResource<T = Record<string, unknown>> {
80
80
  * publish immediately. A database content model that allows creating entries takes its writable fields (and `id` when
81
81
  * it takes the key from you); `userId` / `ctx` say whose row it is for a model limited to the caller's rows.
82
82
  */
83
- create(data: Record<string, unknown>, options?: Pick<ListOptions, 'userId' | 'ctx'>): Promise<T>;
83
+ create(data: Record<string, unknown>, options?: Pick<ListOptions, 'userId' | 'ctx'> & WriteControl): Promise<T>;
84
84
  /**
85
85
  * A partial update -- only the fields present in `data` are changed.
86
86
  * Publish state follows the same rule as create(): omitting `draft` (or
@@ -89,6 +89,6 @@ export declare class ContentResource<T = Record<string, unknown>> {
89
89
  * Pass `draft: true` explicitly to keep (or return) it unpublished.
90
90
  * (A database content model has no drafts: its writable fields only.)
91
91
  */
92
- update(id: number | string, data: Record<string, unknown>, options?: Pick<ListOptions, 'userId' | 'ctx'>): Promise<T>;
93
- delete(id: number | string, options?: Pick<ListOptions, 'userId' | 'ctx'>): Promise<void>;
92
+ update(id: number | string, data: Record<string, unknown>, options?: Pick<ListOptions, 'userId' | 'ctx'> & WriteControl): Promise<T>;
93
+ delete(id: number | string, options?: Pick<ListOptions, 'userId' | 'ctx'> & WriteControl): Promise<void>;
94
94
  }
package/dist/content.js CHANGED
@@ -9,6 +9,14 @@ function control(options) {
9
9
  ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
10
10
  };
11
11
  }
12
+ /** control() plus a write's Idempotency-Key and its retries (only the keys that were given). */
13
+ function writeControl(options) {
14
+ return {
15
+ ...control(options),
16
+ ...(options.idempotencyKey !== undefined ? { idempotencyKey: options.idempotencyKey } : {}),
17
+ ...(options.retries !== undefined ? { retries: options.retries } : {}),
18
+ };
19
+ }
12
20
  /**
13
21
  * Typed access to one content collection's entries. `T` is whatever
14
22
  * shape you expect back (the API's actual response is a plain object per
@@ -83,7 +91,7 @@ export class ContentResource {
83
91
  * it takes the key from you); `userId` / `ctx` say whose row it is for a model limited to the caller's rows.
84
92
  */
85
93
  async create(data, options = {}) {
86
- return this.app.request({ method: 'POST', path: this.root(), query: callerQuery(options), json: data });
94
+ return this.app.request({ method: 'POST', path: this.root(), query: callerQuery(options), json: data, ...writeControl(options) });
87
95
  }
88
96
  /**
89
97
  * A partial update -- only the fields present in `data` are changed.
@@ -94,9 +102,9 @@ export class ContentResource {
94
102
  * (A database content model has no drafts: its writable fields only.)
95
103
  */
96
104
  async update(id, data, options = {}) {
97
- return this.app.request({ method: 'PATCH', path: `${this.root()}/${encodeURIComponent(String(id))}`, query: callerQuery(options), json: data });
105
+ return this.app.request({ method: 'PATCH', path: `${this.root()}/${encodeURIComponent(String(id))}`, query: callerQuery(options), json: data, ...writeControl(options) });
98
106
  }
99
107
  async delete(id, options = {}) {
100
- await this.app.request({ method: 'DELETE', path: `${this.root()}/${encodeURIComponent(String(id))}`, query: callerQuery(options) });
108
+ await this.app.request({ method: 'DELETE', path: `${this.root()}/${encodeURIComponent(String(id))}`, query: callerQuery(options), ...writeControl(options) });
101
109
  }
102
110
  }
@@ -1,5 +1,5 @@
1
1
  import type { VeroXMApp } from './client.js';
2
- import type { RequestControl } from './http.js';
2
+ import type { RequestControl, WriteControl } from './http.js';
3
3
  type Query = Record<string, string | number | boolean | undefined>;
4
4
  /**
5
5
  * Project functions with an HTTP trigger (Developer > Functions). Who may call one is the function's own setting:
@@ -12,10 +12,13 @@ type Query = Record<string, string | number | boolean | undefined>;
12
12
  export declare class FunctionsResource {
13
13
  private readonly app;
14
14
  constructor(app: VeroXMApp);
15
- /** POST /functions/:name with `body` (an object or array) as JSON; the function reads it as `request.body`. */
15
+ /**
16
+ * POST /functions/:name with `body` (an object or array) as JSON; the function reads it as `request.body`. With
17
+ * `idempotencyKey` the function runs once for that key, and the call is retried like a GET.
18
+ */
16
19
  call<T = unknown>(name: string, body?: Record<string, unknown> | unknown[], options?: {
17
20
  query?: Query;
18
- } & RequestControl): Promise<T>;
21
+ } & WriteControl): Promise<T>;
19
22
  /** GET /functions/:name (the function reads `query` as `request.query`). Retried with the app's `retries`. */
20
23
  get<T = unknown>(name: string, query?: Query, options?: RequestControl): Promise<T>;
21
24
  }
package/dist/functions.js CHANGED
@@ -10,10 +10,22 @@ export class FunctionsResource {
10
10
  constructor(app) {
11
11
  this.app = app;
12
12
  }
13
- /** POST /functions/:name with `body` (an object or array) as JSON; the function reads it as `request.body`. */
13
+ /**
14
+ * POST /functions/:name with `body` (an object or array) as JSON; the function reads it as `request.body`. With
15
+ * `idempotencyKey` the function runs once for that key, and the call is retried like a GET.
16
+ */
14
17
  async call(name, body, options = {}) {
15
- const { query, signal, timeoutMs } = options;
16
- return (await this.app.request({ method: 'POST', path: path(name), json: body, query, signal, timeoutMs }));
18
+ const { query, signal, timeoutMs, idempotencyKey, retries } = options;
19
+ return (await this.app.request({
20
+ method: 'POST',
21
+ path: path(name),
22
+ json: body,
23
+ query,
24
+ signal,
25
+ timeoutMs,
26
+ ...(idempotencyKey !== undefined ? { idempotencyKey } : {}),
27
+ ...(retries !== undefined ? { retries } : {}),
28
+ }));
17
29
  }
18
30
  /** GET /functions/:name (the function reads `query` as `request.query`). Retried with the app's `retries`. */
19
31
  async get(name, query = {}, options = {}) {
@@ -1136,6 +1136,26 @@ export interface paths {
1136
1136
  patch?: never;
1137
1137
  trace?: never;
1138
1138
  };
1139
+ "/projects/{uuid}/queries/{slug}": {
1140
+ parameters: {
1141
+ query?: never;
1142
+ header?: never;
1143
+ path?: never;
1144
+ cookie?: never;
1145
+ };
1146
+ /**
1147
+ * A named query's entries
1148
+ * @description The entries of a query saved in the dashboard (Settings > Named queries), by its slug: its content model, filter and sort are fixed, and the answer is the same as the content list's. The key needs `read`, and database:<db>:read when the query reads a database content model. Page with `limit` and `offset` (`limit` up to the query's page limit, which is also the default). Sending `q`, `where`, `sort` or `filter.*` is 400 `fixed_query`. The `X-VeroXM-Query` header names the query.
1149
+ */
1150
+ get: operations["runNamedQuery"];
1151
+ put?: never;
1152
+ post?: never;
1153
+ delete?: never;
1154
+ options?: never;
1155
+ head?: never;
1156
+ patch?: never;
1157
+ trace?: never;
1158
+ };
1139
1159
  "/forms/{publicId}": {
1140
1160
  parameters: {
1141
1161
  query?: never;
@@ -3594,7 +3614,10 @@ export interface operations {
3594
3614
  /** @description A database content model limited to the caller's rows: whose (project keys). */
3595
3615
  userId?: string;
3596
3616
  };
3597
- header?: never;
3617
+ header?: {
3618
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
3619
+ "Idempotency-Key"?: string;
3620
+ };
3598
3621
  path: {
3599
3622
  /** @description The project's UUID. */
3600
3623
  uuid: string;
@@ -3714,7 +3737,10 @@ export interface operations {
3714
3737
  /** @description A database content model limited to the caller's rows: whose (project keys). */
3715
3738
  userId?: string;
3716
3739
  };
3717
- header?: never;
3740
+ header?: {
3741
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
3742
+ "Idempotency-Key"?: string;
3743
+ };
3718
3744
  path: {
3719
3745
  /** @description The project's UUID. */
3720
3746
  uuid: string;
@@ -3753,7 +3779,10 @@ export interface operations {
3753
3779
  /** @description A database content model limited to the caller's rows: whose (project keys). */
3754
3780
  userId?: string;
3755
3781
  };
3756
- header?: never;
3782
+ header?: {
3783
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
3784
+ "Idempotency-Key"?: string;
3785
+ };
3757
3786
  path: {
3758
3787
  /** @description The project's UUID. */
3759
3788
  uuid: string;
@@ -3822,7 +3851,10 @@ export interface operations {
3822
3851
  uploadMedia: {
3823
3852
  parameters: {
3824
3853
  query?: never;
3825
- header?: never;
3854
+ header?: {
3855
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
3856
+ "Idempotency-Key"?: string;
3857
+ };
3826
3858
  path: {
3827
3859
  /** @description The project's UUID. */
3828
3860
  uuid: string;
@@ -3854,7 +3886,10 @@ export interface operations {
3854
3886
  deleteMedia: {
3855
3887
  parameters: {
3856
3888
  query?: never;
3857
- header?: never;
3889
+ header?: {
3890
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
3891
+ "Idempotency-Key"?: string;
3892
+ };
3858
3893
  path: {
3859
3894
  /** @description The project's UUID. */
3860
3895
  uuid: string;
@@ -3882,7 +3917,10 @@ export interface operations {
3882
3917
  updateMediaCaption: {
3883
3918
  parameters: {
3884
3919
  query?: never;
3885
- header?: never;
3920
+ header?: {
3921
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
3922
+ "Idempotency-Key"?: string;
3923
+ };
3886
3924
  path: {
3887
3925
  /** @description The project's UUID. */
3888
3926
  uuid: string;
@@ -3978,7 +4016,10 @@ export interface operations {
3978
4016
  callFunction: {
3979
4017
  parameters: {
3980
4018
  query?: never;
3981
- header?: never;
4019
+ header?: {
4020
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
4021
+ "Idempotency-Key"?: string;
4022
+ };
3982
4023
  path: {
3983
4024
  /** @description The project's UUID. */
3984
4025
  uuid: string;
@@ -4104,7 +4145,10 @@ export interface operations {
4104
4145
  completeTask: {
4105
4146
  parameters: {
4106
4147
  query?: never;
4107
- header?: never;
4148
+ header?: {
4149
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
4150
+ "Idempotency-Key"?: string;
4151
+ };
4108
4152
  path: {
4109
4153
  /** @description The project's UUID. */
4110
4154
  uuid: string;
@@ -4138,7 +4182,10 @@ export interface operations {
4138
4182
  startProcess: {
4139
4183
  parameters: {
4140
4184
  query?: never;
4141
- header?: never;
4185
+ header?: {
4186
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
4187
+ "Idempotency-Key"?: string;
4188
+ };
4142
4189
  path: {
4143
4190
  /** @description The project's UUID. */
4144
4191
  uuid: string;
@@ -4879,6 +4926,48 @@ export interface operations {
4879
4926
  429: components["responses"]["E429"];
4880
4927
  };
4881
4928
  };
4929
+ runNamedQuery: {
4930
+ parameters: {
4931
+ query?: {
4932
+ offset?: number;
4933
+ limit?: number;
4934
+ count?: string;
4935
+ timestamps?: string;
4936
+ locale?: string;
4937
+ state?: string;
4938
+ /** @description A database content model limited to the caller's rows: whose (project keys). `ctx.<name>=` likewise. */
4939
+ userId?: string;
4940
+ };
4941
+ header?: never;
4942
+ path: {
4943
+ /** @description The project's UUID. */
4944
+ uuid: string;
4945
+ /** @description The named query's slug. */
4946
+ slug: string;
4947
+ };
4948
+ cookie?: never;
4949
+ };
4950
+ requestBody?: never;
4951
+ responses: {
4952
+ /** @description OK */
4953
+ 200: {
4954
+ headers: {
4955
+ [name: string]: unknown;
4956
+ };
4957
+ content: {
4958
+ "application/json": components["schemas"]["Entry"][] | number;
4959
+ };
4960
+ };
4961
+ 400: components["responses"]["E400"];
4962
+ 401: components["responses"]["E401"];
4963
+ 403: components["responses"]["E403"];
4964
+ 404: components["responses"]["E404"];
4965
+ 429: components["responses"]["E429"];
4966
+ 502: components["responses"]["E502"];
4967
+ 503: components["responses"]["E503"];
4968
+ 504: components["responses"]["E504"];
4969
+ };
4970
+ };
4882
4971
  getPublicForm: {
4883
4972
  parameters: {
4884
4973
  query?: never;
@@ -4907,7 +4996,10 @@ export interface operations {
4907
4996
  submitFormResponse: {
4908
4997
  parameters: {
4909
4998
  query?: never;
4910
- header?: never;
4999
+ header?: {
5000
+ /** @description Makes a retry safe: the same key with the same request, within 24 hours, gets the first answer again (with `Idempotent-Replayed: true`) and the write is not done twice. The same key with a different request is a 422 `idempotency_key_reused`; while the first is still running, a 409 `idempotency_in_progress` with Retry-After. Use a new random value (a UUID) for each new write. */
5001
+ "Idempotency-Key"?: string;
5002
+ };
4911
5003
  path: {
4912
5004
  /** @description The form id (f_...). */
4913
5005
  publicId: string;
package/dist/http.d.ts CHANGED
@@ -18,7 +18,26 @@ export interface RawRequestOptions extends RequestControl {
18
18
  /** Sent as a `multipart/form-data` body (file uploads) -- fetch sets the boundary Content-Type itself, so never set one manually alongside this. */
19
19
  form?: FormData;
20
20
  headers?: Record<string, string>;
21
- /** Extra attempts for a GET or HEAD that fails in a way worth retrying (see `isRetryable`). Ignored for other methods. */
21
+ /**
22
+ * Extra attempts for a GET or HEAD that fails in a way worth retrying (see `isRetryable`), or for a write sent with
23
+ * an `idempotencyKey`. Ignored for other writes.
24
+ */
25
+ retries?: number;
26
+ /**
27
+ * Sent as `Idempotency-Key`: the server does the write once, and answers a repeat of it (same key, same request,
28
+ * within 24 hours) with the first answer. A write with a key is retried like a GET.
29
+ */
30
+ idempotencyKey?: string;
31
+ }
32
+ /** Writes a retry can't double: the ones that take an `idempotencyKey`. */
33
+ export interface WriteControl extends RequestControl {
34
+ /**
35
+ * Makes retries safe: the server does the write once for this key (any text, 1 to 255 visible characters; a new
36
+ * UUID per write), and a repeat gets the first answer. With a key the write is retried like a GET, with the app's
37
+ * `retries` or this call's.
38
+ */
39
+ idempotencyKey?: string;
40
+ /** Extra attempts, from 0 to 5; only used with `idempotencyKey`. Overrides the app's `retries` for this call. */
22
41
  retries?: number;
23
42
  }
24
43
  /** Throws a RangeError for a `retries` that isn't a whole number from 0 to 5. */
package/dist/http.js CHANGED
@@ -29,8 +29,9 @@ function parseRetryAfter(value) {
29
29
  function isRetryable(err) {
30
30
  if (err instanceof VeroXMTimeoutError)
31
31
  return true;
32
+ // 409 idempotency_in_progress: the first request with the key is still running.
32
33
  if (err instanceof VeroXMApiError)
33
- return RETRY_STATUSES.has(err.status);
34
+ return RETRY_STATUSES.has(err.status) || (err.status === 409 && err.code === 'idempotency_in_progress');
34
35
  // fetch rejects with a TypeError when the network fails (browsers, Node's undici, React Native).
35
36
  return err instanceof TypeError;
36
37
  }
@@ -133,7 +134,10 @@ export async function rawRequest(apiBase, opts, internal = {}) {
133
134
  url.searchParams.set(key, String(value));
134
135
  }
135
136
  }
136
- const headers = { ...opts.headers };
137
+ if (opts.idempotencyKey !== undefined && !/^[\x21-\x7e]{1,255}$/.test(opts.idempotencyKey)) {
138
+ throw new RangeError('idempotencyKey must be 1 to 255 visible characters (no spaces)');
139
+ }
140
+ const headers = { ...opts.headers, ...(opts.idempotencyKey !== undefined ? { 'Idempotency-Key': opts.idempotencyKey } : {}) };
137
141
  let body;
138
142
  if (opts.form) {
139
143
  body = opts.form;
@@ -144,8 +148,9 @@ export async function rawRequest(apiBase, opts, internal = {}) {
144
148
  }
145
149
  const method = opts.method ?? 'GET';
146
150
  const init = { method, headers, body };
147
- // `repeatable` lets a caller vouch for a POST that changes nothing (a GraphQL query).
148
- const repeatable = internal.repeatable ?? REPEATABLE.has(method.toUpperCase());
151
+ // `repeatable` lets a caller vouch for a POST that changes nothing (a GraphQL query). A write with an
152
+ // Idempotency-Key is done once by the server however often it is sent.
153
+ const repeatable = internal.repeatable ?? (REPEATABLE.has(method.toUpperCase()) || opts.idempotencyKey !== undefined);
149
154
  const retries = repeatable ? (opts.retries ?? 0) : 0;
150
155
  const control = { signal: opts.signal, timeoutMs: opts.timeoutMs };
151
156
  for (let n = 0;; n++) {
package/dist/index.d.ts CHANGED
@@ -7,7 +7,7 @@ export type { PasskeyOptionsJSON, PasskeyProvider } from './passkeys.js';
7
7
  export { createPkce } from './pkce.js';
8
8
  export { ContentResource } from './content.js';
9
9
  export type { ListOptions } from './content.js';
10
- export type { RequestControl } from './http.js';
10
+ export type { RequestControl, WriteControl } from './http.js';
11
11
  export { graphqlRequest, VeroXMGraphQLError } from './graphql.js';
12
12
  export type { GraphQLErrorItem, GraphQLRequestOptions } from './graphql.js';
13
13
  export { MediaResource } from './media.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veroxm/sdk",
3
- "version": "1.11.0",
3
+ "version": "1.12.0",
4
4
  "description": "VeroXM client for JavaScript and TypeScript: content, media, experiences, events and the visitor tracker.",
5
5
  "keywords": [
6
6
  "veroxm",