@wiconnect/sdk 0.0.0-stage → 1.0.0-rc.1
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 +43 -0
- package/README.md +35 -2
- package/dist/cjs/client.d.ts +79 -0
- package/dist/cjs/client.js +128 -0
- package/dist/cjs/contract.d.ts +53 -0
- package/dist/cjs/contract.js +76 -0
- package/dist/cjs/enums.d.ts +29 -0
- package/dist/cjs/enums.js +48 -0
- package/dist/cjs/environment.d.ts +6 -0
- package/dist/cjs/environment.js +15 -0
- package/dist/cjs/errors.d.ts +99 -0
- package/dist/cjs/errors.js +144 -0
- package/dist/cjs/index.d.ts +13 -0
- package/dist/cjs/index.js +53 -0
- package/dist/cjs/members.d.ts +61 -0
- package/dist/cjs/members.js +100 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/paging.d.ts +12 -0
- package/dist/cjs/paging.js +35 -0
- package/dist/cjs/presence.d.ts +42 -0
- package/dist/cjs/presence.js +108 -0
- package/dist/cjs/resource.d.ts +17 -0
- package/dist/cjs/resource.js +30 -0
- package/dist/cjs/transport.d.ts +64 -0
- package/dist/cjs/transport.js +332 -0
- package/dist/cjs/types.d.ts +246 -0
- package/dist/cjs/types.js +2 -0
- package/dist/cjs/validate.d.ts +11 -0
- package/dist/cjs/validate.js +67 -0
- package/dist/cjs/version.d.ts +4 -0
- package/dist/cjs/version.js +7 -0
- package/dist/esm/client.d.ts +79 -0
- package/dist/esm/client.js +120 -0
- package/dist/esm/contract.d.ts +53 -0
- package/dist/esm/contract.js +73 -0
- package/dist/esm/enums.d.ts +29 -0
- package/dist/esm/enums.js +45 -0
- package/dist/esm/environment.d.ts +6 -0
- package/dist/esm/environment.js +12 -0
- package/dist/esm/errors.d.ts +99 -0
- package/dist/esm/errors.js +116 -0
- package/dist/esm/index.d.ts +13 -0
- package/dist/esm/index.js +7 -0
- package/dist/esm/members.d.ts +61 -0
- package/dist/esm/members.js +96 -0
- package/dist/esm/package.json +1 -0
- package/dist/esm/paging.d.ts +12 -0
- package/dist/esm/paging.js +31 -0
- package/dist/esm/presence.d.ts +42 -0
- package/dist/esm/presence.js +104 -0
- package/dist/esm/resource.d.ts +17 -0
- package/dist/esm/resource.js +24 -0
- package/dist/esm/transport.d.ts +64 -0
- package/dist/esm/transport.js +326 -0
- package/dist/esm/types.d.ts +246 -0
- package/dist/esm/types.js +1 -0
- package/dist/esm/validate.d.ts +11 -0
- package/dist/esm/validate.js +56 -0
- package/dist/esm/version.d.ts +4 -0
- package/dist/esm/version.js +4 -0
- package/package.json +43 -4
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.isObject = isObject;
|
|
4
|
+
exports.bad = bad;
|
|
5
|
+
exports.requireObject = requireObject;
|
|
6
|
+
exports.onlyKeys = onlyKeys;
|
|
7
|
+
exports.nonEmptyString = nonEmptyString;
|
|
8
|
+
exports.limitOf = limitOf;
|
|
9
|
+
exports.idempotencyKeyOf = idempotencyKeyOf;
|
|
10
|
+
exports.unixSeconds = unixSeconds;
|
|
11
|
+
exports.versionOf = versionOf;
|
|
12
|
+
// Local argument checks. They mirror what the cloud would answer with 400 (it rejects unknown fields and bad
|
|
13
|
+
// values), so a mistake is reported at once, with the argument's name, and nothing is sent.
|
|
14
|
+
const contract_js_1 = require("./contract.js");
|
|
15
|
+
const errors_js_1 = require("./errors.js");
|
|
16
|
+
function isObject(v) {
|
|
17
|
+
return typeof v === "object" && v !== null && !Array.isArray(v);
|
|
18
|
+
}
|
|
19
|
+
function bad(message) {
|
|
20
|
+
throw new errors_js_1.InvalidArgumentError(message);
|
|
21
|
+
}
|
|
22
|
+
function requireObject(v, what) {
|
|
23
|
+
if (!isObject(v))
|
|
24
|
+
bad(`${what} must be an object`);
|
|
25
|
+
return v;
|
|
26
|
+
}
|
|
27
|
+
/** Refuses keys the cloud would reject as unknown (and so catches typos like `emial`). */
|
|
28
|
+
function onlyKeys(o, allowed, what) {
|
|
29
|
+
for (const k of Object.keys(o))
|
|
30
|
+
if (!allowed.includes(k))
|
|
31
|
+
bad(`${what}: unknown option "${k}" (allowed: ${allowed.join(", ")})`);
|
|
32
|
+
}
|
|
33
|
+
function nonEmptyString(v, what, max = 2048) {
|
|
34
|
+
if (typeof v !== "string" || v.trim() === "")
|
|
35
|
+
bad(`${what} must be a non-empty string`);
|
|
36
|
+
if (v.length > max)
|
|
37
|
+
bad(`${what} is longer than ${max} characters`);
|
|
38
|
+
return v;
|
|
39
|
+
}
|
|
40
|
+
function limitOf(v) {
|
|
41
|
+
if (v === undefined)
|
|
42
|
+
return undefined;
|
|
43
|
+
if (typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > contract_js_1.CONTRACT.limits.pageMax)
|
|
44
|
+
bad(`limit must be an integer from 1 to ${contract_js_1.CONTRACT.limits.pageMax}`);
|
|
45
|
+
return v;
|
|
46
|
+
}
|
|
47
|
+
const KEY_RE = /^[A-Za-z0-9_-]{1,64}$/;
|
|
48
|
+
function idempotencyKeyOf(v) {
|
|
49
|
+
if (v === undefined)
|
|
50
|
+
return undefined;
|
|
51
|
+
if (typeof v !== "string" || !KEY_RE.test(v))
|
|
52
|
+
bad("idempotencyKey must be 1-64 characters from A-Z a-z 0-9 _ -");
|
|
53
|
+
return v;
|
|
54
|
+
}
|
|
55
|
+
/** Unix seconds. A value in milliseconds is the usual mistake, so values beyond year 2100 are refused. */
|
|
56
|
+
function unixSeconds(v, what) {
|
|
57
|
+
if (typeof v !== "number" || !Number.isInteger(v) || v < 1)
|
|
58
|
+
bad(`${what} must be a whole number of Unix seconds`);
|
|
59
|
+
if (v > 4_102_444_800)
|
|
60
|
+
bad(`${what} is beyond the year 2100: is it in milliseconds? The cloud uses Unix seconds`);
|
|
61
|
+
return v;
|
|
62
|
+
}
|
|
63
|
+
function versionOf(v) {
|
|
64
|
+
if (typeof v !== "number" || !Number.isInteger(v) || v < 0)
|
|
65
|
+
bad("version is required: pass the `version` you read (a whole number, 0 or more)");
|
|
66
|
+
return v;
|
|
67
|
+
}
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** The SDK version. `test/packaging.test.mjs` keeps it equal to package.json. */
|
|
2
|
+
export declare const VERSION = "1.0.0-rc.1";
|
|
3
|
+
/** Sent as the User-Agent so the cloud's logs and a support request can tell which SDK called. */
|
|
4
|
+
export declare const USER_AGENT = "wiconnect-sdk-js/1.0.0-rc.1";
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.USER_AGENT = exports.VERSION = void 0;
|
|
4
|
+
/** The SDK version. `test/packaging.test.mjs` keeps it equal to package.json. */
|
|
5
|
+
exports.VERSION = "1.0.0-rc.1";
|
|
6
|
+
/** Sent as the User-Agent so the cloud's logs and a support request can tell which SDK called. */
|
|
7
|
+
exports.USER_AGENT = `wiconnect-sdk-js/${exports.VERSION}`;
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { Members } from "./members.js";
|
|
2
|
+
import { type IterateOptions } from "./paging.js";
|
|
3
|
+
import { PresenceClient, type PresenceOptions } from "./presence.js";
|
|
4
|
+
import { Resource, type ListOptions } from "./resource.js";
|
|
5
|
+
import { type CallOptions, type ClientOptions } from "./transport.js";
|
|
6
|
+
import type { Capabilities, Credential, Diagnostics, GrantState, Page, Session, Site } from "./types.js";
|
|
7
|
+
export type { ListOptions } from "./resource.js";
|
|
8
|
+
export interface WiConnectOptions extends ClientOptions {
|
|
9
|
+
/** The integration credential (`wci_…`) issued by an owner or administrator. Keep it on your server. */
|
|
10
|
+
credential: string;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* The client for your own backend. One instance per credential; it is safe to share between requests.
|
|
14
|
+
*
|
|
15
|
+
* ```ts
|
|
16
|
+
* const wc = new WiConnect({ baseUrl: "https://cloud.example.com", credential: process.env.WICONNECT_CREDENTIAL! });
|
|
17
|
+
* const { items } = await wc.sessions.list("my-site");
|
|
18
|
+
* ```
|
|
19
|
+
*/
|
|
20
|
+
export declare class WiConnect {
|
|
21
|
+
readonly sites: Sites;
|
|
22
|
+
readonly sessions: Sessions;
|
|
23
|
+
readonly members: Members;
|
|
24
|
+
readonly capabilities: CapabilitiesApi;
|
|
25
|
+
readonly diagnostics: DiagnosticsApi;
|
|
26
|
+
private readonly t;
|
|
27
|
+
private readonly shared;
|
|
28
|
+
constructor(options: WiConnectOptions);
|
|
29
|
+
/** What this credential is and may do: organization, bound sites, scopes, expiry. Never returns the secret. */
|
|
30
|
+
credential(options?: CallOptions): Promise<Credential>;
|
|
31
|
+
/**
|
|
32
|
+
* A presence client that shares this client's base URL and transport settings. The presence token is a
|
|
33
|
+
* different secret (issued per site, `read` or `write`), so it is given separately.
|
|
34
|
+
*/
|
|
35
|
+
presence(options: Pick<PresenceOptions, "siteId" | "token">): PresenceClient;
|
|
36
|
+
}
|
|
37
|
+
export declare class Sites extends Resource {
|
|
38
|
+
list(options?: ListOptions): Promise<Page<Site>>;
|
|
39
|
+
iterate(options?: ListOptions & IterateOptions): AsyncGenerator<Site, void, undefined>;
|
|
40
|
+
get(siteId: string, options?: CallOptions): Promise<Site>;
|
|
41
|
+
}
|
|
42
|
+
export interface ListSessionsOptions extends ListOptions {
|
|
43
|
+
/** The cloud's grant state. Unknown values are sent as given. */
|
|
44
|
+
grantState?: GrantState;
|
|
45
|
+
/** With `subject`: one identity. */
|
|
46
|
+
issuer?: string;
|
|
47
|
+
subject?: string;
|
|
48
|
+
}
|
|
49
|
+
export interface RevokeOptions extends CallOptions {
|
|
50
|
+
/** Refuse, and revoke nothing, when the executor cannot disconnect at once (409 capability_unsupported). */
|
|
51
|
+
requireImmediate?: boolean;
|
|
52
|
+
/** Kept in the audit record. No personal data. */
|
|
53
|
+
reason?: string;
|
|
54
|
+
/** Repeat the same key to repeat a request safely. Default: a fresh key per call, reused across its retries. */
|
|
55
|
+
idempotencyKey?: string;
|
|
56
|
+
}
|
|
57
|
+
export declare class Sessions extends Resource {
|
|
58
|
+
/** A page of the site's network sessions, newest first. */
|
|
59
|
+
list(siteId: string, options?: ListSessionsOptions): Promise<Page<Session>>;
|
|
60
|
+
/** Every session of the site, page by page. */
|
|
61
|
+
iterate(siteId: string, options?: ListSessionsOptions & IterateOptions): AsyncGenerator<Session, void, undefined>;
|
|
62
|
+
/** One session with its layered state. */
|
|
63
|
+
get(id: string, options?: CallOptions): Promise<Session>;
|
|
64
|
+
/**
|
|
65
|
+
* Ask for the end of a session. Device-wide, as the cloud does it. The answer is 202 and says what is KNOWN:
|
|
66
|
+
* `revocation.state` is `pending` until the executor confirms, and `pending` is not "disconnected". Poll
|
|
67
|
+
* `sessions.get` for `confirmed`. `unconfirmed_expired` is a timeout, not a confirmation.
|
|
68
|
+
* Safe to repeat: every automatic retry carries the same Idempotency-Key, so it is never carried out twice.
|
|
69
|
+
*/
|
|
70
|
+
revoke(id: string, options?: RevokeOptions): Promise<Session>;
|
|
71
|
+
}
|
|
72
|
+
export declare class CapabilitiesApi extends Resource {
|
|
73
|
+
/** What the site's executor can and cannot do. Unreported or stale facts are `unknown`, never `supported`. */
|
|
74
|
+
get(siteId: string, options?: CallOptions): Promise<Capabilities>;
|
|
75
|
+
}
|
|
76
|
+
export declare class DiagnosticsApi extends Resource {
|
|
77
|
+
/** Where the chain from configuration to execution stands. `observed.wan` is `unknown` in the first release. */
|
|
78
|
+
get(siteId: string, options?: CallOptions): Promise<Diagnostics>;
|
|
79
|
+
}
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
|
+
import { assertServerSide } from "./environment.js";
|
|
3
|
+
import { InvalidArgumentError } from "./errors.js";
|
|
4
|
+
import { Members } from "./members.js";
|
|
5
|
+
import { asPage, walk } from "./paging.js";
|
|
6
|
+
import { PresenceClient } from "./presence.js";
|
|
7
|
+
import { Resource, BASE, callOf, checkCursor, enc, CALL_KEYS } from "./resource.js";
|
|
8
|
+
import { Transport } from "./transport.js";
|
|
9
|
+
import { bad, idempotencyKeyOf, limitOf, nonEmptyString, onlyKeys, requireObject } from "./validate.js";
|
|
10
|
+
/**
|
|
11
|
+
* The client for your own backend. One instance per credential; it is safe to share between requests.
|
|
12
|
+
*
|
|
13
|
+
* ```ts
|
|
14
|
+
* const wc = new WiConnect({ baseUrl: "https://cloud.example.com", credential: process.env.WICONNECT_CREDENTIAL! });
|
|
15
|
+
* const { items } = await wc.sessions.list("my-site");
|
|
16
|
+
* ```
|
|
17
|
+
*/
|
|
18
|
+
export class WiConnect {
|
|
19
|
+
sites;
|
|
20
|
+
sessions;
|
|
21
|
+
members;
|
|
22
|
+
capabilities;
|
|
23
|
+
diagnostics;
|
|
24
|
+
t;
|
|
25
|
+
shared;
|
|
26
|
+
constructor(options) {
|
|
27
|
+
assertServerSide();
|
|
28
|
+
const o = requireObject(options, "options");
|
|
29
|
+
const credential = o.credential;
|
|
30
|
+
if (typeof credential !== "string" || !credential.startsWith("wci_") || credential.length < 8) {
|
|
31
|
+
throw new InvalidArgumentError("credential must be an integration credential (it starts with wci_). A venue presence token is not one: pass it to PresenceClient.");
|
|
32
|
+
}
|
|
33
|
+
const { baseUrl, timeoutMs, retry, fetch, userAgentSuffix } = o;
|
|
34
|
+
this.shared = { baseUrl, timeoutMs, retry, fetch, userAgentSuffix };
|
|
35
|
+
this.t = new Transport(this.shared, () => credential);
|
|
36
|
+
this.sites = new Sites(this.t);
|
|
37
|
+
this.sessions = new Sessions(this.t);
|
|
38
|
+
this.members = new Members(this.t);
|
|
39
|
+
this.capabilities = new CapabilitiesApi(this.t);
|
|
40
|
+
this.diagnostics = new DiagnosticsApi(this.t);
|
|
41
|
+
}
|
|
42
|
+
/** What this credential is and may do: organization, bound sites, scopes, expiry. Never returns the secret. */
|
|
43
|
+
async credential(options = {}) {
|
|
44
|
+
onlyKeys(options, CALL_KEYS, "credential()");
|
|
45
|
+
return (await this.t.request({ method: "GET", path: `${BASE}/credential`, ...callOf(options) })).data;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* A presence client that shares this client's base URL and transport settings. The presence token is a
|
|
49
|
+
* different secret (issued per site, `read` or `write`), so it is given separately.
|
|
50
|
+
*/
|
|
51
|
+
presence(options) {
|
|
52
|
+
return new PresenceClient({ ...this.shared, ...options });
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
export class Sites extends Resource {
|
|
56
|
+
async list(options = {}) {
|
|
57
|
+
onlyKeys(options, ["limit", "cursor", ...CALL_KEYS], "sites.list()");
|
|
58
|
+
return asPage(await this.getJson(`${BASE}/sites`, { limit: limitOf(options.limit), cursor: checkCursor(options.cursor) }, callOf(options)));
|
|
59
|
+
}
|
|
60
|
+
iterate(options = {}) {
|
|
61
|
+
const { maxPages, ...rest } = options;
|
|
62
|
+
return walk((cursor) => this.list({ ...rest, cursor }), { maxPages });
|
|
63
|
+
}
|
|
64
|
+
async get(siteId, options = {}) {
|
|
65
|
+
onlyKeys(options, CALL_KEYS, "sites.get()");
|
|
66
|
+
return this.getJson(`${BASE}/sites/${enc(nonEmptyString(siteId, "siteId"))}`, {}, callOf(options));
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
export class Sessions extends Resource {
|
|
70
|
+
/** A page of the site's network sessions, newest first. */
|
|
71
|
+
async list(siteId, options = {}) {
|
|
72
|
+
onlyKeys(options, ["limit", "cursor", "grantState", "issuer", "subject", ...CALL_KEYS], "sessions.list()");
|
|
73
|
+
return asPage(await this.getJson(`${BASE}/sites/${enc(nonEmptyString(siteId, "siteId"))}/sessions`, { limit: limitOf(options.limit), cursor: checkCursor(options.cursor), grant_state: options.grantState, issuer: options.issuer, subject: options.subject }, callOf(options)));
|
|
74
|
+
}
|
|
75
|
+
/** Every session of the site, page by page. */
|
|
76
|
+
iterate(siteId, options = {}) {
|
|
77
|
+
const { maxPages, ...rest } = options;
|
|
78
|
+
return walk((cursor) => this.list(siteId, { ...rest, cursor }), { maxPages });
|
|
79
|
+
}
|
|
80
|
+
/** One session with its layered state. */
|
|
81
|
+
async get(id, options = {}) {
|
|
82
|
+
onlyKeys(options, CALL_KEYS, "sessions.get()");
|
|
83
|
+
return this.getJson(`${BASE}/sessions/${enc(nonEmptyString(id, "id"))}`, {}, callOf(options));
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Ask for the end of a session. Device-wide, as the cloud does it. The answer is 202 and says what is KNOWN:
|
|
87
|
+
* `revocation.state` is `pending` until the executor confirms, and `pending` is not "disconnected". Poll
|
|
88
|
+
* `sessions.get` for `confirmed`. `unconfirmed_expired` is a timeout, not a confirmation.
|
|
89
|
+
* Safe to repeat: every automatic retry carries the same Idempotency-Key, so it is never carried out twice.
|
|
90
|
+
*/
|
|
91
|
+
async revoke(id, options = {}) {
|
|
92
|
+
requireObject(options, "options");
|
|
93
|
+
onlyKeys(options, ["requireImmediate", "reason", "idempotencyKey", ...CALL_KEYS], "sessions.revoke()");
|
|
94
|
+
const key = idempotencyKeyOf(options.idempotencyKey) ?? randomUUID();
|
|
95
|
+
let body;
|
|
96
|
+
if (options.requireImmediate !== undefined) {
|
|
97
|
+
if (typeof options.requireImmediate !== "boolean")
|
|
98
|
+
bad("requireImmediate must be true or false");
|
|
99
|
+
body = { require_immediate: options.requireImmediate };
|
|
100
|
+
}
|
|
101
|
+
if (options.reason !== undefined)
|
|
102
|
+
body = { ...body, reason: nonEmptyString(options.reason, "reason", 200) };
|
|
103
|
+
const path = `${BASE}/sessions/${enc(nonEmptyString(id, "id"))}/revoke`;
|
|
104
|
+
return (await this.t.request({ method: "POST", path, body, idempotencyKey: key, ...callOf(options) })).data;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
export class CapabilitiesApi extends Resource {
|
|
108
|
+
/** What the site's executor can and cannot do. Unreported or stale facts are `unknown`, never `supported`. */
|
|
109
|
+
async get(siteId, options = {}) {
|
|
110
|
+
onlyKeys(options, CALL_KEYS, "capabilities.get()");
|
|
111
|
+
return this.getJson(`${BASE}/sites/${enc(nonEmptyString(siteId, "siteId"))}/capabilities`, {}, callOf(options));
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
export class DiagnosticsApi extends Resource {
|
|
115
|
+
/** Where the chain from configuration to execution stands. `observed.wan` is `unknown` in the first release. */
|
|
116
|
+
async get(siteId, options = {}) {
|
|
117
|
+
onlyKeys(options, CALL_KEYS, "diagnostics.get()");
|
|
118
|
+
return this.getJson(`${BASE}/sites/${enc(nonEmptyString(siteId, "siteId"))}/diagnostics`, {}, callOf(options));
|
|
119
|
+
}
|
|
120
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
export declare const CONTRACT: {
|
|
2
|
+
readonly enums: {
|
|
3
|
+
readonly GrantState: string[];
|
|
4
|
+
readonly Scope: string[];
|
|
5
|
+
readonly MemberState: string[];
|
|
6
|
+
readonly MemberWritableState: string[];
|
|
7
|
+
readonly EnforcerKind: string[];
|
|
8
|
+
readonly AuthorizedState: string[];
|
|
9
|
+
readonly EndedReason: string[];
|
|
10
|
+
readonly AppliedState: string[];
|
|
11
|
+
readonly AppliedBy: string[];
|
|
12
|
+
readonly PresenceState: string[];
|
|
13
|
+
readonly PresenceSource: string[];
|
|
14
|
+
readonly WanState: string[];
|
|
15
|
+
readonly WanSource: string[];
|
|
16
|
+
readonly RevocationState: string[];
|
|
17
|
+
readonly RevocationConfirmedBy: string[];
|
|
18
|
+
readonly DisconnectOutcome: string[];
|
|
19
|
+
readonly CapabilityState: string[];
|
|
20
|
+
readonly CapabilitiesEnforcer: string[];
|
|
21
|
+
readonly DiagnosticsEnforcerState: string[];
|
|
22
|
+
readonly CredentialState: string[];
|
|
23
|
+
};
|
|
24
|
+
readonly properties: {
|
|
25
|
+
readonly Session: string[];
|
|
26
|
+
readonly SessionState: string[];
|
|
27
|
+
readonly Revocation: string[];
|
|
28
|
+
readonly Capability: string[];
|
|
29
|
+
readonly Capabilities: string[];
|
|
30
|
+
readonly Diagnostics: string[];
|
|
31
|
+
readonly Site: string[];
|
|
32
|
+
readonly Credential: string[];
|
|
33
|
+
readonly SessionPage: string[];
|
|
34
|
+
readonly Member: string[];
|
|
35
|
+
readonly MemberSaved: string[];
|
|
36
|
+
readonly MemberCreate: readonly ["issuer", "subject", "expires_at"];
|
|
37
|
+
readonly MemberUpdate: readonly ["version", "state", "expires_at"];
|
|
38
|
+
readonly RevokeRequest: readonly ["require_immediate", "reason"];
|
|
39
|
+
};
|
|
40
|
+
/** The operations this SDK calls: all first-release (`x-wc-release: first`) operations of the frozen draft. */
|
|
41
|
+
readonly operations: Record<string, {
|
|
42
|
+
method: string;
|
|
43
|
+
path: string;
|
|
44
|
+
scope: string;
|
|
45
|
+
}>;
|
|
46
|
+
readonly limits: {
|
|
47
|
+
readonly pageDefault: 50;
|
|
48
|
+
readonly pageMax: 200;
|
|
49
|
+
readonly idempotencyKeyMax: 64;
|
|
50
|
+
readonly defaultTimeoutMs: 15000;
|
|
51
|
+
readonly maxRetries: 3;
|
|
52
|
+
};
|
|
53
|
+
};
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
// Tables that tie the hand-written types to the frozen draft. `satisfies Record<keyof T, 1>` makes the compiler
|
|
2
|
+
// check each key list against its interface; test/contract-drift.test.mjs checks it against the draft YAML.
|
|
3
|
+
import * as E from "./enums.js";
|
|
4
|
+
const keys = (o) => Object.keys(o);
|
|
5
|
+
export const CONTRACT = {
|
|
6
|
+
enums: {
|
|
7
|
+
GrantState: [...E.GRANT_STATES],
|
|
8
|
+
Scope: [...E.SCOPES],
|
|
9
|
+
MemberState: [...E.MEMBER_STATES],
|
|
10
|
+
MemberWritableState: [...E.MEMBER_WRITABLE_STATES],
|
|
11
|
+
EnforcerKind: [...E.ENFORCER_KINDS],
|
|
12
|
+
AuthorizedState: [...E.AUTHORIZED_STATES],
|
|
13
|
+
EndedReason: [...E.ENDED_REASONS],
|
|
14
|
+
AppliedState: [...E.APPLIED_STATES],
|
|
15
|
+
AppliedBy: [...E.APPLIED_BY],
|
|
16
|
+
PresenceState: [...E.PRESENCE_STATES],
|
|
17
|
+
PresenceSource: [...E.PRESENCE_SOURCES],
|
|
18
|
+
WanState: [...E.WAN_STATES],
|
|
19
|
+
WanSource: [...E.WAN_SOURCES],
|
|
20
|
+
RevocationState: [...E.REVOCATION_STATES],
|
|
21
|
+
RevocationConfirmedBy: [...E.REVOCATION_CONFIRMED_BY],
|
|
22
|
+
DisconnectOutcome: [...E.DISCONNECT_OUTCOMES],
|
|
23
|
+
CapabilityState: [...E.CAPABILITY_STATES],
|
|
24
|
+
CapabilitiesEnforcer: [...E.CAPABILITIES_ENFORCER_KINDS],
|
|
25
|
+
DiagnosticsEnforcerState: [...E.DIAGNOSTICS_ENFORCER_STATES],
|
|
26
|
+
CredentialState: [...E.CREDENTIAL_STATES],
|
|
27
|
+
},
|
|
28
|
+
properties: {
|
|
29
|
+
Session: keys({
|
|
30
|
+
id: 1, site_id: 1, subject: 1, device: 1, class: 1, synthetic: 1, issued_at: 1, expires_at: 1,
|
|
31
|
+
enforcer: 1, grant_state: 1, state: 1, revocation: 1,
|
|
32
|
+
}),
|
|
33
|
+
SessionState: keys({ saved: 1, authorized: 1, applied: 1, observed: 1 }),
|
|
34
|
+
Revocation: keys({
|
|
35
|
+
state: 1, requested_at: 1, confirmed_at: 1, confirmed_by: 1, latest_effect_at: 1, disconnect: 1, request_id: 1,
|
|
36
|
+
}),
|
|
37
|
+
Capability: keys({ key: 1, state: 1, value: 1, reason: 1, source: 1, reported_at: 1 }),
|
|
38
|
+
Capabilities: keys({ site_id: 1, enforcer: 1, items: 1 }),
|
|
39
|
+
Diagnostics: keys({
|
|
40
|
+
site_id: 1, generated_at: 1, enforcer: 1, config: 1, native_setup: 1, last_identity_test: 1, observed: 1,
|
|
41
|
+
}),
|
|
42
|
+
Site: keys({
|
|
43
|
+
id: 1, slug: 1, display_name: 1, network_name: 1, landing_url: 1, theme: 1, timezone: 1, contact: 1, consent: 1,
|
|
44
|
+
has_logo: 1, disabled: 1, grant_scope: 1, created: 1, version: 1,
|
|
45
|
+
}),
|
|
46
|
+
Credential: keys({
|
|
47
|
+
id: 1, name: 1, organization: 1, sites: 1, scopes: 1, org_wide: 1, state: 1, created_at: 1, expires_at: 1,
|
|
48
|
+
last_used_at: 1, issued_by: 1, previous_secret_ends_at: 1, version: 1,
|
|
49
|
+
}),
|
|
50
|
+
SessionPage: keys({ items: 1, limit: 1, next_cursor: 1 }),
|
|
51
|
+
Member: keys({ id: 1, issuer: 1, subject: 1, state: 1, expires_at: 1, created_at: 1, updated_at: 1, version: 1 }),
|
|
52
|
+
MemberSaved: keys({ member: 1, saved: 1, sessions: 1 }),
|
|
53
|
+
MemberCreate: ["issuer", "subject", "expires_at"],
|
|
54
|
+
MemberUpdate: ["version", "state", "expires_at"],
|
|
55
|
+
RevokeRequest: ["require_immediate", "reason"],
|
|
56
|
+
},
|
|
57
|
+
/** The operations this SDK calls: all first-release (`x-wc-release: first`) operations of the frozen draft. */
|
|
58
|
+
operations: {
|
|
59
|
+
getCredential: { method: "GET", path: "/integration/v1/credential", scope: "any valid credential" },
|
|
60
|
+
listSites: { method: "GET", path: "/integration/v1/sites", scope: "sites:read" },
|
|
61
|
+
getSite: { method: "GET", path: "/integration/v1/sites/{site}", scope: "sites:read" },
|
|
62
|
+
listSessions: { method: "GET", path: "/integration/v1/sites/{site}/sessions", scope: "sessions:read" },
|
|
63
|
+
getSession: { method: "GET", path: "/integration/v1/sessions/{id}", scope: "sessions:read" },
|
|
64
|
+
revokeSession: { method: "POST", path: "/integration/v1/sessions/{id}/revoke", scope: "sessions:revoke" },
|
|
65
|
+
getCapabilities: { method: "GET", path: "/integration/v1/sites/{site}/capabilities", scope: "diagnostics:read" },
|
|
66
|
+
getDiagnostics: { method: "GET", path: "/integration/v1/sites/{site}/diagnostics", scope: "diagnostics:read" },
|
|
67
|
+
listMembers: { method: "GET", path: "/integration/v1/members", scope: "members:read" },
|
|
68
|
+
createMember: { method: "POST", path: "/integration/v1/members", scope: "members:write" },
|
|
69
|
+
getMember: { method: "GET", path: "/integration/v1/members/{id}", scope: "members:read" },
|
|
70
|
+
updateMember: { method: "PATCH", path: "/integration/v1/members/{id}", scope: "members:write" },
|
|
71
|
+
},
|
|
72
|
+
limits: { pageDefault: 50, pageMax: 200, idempotencyKeyMax: 64, defaultTimeoutMs: 15_000, maxRetries: 3 },
|
|
73
|
+
};
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/** A string union that still accepts values this SDK version has not heard of. */
|
|
2
|
+
export type Open<T extends string> = T | (string & {});
|
|
3
|
+
export declare const GRANT_STATES: readonly ["pending", "applied", "failed", "revoke_pending", "revoked", "expired"];
|
|
4
|
+
/**
|
|
5
|
+
* Scopes of the frozen contract (#1131). The first eight are site scopes; the next four and the two member scopes
|
|
6
|
+
* are organization scopes (issued by an owner only, `org_wide=true`). The first-release server SDK needs
|
|
7
|
+
* sites:read, sessions:read, sessions:revoke, diagnostics:read, members:read and members:write.
|
|
8
|
+
*/
|
|
9
|
+
export declare const SCOPES: readonly ["sites:read", "sites:write", "access:read", "access:write", "sessions:read", "sessions:revoke", "diagnostics:read", "identity:test", "identity:read", "identity:write", "identity:activate", "policy:read", "members:read", "members:write"];
|
|
10
|
+
export declare const ENFORCER_KINDS: readonly ["gateway", "native"];
|
|
11
|
+
export declare const CAPABILITIES_ENFORCER_KINDS: readonly ["gateway", "native", "none"];
|
|
12
|
+
export declare const AUTHORIZED_STATES: readonly ["authorized", "ended"];
|
|
13
|
+
export declare const ENDED_REASONS: readonly ["expired", "revoked", "replaced", "failed"];
|
|
14
|
+
export declare const APPLIED_STATES: readonly ["pending", "confirmed", "failed", "unknown"];
|
|
15
|
+
export declare const APPLIED_BY: readonly ["gateway_ack", "native_accounting_start"];
|
|
16
|
+
export declare const PRESENCE_STATES: readonly ["seen", "not_seen", "unknown"];
|
|
17
|
+
export declare const PRESENCE_SOURCES: readonly ["gateway_observation", "native_accounting_interim"];
|
|
18
|
+
export declare const WAN_STATES: readonly ["observed", "not_observed", "unknown"];
|
|
19
|
+
export declare const WAN_SOURCES: readonly ["wan_proof_probe"];
|
|
20
|
+
export declare const REVOCATION_STATES: readonly ["pending", "confirmed", "unconfirmed_expired", "unknown"];
|
|
21
|
+
export declare const REVOCATION_CONFIRMED_BY: readonly ["gateway_ack", "acct_stop", "disconnect_ack"];
|
|
22
|
+
export declare const DISCONNECT_OUTCOMES: readonly ["ack", "nak", "timeout", "not_available"];
|
|
23
|
+
export declare const CAPABILITY_STATES: readonly ["supported", "unsupported", "unknown"];
|
|
24
|
+
export declare const DIAGNOSTICS_ENFORCER_STATES: readonly ["online", "offline", "unknown", "not_installed"];
|
|
25
|
+
export declare const CREDENTIAL_STATES: readonly ["active", "rotating", "revoked", "expired"];
|
|
26
|
+
/** Member states: `expired` is decided by time and never written. */
|
|
27
|
+
export declare const MEMBER_STATES: readonly ["active", "disabled", "expired"];
|
|
28
|
+
export declare const MEMBER_WRITABLE_STATES: readonly ["active", "disabled"];
|
|
29
|
+
export declare const PRESENCE_INTENTS: readonly ["chat", "focus", "private"];
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
// Enumerations from the frozen draft (docs/integrations/sdk/public-api-draft.yaml). Types are derived from
|
|
2
|
+
// these arrays; test/contract-drift.test.mjs compares them with the draft, so they cannot drift quietly.
|
|
3
|
+
// Every public union is open (`Open<…>`): contract 9.1 says clients must tolerate values added later.
|
|
4
|
+
export const GRANT_STATES = ["pending", "applied", "failed", "revoke_pending", "revoked", "expired"];
|
|
5
|
+
/**
|
|
6
|
+
* Scopes of the frozen contract (#1131). The first eight are site scopes; the next four and the two member scopes
|
|
7
|
+
* are organization scopes (issued by an owner only, `org_wide=true`). The first-release server SDK needs
|
|
8
|
+
* sites:read, sessions:read, sessions:revoke, diagnostics:read, members:read and members:write.
|
|
9
|
+
*/
|
|
10
|
+
export const SCOPES = [
|
|
11
|
+
"sites:read",
|
|
12
|
+
"sites:write",
|
|
13
|
+
"access:read",
|
|
14
|
+
"access:write",
|
|
15
|
+
"sessions:read",
|
|
16
|
+
"sessions:revoke",
|
|
17
|
+
"diagnostics:read",
|
|
18
|
+
"identity:test",
|
|
19
|
+
"identity:read",
|
|
20
|
+
"identity:write",
|
|
21
|
+
"identity:activate",
|
|
22
|
+
"policy:read",
|
|
23
|
+
"members:read",
|
|
24
|
+
"members:write",
|
|
25
|
+
];
|
|
26
|
+
export const ENFORCER_KINDS = ["gateway", "native"];
|
|
27
|
+
export const CAPABILITIES_ENFORCER_KINDS = ["gateway", "native", "none"];
|
|
28
|
+
export const AUTHORIZED_STATES = ["authorized", "ended"];
|
|
29
|
+
export const ENDED_REASONS = ["expired", "revoked", "replaced", "failed"];
|
|
30
|
+
export const APPLIED_STATES = ["pending", "confirmed", "failed", "unknown"];
|
|
31
|
+
export const APPLIED_BY = ["gateway_ack", "native_accounting_start"];
|
|
32
|
+
export const PRESENCE_STATES = ["seen", "not_seen", "unknown"];
|
|
33
|
+
export const PRESENCE_SOURCES = ["gateway_observation", "native_accounting_interim"];
|
|
34
|
+
export const WAN_STATES = ["observed", "not_observed", "unknown"];
|
|
35
|
+
export const WAN_SOURCES = ["wan_proof_probe"];
|
|
36
|
+
export const REVOCATION_STATES = ["pending", "confirmed", "unconfirmed_expired", "unknown"];
|
|
37
|
+
export const REVOCATION_CONFIRMED_BY = ["gateway_ack", "acct_stop", "disconnect_ack"];
|
|
38
|
+
export const DISCONNECT_OUTCOMES = ["ack", "nak", "timeout", "not_available"];
|
|
39
|
+
export const CAPABILITY_STATES = ["supported", "unsupported", "unknown"];
|
|
40
|
+
export const DIAGNOSTICS_ENFORCER_STATES = ["online", "offline", "unknown", "not_installed"];
|
|
41
|
+
export const CREDENTIAL_STATES = ["active", "rotating", "revoked", "expired"];
|
|
42
|
+
/** Member states: `expired` is decided by time and never written. */
|
|
43
|
+
export const MEMBER_STATES = ["active", "disabled", "expired"];
|
|
44
|
+
export const MEMBER_WRITABLE_STATES = ["active", "disabled"];
|
|
45
|
+
export const PRESENCE_INTENTS = ["chat", "focus", "private"];
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The integration credential and the venue presence token are server secrets. A browser or a mini-program bundle
|
|
3
|
+
* is readable by everyone who opens the page, so the SDK refuses to start there (contract 9.2).
|
|
4
|
+
* Put your server in between and call it from the page.
|
|
5
|
+
*/
|
|
6
|
+
export declare function assertServerSide(): void;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { InvalidArgumentError } from "./errors.js";
|
|
2
|
+
/**
|
|
3
|
+
* The integration credential and the venue presence token are server secrets. A browser or a mini-program bundle
|
|
4
|
+
* is readable by everyone who opens the page, so the SDK refuses to start there (contract 9.2).
|
|
5
|
+
* Put your server in between and call it from the page.
|
|
6
|
+
*/
|
|
7
|
+
export function assertServerSide() {
|
|
8
|
+
const g = globalThis;
|
|
9
|
+
if (typeof g.window !== "undefined" && typeof g.window?.document !== "undefined") {
|
|
10
|
+
throw new InvalidArgumentError("@wiconnect/sdk holds server-side secrets and must not run in a browser or a mini-program. Call your own backend from the page instead; the browser/mini-program login SDK is a separate package.");
|
|
11
|
+
}
|
|
12
|
+
}
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import type { AmbiguousCandidate } from "./types.js";
|
|
2
|
+
export interface ErrorFields {
|
|
3
|
+
status?: number;
|
|
4
|
+
code?: string;
|
|
5
|
+
requestId?: string;
|
|
6
|
+
outcomeUnknown?: boolean;
|
|
7
|
+
retryAfterSeconds?: number;
|
|
8
|
+
idempotencyKey?: string;
|
|
9
|
+
attempts?: number;
|
|
10
|
+
}
|
|
11
|
+
/** Base class of every error thrown by this SDK. */
|
|
12
|
+
export declare class WiConnectError extends Error {
|
|
13
|
+
/** HTTP status; undefined when no response was received. */
|
|
14
|
+
status?: number;
|
|
15
|
+
/** Stable machine code from the cloud (`version_conflict`, `rate_limited`, …). Do not parse `message`. */
|
|
16
|
+
code?: string;
|
|
17
|
+
/** The cloud's X-Request-ID: quote it when asking for support. */
|
|
18
|
+
requestId?: string;
|
|
19
|
+
/**
|
|
20
|
+
* True when a WRITE may or may not have happened (timeout, cancel, network loss, 5xx). It is not "failed":
|
|
21
|
+
* re-read before deciding, or repeat a POST with the same `idempotencyKey`. A 429 means it did not run.
|
|
22
|
+
*/
|
|
23
|
+
outcomeUnknown: boolean;
|
|
24
|
+
retryAfterSeconds?: number;
|
|
25
|
+
/** The Idempotency-Key of a POST, so the same request can be repeated safely. */
|
|
26
|
+
idempotencyKey?: string;
|
|
27
|
+
/** How many HTTP attempts were made. */
|
|
28
|
+
attempts?: number;
|
|
29
|
+
constructor(message: string, fields?: ErrorFields);
|
|
30
|
+
/** Only plain fields: no cause, no headers. */
|
|
31
|
+
toJSON(): Record<string, unknown>;
|
|
32
|
+
}
|
|
33
|
+
/** The call was refused locally, before anything was sent. */
|
|
34
|
+
export declare class InvalidArgumentError extends WiConnectError {
|
|
35
|
+
}
|
|
36
|
+
/** The cloud answered with an error status. */
|
|
37
|
+
export declare class ApiError extends WiConnectError {
|
|
38
|
+
}
|
|
39
|
+
export declare class BadRequestError extends ApiError {
|
|
40
|
+
}
|
|
41
|
+
/** 400 member_identity_invalid: the issuer/subject cannot form a member identity (empty, over length, not canonical). */
|
|
42
|
+
export declare class MemberIdentityInvalidError extends BadRequestError {
|
|
43
|
+
}
|
|
44
|
+
/** 401 credential_invalid: absent, unknown, expired or revoked (deliberately not told apart). Do not retry. */
|
|
45
|
+
export declare class CredentialInvalidError extends ApiError {
|
|
46
|
+
}
|
|
47
|
+
/** 403: `scope_forbidden`, `site_forbidden` (this API) or `site_required` / `write_scope_required` (presence). */
|
|
48
|
+
export declare class ForbiddenError extends ApiError {
|
|
49
|
+
}
|
|
50
|
+
/** 404 with an API error body: it does not exist, or belongs to another organization (not told apart). */
|
|
51
|
+
export declare class NotFoundError extends ApiError {
|
|
52
|
+
}
|
|
53
|
+
/** 404 without an API error body: this cloud does not have the endpoint at all (an older cloud than this SDK). */
|
|
54
|
+
export declare class EndpointNotAvailableError extends ApiError {
|
|
55
|
+
}
|
|
56
|
+
export declare class ConflictError extends ApiError {
|
|
57
|
+
}
|
|
58
|
+
/** 409 local_membership_disabled: the site has no enabled local-membership rule, so a member entry would do
|
|
59
|
+
* nothing. Nothing was changed. Enable the rule in the console (an administrator's step), then repeat. */
|
|
60
|
+
export declare class LocalMembershipDisabledError extends ConflictError {
|
|
61
|
+
}
|
|
62
|
+
/** 409 member_exists: that issuer+subject already has an entry. Read it and update it instead. */
|
|
63
|
+
export declare class MemberExistsError extends ConflictError {
|
|
64
|
+
}
|
|
65
|
+
/** 409 version_conflict: someone changed it first. Re-read, then decide; do not overwrite blindly. */
|
|
66
|
+
export declare class VersionConflictError extends ConflictError {
|
|
67
|
+
}
|
|
68
|
+
/** 409 ambiguous_person: one e-mail/phone matches two identities. Nobody was changed. Name one candidate. */
|
|
69
|
+
export declare class AmbiguousPersonError extends ConflictError {
|
|
70
|
+
candidates: AmbiguousCandidate[];
|
|
71
|
+
toJSON(): Record<string, unknown>;
|
|
72
|
+
}
|
|
73
|
+
export declare class IdempotencyKeyReuseError extends ApiError {
|
|
74
|
+
}
|
|
75
|
+
export declare class VersionRequiredError extends ApiError {
|
|
76
|
+
}
|
|
77
|
+
/** 429: it did NOT run. `retryAfterSeconds` says when to try again. */
|
|
78
|
+
export declare class RateLimitedError extends ApiError {
|
|
79
|
+
}
|
|
80
|
+
export declare class ServerError extends ApiError {
|
|
81
|
+
}
|
|
82
|
+
/** No usable response arrived. */
|
|
83
|
+
export declare class TransportError extends WiConnectError {
|
|
84
|
+
}
|
|
85
|
+
export declare class NetworkError extends TransportError {
|
|
86
|
+
/** A short, redacted reason such as ECONNRESET. */
|
|
87
|
+
reason?: string;
|
|
88
|
+
toJSON(): Record<string, unknown>;
|
|
89
|
+
}
|
|
90
|
+
export declare class TimeoutError extends TransportError {
|
|
91
|
+
}
|
|
92
|
+
export declare class AbortedError extends TransportError {
|
|
93
|
+
}
|
|
94
|
+
/** The cloud answered 2xx with something that is not the documented shape. */
|
|
95
|
+
export declare class ProtocolError extends WiConnectError {
|
|
96
|
+
}
|
|
97
|
+
export declare function isWiConnectError(e: unknown): e is WiConnectError;
|
|
98
|
+
/** Removes known secrets and anything shaped like an integration credential from text that may be shown. */
|
|
99
|
+
export declare function redact(text: string, secrets: Iterable<string>): string;
|