@veroxm/sdk 1.10.0 → 1.11.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,12 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.11.0
4
+
5
+ - Query text: `content(slug).list({ q })`, `search({ q })` and `count({ q })` take one readable line instead of `where`
6
+ and `sort`: `city = "Riyadh" AND area >= 500 ORDER BY area DESC` (`= != > >= < <= ~`, `IN`, `NOT IN`, `BETWEEN`,
7
+ `IS [NOT] EMPTY`, `AND`, `ORDER BY`, dates like `-30d`). A query that doesn't parse rejects with a `VeroXMApiError`
8
+ whose `code` is `invalid_query`. Needs a VeroXM server with query text; without `q`, requests are unchanged.
9
+
3
10
  ## 1.10.0
4
11
 
5
12
  - Timeouts, retries and cancelling, all off unless you set them. `initializeApp({ timeoutMs, retries })` sets them for
@@ -7,6 +14,11 @@
7
14
  `AbortSignal`) and their own `timeoutMs`. A request that runs out of time rejects with the new `VeroXMTimeoutError`
8
15
  (`code: 'timeout'`). Only GET and HEAD requests are retried, after a network error, a timeout, or 429, 502, 503 or
9
16
  504, with backoff and the API's `Retry-After` (up to 10 s). File uploads don't take the app's time limit.
17
+ - `graphqlRequest({ baseUrl, token, query, variables, signal, timeoutMs, retries })` sends a GraphQL document to
18
+ `/public/v2/graphql` and returns its `data`; answers with `errors` reject with the new `VeroXMGraphQLError` (a
19
+ `VeroXMApiError` with `errors`, and `code` from the first error's `extensions.code`). A document with a mutation is
20
+ never retried. `@veroxm/react-sdk` 1.5 reads through it. `fetch` sends with your own fetch (e.g. adding Next.js
21
+ cache options).
10
22
 
11
23
  ## 1.9.0
12
24
 
package/README.md CHANGED
@@ -413,6 +413,26 @@ controller.abort(); // rejects with an AbortError
413
413
  - **`signal`** (call): taken by `list`, `search`, `count`, `get`, `functions.call` and `functions.get`. A cancelled call
414
414
  rejects with the signal's reason and stops any wait for a retry.
415
415
 
416
+ ## GraphQL
417
+
418
+ From 1.10, `graphqlRequest` sends a document to the public GraphQL API and returns its `data`:
419
+
420
+ ```ts
421
+ import { graphqlRequest, VeroXMGraphQLError } from '@veroxm/sdk';
422
+
423
+ const data = await graphqlRequest<{ entries: { items: unknown[] } }>({
424
+ baseUrl: 'https://cms.example.com',
425
+ token: process.env.VEROXM_API_KEY!,
426
+ query: 'query($c: String!) { entries(collection: $c, limit: 5) { items { id data } } }',
427
+ variables: { c: 'posts' },
428
+ timeoutMs: 8000,
429
+ retries: 2, // never for a document with a mutation
430
+ });
431
+ ```
432
+
433
+ An answer with `errors` rejects with `VeroXMGraphQLError` (`errors`, and `code` from the first error's
434
+ `extensions.code`). `@veroxm/react-sdk` reads through this function.
435
+
416
436
  ## Stability
417
437
 
418
438
  Follows semantic versioning. From 1.0, breaking changes come only in a major version, after at least one minor release with the
package/dist/content.d.ts CHANGED
@@ -6,6 +6,12 @@ export interface ListOptions extends RequestControl {
6
6
  whereRelation?: Record<string, Record<string, string>>;
7
7
  /** e.g. "created_at:desc" or "title:asc,created_at:desc". */
8
8
  sort?: string;
9
+ /**
10
+ * Query text instead of `where` and `sort` (not both): `city = "Riyadh" AND area >= 500 ORDER BY area DESC`. Operators
11
+ * `= != > >= < <= ~` (contains), `IN (…)`, `NOT IN (…)`, `BETWEEN a AND b`, `IS [NOT] EMPTY`, `AND`; dates like `-30d`
12
+ * or `startOfMonth()`. A query that doesn't parse rejects with a `VeroXMApiError` whose `code` is `invalid_query`.
13
+ */
14
+ q?: string;
9
15
  /** Pass "only_draft" to include unpublished entries; anything else (including omitted) returns published-only. */
10
16
  state?: 'only_draft' | string;
11
17
  offset?: number;
package/dist/content.js CHANGED
@@ -31,6 +31,7 @@ export class ContentResource {
31
31
  limit: options.limit,
32
32
  offset: options.offset,
33
33
  sort: options.sort,
34
+ q: options.q,
34
35
  state: options.state,
35
36
  count: options.count ? '1' : undefined,
36
37
  timestamps: options.timestamps ? '1' : undefined,
package/dist/embed.d.ts CHANGED
@@ -50,6 +50,19 @@ export interface FormEmbedOptions {
50
50
  endingId: string | null;
51
51
  }) => void;
52
52
  onClose?: () => void;
53
+ /**
54
+ * Records the send as `$form_submitted` (usable as an experience's goal): your @veroxm/sdk tracker. The script-tag
55
+ * embed uses the VeroXM script tag's tracker (window.veroxm) when the page has it. Pass `false` to not record it.
56
+ * @since 1.10.0
57
+ */
58
+ tracker?: FormEmbedTracker | false;
59
+ }
60
+ /** The part of a VeroxmTracker the embed uses (structural: this file has no imports). */
61
+ export interface FormEmbedTracker {
62
+ formSubmitted(form: string, submission: {
63
+ responseId?: string;
64
+ endingId?: string | null;
65
+ }): void;
53
66
  }
54
67
  export interface FormEmbed {
55
68
  readonly iframe: HTMLIFrameElement;
package/dist/embed.js CHANGED
@@ -32,6 +32,15 @@ function el(tag, className) {
32
32
  e.className = className;
33
33
  return e;
34
34
  }
35
+ /** The tracker a send is recorded with: the option, else the VeroXM script tag's (window.veroxm.tracker), else none. */
36
+ function submitTracker(options) {
37
+ if (options.tracker === false)
38
+ return null;
39
+ if (options.tracker)
40
+ return options.tracker;
41
+ const global = window.veroxm?.tracker;
42
+ return global && typeof global.formSubmitted === 'function' ? global : null;
43
+ }
35
44
  function resolve(target) {
36
45
  if (!target)
37
46
  return null;
@@ -177,6 +186,12 @@ export function embedForm(options) {
177
186
  options.onStarted?.();
178
187
  else if (m.type === 'submitted' && m.responseId) {
179
188
  options.onSubmit?.({ responseId: m.responseId, endingId: m.endingId ?? null });
189
+ try {
190
+ submitTracker(options)?.formSubmitted(options.form, { responseId: m.responseId, endingId: m.endingId ?? null });
191
+ }
192
+ catch {
193
+ // tracking never breaks the form
194
+ }
180
195
  if (mode === 'toast')
181
196
  storageSet(dismissKey, String(Date.now() + 3650 * 86400000));
182
197
  if (options.autoCloseSeconds !== undefined && mode !== 'inline') {
@@ -829,6 +829,26 @@ export interface paths {
829
829
  patch?: never;
830
830
  trace?: never;
831
831
  };
832
+ "/projects/{uuid}/files/{token}": {
833
+ parameters: {
834
+ query?: never;
835
+ header?: never;
836
+ path?: never;
837
+ cookie?: never;
838
+ };
839
+ /**
840
+ * A file kept in a connected database, by the signed link an entry carries
841
+ * @description A database model field marked as a file comes back as `{ url, expiresAt }` (or null): this is that `url`. No token: the link is the credential, for one file, one caller's view of one row, for an hour, so it works in `<img src>`. The type comes from the bytes (images and PDF are shown, anything else downloaded); never larger than 10 MB. Each use is checked again, metered and logged like any read.
842
+ */
843
+ get: operations["getDatabaseFile"];
844
+ put?: never;
845
+ post?: never;
846
+ delete?: never;
847
+ options?: never;
848
+ head?: never;
849
+ patch?: never;
850
+ trace?: never;
851
+ };
832
852
  "/projects/{uuid}/setup": {
833
853
  parameters: {
834
854
  query?: never;
@@ -900,6 +920,26 @@ export interface paths {
900
920
  patch?: never;
901
921
  trace?: never;
902
922
  };
923
+ "/projects/{uuid}/setup/types": {
924
+ parameters: {
925
+ query?: never;
926
+ header?: never;
927
+ path?: never;
928
+ cookie?: never;
929
+ };
930
+ /**
931
+ * The project's collections and database models with their types, for `veroxm types` (setup keys)
932
+ * @description Names and types only: no entries, secret values or database hosts. Each model field says how its values come back, which filter operators fit it, and whether it can be written.
933
+ */
934
+ get: operations["getProjectTypes"];
935
+ put?: never;
936
+ post?: never;
937
+ delete?: never;
938
+ options?: never;
939
+ head?: never;
940
+ patch?: never;
941
+ trace?: never;
942
+ };
903
943
  "/projects/{uuid}/setup/environment": {
904
944
  parameters: {
905
945
  query?: never;
@@ -1265,6 +1305,8 @@ export interface components {
1265
1305
  errors?: unknown;
1266
1306
  statusCode?: number;
1267
1307
  retryAfterSeconds?: number;
1308
+ /** @description With code `invalid_query`: where in the query text (`q`) the problem is, counting from 0. */
1309
+ at?: number;
1268
1310
  /** @description With code `two_step_required` or `two_step_setup_required`: send it to /auth/two-step (or /auth/two-step/setup/...) to finish signing in. Good for 10 minutes. */
1269
1311
  ticket?: string;
1270
1312
  /** @description With a ticket: the ways the person can take the second step (or set one up). */
@@ -1551,6 +1593,8 @@ export interface components {
1551
1593
  };
1552
1594
  /** @description For example "created_at:desc" or "title:asc,created_at:desc". */
1553
1595
  sort?: string;
1596
+ /** @description Query text instead of `where` and `sort` (not both): `city = "Riyadh" AND area >= 500 AND deleted_at IS EMPTY ORDER BY area DESC`. Operators `= != > >= < <= ~` (contains), `IN (…)`, `NOT IN (…)`, `BETWEEN a AND b`, `IS [NOT] EMPTY`; `OR` between values of one field; dates `-30d`, `-6h`, `now()`, `today()`, `startOfMonth()`, `startOfYear()` (UTC). A query that doesn't parse is 400 `invalid_query` with `at`, its position. */
1597
+ q?: string;
1554
1598
  /** @description "only_draft" for unpublished entries. */
1555
1599
  state?: string;
1556
1600
  offset?: number;
@@ -1784,6 +1828,7 @@ export interface components {
1784
1828
  * @enum {string}
1785
1829
  */
1786
1830
  type: "page" | "track" | "page_end" | "click" | "rage" | "submit" | "scroll" | "vitals";
1831
+ /** @description Required for track. Standard events have checked properties: `$slot_impression` ({ slot, experienceId?, variantId?, path? }) and `$form_submitted` ({ form, responseId?, endingId? }). */
1787
1832
  name?: string;
1788
1833
  properties?: {
1789
1834
  [key: string]: unknown;
@@ -1928,6 +1973,89 @@ export interface components {
1928
1973
  /** @description As in the preview. */
1929
1974
  codeManaged?: boolean;
1930
1975
  };
1976
+ TypedModelField: {
1977
+ name: string;
1978
+ /**
1979
+ * @description How values come back: string, number, number|string (a number when it fits exactly, otherwise text), boolean, json or unknown.
1980
+ * @enum {string}
1981
+ */
1982
+ kind: "string" | "number" | "number|string" | "boolean" | "json" | "unknown";
1983
+ nullable: boolean;
1984
+ /**
1985
+ * @description What the column holds, for the filter operators that make sense on it.
1986
+ * @enum {string}
1987
+ */
1988
+ family: "text" | "number" | "date" | "boolean" | "other";
1989
+ /** @description Callers may filter on it. */
1990
+ filter: boolean;
1991
+ sort: boolean;
1992
+ /** @description Callers may set it on create or update. */
1993
+ write: boolean;
1994
+ /** @description Returned as ••••<last 4> unless asked for in full. */
1995
+ masked: boolean;
1996
+ /** @description Accepted on writes, never returned. */
1997
+ writeOnly: boolean;
1998
+ /** @description Binary data, as base64 text. */
1999
+ binary?: boolean;
2000
+ /** @description A file: returned as a signed link `{ url, expiresAt }` (GET /projects/{uuid}/files/{token}) or null, never its bytes. */
2001
+ file?: boolean;
2002
+ /** @description The values an ENUM column lists. */
2003
+ values?: string[];
2004
+ };
2005
+ ProjectTypes: {
2006
+ /** @enum {string} */
2007
+ format: "veroxm.types";
2008
+ /** @enum {integer} */
2009
+ version: 1;
2010
+ project: {
2011
+ name: string;
2012
+ uuid: string;
2013
+ };
2014
+ collections: {
2015
+ slug: string;
2016
+ name: string;
2017
+ fields: {
2018
+ name: string;
2019
+ /** @description The field type: text, number, boolean, relation, media, enumeration... */
2020
+ type: string;
2021
+ /** @description relation and media: a list (true) or one (false). */
2022
+ many?: boolean;
2023
+ /** @description relation: the related collection's slug. */
2024
+ target?: string | null;
2025
+ /** @description enumeration and multi_enumeration: the listed values. */
2026
+ values?: string[];
2027
+ }[];
2028
+ }[];
2029
+ models: {
2030
+ slug: string;
2031
+ name: string;
2032
+ /** @description The connected database's slug. */
2033
+ database: string;
2034
+ key: {
2035
+ kind: string;
2036
+ family: string;
2037
+ };
2038
+ fields: components["schemas"]["TypedModelField"][];
2039
+ relations: {
2040
+ name: string;
2041
+ /** @enum {string} */
2042
+ kind: "one" | "many";
2043
+ fields: components["schemas"]["TypedModelField"][];
2044
+ }[];
2045
+ writes: {
2046
+ create: boolean;
2047
+ update: boolean;
2048
+ delete: boolean;
2049
+ };
2050
+ }[];
2051
+ databases: string[];
2052
+ processes: string[];
2053
+ /** @description Secret names, never values. */
2054
+ secrets: string[];
2055
+ allowedHosts: string[];
2056
+ /** @description The end-user roles the project lists (sign-in settings). */
2057
+ roles: string[];
2058
+ };
1931
2059
  ProjectEnvironment: {
1932
2060
  /** @description The project's name. */
1933
2061
  project: string;
@@ -3418,6 +3546,8 @@ export interface operations {
3418
3546
  listEntries: {
3419
3547
  parameters: {
3420
3548
  query?: {
3549
+ /** @description Query text instead of `where` and `sort` (not both): `city = "Riyadh" AND area >= 500 AND deleted_at IS EMPTY ORDER BY area DESC`. Operators `= != > >= < <= ~` (contains), `IN (…)`, `NOT IN (…)`, `BETWEEN a AND b`, `IS [NOT] EMPTY`; `OR` between values of one field; dates `-30d`, `-6h`, `now()`, `today()`, `startOfMonth()`, `startOfYear()` (UTC). A query that doesn't parse is 400 `invalid_query` with `at`, its position. */
3550
+ q?: string;
3421
3551
  sort?: string;
3422
3552
  state?: string;
3423
3553
  offset?: number;
@@ -4182,6 +4312,64 @@ export interface operations {
4182
4312
  504: components["responses"]["E504"];
4183
4313
  };
4184
4314
  };
4315
+ getDatabaseFile: {
4316
+ parameters: {
4317
+ query?: never;
4318
+ header?: never;
4319
+ path: {
4320
+ /** @description The project's UUID. */
4321
+ uuid: string;
4322
+ /** @description The last part of the link, as the entry gave it. */
4323
+ token: string;
4324
+ };
4325
+ cookie?: never;
4326
+ };
4327
+ requestBody?: never;
4328
+ responses: {
4329
+ /** @description The file */
4330
+ 200: {
4331
+ headers: {
4332
+ [name: string]: unknown;
4333
+ };
4334
+ content: {
4335
+ "image/png": string;
4336
+ "image/jpeg": string;
4337
+ "image/gif": string;
4338
+ "image/webp": string;
4339
+ "image/bmp": string;
4340
+ "image/avif": string;
4341
+ "application/pdf": string;
4342
+ "image/svg+xml": string;
4343
+ "application/zip": string;
4344
+ "application/octet-stream": string;
4345
+ };
4346
+ };
4347
+ 403: components["responses"]["E403"];
4348
+ 404: components["responses"]["E404"];
4349
+ /** @description The file is over 10 MB */
4350
+ 413: {
4351
+ headers: {
4352
+ [name: string]: unknown;
4353
+ };
4354
+ content: {
4355
+ "application/json": components["schemas"]["Error"];
4356
+ };
4357
+ };
4358
+ /** @description The column's value isn't a file (binary data, a data URL or base64) */
4359
+ 422: {
4360
+ headers: {
4361
+ [name: string]: unknown;
4362
+ };
4363
+ content: {
4364
+ "application/json": components["schemas"]["Error"];
4365
+ };
4366
+ };
4367
+ 429: components["responses"]["E429"];
4368
+ 502: components["responses"]["E502"];
4369
+ 503: components["responses"]["E503"];
4370
+ 504: components["responses"]["E504"];
4371
+ };
4372
+ };
4185
4373
  exportSetup: {
4186
4374
  parameters: {
4187
4375
  query?: never;
@@ -4310,6 +4498,33 @@ export interface operations {
4310
4498
  429: components["responses"]["E429"];
4311
4499
  };
4312
4500
  };
4501
+ getProjectTypes: {
4502
+ parameters: {
4503
+ query?: never;
4504
+ header?: never;
4505
+ path: {
4506
+ /** @description The project's UUID. */
4507
+ uuid: string;
4508
+ };
4509
+ cookie?: never;
4510
+ };
4511
+ requestBody?: never;
4512
+ responses: {
4513
+ /** @description OK */
4514
+ 200: {
4515
+ headers: {
4516
+ [name: string]: unknown;
4517
+ };
4518
+ content: {
4519
+ "application/json": components["schemas"]["ProjectTypes"];
4520
+ };
4521
+ };
4522
+ 401: components["responses"]["E401"];
4523
+ 403: components["responses"]["E403"];
4524
+ 404: components["responses"]["E404"];
4525
+ 429: components["responses"]["E429"];
4526
+ };
4527
+ };
4313
4528
  getProjectEnvironment: {
4314
4529
  parameters: {
4315
4530
  query?: never;
@@ -0,0 +1,42 @@
1
+ import { VeroXMApiError } from './errors.js';
2
+ import { type RequestControl } from './http.js';
3
+ /** One entry of a GraphQL response's `errors` array. */
4
+ export interface GraphQLErrorItem {
5
+ message: string;
6
+ extensions?: Record<string, unknown>;
7
+ }
8
+ /**
9
+ * A GraphQL response that came back with `errors` (the HTTP status is usually 200). `errors` is the response's array;
10
+ * `code` is the first error's `extensions.code` when it has one, such as `QUERY_TOO_COMPLEX`.
11
+ */
12
+ export declare class VeroXMGraphQLError extends VeroXMApiError {
13
+ readonly errors: readonly GraphQLErrorItem[];
14
+ constructor(status: number, body: {
15
+ errors: readonly GraphQLErrorItem[];
16
+ });
17
+ }
18
+ export interface GraphQLRequestOptions extends RequestControl {
19
+ /** Your VeroXM deployment's origin, e.g. "https://cms.example.com". The endpoint is `/public/v2/graphql`. */
20
+ baseUrl: string;
21
+ /** Sent as `Authorization: Bearer <token>`: a project API key, or a signed-in end user's access token. */
22
+ token: string;
23
+ query: string;
24
+ /** Any object (an interface works too); sent as JSON. */
25
+ variables?: object;
26
+ /**
27
+ * Extra attempts (0 to 5) after a network error, a timeout, or 429, 502, 503 or 504, as for `VeroXMApp`'s
28
+ * `retries`. Only for documents without a mutation: a document containing `mutation` is sent once.
29
+ */
30
+ retries?: number;
31
+ /**
32
+ * The fetch to send with, instead of the global one: e.g. one that adds Next.js's `{ cache: 'force-cache', next: {
33
+ * tags } }`, or a test double. It gets the same (url, init) the SDK would pass to fetch.
34
+ */
35
+ fetch?: typeof fetch;
36
+ }
37
+ /**
38
+ * Sends one GraphQL document to the public API and returns its `data`. Rejects with `VeroXMGraphQLError` when the
39
+ * response has `errors`, `VeroXMApiError` for any other non-2xx answer, `VeroXMTimeoutError` after `timeoutMs`, and the
40
+ * signal's reason when `signal` aborts. Used by `@veroxm/react-sdk`; usable on its own for a custom query.
41
+ */
42
+ export declare function graphqlRequest<T = unknown>(options: GraphQLRequestOptions): Promise<T>;
@@ -0,0 +1,50 @@
1
+ import { VeroXMApiError } from './errors.js';
2
+ import { rawRequest } from './http.js';
3
+ /**
4
+ * A GraphQL response that came back with `errors` (the HTTP status is usually 200). `errors` is the response's array;
5
+ * `code` is the first error's `extensions.code` when it has one, such as `QUERY_TOO_COMPLEX`.
6
+ */
7
+ export class VeroXMGraphQLError extends VeroXMApiError {
8
+ constructor(status, body) {
9
+ super(status, body);
10
+ this.name = 'VeroXMGraphQLError';
11
+ this.errors = body.errors;
12
+ if (body.errors[0]?.message)
13
+ this.message = body.errors[0].message;
14
+ const code = body.errors[0]?.extensions?.code;
15
+ if (typeof code === 'string')
16
+ this.code = code;
17
+ }
18
+ }
19
+ /** True when the document has no mutation, so sending it twice changes nothing. Errs towards "not safe". */
20
+ function readOnly(query) {
21
+ return !/\bmutation\b/.test(query);
22
+ }
23
+ /**
24
+ * Sends one GraphQL document to the public API and returns its `data`. Rejects with `VeroXMGraphQLError` when the
25
+ * response has `errors`, `VeroXMApiError` for any other non-2xx answer, `VeroXMTimeoutError` after `timeoutMs`, and the
26
+ * signal's reason when `signal` aborts. Used by `@veroxm/react-sdk`; usable on its own for a custom query.
27
+ */
28
+ export async function graphqlRequest(options) {
29
+ const apiBase = `${options.baseUrl.replace(/\/$/, '')}/public/v2`;
30
+ const body = (await rawRequest(apiBase, {
31
+ method: 'POST',
32
+ path: '/graphql',
33
+ json: { query: options.query, ...(options.variables !== undefined ? { variables: options.variables } : {}) },
34
+ headers: { Authorization: `Bearer ${options.token}` },
35
+ signal: options.signal,
36
+ timeoutMs: options.timeoutMs,
37
+ retries: options.retries,
38
+ }, { repeatable: readOnly(options.query), fetch: options.fetch }).catch((e) => {
39
+ // The API answers a failed GraphQL request with its errors array, whatever the status.
40
+ if (e instanceof VeroXMApiError && hasErrors(e.body))
41
+ throw new VeroXMGraphQLError(e.status, e.body);
42
+ throw e;
43
+ }));
44
+ if (hasErrors(body))
45
+ throw new VeroXMGraphQLError(200, body);
46
+ return (body?.data ?? null);
47
+ }
48
+ function hasErrors(body) {
49
+ return !!body && typeof body === 'object' && Array.isArray(body.errors) && body.errors.length > 0;
50
+ }
package/dist/http.d.ts CHANGED
@@ -34,4 +34,7 @@ export declare function checkTimeout(value: number | undefined): void;
34
34
  *
35
35
  * Without `timeoutMs`, `signal` or `retries` this is a single plain fetch, exactly as before those options existed.
36
36
  */
37
- export declare function rawRequest(apiBase: string, opts: RawRequestOptions): Promise<unknown>;
37
+ export declare function rawRequest(apiBase: string, opts: RawRequestOptions, internal?: {
38
+ repeatable?: boolean;
39
+ fetch?: typeof fetch;
40
+ }): Promise<unknown>;
package/dist/http.js CHANGED
@@ -75,7 +75,7 @@ export function checkTimeout(value) {
75
75
  checkPositive('timeoutMs', value);
76
76
  }
77
77
  /** One attempt. A timeout or the caller's signal aborts the fetch and the reading of the body. */
78
- async function attempt(url, init, control) {
78
+ async function attempt(url, init, control, fetchImpl) {
79
79
  const { signal, timeoutMs } = control;
80
80
  if (signal?.aborted)
81
81
  throw abortReason(signal);
@@ -90,7 +90,7 @@ async function attempt(url, init, control) {
90
90
  }, timeoutMs)
91
91
  : undefined;
92
92
  try {
93
- const res = await fetch(url, controller ? { ...init, signal: controller.signal } : init);
93
+ const res = await fetchImpl(url, controller ? { ...init, signal: controller.signal } : init);
94
94
  const text = await res.text();
95
95
  const parsed = text ? safeJsonParse(text) : null;
96
96
  if (!res.ok) {
@@ -122,7 +122,7 @@ async function attempt(url, init, control) {
122
122
  *
123
123
  * Without `timeoutMs`, `signal` or `retries` this is a single plain fetch, exactly as before those options existed.
124
124
  */
125
- export async function rawRequest(apiBase, opts) {
125
+ export async function rawRequest(apiBase, opts, internal = {}) {
126
126
  checkTimeout(opts.timeoutMs);
127
127
  checkRetries(opts.retries);
128
128
  const base = apiBase.endsWith('/') ? apiBase : `${apiBase}/`;
@@ -144,11 +144,13 @@ export async function rawRequest(apiBase, opts) {
144
144
  }
145
145
  const method = opts.method ?? 'GET';
146
146
  const init = { method, headers, body };
147
- const retries = REPEATABLE.has(method.toUpperCase()) ? (opts.retries ?? 0) : 0;
147
+ // `repeatable` lets a caller vouch for a POST that changes nothing (a GraphQL query).
148
+ const repeatable = internal.repeatable ?? REPEATABLE.has(method.toUpperCase());
149
+ const retries = repeatable ? (opts.retries ?? 0) : 0;
148
150
  const control = { signal: opts.signal, timeoutMs: opts.timeoutMs };
149
151
  for (let n = 0;; n++) {
150
152
  try {
151
- return await attempt(url.toString(), init, control);
153
+ return await attempt(url.toString(), init, control, internal.fetch ?? fetch);
152
154
  }
153
155
  catch (e) {
154
156
  if (n >= retries || !isRetryable(e) || opts.signal?.aborted)
package/dist/index.d.ts CHANGED
@@ -8,6 +8,8 @@ export { createPkce } from './pkce.js';
8
8
  export { ContentResource } from './content.js';
9
9
  export type { ListOptions } from './content.js';
10
10
  export type { RequestControl } from './http.js';
11
+ export { graphqlRequest, VeroXMGraphQLError } from './graphql.js';
12
+ export type { GraphQLErrorItem, GraphQLRequestOptions } from './graphql.js';
11
13
  export { MediaResource } from './media.js';
12
14
  export type { MediaItem, MediaPage, UploadableFile } from './media.js';
13
15
  export { FunctionsResource } from './functions.js';
@@ -18,7 +20,7 @@ export type { ProcessRun, ProcessRunDetail, ProcessRunListOptions } from './proc
18
20
  export { FormsResource } from './forms.js';
19
21
  export type { FormDetail, FormResponse, FormResponseListOptions, FormResponsePage, FormSummary } from './forms.js';
20
22
  export { embedForm, embedFormsFromPage } from './embed.js';
21
- export type { FormEmbed, FormEmbedMode, FormEmbedOpenTrigger, FormEmbedOptions } from './embed.js';
23
+ export type { FormEmbed, FormEmbedMode, FormEmbedOpenTrigger, FormEmbedOptions, FormEmbedTracker } from './embed.js';
22
24
  export type { Schemas } from './schemas.js';
23
25
  export type { paths as ApiPaths, components as ApiComponents, operations as ApiOperations } from './generated/api.js';
24
26
  export { VeroXMApiError, VeroXMNotAuthenticatedError, VeroXMTimeoutError, VeroXMTwoStepRequiredError } from './errors.js';
@@ -28,3 +30,5 @@ export type { TokenStorage, StoredSession, AuthUser } from './token-storage.js';
28
30
  export { VeroxmTracker, createTracker } from './tracker.js';
29
31
  export type { TrackerOptions, TrackerStorage, ConsentChoices, ConsentValue, StoredConsent, ExperienceDecision, GetExperienceOptions, Recommendations, } from './tracker.js';
30
32
  export type { PostHogLike, PosthogExposureHint } from './posthog.js';
33
+ export { STANDARD_EVENTS } from './standard-events.js';
34
+ export type { FormSubmission, SlotTestVariant, StandardEventName } from './standard-events.js';
package/dist/index.js CHANGED
@@ -3,6 +3,8 @@ export { VeroXMAuth } from './auth.js';
3
3
  export { browserPasskeys, creationOptionsFromJSON, credentialToJSON, requestOptionsFromJSON } from './passkeys.js';
4
4
  export { createPkce } from './pkce.js';
5
5
  export { ContentResource } from './content.js';
6
+ // GraphQL (/public/v2/graphql), the transport @veroxm/react-sdk reads through.
7
+ export { graphqlRequest, VeroXMGraphQLError } from './graphql.js';
6
8
  export { MediaResource } from './media.js';
7
9
  export { FunctionsResource } from './functions.js';
8
10
  export { TasksResource } from './tasks.js';
@@ -14,3 +16,5 @@ export { VeroXMApiError, VeroXMNotAuthenticatedError, VeroXMTimeoutError, VeroXM
14
16
  export { MemoryTokenStorage, BrowserLocalStorageTokenStorage } from './token-storage.js';
15
17
  // Experience OS visitor tracking (page views, actions, consent, identify).
16
18
  export { VeroxmTracker, createTracker } from './tracker.js';
19
+ // Standard events: `$slot_impression` and `$form_submitted` (tracker.slotImpression, tracker.formSubmitted).
20
+ export { STANDARD_EVENTS } from './standard-events.js';
@@ -0,0 +1,24 @@
1
+ /** The names of VeroXM's standard events. */
2
+ export declare const STANDARD_EVENTS: {
3
+ /** A slot was shown on a page. Properties: `slot`, and `experienceId` + `variantId` for a slot test's variant. */
4
+ readonly slotImpression: "$slot_impression";
5
+ /** A VeroXM form in the page was sent. Properties: `form` (f_...), `responseId`, `endingId`. */
6
+ readonly formSubmitted: "$form_submitted";
7
+ };
8
+ export type StandardEventName = (typeof STANDARD_EVENTS)[keyof typeof STANDARD_EVENTS];
9
+ /** A slot test's variant, as slot reads and `getExperience` return it. */
10
+ export interface SlotTestVariant {
11
+ experienceId: number;
12
+ variantId: number;
13
+ }
14
+ /** What a form embed reports when the form is sent. */
15
+ export interface FormSubmission {
16
+ responseId?: string;
17
+ endingId?: string | null;
18
+ }
19
+ /**
20
+ * Why the API would refuse this standard event ('' when it wouldn't, or for any other name). The tracker drops a
21
+ * standard event that would be refused, so one bad event can't get a whole batch rejected.
22
+ * @internal
23
+ */
24
+ export declare function standardEventProblem(name: string, p?: Record<string, unknown>): string;
@@ -0,0 +1,40 @@
1
+ // Standard events: `track` events whose name VeroXM defines and whose properties the API checks
2
+ // (apps/api/src/events/standard-events.ts -- keep the two in step). Being `track` events, they work as an
3
+ // experience's goal like any other name: `$form_submitted` as the goal of a test measures form sends.
4
+ /** The names of VeroXM's standard events. */
5
+ export const STANDARD_EVENTS = {
6
+ /** A slot was shown on a page. Properties: `slot`, and `experienceId` + `variantId` for a slot test's variant. */
7
+ slotImpression: '$slot_impression',
8
+ /** A VeroXM form in the page was sent. Properties: `form` (f_...), `responseId`, `endingId`. */
9
+ formSubmitted: '$form_submitted',
10
+ };
11
+ const SLOT_NAME = /^[a-z0-9][a-z0-9._-]{0,119}$/;
12
+ const FORM_ID = /^f_[A-Za-z0-9]{6,40}$/;
13
+ const PUBLIC_ID = /^[A-Za-z0-9_-]{1,64}$/;
14
+ const isId = (v) => typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= 4294967295;
15
+ /**
16
+ * Why the API would refuse this standard event ('' when it wouldn't, or for any other name). The tracker drops a
17
+ * standard event that would be refused, so one bad event can't get a whole batch rejected.
18
+ * @internal
19
+ */
20
+ export function standardEventProblem(name, p = {}) {
21
+ if (name === STANDARD_EVENTS.slotImpression) {
22
+ if (typeof p.slot !== 'string' || !SLOT_NAME.test(p.slot))
23
+ return '"slot" must be a slot name';
24
+ if ((p.experienceId === undefined) !== (p.variantId === undefined))
25
+ return '"experienceId" and "variantId" go together';
26
+ if (p.experienceId !== undefined && (!isId(p.experienceId) || !isId(p.variantId)))
27
+ return '"experienceId" and "variantId" must be positive integers';
28
+ if (p.path !== undefined && (typeof p.path !== 'string' || p.path.length > 500))
29
+ return '"path" must be text of at most 500 characters';
30
+ }
31
+ else if (name === STANDARD_EVENTS.formSubmitted) {
32
+ if (typeof p.form !== 'string' || !FORM_ID.test(p.form))
33
+ return '"form" must be a form id (f_...)';
34
+ if (p.responseId !== undefined && (typeof p.responseId !== 'string' || !PUBLIC_ID.test(p.responseId)))
35
+ return '"responseId" must be a response id';
36
+ if (p.endingId !== undefined && p.endingId !== null && (typeof p.endingId !== 'string' || !PUBLIC_ID.test(p.endingId)))
37
+ return '"endingId" must be an ending id or null';
38
+ }
39
+ return '';
40
+ }
package/dist/tracker.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { Schemas } from './schemas.js';
2
2
  import { type Vitals } from './autocapture.js';
3
3
  import { type PostHogLike, type PosthogExposureHint } from './posthog.js';
4
+ import { type FormSubmission, type SlotTestVariant } from './standard-events.js';
4
5
  export interface TrackerStorage {
5
6
  get(key: string): string | null;
6
7
  set(key: string, value: string): void;
@@ -129,6 +130,8 @@ export declare class VeroxmTracker {
129
130
  private session;
130
131
  private pageState;
131
132
  private pagesSeen;
133
+ /** Slot impressions sent for this page view (slot:variant). */
134
+ private readonly impressions;
132
135
  private readonly vitals;
133
136
  private scrollCheckedAt;
134
137
  private scrollTimer;
@@ -150,6 +153,18 @@ export declare class VeroxmTracker {
150
153
  getConsent(): StoredConsent;
151
154
  /** Records an action, e.g. track('demo_requested', { plan: 'enterprise' }). */
152
155
  track(name: string, properties?: Record<string, unknown>): void;
156
+ /**
157
+ * Records that a slot was shown (`$slot_impression`), with the visitor's variant when the slot is under test.
158
+ * Sent once per slot and variant per page view, however often it is called (re-renders don't count again).
159
+ * @since 1.10.0
160
+ */
161
+ slotImpression(slot: string, test?: SlotTestVariant | null): void;
162
+ /**
163
+ * Records that a VeroXM form was sent (`$form_submitted`). `embedForm` and `<VeroxmForm>` call this for you when
164
+ * given a tracker. Use `$form_submitted` as an experience's goal to measure form sends.
165
+ * @since 1.10.0
166
+ */
167
+ formSubmitted(form: string, submission?: FormSubmission): void;
153
168
  /** Records a page or screen view. In a browser, path/url/title/referrer are added automatically. */
154
169
  page(properties?: Record<string, unknown>): void;
155
170
  /** Saves the visitor's consent answers (true = granted, false = denied, omitted = unchanged). */
package/dist/tracker.js CHANGED
@@ -48,10 +48,14 @@
48
48
  // data-veroxm-ignore on an element (or an ancestor) leaves it out;
49
49
  // data-veroxm-mask keeps its text out. Held until consent like everything else.
50
50
  //
51
+ // Standard events (increment 8): slotImpression() and formSubmitted() send `$slot_impression` and `$form_submitted`,
52
+ // `track` events with checked properties (standard-events.ts).
53
+ //
51
54
  // PostHog (Insights I1): when the project sends test exposures to PostHog, a decision carries `posthog` and the
52
55
  // tracker sends the exposure to the page's PostHog (window.posthog, or the `posthog` option) -- see posthog.ts.
53
56
  import { ClsWindow, MAX_PATH, RageDetector, campaignKey, clickTarget, fraction, hrefFor, isIgnored, labelFor, nextSession, parseSession, scrollBucket, selectorFor, shortText, vitalsReport, } from './autocapture.js';
54
57
  import { findPosthog, readHint, sendPosthogExposure } from './posthog.js';
58
+ import { STANDARD_EVENTS, standardEventProblem } from './standard-events.js';
55
59
  const BATCH_SIZE = 20;
56
60
  const MAX_QUEUE = 1000;
57
61
  const MAX_BACKOFF_MS = 5 * 60 * 1000;
@@ -127,6 +131,8 @@ export class VeroxmTracker {
127
131
  this.session = null;
128
132
  this.pageState = null;
129
133
  this.pagesSeen = 0;
134
+ /** Slot impressions sent for this page view (slot:variant). */
135
+ this.impressions = new Set();
130
136
  this.vitals = {};
131
137
  this.scrollCheckedAt = 0;
132
138
  this.scrollTimer = null;
@@ -203,8 +209,43 @@ export class VeroxmTracker {
203
209
  }
204
210
  /** Records an action, e.g. track('demo_requested', { plan: 'enterprise' }). */
205
211
  track(name, properties) {
212
+ // A standard event the API would refuse is dropped here, so it can't get the rest of its batch rejected.
213
+ const problem = standardEventProblem(name, properties);
214
+ if (problem) {
215
+ this.onError(new Error(`VeroXM: ${name} not sent: ${problem}`));
216
+ return;
217
+ }
206
218
  this.enqueue({ type: 'track', name, properties });
207
219
  }
220
+ /**
221
+ * Records that a slot was shown (`$slot_impression`), with the visitor's variant when the slot is under test.
222
+ * Sent once per slot and variant per page view, however often it is called (re-renders don't count again).
223
+ * @since 1.10.0
224
+ */
225
+ slotImpression(slot, test) {
226
+ const key = `${slot}:${test?.variantId ?? ''}`;
227
+ if (this.impressions.has(key))
228
+ return;
229
+ this.impressions.add(key);
230
+ const path = typeof window !== 'undefined' && window.location ? window.location.pathname.slice(0, MAX_PATH) : undefined;
231
+ this.track(STANDARD_EVENTS.slotImpression, {
232
+ slot,
233
+ ...(test ? { experienceId: test.experienceId, variantId: test.variantId } : {}),
234
+ ...(path ? { path } : {}),
235
+ });
236
+ }
237
+ /**
238
+ * Records that a VeroXM form was sent (`$form_submitted`). `embedForm` and `<VeroxmForm>` call this for you when
239
+ * given a tracker. Use `$form_submitted` as an experience's goal to measure form sends.
240
+ * @since 1.10.0
241
+ */
242
+ formSubmitted(form, submission = {}) {
243
+ this.track(STANDARD_EVENTS.formSubmitted, {
244
+ form,
245
+ ...(submission.responseId ? { responseId: submission.responseId } : {}),
246
+ ...(submission.endingId !== undefined ? { endingId: submission.endingId } : {}),
247
+ });
248
+ }
208
249
  /** Records a page or screen view. In a browser, path/url/title/referrer are added automatically. */
209
250
  page(properties) {
210
251
  const auto = {};
@@ -218,6 +259,10 @@ export class VeroxmTracker {
218
259
  auto.referrer = document.referrer;
219
260
  }
220
261
  }
262
+ // A later page view (a single-page app moving on): slots shown on it count again. Impressions recorded before the
263
+ // first page() of a load belong to that first page view.
264
+ if (this.pagesSeen > 0)
265
+ this.impressions.clear();
221
266
  // A single-page app moving on: the page before it is done.
222
267
  if (this.pageState) {
223
268
  this.pausePage();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veroxm/sdk",
3
- "version": "1.10.0",
3
+ "version": "1.11.0",
4
4
  "description": "VeroXM client for JavaScript and TypeScript: content, media, experiences, events and the visitor tracker.",
5
5
  "keywords": [
6
6
  "veroxm",