@veroxm/sdk 0.3.0 → 1.1.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,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.1.0
4
+
5
+ - `tracker.identifyAccount(accessToken, traits?)`: links the visitor to a signed-in end user's account, checked
6
+ with their own access token, so segments can target `account.role` and `account.emailVerified`, which a page
7
+ can't fake. Needs a VeroXM with accounts linking (public API 2.2); an older one answers 400.
8
+ - `Schemas['IdentifyRequest']`: `userId` is optional, and `accountToken` is new.
9
+
10
+ ## 1.0.0
11
+
12
+ - Stable: from 1.0, breaking changes come only in a major version, after a deprecation period. What that covers
13
+ and what it doesn't: the [stability policy](https://docs.veroxm.com/sdks/stability). The public API is listed in `api-report.md`.
14
+ - `auth.signInWithCredentials()` resolves to the signed-in person (`AuthUser | null`), like `signInWithEmail()`. It
15
+ resolved to nothing before; code that ignores the result is unaffected.
16
+ - `VeroXMApp.request()` is marked `@internal`: use the resources (`content`, `media`, `functions`, `tasks`,
17
+ `processes`), or `ApiPaths` with a typed fetch helper, for calls the SDK doesn't wrap.
18
+
3
19
  ## 0.3.0
4
20
 
5
21
  - `app.functions` (call functions with an HTTP trigger), `app.tasks` (process tasks for end users and server keys)
package/README.md CHANGED
@@ -343,6 +343,12 @@ try {
343
343
  }
344
344
  ```
345
345
 
346
+ ## Stability
347
+
348
+ Follows semantic versioning. From 1.0, breaking changes come only in a major version, after at least one minor release with the
349
+ feature marked deprecated. What the promise covers (and what it doesn't, such as anything marked `@internal` or
350
+ `@experimental`) is in the [stability policy](https://docs.veroxm.com/sdks/stability).
351
+
346
352
  ## Documentation and support
347
353
 
348
354
  - Guide: https://docs.veroxm.com/sdks#veroxm-sdk
package/dist/auth.d.ts CHANGED
@@ -56,7 +56,7 @@ export declare class VeroXMAuth {
56
56
  /** Static-key mode: no login round-trip, no expiry, no refresh token. */
57
57
  signInWithApiKey(apiKey: string): void;
58
58
  /** Username/password mode -- exchanges credentials for an access+refresh token pair and persists it via the configured TokenStorage. */
59
- signInWithCredentials(username: string, password: string): Promise<void>;
59
+ signInWithCredentials(username: string, password: string): Promise<AuthUser | null>;
60
60
  /** Signs in a built-in account with its email and password. Throws VeroXMApiError with code `email_not_verified` until the email is confirmed. */
61
61
  signInWithEmail(email: string, password: string): Promise<AuthUser | null>;
62
62
  /** Signs out here: the refresh token is revoked on the server too (best effort), and the stored session cleared. */
package/dist/auth.js CHANGED
@@ -63,6 +63,7 @@ export class VeroXMAuth {
63
63
  }));
64
64
  this.apiKey = null;
65
65
  await this.persistSession(data);
66
+ return this.currentUser();
66
67
  }
67
68
  /** Signs in a built-in account with its email and password. Throws VeroXMApiError with code `email_not_verified` until the email is confirmed. */
68
69
  async signInWithEmail(email, password) {
package/dist/client.d.ts CHANGED
@@ -42,6 +42,9 @@ export declare class VeroXMApp {
42
42
  * 401 (clock skew, or a token revoked server-side since the last
43
43
  * proactive refresh), forces one refresh and retries exactly once
44
44
  * before giving up.
45
+ *
46
+ * @internal Not part of the stable API (docs/SDK-STABILITY.md): its options can change in a minor release. Use the
47
+ * resources (`content`, `media`, `functions`, `tasks`, `processes`), or `ApiPaths` with a typed fetch helper.
45
48
  */
46
49
  request(opts: RawRequestOptions): Promise<unknown>;
47
50
  }
package/dist/client.js CHANGED
@@ -45,6 +45,9 @@ export class VeroXMApp {
45
45
  * 401 (clock skew, or a token revoked server-side since the last
46
46
  * proactive refresh), forces one refresh and retries exactly once
47
47
  * before giving up.
48
+ *
49
+ * @internal Not part of the stable API (docs/SDK-STABILITY.md): its options can change in a minor release. Use the
50
+ * resources (`content`, `media`, `functions`, `tasks`, `processes`), or `ApiPaths` with a typed fetch helper.
48
51
  */
49
52
  async request(opts) {
50
53
  const token = await this.auth.getAccessToken();
@@ -492,6 +492,60 @@ export interface paths {
492
492
  patch?: never;
493
493
  trace?: never;
494
494
  };
495
+ "/projects/{uuid}/setup": {
496
+ parameters: {
497
+ query?: never;
498
+ header?: never;
499
+ path?: never;
500
+ cookie?: never;
501
+ };
502
+ /** The project's setup file (setup keys) */
503
+ get: operations["exportSetup"];
504
+ put?: never;
505
+ post?: never;
506
+ delete?: never;
507
+ options?: never;
508
+ head?: never;
509
+ patch?: never;
510
+ trace?: never;
511
+ };
512
+ "/projects/{uuid}/setup/preview": {
513
+ parameters: {
514
+ query?: never;
515
+ header?: never;
516
+ path?: never;
517
+ cookie?: never;
518
+ };
519
+ get?: never;
520
+ put?: never;
521
+ /** Compare a setup file with the project, changing nothing (setup keys) */
522
+ post: operations["previewSetup"];
523
+ delete?: never;
524
+ options?: never;
525
+ head?: never;
526
+ patch?: never;
527
+ trace?: never;
528
+ };
529
+ "/projects/{uuid}/setup/apply": {
530
+ parameters: {
531
+ query?: never;
532
+ header?: never;
533
+ path?: never;
534
+ cookie?: never;
535
+ };
536
+ get?: never;
537
+ put?: never;
538
+ /**
539
+ * Apply a previewed setup file, all or nothing (setup keys)
540
+ * @description Makes the changes a preview listed with `applies: true`. 409 (`code: "stale_preview"`) when the project changed after the preview: preview again.
541
+ */
542
+ post: operations["applySetup"];
543
+ delete?: never;
544
+ options?: never;
545
+ head?: never;
546
+ patch?: never;
547
+ trace?: never;
548
+ };
495
549
  "/projects/{uuid}/events": {
496
550
  parameters: {
497
551
  query?: never;
@@ -535,7 +589,7 @@ export interface paths {
535
589
  };
536
590
  get?: never;
537
591
  put?: never;
538
- /** Link a visitor to your user id */
592
+ /** Link a visitor to your user id, or to a signed-in end user with their accountToken */
539
593
  post: operations["identify"];
540
594
  delete?: never;
541
595
  options?: never;
@@ -944,7 +998,10 @@ export interface components {
944
998
  };
945
999
  IdentifyRequest: {
946
1000
  visitorId: string;
947
- userId: string;
1001
+ /** @description Your own id for this person. Not with accountToken; ids starting "account:" are refused. */
1002
+ userId?: string;
1003
+ /** @description A signed-in end user's access token: links the visitor to that account (the profile's user id is then "account:<id>"). */
1004
+ accountToken?: string;
948
1005
  traits?: {
949
1006
  [key: string]: unknown;
950
1007
  };
@@ -978,6 +1035,50 @@ export interface components {
978
1035
  strategy: "personal" | "popular";
979
1036
  items: components["schemas"]["Entry"][];
980
1037
  };
1038
+ /** @description A project setup file, as GET /setup returns it: `format` ("veroxm.project-config"), `version`, the locales, collections and fields, webhooks, functions (with their code), sign-in settings and providers, segments, experiences, journeys, processes, slots and the approval workflow. An area a file leaves out is left alone. See docs.veroxm.com/managing-projects/environments#setup-file. */
1039
+ SetupFile: {
1040
+ [key: string]: unknown;
1041
+ };
1042
+ SetupChange: {
1043
+ /**
1044
+ * @description remove: in the project, not the file. conflict: differs but can't be applied (detail says why).
1045
+ * @enum {string}
1046
+ */
1047
+ kind: "add" | "change" | "remove" | "conflict";
1048
+ /** @description What it is: "collection", "field", "function", "experience", "journey", ... (an open set). */
1049
+ area: string;
1050
+ /** @description Which one: a slug, a name or a key. */
1051
+ key: string;
1052
+ /** @description What differs, or why it can't be applied. */
1053
+ detail: string;
1054
+ /** @description Whether apply makes this change. */
1055
+ applies: boolean;
1056
+ };
1057
+ SetupPreview: {
1058
+ /** @description The file's problems ("path: problem"). When there are any, nothing else is compared. */
1059
+ errors: string[];
1060
+ changes: components["schemas"]["SetupChange"][];
1061
+ /** @description The project's setup as compared. Send it with apply, which refuses if the project changed since. */
1062
+ baseHash: string;
1063
+ };
1064
+ SetupPreviewRequest: {
1065
+ config: components["schemas"]["SetupFile"];
1066
+ /** @description Also list (and, for webhooks, functions and sign-in providers, remove) what the project has and the file doesn't. */
1067
+ prune?: boolean;
1068
+ };
1069
+ SetupApplyRequest: {
1070
+ config: components["schemas"]["SetupFile"];
1071
+ /** @description From the preview. */
1072
+ baseHash: string;
1073
+ /** @description As in the preview. */
1074
+ prune?: boolean;
1075
+ };
1076
+ SetupApplied: {
1077
+ /** @description How many changes were made. */
1078
+ applied: number;
1079
+ /** @description The changes made. */
1080
+ changes: components["schemas"]["SetupChange"][];
1081
+ };
981
1082
  };
982
1083
  responses: {
983
1084
  /** @description The request is not valid */
@@ -2234,6 +2335,96 @@ export interface operations {
2234
2335
  429: components["responses"]["E429"];
2235
2336
  };
2236
2337
  };
2338
+ exportSetup: {
2339
+ parameters: {
2340
+ query?: never;
2341
+ header?: never;
2342
+ path: {
2343
+ /** @description The project's UUID. */
2344
+ uuid: string;
2345
+ };
2346
+ cookie?: never;
2347
+ };
2348
+ requestBody?: never;
2349
+ responses: {
2350
+ /** @description OK */
2351
+ 200: {
2352
+ headers: {
2353
+ [name: string]: unknown;
2354
+ };
2355
+ content: {
2356
+ "application/json": components["schemas"]["SetupFile"];
2357
+ };
2358
+ };
2359
+ 401: components["responses"]["E401"];
2360
+ 403: components["responses"]["E403"];
2361
+ 429: components["responses"]["E429"];
2362
+ };
2363
+ };
2364
+ previewSetup: {
2365
+ parameters: {
2366
+ query?: never;
2367
+ header?: never;
2368
+ path: {
2369
+ /** @description The project's UUID. */
2370
+ uuid: string;
2371
+ };
2372
+ cookie?: never;
2373
+ };
2374
+ requestBody: {
2375
+ content: {
2376
+ "application/json": components["schemas"]["SetupPreviewRequest"];
2377
+ };
2378
+ };
2379
+ responses: {
2380
+ /** @description OK */
2381
+ 200: {
2382
+ headers: {
2383
+ [name: string]: unknown;
2384
+ };
2385
+ content: {
2386
+ "application/json": components["schemas"]["SetupPreview"];
2387
+ };
2388
+ };
2389
+ 401: components["responses"]["E401"];
2390
+ 403: components["responses"]["E403"];
2391
+ 413: components["responses"]["E413"];
2392
+ 429: components["responses"]["E429"];
2393
+ };
2394
+ };
2395
+ applySetup: {
2396
+ parameters: {
2397
+ query?: never;
2398
+ header?: never;
2399
+ path: {
2400
+ /** @description The project's UUID. */
2401
+ uuid: string;
2402
+ };
2403
+ cookie?: never;
2404
+ };
2405
+ requestBody: {
2406
+ content: {
2407
+ "application/json": components["schemas"]["SetupApplyRequest"];
2408
+ };
2409
+ };
2410
+ responses: {
2411
+ /** @description OK */
2412
+ 200: {
2413
+ headers: {
2414
+ [name: string]: unknown;
2415
+ };
2416
+ content: {
2417
+ "application/json": components["schemas"]["SetupApplied"];
2418
+ };
2419
+ };
2420
+ 400: components["responses"]["E400"];
2421
+ 401: components["responses"]["E401"];
2422
+ 403: components["responses"]["E403"];
2423
+ 409: components["responses"]["E409"];
2424
+ 413: components["responses"]["E413"];
2425
+ 429: components["responses"]["E429"];
2426
+ };
2427
+ };
2237
2428
  sendEvents: {
2238
2429
  parameters: {
2239
2430
  query?: never;
package/dist/tracker.d.ts CHANGED
@@ -98,6 +98,13 @@ export declare class VeroxmTracker {
98
98
  consent(choices: ConsentChoices): Promise<void>;
99
99
  /** Links this visitor to your own user id (e.g. after sign-in) and updates their traits. Needs analytics consent. */
100
100
  identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
101
+ /**
102
+ * Links this visitor to a signed-in end user's account (built-in accounts or your sign-in provider), checked with
103
+ * their own access token, so segments can target account roles that a page can't fake. Needs analytics consent.
104
+ * Call it after sign-in, e.g. `tracker.identifyAccount(await app.auth.getAccessToken())`.
105
+ * @since 1.1.0
106
+ */
107
+ identifyAccount(accessToken: string, traits?: Record<string, unknown>): Promise<void>;
101
108
  /** Call on sign-out: starts a new anonymous visitor on this device. Consent answers are kept. */
102
109
  reset(): void;
103
110
  /**
package/dist/tracker.js CHANGED
@@ -217,6 +217,19 @@ export class VeroxmTracker {
217
217
  await this.post('/identify', { visitorId: this.visitorId, userId, ...(traits ? { traits } : {}) }).catch((e) => this.onError(e));
218
218
  this.changed(); // traits can change which segment the visitor is in
219
219
  }
220
+ /**
221
+ * Links this visitor to a signed-in end user's account (built-in accounts or your sign-in provider), checked with
222
+ * their own access token, so segments can target account roles that a page can't fake. Needs analytics consent.
223
+ * Call it after sign-in, e.g. `tracker.identifyAccount(await app.auth.getAccessToken())`.
224
+ * @since 1.1.0
225
+ */
226
+ async identifyAccount(accessToken, traits) {
227
+ if (!this.canSend())
228
+ return;
229
+ await this.flush();
230
+ await this.post('/identify', { visitorId: this.visitorId, accountToken: accessToken, ...(traits ? { traits } : {}) }).catch((e) => this.onError(e));
231
+ this.changed();
232
+ }
220
233
  /** Call on sign-out: starts a new anonymous visitor on this device. Consent answers are kept. */
221
234
  reset() {
222
235
  this.queue = [];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veroxm/sdk",
3
- "version": "0.3.0",
3
+ "version": "1.1.0",
4
4
  "description": "VeroXM client for JavaScript and TypeScript: content, media, experiences, events and the visitor tracker.",
5
5
  "keywords": [
6
6
  "veroxm",
@@ -43,7 +43,8 @@
43
43
  "scripts": {
44
44
  "build": "tsc -p tsconfig.json",
45
45
  "test": "vitest run",
46
- "gen:types": "node scripts/gen-types.mjs"
46
+ "gen:types": "node scripts/gen-types.mjs",
47
+ "api:report": "node ../../scripts/api-report.mjs . --write"
47
48
  },
48
49
  "devDependencies": {
49
50
  "openapi-typescript": "^7.13.0",