@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 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 { namespace, callId, token, fwRequestId, baseURL } = options;
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(response, transport, method, endpoint, duration = 0) {
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.145",
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
+ }