@veroxm/sdk 0.2.0 → 1.0.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 +20 -0
- package/README.md +49 -1
- package/dist/auth.d.ts +8 -13
- package/dist/auth.js +1 -0
- package/dist/client.d.ts +14 -2
- package/dist/client.js +11 -2
- package/dist/errors.js +6 -0
- package/dist/functions.d.ts +21 -0
- package/dist/functions.js +24 -0
- package/dist/generated/api.d.ts +2586 -0
- package/dist/generated/api.js +5 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.js +3 -0
- package/dist/media.d.ts +5 -16
- package/dist/processes.d.ts +25 -0
- package/dist/processes.js +23 -0
- package/dist/schemas.d.ts +6 -0
- package/dist/schemas.js +1 -0
- package/dist/tasks.d.ts +24 -0
- package/dist/tasks.js +23 -0
- package/dist/token-storage.d.ts +2 -7
- package/dist/tracker.d.ts +9 -5
- package/dist/tracker.js +1 -1
- package/package.json +5 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.0.0
|
|
4
|
+
|
|
5
|
+
- Stable: from 1.0, breaking changes come only in a major version, after a deprecation period. What that covers
|
|
6
|
+
and what it doesn't: the [stability policy](https://docs.veroxm.com/sdks/stability). The public API is listed in `api-report.md`.
|
|
7
|
+
- `auth.signInWithCredentials()` resolves to the signed-in person (`AuthUser | null`), like `signInWithEmail()`. It
|
|
8
|
+
resolved to nothing before; code that ignores the result is unaffected.
|
|
9
|
+
- `VeroXMApp.request()` is marked `@internal`: use the resources (`content`, `media`, `functions`, `tasks`,
|
|
10
|
+
`processes`), or `ApiPaths` with a typed fetch helper, for calls the SDK doesn't wrap.
|
|
11
|
+
|
|
12
|
+
## 0.3.0
|
|
13
|
+
|
|
14
|
+
- `app.functions` (call functions with an HTTP trigger), `app.tasks` (process tasks for end users and server keys)
|
|
15
|
+
and `app.processes` (start runs and read them, server keys).
|
|
16
|
+
- Types generated from the API's OpenAPI document (`/public/v2/openapi.json`): `MediaItem`, `Account`,
|
|
17
|
+
`AuthUser` and the rest are the API's own schemas, exported as `Schemas`, with `ApiPaths` and `ApiOperations`.
|
|
18
|
+
`MediaItem` gains the WebP addresses, tags, focal point and hotspots the API already sent.
|
|
19
|
+
- `ExperienceDecision.reason` includes `'holdout'` (a visitor in the impact holdout): show your default.
|
|
20
|
+
- Fixed: for the API framework's own errors (a malformed id, a body that fails validation),
|
|
21
|
+
`VeroXMApiError.message` is the reason, such as "Validation failed (numeric string is expected)", not "Bad Request".
|
|
22
|
+
|
|
3
23
|
## 0.2.0
|
|
4
24
|
|
|
5
25
|
- End-user accounts on `app.auth`: `signUp`, `verifyEmail`, `resendVerification`, `signInWithEmail`,
|
package/README.md
CHANGED
|
@@ -239,7 +239,7 @@ and/or a JSON config.
|
|
|
239
239
|
|
|
240
240
|
```ts
|
|
241
241
|
const d = await tracker.getExperience<HeroEntry, { cta?: string }>('home.hero');
|
|
242
|
-
if (d.reason === 'none') renderDefaultHero();
|
|
242
|
+
if (d.reason === 'none' || d.reason === 'holdout') renderDefaultHero();
|
|
243
243
|
else renderHero(d.content ?? defaultHero, d.config?.cta);
|
|
244
244
|
|
|
245
245
|
// A config-only experience doubles as a feature flag:
|
|
@@ -251,6 +251,8 @@ const stop = tracker.subscribe(() => rerenderExperiences());
|
|
|
251
251
|
|
|
252
252
|
- **Never throws.** Errors and timeouts (`timeoutMs`, default 1500) resolve
|
|
253
253
|
to `reason: 'none'` with `error` set -- show your default.
|
|
254
|
+
- **Holdout:** a visitor in the project's impact holdout gets
|
|
255
|
+
`reason: 'holdout'` -- show your default for that too.
|
|
254
256
|
- **Consent:** before analytics consent it resolves to `'none'` with
|
|
255
257
|
`waitingForConsent: true` and makes no request (a sticky assignment needs
|
|
256
258
|
a stored visitor id, and the server records an exposure). Segment
|
|
@@ -281,6 +283,46 @@ read; otherwise (and to fill a short list) you get the most-read entries.
|
|
|
281
283
|
What the visitor already read is left out of personal results. Never
|
|
282
284
|
throws: an error returns an empty list with `error` set.
|
|
283
285
|
|
|
286
|
+
## Functions, tasks and processes
|
|
287
|
+
|
|
288
|
+
```ts
|
|
289
|
+
// A function with an HTTP trigger (Developer > Functions). JSON comes back parsed,
|
|
290
|
+
// text as a string, and null when the function returned nothing.
|
|
291
|
+
const quote = await app.functions.call<{ total: number }>('price-quote', { items: [1, 2] });
|
|
292
|
+
const hello = await app.functions.get<string>('greet', { name: 'Amira' });
|
|
293
|
+
|
|
294
|
+
// Process tasks: a signed-in person's own, or any of the project's with a server key.
|
|
295
|
+
const tasks = await app.tasks.list(); // open ones; { status, entryId } to filter
|
|
296
|
+
const task = await app.tasks.get(tasks[0].id); // task.record: the entry's current values
|
|
297
|
+
await app.tasks.complete(task.id, 'approve', { note: 'Looks good' });
|
|
298
|
+
|
|
299
|
+
// Processes, from your server (a key with every ability).
|
|
300
|
+
const { runId } = await app.processes.start('onboarding', entryId, { plan: 'gold' });
|
|
301
|
+
const run = await app.processes.run(runId); // run.activity: what each step did
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
A function that fails rejects with `VeroXMApiError` whose `code` is
|
|
305
|
+
`function_error` (the error is in the call log), `function_timeout`,
|
|
306
|
+
`function_limit` (the month's limit is used up) or `functions_disabled`.
|
|
307
|
+
A process that can't start rejects with a 409 and `code` `already_running`,
|
|
308
|
+
`already_ran`, `not_live` or `no_entry`.
|
|
309
|
+
|
|
310
|
+
## Types from the API
|
|
311
|
+
|
|
312
|
+
The SDK's types are generated from the public API's OpenAPI document, which
|
|
313
|
+
the API serves at `/public/v2/openapi.json`, so they can't drift from what it
|
|
314
|
+
sends. They're exported too:
|
|
315
|
+
|
|
316
|
+
```ts
|
|
317
|
+
import type { Schemas, ApiPaths, ApiOperations } from '@veroxm/sdk';
|
|
318
|
+
|
|
319
|
+
type Task = Schemas['Task'];
|
|
320
|
+
type Decision = Schemas['Decision'];
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
`ApiPaths` works with typed fetch helpers such as `openapi-fetch` if you
|
|
324
|
+
call a route the SDK doesn't wrap.
|
|
325
|
+
|
|
284
326
|
## Errors
|
|
285
327
|
|
|
286
328
|
Every non-2xx response throws `VeroXMApiError` (`.status`, `.body`, a
|
|
@@ -301,6 +343,12 @@ try {
|
|
|
301
343
|
}
|
|
302
344
|
```
|
|
303
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
|
+
|
|
304
352
|
## Documentation and support
|
|
305
353
|
|
|
306
354
|
- Guide: https://docs.veroxm.com/sdks#veroxm-sdk
|
package/dist/auth.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { AuthUser, TokenStorage } from './token-storage.js';
|
|
2
|
+
import type { Schemas } from './schemas.js';
|
|
2
3
|
/** A code from an email, with the address; or the token from the email's link. */
|
|
3
4
|
export type EmailCode = {
|
|
4
5
|
email: string;
|
|
@@ -6,19 +7,13 @@ export type EmailCode = {
|
|
|
6
7
|
} | {
|
|
7
8
|
token: string;
|
|
8
9
|
};
|
|
9
|
-
/**
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
signInMethods: string[];
|
|
15
|
-
}
|
|
10
|
+
/**
|
|
11
|
+
* The signed-in person's account, from `getAccount()`. `signInMethods`: `password`, a social provider's key such as
|
|
12
|
+
* `google`, or `identity_provider`.
|
|
13
|
+
*/
|
|
14
|
+
export type Account = Schemas['Account'];
|
|
16
15
|
/** A social sign-in option to show a button for. */
|
|
17
|
-
export
|
|
18
|
-
key: string;
|
|
19
|
-
kind: 'google' | 'microsoft' | 'apple' | 'oidc';
|
|
20
|
-
name: string;
|
|
21
|
-
}
|
|
16
|
+
export type SocialProvider = Schemas['SocialProvider'];
|
|
22
17
|
/** What `startSocialSignIn` returns: send the person to `url`, keep the rest until they come back. */
|
|
23
18
|
export interface SocialSignInStart {
|
|
24
19
|
url: string;
|
|
@@ -61,7 +56,7 @@ export declare class VeroXMAuth {
|
|
|
61
56
|
/** Static-key mode: no login round-trip, no expiry, no refresh token. */
|
|
62
57
|
signInWithApiKey(apiKey: string): void;
|
|
63
58
|
/** Username/password mode -- exchanges credentials for an access+refresh token pair and persists it via the configured TokenStorage. */
|
|
64
|
-
signInWithCredentials(username: string, password: string): Promise<
|
|
59
|
+
signInWithCredentials(username: string, password: string): Promise<AuthUser | null>;
|
|
65
60
|
/** Signs in a built-in account with its email and password. Throws VeroXMApiError with code `email_not_verified` until the email is confirmed. */
|
|
66
61
|
signInWithEmail(email: string, password: string): Promise<AuthUser | null>;
|
|
67
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
|
@@ -2,6 +2,9 @@ import { type RawRequestOptions } from './http.js';
|
|
|
2
2
|
import { VeroXMAuth, type PendingStore } from './auth.js';
|
|
3
3
|
import { ContentResource } from './content.js';
|
|
4
4
|
import { MediaResource } from './media.js';
|
|
5
|
+
import { FunctionsResource } from './functions.js';
|
|
6
|
+
import { TasksResource } from './tasks.js';
|
|
7
|
+
import { ProcessesResource } from './processes.js';
|
|
5
8
|
import { type TokenStorage } from './token-storage.js';
|
|
6
9
|
export interface VeroXMAppOptions {
|
|
7
10
|
/** Your VeroXM deployment's origin, e.g. "https://cms.example.com" -- no trailing /public/... needed, VeroXMApp builds that itself. */
|
|
@@ -15,11 +18,17 @@ export interface VeroXMAppOptions {
|
|
|
15
18
|
}
|
|
16
19
|
/**
|
|
17
20
|
* The SDK's entry point -- one `initializeApp()` call, Firebase-style,
|
|
18
|
-
* then `app.auth`, `app.content(slug)`,
|
|
19
|
-
* else. See this package's README for a full quickstart.
|
|
21
|
+
* then `app.auth`, `app.content(slug)`, `app.media()`, `app.functions`,
|
|
22
|
+
* `app.tasks` and `app.processes` for everything else. See this package's README for a full quickstart.
|
|
20
23
|
*/
|
|
21
24
|
export declare class VeroXMApp {
|
|
22
25
|
readonly auth: VeroXMAuth;
|
|
26
|
+
/** Project functions with an HTTP trigger: `app.functions.call('quote', {items})`. */
|
|
27
|
+
readonly functions: FunctionsResource;
|
|
28
|
+
/** Process tasks: an end user's own, or any of the project's with a server key. */
|
|
29
|
+
readonly tasks: TasksResource;
|
|
30
|
+
/** Start processes and read their runs (server keys). */
|
|
31
|
+
readonly processes: ProcessesResource;
|
|
23
32
|
private readonly apiBase;
|
|
24
33
|
private constructor();
|
|
25
34
|
static initializeApp(options: VeroXMAppOptions): VeroXMApp;
|
|
@@ -33,6 +42,9 @@ export declare class VeroXMApp {
|
|
|
33
42
|
* 401 (clock skew, or a token revoked server-side since the last
|
|
34
43
|
* proactive refresh), forces one refresh and retries exactly once
|
|
35
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.
|
|
36
48
|
*/
|
|
37
49
|
request(opts: RawRequestOptions): Promise<unknown>;
|
|
38
50
|
}
|
package/dist/client.js
CHANGED
|
@@ -3,6 +3,9 @@ import { VeroXMApiError } from './errors.js';
|
|
|
3
3
|
import { VeroXMAuth } from './auth.js';
|
|
4
4
|
import { ContentResource } from './content.js';
|
|
5
5
|
import { MediaResource } from './media.js';
|
|
6
|
+
import { FunctionsResource } from './functions.js';
|
|
7
|
+
import { TasksResource } from './tasks.js';
|
|
8
|
+
import { ProcessesResource } from './processes.js';
|
|
6
9
|
import { MemoryTokenStorage, BrowserLocalStorageTokenStorage } from './token-storage.js';
|
|
7
10
|
function defaultTokenStorage(projectId) {
|
|
8
11
|
if (typeof window !== 'undefined' && typeof window.localStorage !== 'undefined') {
|
|
@@ -12,13 +15,16 @@ function defaultTokenStorage(projectId) {
|
|
|
12
15
|
}
|
|
13
16
|
/**
|
|
14
17
|
* The SDK's entry point -- one `initializeApp()` call, Firebase-style,
|
|
15
|
-
* then `app.auth`, `app.content(slug)`,
|
|
16
|
-
* else. See this package's README for a full quickstart.
|
|
18
|
+
* then `app.auth`, `app.content(slug)`, `app.media()`, `app.functions`,
|
|
19
|
+
* `app.tasks` and `app.processes` for everything else. See this package's README for a full quickstart.
|
|
17
20
|
*/
|
|
18
21
|
export class VeroXMApp {
|
|
19
22
|
constructor(apiBase, tokenStorage, pendingStore) {
|
|
20
23
|
this.apiBase = apiBase;
|
|
21
24
|
this.auth = new VeroXMAuth(apiBase, tokenStorage, pendingStore);
|
|
25
|
+
this.functions = new FunctionsResource(this);
|
|
26
|
+
this.tasks = new TasksResource(this);
|
|
27
|
+
this.processes = new ProcessesResource(this);
|
|
22
28
|
}
|
|
23
29
|
static initializeApp(options) {
|
|
24
30
|
const base = options.baseUrl.replace(/\/$/, '');
|
|
@@ -39,6 +45,9 @@ export class VeroXMApp {
|
|
|
39
45
|
* 401 (clock skew, or a token revoked server-side since the last
|
|
40
46
|
* proactive refresh), forces one refresh and retries exactly once
|
|
41
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.
|
|
42
51
|
*/
|
|
43
52
|
async request(opts) {
|
|
44
53
|
const token = await this.auth.getAccessToken();
|
package/dist/errors.js
CHANGED
|
@@ -19,6 +19,12 @@ export class VeroXMApiError extends Error {
|
|
|
19
19
|
static messageFrom(status, body) {
|
|
20
20
|
if (body && typeof body === 'object') {
|
|
21
21
|
const b = body;
|
|
22
|
+
// The framework's own shape names the status in `error` ("Bad Request") and says what's wrong in `message`.
|
|
23
|
+
const framework = typeof b.statusCode === 'number';
|
|
24
|
+
if (framework && typeof b.message === 'string')
|
|
25
|
+
return b.message;
|
|
26
|
+
if (framework && Array.isArray(b.message))
|
|
27
|
+
return b.message.join(', ');
|
|
22
28
|
if (typeof b.error === 'string')
|
|
23
29
|
return b.error;
|
|
24
30
|
if (typeof b.message === 'string')
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { VeroXMApp } from './client.js';
|
|
2
|
+
type Query = Record<string, string | number | boolean | undefined>;
|
|
3
|
+
/**
|
|
4
|
+
* Project functions with an HTTP trigger (Developer > Functions). Who may call one is the function's own setting:
|
|
5
|
+
* anyone with one of the project's keys, signed-in end users, or server keys only.
|
|
6
|
+
*
|
|
7
|
+
* Answers come back as the function returned them: JSON parsed, text as a string, and `null` when it returned
|
|
8
|
+
* nothing. A failure rejects with VeroXMApiError: `code` is "function_error" (500, the error is in the call log),
|
|
9
|
+
* "function_timeout" (504), "function_limit" (429, the month's limit is used up) or "functions_disabled" (503).
|
|
10
|
+
*/
|
|
11
|
+
export declare class FunctionsResource {
|
|
12
|
+
private readonly app;
|
|
13
|
+
constructor(app: VeroXMApp);
|
|
14
|
+
/** POST /functions/:name with `body` (an object or array) as JSON; the function reads it as `request.body`. */
|
|
15
|
+
call<T = unknown>(name: string, body?: Record<string, unknown> | unknown[], options?: {
|
|
16
|
+
query?: Query;
|
|
17
|
+
}): Promise<T>;
|
|
18
|
+
/** GET /functions/:name (the function reads `query` as `request.query`). */
|
|
19
|
+
get<T = unknown>(name: string, query?: Query): Promise<T>;
|
|
20
|
+
}
|
|
21
|
+
export {};
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Project functions with an HTTP trigger (Developer > Functions). Who may call one is the function's own setting:
|
|
3
|
+
* anyone with one of the project's keys, signed-in end users, or server keys only.
|
|
4
|
+
*
|
|
5
|
+
* Answers come back as the function returned them: JSON parsed, text as a string, and `null` when it returned
|
|
6
|
+
* nothing. A failure rejects with VeroXMApiError: `code` is "function_error" (500, the error is in the call log),
|
|
7
|
+
* "function_timeout" (504), "function_limit" (429, the month's limit is used up) or "functions_disabled" (503).
|
|
8
|
+
*/
|
|
9
|
+
export class FunctionsResource {
|
|
10
|
+
constructor(app) {
|
|
11
|
+
this.app = app;
|
|
12
|
+
}
|
|
13
|
+
/** POST /functions/:name with `body` (an object or array) as JSON; the function reads it as `request.body`. */
|
|
14
|
+
async call(name, body, options = {}) {
|
|
15
|
+
return (await this.app.request({ method: 'POST', path: path(name), json: body, query: options.query }));
|
|
16
|
+
}
|
|
17
|
+
/** GET /functions/:name (the function reads `query` as `request.query`). */
|
|
18
|
+
async get(name, query = {}) {
|
|
19
|
+
return (await this.app.request({ path: path(name), query }));
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
function path(name) {
|
|
23
|
+
return `/functions/${encodeURIComponent(name)}`;
|
|
24
|
+
}
|