@unboundcx/sdk 4.13.145 → 4.13.146-security.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/base.js +74 -3
- package/index.js +6 -0
- package/lib/refreshInterceptor.js +127 -0
- package/package.json +1 -1
- package/services/licenses.js +330 -0
- package/services/login.js +21 -0
- package/services/oauth.js +159 -0
package/base.js
CHANGED
|
@@ -13,6 +13,8 @@
|
|
|
13
13
|
* npm install mime-types
|
|
14
14
|
*/
|
|
15
15
|
|
|
16
|
+
import { handleUnauthorized } from './lib/refreshInterceptor.js';
|
|
17
|
+
|
|
16
18
|
const requestBySdk = new WeakMap();
|
|
17
19
|
const SDK_REQUEST = Symbol.for('unbound.sdk.request');
|
|
18
20
|
|
|
@@ -49,12 +51,33 @@ export class BaseSDK {
|
|
|
49
51
|
this.fwRequestId = arguments[3];
|
|
50
52
|
} else {
|
|
51
53
|
// New object-based parameters
|
|
52
|
-
const {
|
|
54
|
+
const {
|
|
55
|
+
namespace,
|
|
56
|
+
callId,
|
|
57
|
+
token,
|
|
58
|
+
fwRequestId,
|
|
59
|
+
baseURL,
|
|
60
|
+
autoRefresh,
|
|
61
|
+
onUnauthorized,
|
|
62
|
+
refreshToken,
|
|
63
|
+
} = options;
|
|
53
64
|
this.namespace = namespace || process?.env?.namespace;
|
|
54
65
|
this.callId = callId;
|
|
55
66
|
this.token = token;
|
|
56
67
|
this.fwRequestId = fwRequestId;
|
|
57
68
|
this._constructorBaseURL = baseURL;
|
|
69
|
+
// api#222 -- opt-in only (default false): existing callers get no
|
|
70
|
+
// behavior change. When on, a 401 from any non-/login* endpoint
|
|
71
|
+
// triggers one single-flight refresh + one retry (lib/refreshInterceptor.js).
|
|
72
|
+
this._autoRefresh = autoRefresh === true;
|
|
73
|
+
this._onUnauthorized =
|
|
74
|
+
typeof onUnauthorized === 'function' ? onUnauthorized : null;
|
|
75
|
+
// Bearer-delivery clients only: the raw refresh token, so autoRefresh
|
|
76
|
+
// has something to send to POST /login/refresh (cookie clients rely
|
|
77
|
+
// on the browser's own refreshToken cookie and never need this).
|
|
78
|
+
// Seeded via this option or setRefreshToken(); updated in place on
|
|
79
|
+
// every rotation by lib/refreshInterceptor.js.
|
|
80
|
+
this._refreshToken = refreshToken;
|
|
58
81
|
}
|
|
59
82
|
this.baseURL;
|
|
60
83
|
this.transports = new Map();
|
|
@@ -104,6 +127,10 @@ export class BaseSDK {
|
|
|
104
127
|
this.token = token;
|
|
105
128
|
}
|
|
106
129
|
|
|
130
|
+
setRefreshToken(refreshToken) {
|
|
131
|
+
this._refreshToken = refreshToken;
|
|
132
|
+
}
|
|
133
|
+
|
|
107
134
|
setNamespace(namespace) {
|
|
108
135
|
this.namespace = namespace;
|
|
109
136
|
const defaultDomain = 'api.unbound.cx';
|
|
@@ -278,6 +305,7 @@ export class BaseSDK {
|
|
|
278
305
|
params,
|
|
279
306
|
returnRawResponse,
|
|
280
307
|
startTime,
|
|
308
|
+
forceFetch,
|
|
281
309
|
);
|
|
282
310
|
}
|
|
283
311
|
} else {
|
|
@@ -292,6 +320,7 @@ export class BaseSDK {
|
|
|
292
320
|
params,
|
|
293
321
|
returnRawResponse,
|
|
294
322
|
startTime,
|
|
323
|
+
forceFetch,
|
|
295
324
|
);
|
|
296
325
|
}
|
|
297
326
|
|
|
@@ -307,6 +336,7 @@ export class BaseSDK {
|
|
|
307
336
|
method,
|
|
308
337
|
endpoint,
|
|
309
338
|
duration,
|
|
339
|
+
{ originalParams: params, forceFetch },
|
|
310
340
|
);
|
|
311
341
|
}
|
|
312
342
|
|
|
@@ -357,6 +387,7 @@ export class BaseSDK {
|
|
|
357
387
|
params = {},
|
|
358
388
|
returnRawResponse = false,
|
|
359
389
|
startTime = Date.now(),
|
|
390
|
+
forceFetch = false,
|
|
360
391
|
) {
|
|
361
392
|
const { body, query, headers = {} } = params;
|
|
362
393
|
|
|
@@ -438,10 +469,20 @@ export class BaseSDK {
|
|
|
438
469
|
return response;
|
|
439
470
|
}
|
|
440
471
|
|
|
441
|
-
return this._processResponse(response, 'https', method, endpoint, duration
|
|
472
|
+
return this._processResponse(response, 'https', method, endpoint, duration, {
|
|
473
|
+
originalParams: params,
|
|
474
|
+
forceFetch,
|
|
475
|
+
});
|
|
442
476
|
}
|
|
443
477
|
|
|
444
|
-
async _processResponse(
|
|
478
|
+
async _processResponse(
|
|
479
|
+
response,
|
|
480
|
+
transport,
|
|
481
|
+
method,
|
|
482
|
+
endpoint,
|
|
483
|
+
duration = 0,
|
|
484
|
+
retryCtx = {},
|
|
485
|
+
) {
|
|
445
486
|
// Check if the response indicates an HTTP error
|
|
446
487
|
// These are API/configuration errors, not transport failures
|
|
447
488
|
|
|
@@ -518,6 +559,36 @@ export class BaseSDK {
|
|
|
518
559
|
);
|
|
519
560
|
}
|
|
520
561
|
|
|
562
|
+
// api#222 -- opt-in single-flight refresh + one retry on 401. Off by
|
|
563
|
+
// default (this._autoRefresh set only via the `autoRefresh` ctor
|
|
564
|
+
// option); the retry's own params carry `__skipAutoRefresh` so a 401
|
|
565
|
+
// on the RETRY itself always falls through to onUnauthorized instead
|
|
566
|
+
// of looping.
|
|
567
|
+
if (response.status === 401 && this._autoRefresh) {
|
|
568
|
+
return handleUnauthorized(this, {
|
|
569
|
+
status: response.status,
|
|
570
|
+
endpoint,
|
|
571
|
+
method,
|
|
572
|
+
alreadyRetried: retryCtx?.originalParams?.__skipAutoRefresh === true,
|
|
573
|
+
originalError: httpError,
|
|
574
|
+
retry: () =>
|
|
575
|
+
// forceFetch: true (not retryCtx.forceFetch) -- the retry must
|
|
576
|
+
// always go over plain HTTP, never the original transport. A
|
|
577
|
+
// socket transport call that 401'd still holds the pre-rotation
|
|
578
|
+
// JWT (the rotation reaches the socket asynchronously via NATS),
|
|
579
|
+
// so retrying over the same socket would 401 again and trigger
|
|
580
|
+
// onUnauthorized even though the refresh above just succeeded.
|
|
581
|
+
// See _getAvailableTransport (base.js:~185): forceFetch skips
|
|
582
|
+
// transports entirely and goes straight to HTTP.
|
|
583
|
+
this.#request(
|
|
584
|
+
endpoint,
|
|
585
|
+
method,
|
|
586
|
+
{ ...(retryCtx.originalParams || {}), __skipAutoRefresh: true },
|
|
587
|
+
true,
|
|
588
|
+
),
|
|
589
|
+
});
|
|
590
|
+
}
|
|
591
|
+
|
|
521
592
|
throw httpError;
|
|
522
593
|
}
|
|
523
594
|
|
package/index.js
CHANGED
|
@@ -47,6 +47,7 @@ import { FaxService } from './services/fax.js';
|
|
|
47
47
|
import { DocumentsService } from './services/documents.js';
|
|
48
48
|
import { EsignService } from './services/esign.js';
|
|
49
49
|
import { PermissionsService } from './services/permissions.js';
|
|
50
|
+
import { LicensesService } from './services/licenses.js';
|
|
50
51
|
import { UsersService } from './services/users.js';
|
|
51
52
|
import { TriggersService } from './services/triggers.js';
|
|
52
53
|
import { RecentsService } from './services/recents.js';
|
|
@@ -56,6 +57,7 @@ import { ChatService } from './services/chat.js';
|
|
|
56
57
|
import { DeveloperApisService } from './services/developerApis.js';
|
|
57
58
|
import { TextService } from './services/text.js';
|
|
58
59
|
import { ReportingService } from './services/reporting.js';
|
|
60
|
+
import { OAuthService } from './services/oauth.js';
|
|
59
61
|
import {
|
|
60
62
|
DataImportService,
|
|
61
63
|
DataExportService,
|
|
@@ -157,12 +159,14 @@ class UnboundSDK extends BaseSDK {
|
|
|
157
159
|
this.documents = new DocumentsService(this);
|
|
158
160
|
this.esign = new EsignService(this);
|
|
159
161
|
this.permissions = new PermissionsService(this);
|
|
162
|
+
this.licenses = new LicensesService(this);
|
|
160
163
|
this.users = new UsersService(this);
|
|
161
164
|
this.reporting = new ReportingService(this);
|
|
162
165
|
this.triggers = new TriggersService(this);
|
|
163
166
|
this.recents = new RecentsService(this);
|
|
164
167
|
this.search = new SearchService(this);
|
|
165
168
|
this.directory = new DirectoryService(this);
|
|
169
|
+
this.oauth = new OAuthService(this);
|
|
166
170
|
this.chat = new ChatService(this);
|
|
167
171
|
this.developerApis = new DeveloperApisService(this);
|
|
168
172
|
this.dataImport = new DataImportService(this);
|
|
@@ -378,11 +382,13 @@ export { KnowledgeBaseService } from './services/knowledgeBase.js';
|
|
|
378
382
|
export { FaxService } from './services/fax.js';
|
|
379
383
|
export { EsignService, EsignPublicService } from './services/esign.js';
|
|
380
384
|
export { PermissionsService } from './services/permissions.js';
|
|
385
|
+
export { LicensesService } from './services/licenses.js';
|
|
381
386
|
export { UsersService } from './services/users.js';
|
|
382
387
|
export { ReportingService } from './services/reporting.js';
|
|
383
388
|
export { RecentsService } from './services/recents.js';
|
|
384
389
|
export { SearchService } from './services/search.js';
|
|
385
390
|
export { DirectoryService } from './services/directory.js';
|
|
391
|
+
export { OAuthService } from './services/oauth.js';
|
|
386
392
|
export { ChatService } from './services/chat.js';
|
|
387
393
|
export { DeveloperApisService } from './services/developerApis.js';
|
|
388
394
|
export {
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
// api#222 client contract -- single-flight 401 -> refresh -> retry-once.
|
|
2
|
+
// base.js's `#request` funnels BOTH the Socket.IO transport and the plain
|
|
3
|
+
// HTTP fallback through the same `_processResponse` (see base.js), so this
|
|
4
|
+
// one hook covers every transport without a per-transport copy.
|
|
5
|
+
//
|
|
6
|
+
// Usage (base.js only -- app code never imports this directly):
|
|
7
|
+
// handleUnauthorized(sdk, { status, endpoint, retry, originalError })
|
|
8
|
+
//
|
|
9
|
+
// `retry` is a caller-supplied () => Promise that re-issues the ORIGINAL
|
|
10
|
+
// request. It has to come from the caller because #request is a private
|
|
11
|
+
// class field method -- this module can't call it directly.
|
|
12
|
+
|
|
13
|
+
// Keyed per SDK instance: a shared module-level variable would let one
|
|
14
|
+
// SDK instance's refresh starve a concurrent, unrelated SDK instance's own
|
|
15
|
+
// 401 recovery (a different user/session in the same Node process -- the
|
|
16
|
+
// API itself increasingly consumes this SDK server-side). Each instance
|
|
17
|
+
// still single-flights its own concurrent 401s against itself.
|
|
18
|
+
const inFlightRefreshBySdk = new WeakMap();
|
|
19
|
+
|
|
20
|
+
// Only the routes that WOULD cause a refresh loop (or make no sense to
|
|
21
|
+
// refresh) are excluded: refreshing itself (POST /login/refresh), the
|
|
22
|
+
// initial password login (POST /login), and logout (DELETE /login). Every
|
|
23
|
+
// other /login/* call -- notably GET /login/validate, which a page reload
|
|
24
|
+
// hits with a stale access cookie -- is refreshable: a valid refresh cookie
|
|
25
|
+
// must be able to recover it instead of bouncing the user to the password
|
|
26
|
+
// form.
|
|
27
|
+
function isNonRefreshableLoginRoute(method, endpoint) {
|
|
28
|
+
if (typeof endpoint !== 'string') return false;
|
|
29
|
+
const m = typeof method === 'string' ? method.toUpperCase() : '';
|
|
30
|
+
if (endpoint === '/login/refresh' && m === 'POST') return true;
|
|
31
|
+
if (endpoint === '/login' && (m === 'POST' || m === 'DELETE')) return true;
|
|
32
|
+
return false;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
export function shouldAttemptRefresh(sdk, status, endpoint, method) {
|
|
36
|
+
return (
|
|
37
|
+
status === 401 &&
|
|
38
|
+
sdk?._autoRefresh === true &&
|
|
39
|
+
!isNonRefreshableLoginRoute(method, endpoint) &&
|
|
40
|
+
typeof sdk?.login?.refresh === 'function'
|
|
41
|
+
);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
async function runRefresh(sdk) {
|
|
45
|
+
let inFlight = inFlightRefreshBySdk.get(sdk);
|
|
46
|
+
if (!inFlight) {
|
|
47
|
+
// Bearer clients (constructed with a raw token, no browser cookie jar)
|
|
48
|
+
// have to hand their raw refresh token back on every call -- the SDK
|
|
49
|
+
// never gets one implicitly the way a cookie client's browser does.
|
|
50
|
+
// sdk._refreshToken is set from login/refresh's own response below, or
|
|
51
|
+
// may be seeded via sdk.setRefreshToken() by a caller that obtained it
|
|
52
|
+
// out of band. Cookie clients simply have no stored value: `undefined`
|
|
53
|
+
// is fine, refresh() omits body.refreshToken and relies on the cookie.
|
|
54
|
+
inFlight = sdk.login
|
|
55
|
+
.refresh(sdk._refreshToken)
|
|
56
|
+
.then((result) => {
|
|
57
|
+
// Bearer clients get a new access token AND a new (rotated) refresh
|
|
58
|
+
// token back in the body; cookie clients rely on the Set-Cookie
|
|
59
|
+
// pair the refresh response already sent -- there is no token
|
|
60
|
+
// string to apply to the SDK instance for them.
|
|
61
|
+
if (result?.token) {
|
|
62
|
+
sdk.setToken(result.token);
|
|
63
|
+
} else if (typeof sdk?.setToken === 'function') {
|
|
64
|
+
// Cookie-mode refresh: no token string comes back (the Set-Cookie
|
|
65
|
+
// pair already rotated the browser's cookies), but a stale
|
|
66
|
+
// in-memory access token left on the SDK would keep going out as
|
|
67
|
+
// an Authorization header, which checkApiAuth prefers over the
|
|
68
|
+
// fresh cookie. Clear it so the next request relies on the cookie.
|
|
69
|
+
sdk.setToken(null);
|
|
70
|
+
}
|
|
71
|
+
if (result?.refreshToken) sdk._refreshToken = result.refreshToken;
|
|
72
|
+
return result;
|
|
73
|
+
})
|
|
74
|
+
.finally(() => {
|
|
75
|
+
inFlightRefreshBySdk.delete(sdk);
|
|
76
|
+
});
|
|
77
|
+
inFlightRefreshBySdk.set(sdk, inFlight);
|
|
78
|
+
}
|
|
79
|
+
return inFlight;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function notifyUnauthorized(sdk, err) {
|
|
83
|
+
if (typeof sdk?._onUnauthorized !== 'function') return;
|
|
84
|
+
try {
|
|
85
|
+
sdk._onUnauthorized(err);
|
|
86
|
+
} catch (callbackErr) {
|
|
87
|
+
console.error(
|
|
88
|
+
'refreshInterceptor :: onUnauthorized callback threw ::',
|
|
89
|
+
callbackErr,
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* @param {object} sdk
|
|
96
|
+
* @param {object} ctx
|
|
97
|
+
* @param {number} ctx.status
|
|
98
|
+
* @param {string} ctx.endpoint
|
|
99
|
+
* @param {string} [ctx.method]
|
|
100
|
+
* @param {() => Promise<any>} ctx.retry
|
|
101
|
+
* @param {Error} ctx.originalError -- rethrown whenever refresh isn't
|
|
102
|
+
* attempted, fails, or the retry itself still comes back 401 (never loop
|
|
103
|
+
* past one retry).
|
|
104
|
+
* @param {boolean} [ctx.alreadyRetried]
|
|
105
|
+
*/
|
|
106
|
+
export async function handleUnauthorized(
|
|
107
|
+
sdk,
|
|
108
|
+
{ status, endpoint, method, retry, originalError, alreadyRetried = false },
|
|
109
|
+
) {
|
|
110
|
+
if (alreadyRetried || !shouldAttemptRefresh(sdk, status, endpoint, method)) {
|
|
111
|
+
throw originalError;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
try {
|
|
115
|
+
await runRefresh(sdk);
|
|
116
|
+
} catch (refreshErr) {
|
|
117
|
+
notifyUnauthorized(sdk, originalError);
|
|
118
|
+
throw originalError;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
try {
|
|
122
|
+
return await retry();
|
|
123
|
+
} catch (retryErr) {
|
|
124
|
+
if (retryErr?.status === 401) notifyUnauthorized(sdk, retryErr);
|
|
125
|
+
throw retryErr;
|
|
126
|
+
}
|
|
127
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@unboundcx/sdk",
|
|
3
|
-
"version": "4.13.
|
|
3
|
+
"version": "4.13.146-security.1",
|
|
4
4
|
"description": "Official JavaScript SDK for the Unbound API - A comprehensive toolkit for integrating with Unbound's communication, AI, and data management services",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"type": "module",
|
|
@@ -0,0 +1,330 @@
|
|
|
1
|
+
import { internalRequest } from '../base.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Entitlements / license administration (W2, plan §2 frozen contract).
|
|
5
|
+
* Tenant-admin methods hit `/permissions/*` (admin:license:manage /
|
|
6
|
+
* admin:user:manage, real guard in the controller). Brand-owner methods
|
|
7
|
+
* hit `/permissions/brand/*` (requireBrandOwner + brandId ownership
|
|
8
|
+
* check, 2D). Neither is tenant-writable for seats/overrides/AI --
|
|
9
|
+
* those live under `/internal/authz/*` for account-builder/billing and
|
|
10
|
+
* are not exposed here.
|
|
11
|
+
*/
|
|
12
|
+
export class LicensesService {
|
|
13
|
+
constructor(sdk) {
|
|
14
|
+
this.sdk = sdk;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Get the tenant's license catalog: license types, seat usage, and the
|
|
19
|
+
* capability catalog.
|
|
20
|
+
* @returns {Promise<Object>} `{ mode, licenseTypes[], capabilities[] }`
|
|
21
|
+
* @example
|
|
22
|
+
* const { licenseTypes } = await sdk.licenses.getCatalog();
|
|
23
|
+
*/
|
|
24
|
+
async getCatalog() {
|
|
25
|
+
return internalRequest(this.sdk, '/permissions/licenses', 'GET');
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* List users stuck in `needs_seat` (no free seat at assign time).
|
|
30
|
+
* @param {string} [licenseTypeCode] - Filter to one license type
|
|
31
|
+
* @returns {Promise<Object>} `{ results: [{ userId, licenseTypeCode, source, createdAt }] }`
|
|
32
|
+
* @example
|
|
33
|
+
* const { results } = await sdk.licenses.listNeedsSeat('license.support');
|
|
34
|
+
*/
|
|
35
|
+
async listNeedsSeat(licenseTypeCode) {
|
|
36
|
+
const params = licenseTypeCode ? { query: { licenseTypeCode } } : {};
|
|
37
|
+
return internalRequest(
|
|
38
|
+
this.sdk,
|
|
39
|
+
'/permissions/licenses/needs-seat',
|
|
40
|
+
'GET',
|
|
41
|
+
params,
|
|
42
|
+
);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Get one user's licenses and resolved entitlements.
|
|
47
|
+
* @param {string} userId
|
|
48
|
+
* @returns {Promise<Object>} `{ licenses[], capabilities[], disabledCapabilities[], licenseGate }`
|
|
49
|
+
* @example
|
|
50
|
+
* await sdk.licenses.getUserLicenses('user-123');
|
|
51
|
+
*/
|
|
52
|
+
async getUserLicenses(userId) {
|
|
53
|
+
this.sdk.validateParams(
|
|
54
|
+
{ userId },
|
|
55
|
+
{ userId: { type: 'string', required: true } },
|
|
56
|
+
);
|
|
57
|
+
return internalRequest(
|
|
58
|
+
this.sdk,
|
|
59
|
+
`/permissions/users/${userId}/licenses`,
|
|
60
|
+
'GET',
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Assign a license directly to a user. 409s with
|
|
66
|
+
* `code:'seat_limit_reached'` at capacity or `code:'license_type_disabled'`
|
|
67
|
+
* for a disabled type.
|
|
68
|
+
* @param {string} userId
|
|
69
|
+
* @param {string} licenseTypeCode
|
|
70
|
+
* @returns {Promise<Object>} The assigned license row
|
|
71
|
+
* @example
|
|
72
|
+
* await sdk.licenses.assignUserLicense('user-123', 'license.core');
|
|
73
|
+
*/
|
|
74
|
+
async assignUserLicense(userId, licenseTypeCode) {
|
|
75
|
+
this.sdk.validateParams(
|
|
76
|
+
{ userId, licenseTypeCode },
|
|
77
|
+
{
|
|
78
|
+
userId: { type: 'string', required: true },
|
|
79
|
+
licenseTypeCode: { type: 'string', required: true },
|
|
80
|
+
},
|
|
81
|
+
);
|
|
82
|
+
return internalRequest(
|
|
83
|
+
this.sdk,
|
|
84
|
+
`/permissions/users/${userId}/licenses`,
|
|
85
|
+
'POST',
|
|
86
|
+
{ body: { licenseTypeCode } },
|
|
87
|
+
);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Remove a user's direct license grant (group-sourced grants are
|
|
92
|
+
* unaffected -- see `recomputeUserLicenses`).
|
|
93
|
+
* @param {string} userId
|
|
94
|
+
* @param {string} licenseTypeCode
|
|
95
|
+
* @returns {Promise<Object>}
|
|
96
|
+
* @example
|
|
97
|
+
* await sdk.licenses.removeUserLicense('user-123', 'license.core');
|
|
98
|
+
*/
|
|
99
|
+
async removeUserLicense(userId, licenseTypeCode) {
|
|
100
|
+
this.sdk.validateParams(
|
|
101
|
+
{ userId, licenseTypeCode },
|
|
102
|
+
{
|
|
103
|
+
userId: { type: 'string', required: true },
|
|
104
|
+
licenseTypeCode: { type: 'string', required: true },
|
|
105
|
+
},
|
|
106
|
+
);
|
|
107
|
+
return internalRequest(
|
|
108
|
+
this.sdk,
|
|
109
|
+
`/permissions/users/${userId}/licenses/${licenseTypeCode}`,
|
|
110
|
+
'DELETE',
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Get a group's license types (group-sourced grants fan out to members).
|
|
116
|
+
* @param {string} groupId
|
|
117
|
+
* @returns {Promise<Object>} `{ licenseTypeCodes: [] }`
|
|
118
|
+
* @example
|
|
119
|
+
* await sdk.licenses.getGroupLicenses('group-123');
|
|
120
|
+
*/
|
|
121
|
+
async getGroupLicenses(groupId) {
|
|
122
|
+
this.sdk.validateParams(
|
|
123
|
+
{ groupId },
|
|
124
|
+
{ groupId: { type: 'string', required: true } },
|
|
125
|
+
);
|
|
126
|
+
return internalRequest(
|
|
127
|
+
this.sdk,
|
|
128
|
+
`/permissions/groups/${groupId}/licenses`,
|
|
129
|
+
'GET',
|
|
130
|
+
);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Replace a group's license types. Triggers a `recomputeUserLicenses`
|
|
135
|
+
* fan-out for every member.
|
|
136
|
+
* @param {string} groupId
|
|
137
|
+
* @param {string[]} licenseTypeCodes
|
|
138
|
+
* @returns {Promise<Object>}
|
|
139
|
+
* @example
|
|
140
|
+
* await sdk.licenses.setGroupLicenses('group-123', ['license.core']);
|
|
141
|
+
*/
|
|
142
|
+
async setGroupLicenses(groupId, licenseTypeCodes) {
|
|
143
|
+
this.sdk.validateParams(
|
|
144
|
+
{ groupId, licenseTypeCodes },
|
|
145
|
+
{
|
|
146
|
+
groupId: { type: 'string', required: true },
|
|
147
|
+
licenseTypeCodes: { type: 'array', required: true },
|
|
148
|
+
},
|
|
149
|
+
);
|
|
150
|
+
return internalRequest(
|
|
151
|
+
this.sdk,
|
|
152
|
+
`/permissions/groups/${groupId}/licenses`,
|
|
153
|
+
'PUT',
|
|
154
|
+
{ body: { licenseTypeCodes } },
|
|
155
|
+
);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Set a user's active/disabled status (W1-3). Disabling bumps the
|
|
160
|
+
* user's token_version and logs them out of every queue.
|
|
161
|
+
* @param {string} userId
|
|
162
|
+
* @param {'active'|'disabled'} status
|
|
163
|
+
* @returns {Promise<Object>}
|
|
164
|
+
* @example
|
|
165
|
+
* await sdk.licenses.setUserStatus('user-123', 'disabled');
|
|
166
|
+
*/
|
|
167
|
+
async setUserStatus(userId, status) {
|
|
168
|
+
this.sdk.validateParams(
|
|
169
|
+
{ userId, status },
|
|
170
|
+
{
|
|
171
|
+
userId: { type: 'string', required: true },
|
|
172
|
+
status: { type: 'string', required: true },
|
|
173
|
+
},
|
|
174
|
+
);
|
|
175
|
+
return internalRequest(
|
|
176
|
+
this.sdk,
|
|
177
|
+
`/permissions/users/${userId}/status`,
|
|
178
|
+
'PUT',
|
|
179
|
+
{ body: { status } },
|
|
180
|
+
);
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
// -- Brand-owner methods (requireBrandOwner; 2D api routes) --------------
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* Brand owner: list the tenant accounts under this brand, with their
|
|
187
|
+
* seats and overrides.
|
|
188
|
+
* @returns {Promise<Object>} `{ accounts: [{ id, name, code, aiEnabled, seats[], overrides[] }] }`
|
|
189
|
+
* @example
|
|
190
|
+
* const { accounts } = await sdk.licenses.listBrandAccounts();
|
|
191
|
+
*/
|
|
192
|
+
async listBrandAccounts() {
|
|
193
|
+
return internalRequest(this.sdk, '/permissions/brand/accounts', 'GET');
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Brand owner: get one brand account's entitlements.
|
|
198
|
+
* @param {string} accountId
|
|
199
|
+
* @returns {Promise<Object>} `{ id, name, code, aiEnabled, seats[], overrides[] }`
|
|
200
|
+
* @example
|
|
201
|
+
* await sdk.licenses.getBrandAccountEntitlements('acct-123');
|
|
202
|
+
*/
|
|
203
|
+
async getBrandAccountEntitlements(accountId) {
|
|
204
|
+
this.sdk.validateParams(
|
|
205
|
+
{ accountId },
|
|
206
|
+
{ accountId: { type: 'string', required: true } },
|
|
207
|
+
);
|
|
208
|
+
return internalRequest(
|
|
209
|
+
this.sdk,
|
|
210
|
+
`/permissions/brand/accounts/${accountId}/entitlements`,
|
|
211
|
+
'GET',
|
|
212
|
+
);
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/**
|
|
216
|
+
* Brand owner: set a brand account's seat pool for one license type.
|
|
217
|
+
* @param {string} accountId
|
|
218
|
+
* @param {string} licenseTypeCode
|
|
219
|
+
* @param {Object} seats
|
|
220
|
+
* @param {number} seats.seatCount
|
|
221
|
+
* @param {boolean} [seats.enabled]
|
|
222
|
+
* @param {boolean} [seats.isDefaultForNewUsers]
|
|
223
|
+
* @returns {Promise<Object>}
|
|
224
|
+
* @example
|
|
225
|
+
* await sdk.licenses.setBrandAccountSeats('acct-123', 'license.core', { seatCount: 25 });
|
|
226
|
+
*/
|
|
227
|
+
async setBrandAccountSeats(
|
|
228
|
+
accountId,
|
|
229
|
+
licenseTypeCode,
|
|
230
|
+
{ seatCount, enabled, isDefaultForNewUsers } = {},
|
|
231
|
+
) {
|
|
232
|
+
this.sdk.validateParams(
|
|
233
|
+
{ accountId, licenseTypeCode, seatCount },
|
|
234
|
+
{
|
|
235
|
+
accountId: { type: 'string', required: true },
|
|
236
|
+
licenseTypeCode: { type: 'string', required: true },
|
|
237
|
+
seatCount: { type: 'number', required: true },
|
|
238
|
+
},
|
|
239
|
+
);
|
|
240
|
+
const body = { seatCount };
|
|
241
|
+
if (enabled !== undefined) body.enabled = enabled;
|
|
242
|
+
if (isDefaultForNewUsers !== undefined)
|
|
243
|
+
body.isDefaultForNewUsers = isDefaultForNewUsers;
|
|
244
|
+
return internalRequest(
|
|
245
|
+
this.sdk,
|
|
246
|
+
`/permissions/brand/accounts/${accountId}/license-seats/${licenseTypeCode}`,
|
|
247
|
+
'PUT',
|
|
248
|
+
{ body },
|
|
249
|
+
);
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
/**
|
|
253
|
+
* Brand owner: enable or disable a capability override for a brand
|
|
254
|
+
* account.
|
|
255
|
+
* @param {string} accountId
|
|
256
|
+
* @param {string} capabilityCode
|
|
257
|
+
* @param {Object} override
|
|
258
|
+
* @param {'enable'|'disable'} override.mode
|
|
259
|
+
* @param {string} [override.reason]
|
|
260
|
+
* @returns {Promise<Object>}
|
|
261
|
+
* @example
|
|
262
|
+
* await sdk.licenses.setBrandAccountOverride('acct-123', 'capability.chat', { mode: 'disable', reason: 'trial ended' });
|
|
263
|
+
*/
|
|
264
|
+
async setBrandAccountOverride(accountId, capabilityCode, { mode, reason } = {}) {
|
|
265
|
+
this.sdk.validateParams(
|
|
266
|
+
{ accountId, capabilityCode, mode },
|
|
267
|
+
{
|
|
268
|
+
accountId: { type: 'string', required: true },
|
|
269
|
+
capabilityCode: { type: 'string', required: true },
|
|
270
|
+
mode: { type: 'string', required: true },
|
|
271
|
+
},
|
|
272
|
+
);
|
|
273
|
+
const body = { mode };
|
|
274
|
+
if (reason !== undefined) body.reason = reason;
|
|
275
|
+
return internalRequest(
|
|
276
|
+
this.sdk,
|
|
277
|
+
`/permissions/brand/accounts/${accountId}/capability-overrides/${capabilityCode}`,
|
|
278
|
+
'PUT',
|
|
279
|
+
{ body },
|
|
280
|
+
);
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
/**
|
|
284
|
+
* Brand owner: remove a capability override, reverting to the license
|
|
285
|
+
* template default.
|
|
286
|
+
* @param {string} accountId
|
|
287
|
+
* @param {string} capabilityCode
|
|
288
|
+
* @returns {Promise<Object>}
|
|
289
|
+
* @example
|
|
290
|
+
* await sdk.licenses.deleteBrandAccountOverride('acct-123', 'capability.chat');
|
|
291
|
+
*/
|
|
292
|
+
async deleteBrandAccountOverride(accountId, capabilityCode) {
|
|
293
|
+
this.sdk.validateParams(
|
|
294
|
+
{ accountId, capabilityCode },
|
|
295
|
+
{
|
|
296
|
+
accountId: { type: 'string', required: true },
|
|
297
|
+
capabilityCode: { type: 'string', required: true },
|
|
298
|
+
},
|
|
299
|
+
);
|
|
300
|
+
return internalRequest(
|
|
301
|
+
this.sdk,
|
|
302
|
+
`/permissions/brand/accounts/${accountId}/capability-overrides/${capabilityCode}`,
|
|
303
|
+
'DELETE',
|
|
304
|
+
);
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* Brand owner: turn the account's AI features on/off.
|
|
309
|
+
* @param {string} accountId
|
|
310
|
+
* @param {boolean} enabled
|
|
311
|
+
* @returns {Promise<Object>}
|
|
312
|
+
* @example
|
|
313
|
+
* await sdk.licenses.setBrandAccountAiEnabled('acct-123', true);
|
|
314
|
+
*/
|
|
315
|
+
async setBrandAccountAiEnabled(accountId, enabled) {
|
|
316
|
+
this.sdk.validateParams(
|
|
317
|
+
{ accountId, enabled },
|
|
318
|
+
{
|
|
319
|
+
accountId: { type: 'string', required: true },
|
|
320
|
+
enabled: { type: 'boolean', required: true },
|
|
321
|
+
},
|
|
322
|
+
);
|
|
323
|
+
return internalRequest(
|
|
324
|
+
this.sdk,
|
|
325
|
+
`/permissions/brand/accounts/${accountId}/ai-enabled`,
|
|
326
|
+
'PUT',
|
|
327
|
+
{ body: { enabled } },
|
|
328
|
+
);
|
|
329
|
+
}
|
|
330
|
+
}
|
package/services/login.js
CHANGED
|
@@ -29,14 +29,35 @@ export class LoginService {
|
|
|
29
29
|
}
|
|
30
30
|
}
|
|
31
31
|
|
|
32
|
+
// api#222: bearer clients get refreshToken back on /login too (same
|
|
33
|
+
// contract as /login/refresh) -- seed it onto the sdk instance so
|
|
34
|
+
// autoRefresh has something to send on the very first refresh, and
|
|
35
|
+
// also return it for a caller that manages the token itself.
|
|
36
|
+
if (login?.refreshToken) this.sdk.setRefreshToken(login.refreshToken);
|
|
37
|
+
|
|
32
38
|
return {
|
|
33
39
|
valid: true,
|
|
34
40
|
userId: login.userId,
|
|
35
41
|
namespace: login.namespace,
|
|
36
42
|
url: login.url,
|
|
43
|
+
refreshToken: login.refreshToken,
|
|
37
44
|
};
|
|
38
45
|
}
|
|
39
46
|
|
|
47
|
+
// api#222. Cookie clients: no args -- the refreshToken cookie is sent
|
|
48
|
+
// automatically and the new authToken/refreshToken cookies come back on
|
|
49
|
+
// the response, nothing to apply to the SDK instance. Bearer clients:
|
|
50
|
+
// pass the refresh token string; the response's `token` is returned so
|
|
51
|
+
// the caller (or lib/refreshInterceptor.js) can call sdk.setToken(token).
|
|
52
|
+
// Always forceFetch (true): refresh exists to recover a dead session, so
|
|
53
|
+
// it must never ride a socket transport that itself depends on that
|
|
54
|
+
// session still being alive.
|
|
55
|
+
async refresh(refreshToken) {
|
|
56
|
+
const options = {};
|
|
57
|
+
if (refreshToken) options.body = { refreshToken };
|
|
58
|
+
return internalRequest(this.sdk, '/login/refresh', 'POST', options, true);
|
|
59
|
+
}
|
|
60
|
+
|
|
40
61
|
async logout() {
|
|
41
62
|
const logout = await internalRequest(this.sdk, '/login', 'DELETE', {}, true);
|
|
42
63
|
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import { internalRequest } from '../base.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* OAuth provider -- staff registry of OAuth clients (security-upgrades H1
|
|
5
|
+
* frozen contract). Every method hits `/oauth/clients*` under
|
|
6
|
+
* checkApiAuth; the server enforces `admin:oauthclient:manage`. Public
|
|
7
|
+
* authorize/token/introspect/revoke endpoints (H2/H3/H4) are not client
|
|
8
|
+
* methods -- they are third-party-facing, not called through this SDK.
|
|
9
|
+
*
|
|
10
|
+
* Exposed as `sdk.oauth.clients.*` (nested, since `oauth` is expected to
|
|
11
|
+
* grow other sub-surfaces alongside `clients` as H2-H4 land).
|
|
12
|
+
*/
|
|
13
|
+
export class OAuthService {
|
|
14
|
+
constructor(sdk) {
|
|
15
|
+
this.sdk = sdk;
|
|
16
|
+
this.clients = new OAuthClientsService(sdk);
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
class OAuthClientsService {
|
|
21
|
+
constructor(sdk) {
|
|
22
|
+
this.sdk = sdk;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* List this account's OAuth clients.
|
|
27
|
+
* @returns {Promise<Object>} `{ clients: [...] }`
|
|
28
|
+
* @example
|
|
29
|
+
* const { clients } = await sdk.oauth.clients.list();
|
|
30
|
+
*/
|
|
31
|
+
async list() {
|
|
32
|
+
return internalRequest(this.sdk, '/oauth/clients', 'GET');
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Register a new OAuth client.
|
|
37
|
+
* @param {Object} body
|
|
38
|
+
* @param {string} body.name
|
|
39
|
+
* @param {string} body.clientType - 'confidential' | 'public'
|
|
40
|
+
* @param {string[]} body.redirectUris
|
|
41
|
+
* @param {string[]} body.grantTypes - subset of 'authorization_code' | 'refresh_token' | 'client_credentials'
|
|
42
|
+
* @param {string[]} body.allowedScopes
|
|
43
|
+
* @param {string} [body.linkedUserId] - required when grantTypes includes 'client_credentials' (D11)
|
|
44
|
+
* @param {string} [body.logoUrl]
|
|
45
|
+
* @returns {Promise<Object>} `{ client, secret? }` -- secret is plaintext, shown once, confidential clients only
|
|
46
|
+
* @example
|
|
47
|
+
* const { client, secret } = await sdk.oauth.clients.create({
|
|
48
|
+
* name: 'Zapier',
|
|
49
|
+
* clientType: 'confidential',
|
|
50
|
+
* redirectUris: ['https://zapier.com/oauth/callback'],
|
|
51
|
+
* grantTypes: ['authorization_code', 'refresh_token'],
|
|
52
|
+
* allowedScopes: ['cdp:object:*:read'],
|
|
53
|
+
* });
|
|
54
|
+
*/
|
|
55
|
+
async create(body) {
|
|
56
|
+
this.sdk.validateParams(body || {}, {
|
|
57
|
+
name: { type: 'string', required: true },
|
|
58
|
+
clientType: { type: 'string', required: true },
|
|
59
|
+
redirectUris: { type: 'array', required: true },
|
|
60
|
+
grantTypes: { type: 'array', required: true },
|
|
61
|
+
allowedScopes: { type: 'array', required: true },
|
|
62
|
+
linkedUserId: { type: 'string', required: false },
|
|
63
|
+
logoUrl: { type: 'string', required: false },
|
|
64
|
+
});
|
|
65
|
+
return internalRequest(this.sdk, '/oauth/clients', 'POST', { body });
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Get one OAuth client.
|
|
70
|
+
* @param {string} id
|
|
71
|
+
* @returns {Promise<Object>} `{ client }`
|
|
72
|
+
*/
|
|
73
|
+
async get(id) {
|
|
74
|
+
this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
|
|
75
|
+
return internalRequest(this.sdk, `/oauth/clients/${id}`, 'GET');
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Update an OAuth client. Any subset of the create fields, plus `status`
|
|
80
|
+
* ('active' | 'disabled').
|
|
81
|
+
* @param {string} id
|
|
82
|
+
* @param {Object} body
|
|
83
|
+
* @returns {Promise<Object>} `{ client }`
|
|
84
|
+
*/
|
|
85
|
+
async update(id, body) {
|
|
86
|
+
this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
|
|
87
|
+
return internalRequest(this.sdk, `/oauth/clients/${id}`, 'PUT', { body });
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Soft-delete an OAuth client.
|
|
92
|
+
* @param {string} id
|
|
93
|
+
* @returns {Promise<Object>} `{ message }`
|
|
94
|
+
*/
|
|
95
|
+
async remove(id) {
|
|
96
|
+
this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
|
|
97
|
+
return internalRequest(this.sdk, `/oauth/clients/${id}`, 'DELETE');
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* List a client's secrets (id/createdAt/expiresAt/revokedAt/lastUsedAt
|
|
102
|
+
* only -- never the hash or plaintext). Use the returned `id` values
|
|
103
|
+
* with revokeSecret() to decommission an old/compromised secret.
|
|
104
|
+
* @param {string} id
|
|
105
|
+
* @returns {Promise<Object>} `{ secrets: [...] }`
|
|
106
|
+
*/
|
|
107
|
+
async listSecrets(id) {
|
|
108
|
+
this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
|
|
109
|
+
return internalRequest(this.sdk, `/oauth/clients/${id}/secrets`, 'GET');
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Mint a new client secret. The old secret keeps working until revoked.
|
|
114
|
+
* @param {string} id
|
|
115
|
+
* @returns {Promise<Object>} `{ secret }` -- plaintext, shown once
|
|
116
|
+
*/
|
|
117
|
+
async rotateSecret(id) {
|
|
118
|
+
this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
|
|
119
|
+
return internalRequest(this.sdk, `/oauth/clients/${id}/secrets`, 'POST');
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* Revoke one of a client's secrets.
|
|
124
|
+
* @param {string} id
|
|
125
|
+
* @param {string} secretId
|
|
126
|
+
* @returns {Promise<Object>} `{ message }`
|
|
127
|
+
*/
|
|
128
|
+
async revokeSecret(id, secretId) {
|
|
129
|
+
this.sdk.validateParams(
|
|
130
|
+
{ id, secretId },
|
|
131
|
+
{ id: { type: 'string', required: true }, secretId: { type: 'string', required: true } },
|
|
132
|
+
);
|
|
133
|
+
return internalRequest(this.sdk, `/oauth/clients/${id}/secrets/${secretId}`, 'DELETE');
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* List a client's user consent grants.
|
|
138
|
+
* @param {string} id
|
|
139
|
+
* @returns {Promise<Object>} `{ grants: [...] }`
|
|
140
|
+
*/
|
|
141
|
+
async listGrants(id) {
|
|
142
|
+
this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
|
|
143
|
+
return internalRequest(this.sdk, `/oauth/clients/${id}/grants`, 'GET');
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Revoke a client's consent grant for one user.
|
|
148
|
+
* @param {string} id
|
|
149
|
+
* @param {string} grantId
|
|
150
|
+
* @returns {Promise<Object>} `{ message }`
|
|
151
|
+
*/
|
|
152
|
+
async revokeGrant(id, grantId) {
|
|
153
|
+
this.sdk.validateParams(
|
|
154
|
+
{ id, grantId },
|
|
155
|
+
{ id: { type: 'string', required: true }, grantId: { type: 'string', required: true } },
|
|
156
|
+
);
|
|
157
|
+
return internalRequest(this.sdk, `/oauth/clients/${id}/grants/${grantId}`, 'DELETE');
|
|
158
|
+
}
|
|
159
|
+
}
|