@buildbase/sdk 0.0.54 → 0.0.55

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.
Files changed (60) hide show
  1. package/AGENTS.md +8 -4
  2. package/CHANGELOG.md +53 -0
  3. package/LICENSE +21 -0
  4. package/README.md +203 -45
  5. package/dist/css/styles.css +1 -1
  6. package/dist/index.cjs +1 -1
  7. package/dist/index.d.ts +196 -88
  8. package/dist/index.mjs +1 -1
  9. package/dist/mcp/index.cjs +1 -1
  10. package/dist/mcp/index.d.ts +226 -16
  11. package/dist/mcp/index.mjs +1 -1
  12. package/dist/react/chunks/SettingsDialog-B6DhyNae.cjs +2 -0
  13. package/dist/react/chunks/SettingsDialog-K38BI74F.mjs +2 -0
  14. package/dist/react/chunks/SubscriptionDialog-BidcQ_vc.mjs +2 -0
  15. package/dist/react/chunks/SubscriptionDialog-CfDLoOzW.cjs +2 -0
  16. package/dist/react/chunks/ar-CCKONfUU.mjs +2 -0
  17. package/dist/react/chunks/ar-DrHMtT1E.cjs +2 -0
  18. package/dist/react/chunks/de-Dhtorn10.cjs +2 -0
  19. package/dist/react/chunks/de-X9mfnMFM.mjs +2 -0
  20. package/dist/react/chunks/es--8iZ7Trv.mjs +2 -0
  21. package/dist/react/chunks/es-CUR7LB6a.cjs +2 -0
  22. package/dist/react/chunks/fr-BqMs_F5g.cjs +2 -0
  23. package/dist/react/chunks/fr-rUp34NG7.mjs +2 -0
  24. package/dist/react/chunks/hi-B_IiucJZ.mjs +2 -0
  25. package/dist/react/chunks/hi-C2i1_hdv.cjs +2 -0
  26. package/dist/react/chunks/ja-4hLI6wMX.cjs +2 -0
  27. package/dist/react/chunks/ja-CIGOj3vV.mjs +2 -0
  28. package/dist/react/chunks/react-BXTDLnE8.cjs +2 -0
  29. package/dist/react/chunks/react-CXCk05WI.mjs +2 -0
  30. package/dist/react/chunks/zh-BSgd6ai5.cjs +2 -0
  31. package/dist/react/chunks/zh-DyVvcYFC.mjs +2 -0
  32. package/dist/react/index.cjs +1 -1
  33. package/dist/react/index.d.ts +460 -142
  34. package/dist/react/index.mjs +1 -1
  35. package/docs/ARCHITECTURE.md +419 -0
  36. package/docs/ERROR_CODES.md +96 -0
  37. package/docs/MCP-AND-AGENT-READINESS.md +893 -0
  38. package/docs/THEMING.md +67 -0
  39. package/docs/UI-CONFIG.md +207 -0
  40. package/package.json +14 -3
  41. package/dist/react/chunks/SettingsDialog-B28WJsAr.cjs +0 -2
  42. package/dist/react/chunks/SettingsDialog-blhppbNm.mjs +0 -2
  43. package/dist/react/chunks/SubscriptionDialog-BTWVX3cH.mjs +0 -2
  44. package/dist/react/chunks/SubscriptionDialog-QKmwvJU1.cjs +0 -2
  45. package/dist/react/chunks/ar-1Z1MOGAP.mjs +0 -2
  46. package/dist/react/chunks/ar-VGzBv3AZ.cjs +0 -2
  47. package/dist/react/chunks/de-BjdDg60Y.cjs +0 -2
  48. package/dist/react/chunks/de-CXUItplO.mjs +0 -2
  49. package/dist/react/chunks/es-BBPsSZUp.cjs +0 -2
  50. package/dist/react/chunks/es-BTbzVutz.mjs +0 -2
  51. package/dist/react/chunks/fr-Cax48X_S.cjs +0 -2
  52. package/dist/react/chunks/fr-DPMeOQu3.mjs +0 -2
  53. package/dist/react/chunks/hi-BJqvpG6d.cjs +0 -2
  54. package/dist/react/chunks/hi-JfJx-LV7.mjs +0 -2
  55. package/dist/react/chunks/ja-CDGtLzTk.mjs +0 -2
  56. package/dist/react/chunks/ja-DvVyj5xX.cjs +0 -2
  57. package/dist/react/chunks/react-6QJCOE-D.cjs +0 -2
  58. package/dist/react/chunks/react-CC6T7Zky.mjs +0 -2
  59. package/dist/react/chunks/zh-BAcqxkxk.cjs +0 -2
  60. package/dist/react/chunks/zh-BNZ2Ooe8.mjs +0 -2
package/dist/index.d.ts CHANGED
@@ -1003,7 +1003,7 @@ interface ISettings {
1003
1003
  /** Auto-create workspace on first login */
1004
1004
  autoCreateFirst: boolean;
1005
1005
  };
1006
- [key: string]: any;
1006
+ [key: string]: unknown;
1007
1007
  }
1008
1008
 
1009
1009
  /**
@@ -1017,9 +1017,14 @@ interface IOsConfig {
1017
1017
  version: ApiVersion;
1018
1018
  orgId: string;
1019
1019
  }
1020
+ /** Lifecycle of the one-time org-settings fetch. */
1021
+ type SettingsStatus = 'idle' | 'loading' | 'loaded' | 'error';
1020
1022
  interface IOsState extends IOsConfig {
1021
1023
  auth?: IAuthConfig;
1022
1024
  settings?: ISettings | null;
1025
+ /** State of the settings fetch — lets UI wait instead of guessing with `?? true` defaults. */
1026
+ settingsStatus?: SettingsStatus;
1027
+ settingsError?: string | null;
1023
1028
  }
1024
1029
 
1025
1030
  /**
@@ -1082,6 +1087,7 @@ interface IBaseApiConfig {
1082
1087
  * - getAuthHeaders()
1083
1088
  * - fetchJson<T>(path, init, errorMessage): GET/POST/etc. with handleApiResponse
1084
1089
  * - fetchResponse(path, init): raw Response for custom parsing (e.g. non-JSON or custom error handling)
1090
+ * - fetchUnwrapped<T>(path, init, errorMessage): fetch → throw on !ok → unwrap { success, data } envelope
1085
1091
  */
1086
1092
  declare abstract class BaseApi {
1087
1093
  protected readonly serverUrl: string;
@@ -1130,6 +1136,12 @@ declare abstract class BaseApi {
1130
1136
  * Caller is responsible for checking response.ok and parsing body.
1131
1137
  */
1132
1138
  protected fetchResponse(path: string, init?: RequestInit): Promise<Response>;
1139
+ /**
1140
+ * Execute request, throw a parsed error on !response.ok, and unwrap the
1141
+ * `{ success, data }` envelope. Shorthand for the common
1142
+ * fetchResponse → throwResponseError → unwrapResponse sequence.
1143
+ */
1144
+ protected fetchUnwrapped<T>(path: string, init?: RequestInit, errorMessage?: string): Promise<T>;
1133
1145
  /**
1134
1146
  * Execute request against an absolute URL (bypasses baseUrl).
1135
1147
  * Useful for endpoints outside the default basePath (e.g. /auth vs /public).
@@ -1171,21 +1183,26 @@ interface AuthRequestParams {
1171
1183
  };
1172
1184
  state?: string;
1173
1185
  }
1186
+ /**
1187
+ * Unwrapped payload of a successful auth request.
1188
+ * ⚠️ Prior to the envelope unification this type described the raw
1189
+ * `{ success, data, message }` wire envelope; `requestAuth` now unwraps the
1190
+ * envelope like every other SDK method and resolves with the payload only.
1191
+ */
1174
1192
  interface AuthRequestResponse {
1175
- success: boolean;
1176
- data: {
1177
- redirectUrl: string;
1178
- };
1179
- message: string;
1193
+ redirectUrl: string;
1180
1194
  }
1181
1195
  declare class AuthApi extends BaseApi {
1182
1196
  constructor(config: Pick<IOsConfig, 'serverUrl' | 'version'> & {
1183
1197
  sessionId?: string;
1184
1198
  });
1185
1199
  /**
1186
- * Initiate OAuth sign-in flow. Returns redirect URL to the auth provider.
1200
+ * Initiate OAuth sign-in flow. Resolves with the redirect URL to the auth provider.
1187
1201
  * Auth endpoints sit at /api/v1/auth/ (outside the /public basePath),
1188
- * so we use fetchAbsoluteUrl to get timeout, retry, and error handling via BaseApi.
1202
+ * so we use fetchAbsoluteUrl to get timeout, retry, and error handling via
1203
+ * BaseApi, then apply the standard throwResponseError → unwrapResponse
1204
+ * sequence (the fetchUnwrapped convention). Non-2xx responses and 2xx
1205
+ * envelopes with `success: false` both throw a structured Error.
1189
1206
  */
1190
1207
  requestAuth(params: AuthRequestParams): Promise<AuthRequestResponse>;
1191
1208
  /** Fetch user profile with the given session ID (used after OAuth redirect or from storage). */
@@ -1336,7 +1353,7 @@ interface NotificationData {
1336
1353
  push?: boolean;
1337
1354
  };
1338
1355
  /** Any additional merge tags available as {{key}} in the email template. */
1339
- [key: string]: any;
1356
+ [key: string]: unknown;
1340
1357
  }
1341
1358
  /** Result of sending a notification. */
1342
1359
  interface NotificationResult {
@@ -1367,64 +1384,64 @@ declare class WorkspaceApi extends BaseApi {
1367
1384
  sessionId?: string;
1368
1385
  onUnauthorized?: () => void;
1369
1386
  });
1370
- getWorkspaces(): Promise<IWorkspace[]>;
1387
+ getWorkspaces(signal?: AbortSignal): Promise<IWorkspace[]>;
1371
1388
  createWorkspace(data: {
1372
1389
  name: string;
1373
1390
  image?: string;
1374
- }): Promise<IWorkspace>;
1375
- updateWorkspace(id: string, data: Partial<IWorkspace>): Promise<IWorkspace>;
1376
- deleteWorkspace(id: string): Promise<{
1391
+ }, signal?: AbortSignal): Promise<IWorkspace>;
1392
+ updateWorkspace(id: string, data: Partial<IWorkspace>, signal?: AbortSignal): Promise<IWorkspace>;
1393
+ deleteWorkspace(id: string, signal?: AbortSignal): Promise<{
1377
1394
  success: boolean;
1378
1395
  }>;
1379
- getWorkspaceUsers(workspaceId: string): Promise<IWorkspaceUser[]>;
1396
+ getWorkspaceUsers(workspaceId: string, signal?: AbortSignal): Promise<IWorkspaceUser[]>;
1380
1397
  addUser(workspaceId: string, config: {
1381
1398
  email: string;
1382
1399
  role: string;
1383
- }): Promise<{
1400
+ }, signal?: AbortSignal): Promise<{
1384
1401
  userId: string;
1385
1402
  workspace: IWorkspace;
1386
1403
  message: string;
1387
1404
  }>;
1388
- removeUser(workspaceId: string, userId: string): Promise<{
1405
+ removeUser(workspaceId: string, userId: string, signal?: AbortSignal): Promise<{
1389
1406
  userId: string;
1390
1407
  workspace: IWorkspace;
1391
1408
  message: string;
1392
1409
  }>;
1393
- updateUser(workspaceId: string, userId: string, data: Partial<IWorkspaceUser>): Promise<{
1410
+ updateUser(workspaceId: string, userId: string, data: Partial<IWorkspaceUser>, signal?: AbortSignal): Promise<{
1394
1411
  userId: string;
1395
1412
  workspace: IWorkspace;
1396
1413
  message: string;
1397
1414
  }>;
1398
1415
  updateSettings(data: {
1399
1416
  permissions: Record<string, string[]>;
1400
- }): Promise<any>;
1401
- updateWorkspacePermissions(workspaceId: string, permissions: Record<string, string[]>): Promise<any>;
1402
- getFeatures(): Promise<IWorkspaceFeature[]>;
1403
- updateFeature(workspaceId: string, key: string, value: boolean): Promise<IWorkspace>;
1404
- getWorkspace(workspaceId: string): Promise<IWorkspace>;
1405
- getProfile(): Promise<IUser>;
1406
- updateUserProfile(config: Partial<IUser>): Promise<IUser>;
1407
- getPasskeys(): Promise<IPasskeySummary[]>;
1408
- renamePasskey(passkeyId: string, name: string): Promise<void>;
1409
- deletePasskey(passkeyId: string): Promise<void>;
1417
+ }, signal?: AbortSignal): Promise<any>;
1418
+ updateWorkspacePermissions(workspaceId: string, permissions: Record<string, string[]>, signal?: AbortSignal): Promise<any>;
1419
+ getFeatures(signal?: AbortSignal): Promise<IWorkspaceFeature[]>;
1420
+ updateFeature(workspaceId: string, key: string, value: boolean, signal?: AbortSignal): Promise<IWorkspace>;
1421
+ getWorkspace(workspaceId: string, signal?: AbortSignal): Promise<IWorkspace>;
1422
+ getProfile(signal?: AbortSignal): Promise<IUser>;
1423
+ updateUserProfile(config: Partial<IUser>, signal?: AbortSignal): Promise<IUser>;
1424
+ getPasskeys(signal?: AbortSignal): Promise<IPasskeySummary[]>;
1425
+ renamePasskey(passkeyId: string, name: string, signal?: AbortSignal): Promise<void>;
1426
+ deletePasskey(passkeyId: string, signal?: AbortSignal): Promise<void>;
1410
1427
  /**
1411
1428
  * Get current subscription for a workspace
1412
1429
  * Returns subscription details including plan, plan version, and group information
1413
1430
  */
1414
- getCurrentSubscription(workspaceId: string): Promise<ISubscriptionResponse>;
1431
+ getCurrentSubscription(workspaceId: string, signal?: AbortSignal): Promise<ISubscriptionResponse>;
1415
1432
  /**
1416
1433
  * Get plan group for a workspace
1417
1434
  * Returns the plan group containing the current plan if subscription exists,
1418
1435
  * otherwise returns the latest published group
1419
1436
  */
1420
- getPlanGroup(workspaceId: string): Promise<IPlanGroupResponse>;
1437
+ getPlanGroup(workspaceId: string, signal?: AbortSignal): Promise<IPlanGroupResponse>;
1421
1438
  /**
1422
1439
  * Get plan group for a workspace with a specific version
1423
1440
  * @param workspaceId - The workspace ID
1424
1441
  * @param groupVersionId - The plan group version ID to fetch
1425
1442
  * @returns Plan group response with the specified version
1426
1443
  */
1427
- getPlanGroupByVersion(workspaceId: string, groupVersionId: string): Promise<IPlanGroupResponse>;
1444
+ getPlanGroupByVersion(workspaceId: string, groupVersionId: string, signal?: AbortSignal): Promise<IPlanGroupResponse>;
1428
1445
  /**
1429
1446
  * Get current group version and available newer versions of the same group
1430
1447
  * - If user has active subscription: returns their current group version + newer versions
@@ -1434,7 +1451,7 @@ declare class WorkspaceApi extends BaseApi {
1434
1451
  * @param workspaceId - The workspace ID
1435
1452
  * @returns Plan group versions response with currentVersion and availableVersions
1436
1453
  */
1437
- getPlanGroupVersions(workspaceId: string): Promise<IPlanGroupVersionsResponse>;
1454
+ getPlanGroupVersions(workspaceId: string, signal?: AbortSignal): Promise<IPlanGroupVersionsResponse>;
1438
1455
  /**
1439
1456
  * Get plan group versions by slug (public, no auth required).
1440
1457
  * Returns the latest published plan group versions for the given plan group slug.
@@ -1443,7 +1460,7 @@ declare class WorkspaceApi extends BaseApi {
1443
1460
  * @param slug - Plan group slug (e.g. 'default', 'enterprise')
1444
1461
  * @returns Plan group versions response with currentVersion and availableVersions
1445
1462
  */
1446
- getPublicPlans(slug: string): Promise<IPublicPlansResponse>;
1463
+ getPublicPlans(slug: string, signal?: AbortSignal): Promise<IPublicPlansResponse>;
1447
1464
  /**
1448
1465
  * Get credit packages (public, no auth required).
1449
1466
  * Returns active credit packages for the org with pricing info.
@@ -1451,7 +1468,7 @@ declare class WorkspaceApi extends BaseApi {
1451
1468
  *
1452
1469
  * @returns Credit packages with pricing variants
1453
1470
  */
1454
- getPublicCreditPackages(): Promise<IPublicCreditPackagesResponse>;
1471
+ getPublicCreditPackages(signal?: AbortSignal): Promise<IPublicCreditPackagesResponse>;
1455
1472
  /**
1456
1473
  * Get plan group version details by ID (public, no auth required).
1457
1474
  * Returns the full plan group version with populated plan versions.
@@ -1460,15 +1477,24 @@ declare class WorkspaceApi extends BaseApi {
1460
1477
  * @param groupVersionId - The plan group version ID to fetch
1461
1478
  * @returns Plan group version with populated plan versions
1462
1479
  */
1463
- getPlanGroupVersion(groupVersionId: string): Promise<IPlanGroupVersion>;
1480
+ getPlanGroupVersion(groupVersionId: string, signal?: AbortSignal): Promise<IPlanGroupVersion>;
1464
1481
  /**
1465
1482
  * Create checkout session for new subscription
1466
1483
  * @param workspaceId - The workspace ID
1467
1484
  * @param request - Checkout session request with planVersionId and optional billing interval/URLs
1468
1485
  * @returns Checkout session response with checkoutUrl to redirect user
1469
1486
  */
1470
- createCheckoutSession(workspaceId: string, request: ICheckoutSessionRequest): Promise<CheckoutResult>;
1471
- selectFreePlan(workspaceId: string, planVersionId: string): Promise<{
1487
+ createCheckoutSession(workspaceId: string, request: ICheckoutSessionRequest, signal?: AbortSignal): Promise<CheckoutResult>;
1488
+ /**
1489
+ * Assign a free (freemium) plan to the workspace without a Stripe checkout.
1490
+ *
1491
+ * This endpoint's envelope carries no `data` payload — it is
1492
+ * `{ success, message }` — so `fetchUnwrapped` resolves with the envelope
1493
+ * itself (its unwrap only extracts `data` when present). On resolution
1494
+ * `success` is therefore always `true`: non-2xx responses and 2xx envelopes
1495
+ * with `success: false` both throw a structured Error.
1496
+ */
1497
+ selectFreePlan(workspaceId: string, planVersionId: string, signal?: AbortSignal): Promise<{
1472
1498
  success: boolean;
1473
1499
  message: string;
1474
1500
  }>;
@@ -1477,12 +1503,12 @@ declare class WorkspaceApi extends BaseApi {
1477
1503
  * Only allows plan changes within the same plan group
1478
1504
  * Returns checkout session if payment is required, otherwise returns subscription update response
1479
1505
  */
1480
- updateSubscription(workspaceId: string, request: ISubscriptionUpdateRequest): Promise<ISubscriptionUpdateResponse | ICheckoutSessionResponse>;
1506
+ updateSubscription(workspaceId: string, request: ISubscriptionUpdateRequest, signal?: AbortSignal): Promise<ISubscriptionUpdateResponse | ICheckoutSessionResponse>;
1481
1507
  /**
1482
1508
  * Create a Stripe Customer Portal session for managing payment methods, invoices, etc.
1483
1509
  * Returns the portal URL — redirect user to it.
1484
1510
  */
1485
- createBillingPortalSession(workspaceId: string, returnUrl?: string): Promise<{
1511
+ createBillingPortalSession(workspaceId: string, returnUrl?: string, signal?: AbortSignal): Promise<{
1486
1512
  url: string;
1487
1513
  }>;
1488
1514
  /**
@@ -1492,35 +1518,35 @@ declare class WorkspaceApi extends BaseApi {
1492
1518
  * @param startingAfter - Invoice ID to start after (for pagination)
1493
1519
  * @returns List of invoices with pagination info
1494
1520
  */
1495
- listInvoices(workspaceId: string, limit?: number, startingAfter?: string): Promise<IInvoiceListResponse>;
1521
+ listInvoices(workspaceId: string, limit?: number, startingAfter?: string, signal?: AbortSignal): Promise<IInvoiceListResponse>;
1496
1522
  /**
1497
1523
  * Get a single invoice by ID
1498
1524
  * @param workspaceId - The workspace ID
1499
1525
  * @param invoiceId - The invoice ID
1500
1526
  * @returns Invoice details
1501
1527
  */
1502
- getInvoice(workspaceId: string, invoiceId: string): Promise<IInvoiceResponse>;
1528
+ getInvoice(workspaceId: string, invoiceId: string, signal?: AbortSignal): Promise<IInvoiceResponse>;
1503
1529
  /**
1504
1530
  * Cancel subscription at the end of the current billing period
1505
1531
  * Sets cancelAtPeriodEnd: true - subscription remains active until period ends
1506
1532
  * @param workspaceId - The workspace ID
1507
1533
  * @returns Updated subscription with cancelAtPeriodEnd and stripeCurrentPeriodEnd
1508
1534
  */
1509
- cancelSubscriptionAtPeriodEnd(workspaceId: string): Promise<ISubscriptionResponse>;
1535
+ cancelSubscriptionAtPeriodEnd(workspaceId: string, signal?: AbortSignal): Promise<ISubscriptionResponse>;
1510
1536
  /**
1511
1537
  * Resume a subscription that was scheduled for cancellation
1512
1538
  * Sets cancelAtPeriodEnd: false - subscription will continue after period ends
1513
1539
  * @param workspaceId - The workspace ID
1514
1540
  * @returns Updated subscription with cancelAtPeriodEnd set to false
1515
1541
  */
1516
- resumeSubscription(workspaceId: string): Promise<ISubscriptionResponse>;
1542
+ resumeSubscription(workspaceId: string, signal?: AbortSignal): Promise<ISubscriptionResponse>;
1517
1543
  /**
1518
1544
  * Record quota usage for a workspace
1519
1545
  * @param workspaceId - The workspace ID
1520
1546
  * @param request - Usage request with quotaSlug, quantity, and optional metadata/source
1521
1547
  * @returns Usage result with consumed/included/available/overage
1522
1548
  */
1523
- recordUsage(workspaceId: string, request: IRecordUsageRequest): Promise<IRecordUsageResponse>;
1549
+ recordUsage(workspaceId: string, request: IRecordUsageRequest, signal?: AbortSignal): Promise<IRecordUsageResponse>;
1524
1550
  /**
1525
1551
  * Record multiple quota usage entries in a single request.
1526
1552
  * Designed for backend-to-backend high-volume scenarios (bulk exports, batch jobs).
@@ -1544,7 +1570,7 @@ declare class WorkspaceApi extends BaseApi {
1544
1570
  source?: string;
1545
1571
  idempotencyKey?: string;
1546
1572
  }>;
1547
- }): Promise<{
1573
+ }, signal?: AbortSignal): Promise<{
1548
1574
  success: boolean;
1549
1575
  total: number;
1550
1576
  succeeded: number;
@@ -1562,20 +1588,20 @@ declare class WorkspaceApi extends BaseApi {
1562
1588
  * @param quotaSlug - The quota slug to check
1563
1589
  * @returns Quota usage status with consumed/included/available/overage/hasOverage
1564
1590
  */
1565
- getQuotaUsageStatus(workspaceId: string, quotaSlug: string): Promise<IQuotaUsageStatusResponse>;
1591
+ getQuotaUsageStatus(workspaceId: string, quotaSlug: string, signal?: AbortSignal): Promise<IQuotaUsageStatusResponse>;
1566
1592
  /**
1567
1593
  * Get usage status for all quotas in the workspace's current plan
1568
1594
  * @param workspaceId - The workspace ID
1569
1595
  * @returns All quota usage statuses keyed by quota slug
1570
1596
  */
1571
- getAllQuotaUsage(workspaceId: string): Promise<IAllQuotaUsageResponse>;
1597
+ getAllQuotaUsage(workspaceId: string, signal?: AbortSignal): Promise<IAllQuotaUsageResponse>;
1572
1598
  /**
1573
1599
  * Get paginated usage logs for a workspace
1574
1600
  * @param workspaceId - The workspace ID
1575
1601
  * @param query - Optional filters: quotaSlug, from, to, source, page, limit
1576
1602
  * @returns Paginated usage log entries
1577
1603
  */
1578
- getUsageLogs(workspaceId: string, query?: IUsageLogsQuery): Promise<IUsageLogsResponse>;
1604
+ getUsageLogs(workspaceId: string, query?: IUsageLogsQuery, signal?: AbortSignal): Promise<IUsageLogsResponse>;
1579
1605
  /**
1580
1606
  * Trigger a notification event for a workspace.
1581
1607
  * Respects all notification gates (org settings, event config, workspace preferences).
@@ -1598,16 +1624,16 @@ declare class WorkspaceApi extends BaseApi {
1598
1624
  * });
1599
1625
  * ```
1600
1626
  */
1601
- sendNotification(workspaceId: string, event: string, userId?: string, data?: NotificationData): Promise<NotificationResult>;
1602
- getNotificationEvents(workspaceId: string): Promise<NotificationEvent[]>;
1603
- getNotificationPreferences(workspaceId: string): Promise<Record<string, {
1627
+ sendNotification(workspaceId: string, event: string, userId?: string, data?: NotificationData, signal?: AbortSignal): Promise<NotificationResult>;
1628
+ getNotificationEvents(workspaceId: string, signal?: AbortSignal): Promise<NotificationEvent[]>;
1629
+ getNotificationPreferences(workspaceId: string, signal?: AbortSignal): Promise<Record<string, {
1604
1630
  email?: boolean;
1605
1631
  push?: boolean;
1606
1632
  }>>;
1607
1633
  updateNotificationPreferences(workspaceId: string, preferences: Record<string, {
1608
1634
  email?: boolean;
1609
1635
  push?: boolean;
1610
- }>): Promise<Record<string, {
1636
+ }>, signal?: AbortSignal): Promise<Record<string, {
1611
1637
  email?: boolean;
1612
1638
  push?: boolean;
1613
1639
  }>>;
@@ -1616,7 +1642,7 @@ declare class WorkspaceApi extends BaseApi {
1616
1642
  * @param workspaceId - The workspace ID
1617
1643
  * @returns Credit balance with available, totalGranted, totalConsumed, totalExpired, totalRefunded
1618
1644
  */
1619
- getCreditBalance(workspaceId: string): Promise<ICreditBalance>;
1645
+ getCreditBalance(workspaceId: string, signal?: AbortSignal): Promise<ICreditBalance>;
1620
1646
  /**
1621
1647
  * Consume credits from a workspace balance.
1622
1648
  * Throws an error with `code: 'INSUFFICIENT_CREDITS'` and `available`/`requested` fields on 402.
@@ -1624,7 +1650,7 @@ declare class WorkspaceApi extends BaseApi {
1624
1650
  * @param request - Consume request with amount, optional description, idempotencyKey, metadata
1625
1651
  * @returns Consume result with consumed amount and balanceAfter
1626
1652
  */
1627
- consumeCredits(workspaceId: string, request: IConsumeCreditsRequest): Promise<IConsumeCreditsResponse>;
1653
+ consumeCredits(workspaceId: string, request: IConsumeCreditsRequest, signal?: AbortSignal): Promise<IConsumeCreditsResponse>;
1628
1654
  /**
1629
1655
  * Create a Stripe checkout session for purchasing a credit package.
1630
1656
  * Returns a checkout URL to redirect the user to.
@@ -1632,35 +1658,35 @@ declare class WorkspaceApi extends BaseApi {
1632
1658
  * @param request - Purchase request with creditPackageId, successUrl, cancelUrl, optional currency
1633
1659
  * @returns Checkout session ID and URL
1634
1660
  */
1635
- purchaseCredits(workspaceId: string, request: ICreditPurchaseRequest): Promise<ICreditPurchaseResponse>;
1661
+ purchaseCredits(workspaceId: string, request: ICreditPurchaseRequest, signal?: AbortSignal): Promise<ICreditPurchaseResponse>;
1636
1662
  /**
1637
1663
  * List available credit packages for purchase.
1638
1664
  * Returns active, non-archived packages sorted by sortOrder then creditAmount.
1639
1665
  * @param workspaceId - The workspace ID
1640
1666
  * @returns Array of credit packages
1641
1667
  */
1642
- getCreditPackages(workspaceId: string): Promise<ICreditPackage[]>;
1668
+ getCreditPackages(workspaceId: string, signal?: AbortSignal): Promise<ICreditPackage[]>;
1643
1669
  /**
1644
1670
  * Get paginated credit transaction history.
1645
1671
  * @param workspaceId - The workspace ID
1646
1672
  * @param query - Optional filters: type, page, limit
1647
1673
  * @returns Paginated credit transactions
1648
1674
  */
1649
- getCreditTransactions(workspaceId: string, query?: ICreditTransactionsQuery): Promise<ICreditTransactionsResponse>;
1675
+ getCreditTransactions(workspaceId: string, query?: ICreditTransactionsQuery, signal?: AbortSignal): Promise<ICreditTransactionsResponse>;
1650
1676
  /**
1651
1677
  * Get paginated credit buckets.
1652
1678
  * @param workspaceId - The workspace ID
1653
1679
  * @param query - Optional filters: status, source, page, limit
1654
1680
  * @returns Paginated credit buckets
1655
1681
  */
1656
- getCreditBuckets(workspaceId: string, query?: ICreditBucketsQuery): Promise<ICreditBucketsResponse>;
1682
+ getCreditBuckets(workspaceId: string, query?: ICreditBucketsQuery, signal?: AbortSignal): Promise<ICreditBucketsResponse>;
1657
1683
  /**
1658
1684
  * Get credits expiring within N days.
1659
1685
  * @param workspaceId - The workspace ID
1660
1686
  * @param days - Look-ahead window in days (1-90, default 7)
1661
1687
  * @returns Expiring credits summary with bucket list
1662
1688
  */
1663
- getExpiringCredits(workspaceId: string, days?: number): Promise<IExpiringCreditsResponse>;
1689
+ getExpiringCredits(workspaceId: string, days?: number, signal?: AbortSignal): Promise<IExpiringCreditsResponse>;
1664
1690
  }
1665
1691
 
1666
1692
  /**
@@ -1787,6 +1813,7 @@ declare const BBAction: {
1787
1813
  readonly SelectPlan: "selectPlan";
1788
1814
  readonly CreditPurchase: "creditPurchase";
1789
1815
  readonly OpenCreditStore: "openCreditStore";
1816
+ readonly OpenConnectGuide: "openConnectGuide";
1790
1817
  readonly Invite: "invite";
1791
1818
  };
1792
1819
  type BBActionType = (typeof BBAction)[keyof typeof BBAction];
@@ -1944,14 +1971,33 @@ declare const PLAN_CURRENCY_OPTIONS: {
1944
1971
  value: "usd" | "eur" | "gbp" | "jpy" | "cad" | "aud" | "chf" | "cny" | "hkd" | "sgd" | "inr" | "mxn" | "brl" | "nzd" | "sek" | "nok" | "dkk" | "pln" | "thb";
1945
1972
  label: string;
1946
1973
  }[];
1974
+ /**
1975
+ * Minor-unit digits for a currency per ISO 4217: 0 (JPY, KRW, …), 2 (most),
1976
+ * or 3 (KWD, BHD, …). The zero- and three-decimal sets are pinned to Stripe's
1977
+ * treatment (the billing backend defines amount semantics); ISK is pinned to 2
1978
+ * (Stripe legacy — ISO 4217 says 0). Any other code defers to the runtime's
1979
+ * CLDR data (IQD/LYD → 3, CLF/UYW → 4, UYI → 0), falling back to 2 for codes
1980
+ * unknown to Intl or malformed.
1981
+ */
1982
+ declare function getCurrencyDecimals(currency: string | null | undefined): number;
1947
1983
  /** True when `currency` has no minor unit (JPY, KRW, …) — amounts are whole units, not cents. */
1948
1984
  declare function isZeroDecimalCurrency(currency: string | null | undefined): boolean;
1949
1985
  /**
1950
1986
  * Convert a minor-unit amount to its display number for `currency`:
1951
1987
  * `minorAmountToDisplay(1999, 'usd')` → `"19.99"`,
1952
- * `minorAmountToDisplay(1000, 'jpy')` → `"1,000"` (zero-decimal — no division).
1988
+ * `minorAmountToDisplay(1000, 'jpy')` → `"1,000"` (zero-decimal — no division),
1989
+ * `minorAmountToDisplay(12345, 'kwd')` → `"12.345"` (three-decimal — ÷1000).
1953
1990
  */
1954
1991
  declare function minorAmountToDisplay(amount: number, currency: string): string;
1992
+ /**
1993
+ * Locale-aware currency formatting of a minor-unit amount via `Intl.NumberFormat`
1994
+ * (`(1999, 'usd', 'en-US')` → `"$19.99"`; `(1000, 'jpy', 'ja-JP')` → `"¥1,000"`;
1995
+ * `(12345, 'kwd')` → `"KWD 12.345"`). The divisor follows the currency's ISO 4217
1996
+ * minor-unit digits (see `getCurrencyDecimals`) — zero-decimal currencies are
1997
+ * never divided, three-decimal divide by 1000. Falls back to the symbol table
1998
+ * when the currency code is empty or malformed.
1999
+ */
2000
+ declare function formatMinorAmountIntl(amount: number, currency: string, locale?: string): string;
1955
2001
  /** Format cents as money string (e.g. 1999, "usd" -> "$19.99"; 1000, "jpy" -> "¥1,000"). Caller must pass currency (e.g. from plan or workspace). */
1956
2002
  declare function formatCents(cents: number, currency: string): string;
1957
2003
  /** Translatable labels for overage/quota formatting */
@@ -1971,15 +2017,16 @@ interface OverageLabels {
1971
2017
  }
1972
2018
  /**
1973
2019
  * Format overage rate for display. When unitSize > 1: "$1.00/1,000 units"; else "$1.00/unit".
1974
- * Pass `labels` for i18n support.
2020
+ * Pass `labels` for i18n support and `locale` to group numbers in the display locale.
1975
2021
  */
1976
- declare function formatOverageRate(overageCents: number | undefined, unitSize: number | undefined, currency: string, labels?: Partial<OverageLabels>): string | null;
2022
+ declare function formatOverageRate(overageCents: number | undefined, unitSize: number | undefined, currency: string, labels?: Partial<OverageLabels>, locale?: string): string | null;
1977
2023
  /**
1978
2024
  * Format overage rate with optional unit label for comparison/preview UIs.
1979
2025
  * e.g. formatOverageRateWithLabel(50, 1000, "video", "usd") -> "$0.50/1,000 videos"
1980
2026
  * Pass `labels` for i18n support. Pass `pluralUnitLabel` to avoid English "s" pluralization.
2027
+ * Pass `locale` to group numbers in the display locale.
1981
2028
  */
1982
- declare function formatOverageRateWithLabel(overageCents: number | undefined, unitSize: number | undefined, unitLabel: string | undefined, currency: string, pluralUnitLabel?: string, labels?: Partial<OverageLabels>): string | null;
2029
+ declare function formatOverageRateWithLabel(overageCents: number | undefined, unitSize: number | undefined, unitLabel: string | undefined, currency: string, pluralUnitLabel?: string, labels?: Partial<OverageLabels>, locale?: string): string | null;
1983
2030
  /**
1984
2031
  * Get singular unit label from item name or slug (e.g. "Videos" -> "video", "reels" -> "reel").
1985
2032
  * Used for quota display in comparison and preview.
@@ -1988,9 +2035,10 @@ declare function formatOverageRateWithLabel(overageCents: number | undefined, un
1988
2035
  declare function getQuotaUnitLabelFromName(nameOrSlug: string, fallback?: string): string;
1989
2036
  /**
1990
2037
  * Format quota "included + overage" for display.
1991
- * Pass `labels` and `pluralUnitLabel` for i18n support.
2038
+ * Pass `labels` and `pluralUnitLabel` for i18n support, and `locale` to group
2039
+ * numbers in the display locale.
1992
2040
  */
1993
- declare function formatQuotaIncludedOverage(included: number | undefined, overageCents: number | undefined, unitLabel: string, currency: string, unitSize?: number, pluralUnitLabel?: string, labels?: Partial<OverageLabels>, allowOverage?: boolean): string;
2041
+ declare function formatQuotaIncludedOverage(included: number | undefined, overageCents: number | undefined, unitLabel: string, currency: string, unitSize?: number, pluralUnitLabel?: string, labels?: Partial<OverageLabels>, allowOverage?: boolean, locale?: string): string;
1994
2042
 
1995
2043
  type QuotaDisplayValue = {
1996
2044
  included: number;
@@ -2022,6 +2070,8 @@ interface QuotaLabels {
2022
2070
  included: string;
2023
2071
  /** e.g. "then" — separator between included and price */
2024
2072
  then: string;
2073
+ /** e.g. "hard limit" — shown when overage is not allowed */
2074
+ hardLimit?: string;
2025
2075
  }
2026
2076
  /**
2027
2077
  * Format a quota display value as "X included, then $Y.YY / unit".
@@ -2149,6 +2199,18 @@ declare function validateInvite(opts: {
2149
2199
  requireSubscription?: boolean;
2150
2200
  }): InviteValidation;
2151
2201
 
2202
+ /** Minimal workspace shape needed for ownership/role checks. Extended by `permissions.WorkspaceLike`. */
2203
+ interface WorkspaceLike$1 {
2204
+ _id: string;
2205
+ createdBy: string | {
2206
+ _id: string;
2207
+ } | null | undefined;
2208
+ users?: Array<string | {
2209
+ _id: string;
2210
+ role?: string;
2211
+ }>;
2212
+ }
2213
+
2152
2214
  /**
2153
2215
  * Role-based permission system.
2154
2216
  * Framework-agnostic — used by both React hooks and server-side BuildBase.
@@ -2166,6 +2228,7 @@ declare function validateInvite(opts: {
2166
2228
  * Both are resolved from the same role→permission map. Owner always gets all
2167
2229
  * platform permissions + any app permissions defined in the config.
2168
2230
  */
2231
+
2169
2232
  declare const Permission: {
2170
2233
  readonly WORKSPACE_SETTINGS_VIEW: "workspace:settings:view";
2171
2234
  readonly WORKSPACE_SETTINGS_EDIT: "workspace:settings:edit";
@@ -2183,15 +2246,7 @@ declare const Permission: {
2183
2246
  type PermissionKey = (typeof Permission)[keyof typeof Permission];
2184
2247
  type RolePermissionMap = Record<string, string[]>;
2185
2248
  declare const DEFAULT_ROLE_PERMISSIONS: RolePermissionMap;
2186
- interface WorkspaceLike {
2187
- _id: string;
2188
- createdBy: string | {
2189
- _id: string;
2190
- } | null | undefined;
2191
- users?: Array<string | {
2192
- _id: string;
2193
- role?: string;
2194
- }>;
2249
+ interface WorkspaceLike extends WorkspaceLike$1 {
2195
2250
  permissions?: Record<string, string[]>;
2196
2251
  }
2197
2252
  interface SettingsLike {
@@ -2248,7 +2303,7 @@ declare function hasPermission(permission: string | string[], ctx: PermissionCon
2248
2303
  *
2249
2304
  * Or manually create `public/push-sw.js` with this content.
2250
2305
  */
2251
- declare const PUSH_SERVICE_WORKER_SCRIPT = "\n// BuildBase Push Notification Service Worker\n// Place this file in your app's public directory (e.g. public/push-sw.js)\n\nself.addEventListener('push', function(event) {\n if (!event.data) return;\n\n try {\n const payload = event.data.json();\n const title = payload.title || 'Notification';\n const options = {\n body: payload.body || '',\n icon: payload.icon || undefined,\n badge: payload.icon || undefined,\n data: { url: payload.url, ...(payload.data || {}) },\n tag: 'buildbase-push-' + Date.now(),\n };\n\n event.waitUntil(\n self.registration.showNotification(title, options)\n );\n } catch (e) {\n console.error('[PushSW] Failed to show notification:', e);\n }\n});\n\nself.addEventListener('notificationclick', function(event) {\n event.notification.close();\n\n const url = event.notification.data && event.notification.data.url;\n if (url) {\n event.waitUntil(\n clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(clientList) {\n for (let i = 0; i < clientList.length; i++) {\n const client = clientList[i];\n if (client.url === url && 'focus' in client) {\n return client.focus();\n }\n }\n if (clients.openWindow) {\n return clients.openWindow(url);\n }\n })\n );\n }\n});\n";
2306
+ declare const PUSH_SERVICE_WORKER_SCRIPT = "\n// BuildBase Push Notification Service Worker\n// Place this file in your app's public directory (e.g. public/push-sw.js)\n\nself.addEventListener('push', function(event) {\n if (!event.data) return;\n\n try {\n const payload = event.data.json();\n // i18n exception: service workers run outside the SDK's translation\n // provider, so this last-resort fallback stays English. The server should\n // always send a localized payload.title.\n const title = payload.title || 'Notification';\n const options = {\n body: payload.body || '',\n icon: payload.icon || undefined,\n badge: payload.icon || undefined,\n data: { url: payload.url, ...(payload.data || {}) },\n tag: 'buildbase-push-' + Date.now(),\n };\n\n event.waitUntil(\n self.registration.showNotification(title, options)\n );\n } catch (e) {\n console.error('[PushSW] Failed to show notification:', e);\n }\n});\n\nself.addEventListener('notificationclick', function(event) {\n event.notification.close();\n\n const url = event.notification.data && event.notification.data.url;\n if (url) {\n event.waitUntil(\n clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(clientList) {\n for (let i = 0; i < clientList.length; i++) {\n const client = clientList[i];\n if (client.url === url && 'focus' in client) {\n return client.focus();\n }\n }\n if (clients.openWindow) {\n return clients.openWindow(url);\n }\n })\n );\n }\n});\n";
2252
2307
 
2253
2308
  interface BetaFormData {
2254
2309
  name?: string;
@@ -2271,6 +2326,24 @@ interface SDKMessages {
2271
2326
  connectedAgentsEmpty: string;
2272
2327
  connectedAgentsAccess: string;
2273
2328
  connectedAgentsGranted: string;
2329
+ connectedAgentsLoadFailed: string;
2330
+ connectedAgentsRevokeFailed: string;
2331
+ mcpConnectAction: string;
2332
+ mcpGuideTitle: string;
2333
+ mcpGuideDescription: string;
2334
+ mcpServerUrlLabel: string;
2335
+ mcpServerUrlHint: string;
2336
+ mcpPromptLabel: string;
2337
+ mcpPromptHint: string;
2338
+ mcpPromptTemplate: string;
2339
+ mcpClientsLabel: string;
2340
+ mcpAddToConfigFile: string;
2341
+ mcpClientChatgptInstructions: string;
2342
+ mcpClientClaudeInstructions: string;
2343
+ mcpClientClineInstructions: string;
2344
+ mcpCopy: string;
2345
+ mcpCopied: string;
2346
+ mcpLearnMore: string;
2274
2347
  inactive: string;
2275
2348
  inactiveHint: string;
2276
2349
  passkeysTitle: string;
@@ -2334,6 +2407,7 @@ interface SDKMessages {
2334
2407
  billingManageOnly: string;
2335
2408
  openSettings: string;
2336
2409
  back: string;
2410
+ close: string;
2337
2411
  };
2338
2412
  };
2339
2413
  subscription: {
@@ -2620,6 +2694,7 @@ interface SDKMessages {
2620
2694
  featureSuccess: string;
2621
2695
  updateSuccess: string;
2622
2696
  actionStatus: string;
2697
+ fallbackName: string;
2623
2698
  };
2624
2699
  danger: {
2625
2700
  title: string;
@@ -2840,6 +2915,7 @@ interface SDKMessages {
2840
2915
  purchaseFailed: string;
2841
2916
  errorLoading: string;
2842
2917
  insufficientCredits: string;
2918
+ insufficientDetail: string;
2843
2919
  };
2844
2920
  loading: {
2845
2921
  restoringSession: string;
@@ -2875,6 +2951,7 @@ interface SDKMessages {
2875
2951
  fetchCreditPackages: string;
2876
2952
  fetchCreditTransactions: string;
2877
2953
  fetchExpiringCredits: string;
2954
+ fetchWorkspaces: string;
2878
2955
  };
2879
2956
  }
2880
2957
  /**
@@ -3019,8 +3096,8 @@ declare function parseWebhookEvent(options: {
3019
3096
  * export const agentConfig: AgentReadyConfig = {
3020
3097
  * serverUrl: process.env.BUILDBASE_URL!,
3021
3098
  * orgId: process.env.BUILDBASE_ORG_ID!,
3022
- * siteUrl: "https://imejis.io",
3023
- * site: { name: "Imejis", description: "Generate images from templates via API." },
3099
+ * siteUrl: "https://example.com",
3100
+ * site: { name: "Acme", description: "Generate images from templates via API." },
3024
3101
  * robots: { contentSignals: { search: true, aiInput: true, aiTrain: false } },
3025
3102
  * };
3026
3103
  * export async function serveAgentPath(req: Request): Promise<Response> {
@@ -3063,7 +3140,7 @@ interface AgentReadinessBundle {
3063
3140
  }
3064
3141
  /** An Agent Skill (Agent Skills Discovery RFC v0.2.0) published by this app. */
3065
3142
  interface AgentSkill {
3066
- /** Stable slug, e.g. `imejis-api`. */
3143
+ /** Stable slug, e.g. `acme-api`. */
3067
3144
  name: string;
3068
3145
  /** One-line human/agent-readable summary. */
3069
3146
  description: string;
@@ -3079,7 +3156,7 @@ interface AgentSkill {
3079
3156
  }
3080
3157
  /** One API described in an API Catalog (RFC 9727 / RFC 9264 linkset). */
3081
3158
  interface ApiCatalogApi {
3082
- /** Anchor URL identifying the API, e.g. `https://api.imejis.io`. */
3159
+ /** Anchor URL identifying the API, e.g. `https://api.example.com`. */
3083
3160
  anchor: string;
3084
3161
  /** OpenAPI / machine-readable description URL (link rel `service-desc`). */
3085
3162
  serviceDesc?: string;
@@ -3100,7 +3177,7 @@ interface McpServerCard {
3100
3177
  endpoint: string;
3101
3178
  /** Transport type. Defaults to `"streamable-http"`. */
3102
3179
  transport?: string;
3103
- /** MCP protocol version the server speaks. Defaults to `"2025-06-18"`. */
3180
+ /** MCP protocol version the server speaks. Defaults to `"2025-11-25"`. */
3104
3181
  protocolVersion?: string;
3105
3182
  /**
3106
3183
  * Capability flags. Booleans per SEP-1649 v1.0; a legacy object value
@@ -3204,7 +3281,7 @@ interface AgentReadyConfig {
3204
3281
  /** The org id (24-hex) whose agent-readiness config to serve. */
3205
3282
  orgId: string;
3206
3283
  /**
3207
- * This app's public origin, e.g. `https://imejis.io`. Used to build absolute
3284
+ * This app's public origin, e.g. `https://example.com`. Used to build absolute
3208
3285
  * URLs in the Agent Card and to match RFC 9728 resource paths.
3209
3286
  */
3210
3287
  siteUrl: string;
@@ -3518,14 +3595,20 @@ declare function resolveWellKnown(requestPath: string, config: AgentReadyConfig)
3518
3595
  * agent-readiness surface. Returns null for paths this app doesn't serve.
3519
3596
  */
3520
3597
  declare function resolveAgentPath(requestPath: string, config: AgentReadyConfig): Promise<DiscoveryDocument | null>;
3521
- /** A WebMCP tool definition exposed to in-page agents via `navigator.modelContext`. */
3522
- interface WebMcpTool {
3598
+ /**
3599
+ * A WebMCP tool definition exposed to in-page agents via `navigator.modelContext`.
3600
+ * `TInput` is the shape your `inputSchema` describes — type your `execute`
3601
+ * parameter inline (`execute: (input: { path: string }) => …`) or pin it with
3602
+ * `WebMcpTool<{ path: string }>`. The default is deliberately loose: the input
3603
+ * arrives from the agent unvalidated, so treat it as untrusted regardless.
3604
+ */
3605
+ interface WebMcpTool<TInput = any> {
3523
3606
  name: string;
3524
3607
  description: string;
3525
3608
  /** JSON Schema for the tool's input. */
3526
3609
  inputSchema: Record<string, unknown>;
3527
3610
  /** Called when an agent invokes the tool. */
3528
- execute: (input: any) => unknown | Promise<unknown>;
3611
+ execute: (input: TInput) => unknown | Promise<unknown>;
3529
3612
  }
3530
3613
  /**
3531
3614
  * Register WebMCP tools with the browser so in-page AI agents can invoke your
@@ -3620,6 +3703,24 @@ interface AppRevokeRequestClaims {
3620
3703
  reason: string;
3621
3704
  [claim: string]: unknown;
3622
3705
  }
3706
+ /**
3707
+ * A verified JWT payload: registered claims (RFC 7519) are typed AND
3708
+ * runtime-validated by {@link verifyClientJwt} (a signed token whose `sub` is
3709
+ * a number is rejected, so the types here are real guarantees). Every other
3710
+ * claim is `unknown` — custom claims are attacker-influenced input until you
3711
+ * narrow them (`typeof payload.sid === 'string'`), even after the signature
3712
+ * checks out.
3713
+ */
3714
+ interface VerifiedJwtPayload {
3715
+ iss?: string;
3716
+ sub?: string;
3717
+ aud?: string | string[];
3718
+ exp?: number;
3719
+ nbf?: number;
3720
+ iat?: number;
3721
+ jti?: string;
3722
+ [claim: string]: unknown;
3723
+ }
3623
3724
  /** Options for {@link verifyClientJwt} (all optional; secure defaults). */
3624
3725
  interface VerifyClientJwtOptions {
3625
3726
  /** Allowed clock skew in seconds for `exp`/`nbf`. Default 60. */
@@ -3641,7 +3742,7 @@ interface VerifyClientJwtOptions {
3641
3742
  * and — by default — that an `exp` is present at all. Optionally pins `iss`/`aud`.
3642
3743
  * Throws {@link AppBridgeError} on any failure.
3643
3744
  */
3644
- declare function verifyClientJwt(token: string, clientSecret: string, options?: VerifyClientJwtOptions): Record<string, any>;
3745
+ declare function verifyClientJwt(token: string, clientSecret: string, options?: VerifyClientJwtOptions): VerifiedJwtPayload;
3645
3746
  /** Extract the token from an `Authorization: Bearer <token>` header. */
3646
3747
  declare function extractBearerToken(authorization: string | null | undefined): string | null;
3647
3748
  /**
@@ -4054,13 +4155,20 @@ declare function BuildBase(config: BuildBaseConfig): BuildBaseResult;
4054
4155
  *
4055
4156
  * export const mcp = createMcpHandler({
4056
4157
  * buildbase,
4057
- * serverInfo: { name: 'imejis', version: '1.0.0' },
4158
+ * serverInfo: { name: 'acme', version: '1.0.0' },
4058
4159
  * auth: {
4059
4160
  * verify: (token) => {
4060
4161
  * const c = verifyClientJwt(token, process.env.BUILDBASE_CLIENT_SECRET!);
4061
- * return { sessionId: String(c.sid), userId: String(c.sub), scopes: c.scope };
4162
+ * // Claims beyond RFC 7519 are `unknown` — narrow before use.
4163
+ * return {
4164
+ * sessionId: typeof c.sid === 'string' ? c.sid : '',
4165
+ * userId: c.sub,
4166
+ * scopes: Array.isArray(c.scope)
4167
+ * ? c.scope.filter((s): s is string => typeof s === 'string')
4168
+ * : undefined,
4169
+ * };
4062
4170
  * },
4063
- * resourceMetadataUrl: 'https://imejis.io/.well-known/oauth-protected-resource',
4171
+ * resourceMetadataUrl: 'https://example.com/.well-known/oauth-protected-resource',
4064
4172
  * },
4065
4173
  * });
4066
4174
  *
@@ -4215,5 +4323,5 @@ declare function buildbaseAuth(options: BuildBaseAuthOptions): {
4215
4323
  resourceMetadataUrl?: string;
4216
4324
  };
4217
4325
 
4218
- export { AI_BOT_USER_AGENTS, ApiVersion, AppBridgeError, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, BuildBase, CURRENCY_DISPLAY, CURRENCY_FLAG, CreditBucketSource, CreditBucketStatus, CreditTransactionType, DEFAULT_ROLE_PERMISSIONS, DunningState, EventEmitter, InvoiceStatuses, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UserApi, WorkspaceApi, appTokenFailure, appTokenSuccess, bearerChallenge, buildA2AAgentCard, buildAgentCard, buildAgentSkillsIndex, buildApiCatalog, buildAuthMd, buildDiscoveryLinkHeader, buildDnsAidRecords, buildLlmsFullTxt, buildLlmsTxt, buildMcpDiscoveryManifest, buildMcpServerCard, buildProtectedResourceMetadata, buildRobotsTxt, buildSecurityTxt, buildSitemap, buildSkillMd, buildWebBotAuthDirectory, buildbaseAuth, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAgentReadinessCache, clearAuthIntent, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, createCreditPurchaseRedirectUrls, createSessionRefCrypto, BuildBase as default, eventEmitter, extractBearerToken, fetchAgentReadiness, formatCents, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, handleAppRevokeRequest, handleAppTokenRequest, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, isZeroDecimalCurrency, minorAmountToDisplay, mintAgentToken, negotiateMarkdown, parseWebhookEvent, provideWebMcpTools, readBBParams, resolveAgentPath, resolveMaxUsers, resolvePermissions, resolveWellKnown, safeRedirect, saveAuthIntent, sha256Digest, signClientJwt, validateInvite, validateRedirectUrl, verifyAppRevokeRequest, verifyAppTokenRequest, verifyClientJwt, verifyWebhookSignature, wantsMarkdown };
4326
+ export { AI_BOT_USER_AGENTS, ApiVersion, AppBridgeError, AuthApi, AuthStatus, BBAction, BBScreen, BBStatus, BB_PARAM, BaseApi, BetaForm, BillingIntervals, BuildBase, CURRENCY_DISPLAY, CURRENCY_FLAG, CreditBucketSource, CreditBucketStatus, CreditTransactionType, DEFAULT_ROLE_PERMISSIONS, DunningState, EventEmitter, InvoiceStatuses, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UserApi, WorkspaceApi, appTokenFailure, appTokenSuccess, bearerChallenge, buildA2AAgentCard, buildAgentCard, buildAgentSkillsIndex, buildApiCatalog, buildAuthMd, buildDiscoveryLinkHeader, buildDnsAidRecords, buildLlmsFullTxt, buildLlmsTxt, buildMcpDiscoveryManifest, buildMcpServerCard, buildProtectedResourceMetadata, buildRobotsTxt, buildSecurityTxt, buildSitemap, buildSkillMd, buildWebBotAuthDirectory, buildbaseAuth, calculateBillableSeats, calculateSeatOverageCents, calculateTotalSubscriptionCents, cleanBBParams, clearAgentReadinessCache, clearAuthIntent, consumeAuthIntent, createBBUrl, createCheckoutRedirectUrls, createCreditPurchaseRedirectUrls, createSessionRefCrypto, BuildBase as default, eventEmitter, extractBearerToken, fetchAgentReadiness, formatCents, formatMinorAmountIntl, formatOverageRate, formatOverageRateWithLabel, formatQuotaIncludedOverage, formatQuotaWithPrice, getAvailableCurrenciesFromPlans, getBasePriceCents, getBillingIntervalAndCurrencyFromPriceId, getCurrencyDecimals, getCurrencyFlag, getCurrencySymbol, getDisplayCurrency, getPerSeatPriceCents, getPricingVariant, getQuotaDisplayValue, getQuotaDisplayWithVariant, getQuotaOverageCents, getQuotaUnitLabelFromName, getSeatPricing, getStripePriceIdForInterval, handleAppRevokeRequest, handleAppTokenRequest, hasPermission, invalidateCreditBalance, invalidateQuotaUsage, invalidateSubscription, isZeroDecimalCurrency, minorAmountToDisplay, mintAgentToken, negotiateMarkdown, parseWebhookEvent, provideWebMcpTools, readBBParams, resolveAgentPath, resolveMaxUsers, resolvePermissions, resolveWellKnown, safeRedirect, saveAuthIntent, sha256Digest, signClientJwt, validateInvite, validateRedirectUrl, verifyAppRevokeRequest, verifyAppTokenRequest, verifyClientJwt, verifyWebhookSignature, wantsMarkdown };
4219
4327
  export type { A2ACardConfig, A2ACardSkill, AgentReadinessBundle, AgentReadyConfig, AgentSkill, ApiCatalogApi, AppRevokeRequestClaims, AppScope, AppTokenRequestClaims, AppTokenResponseBody, AppTokenResult, BBActionType, BBScreenType, BBStatusType, BetaFormData, BetaFormResponse, BillingInterval, BuildBaseAuthOptions, BuildBaseConfig, BuildBaseResult, BuildBaseSession, CheckoutResult, ContentSignals, CreditActions, CreditBucketSourceType, CreditBucketStatusType, CreditTransactionTypeValue, DiscoveryDocument, DnsAidRecord, DunningStateType, EventData, EventType, FeatureActions, FormatQuotaWithPriceOptions, GetCheckoutStripeParams, HandlerResult, IAllQuotaUsageResponse, IBaseApiConfig, IBasePricing, IBetaConfig, ICheckoutSessionRequest, ICheckoutSessionResponse, ICheckoutStripeOptions, IConsumeCreditsRequest, IConsumeCreditsResponse, ICreditBalance, ICreditBucket, ICreditBucketsQuery, ICreditBucketsResponse, ICreditPackage, ICreditPackagePricingVariant, ICreditPurchaseRequest, ICreditPurchaseResponse, ICreditTransaction, ICreditTransactionsQuery, ICreditTransactionsResponse, IEventCallbacks, IExpiringCreditsResponse, IInvoice, IInvoiceListResponse, IInvoiceResponse, IOsConfig, IOsState, IPlan, IPlanGroup, IPlanGroupInfo, IPlanGroupLatestVersion, IPlanGroupResponse, IPlanGroupVersion, IPlanGroupVersionWithPlans, IPlanGroupVersionsResponse, IPlanVersion, IPlanVersionSummary, IPlanVersionWithPlan, IPricingVariant, IPublicCreditPackage, IPublicCreditPackagesResponse, IPublicPlanItem, IPublicPlanItemCategory, IPublicPlanVersion, IPublicPlansResponse, IQuotaByInterval, IQuotaIntervalValue, IQuotaOveragePriceIdsByInterval, IQuotaOveragesByInterval, IQuotaUsageStatus, IQuotaUsageStatusResponse, IRecordUsageRequest, IRecordUsageResponse, ISettings, IStripePricesByInterval, ISubscription, ISubscriptionItem, ISubscriptionResponse, ISubscriptionUpdateRequest, ISubscriptionUpdateResponse, IUsageLogEntry, IUsageLogsQuery, IUsageLogsResponse, IUser, IWorkspace, InviteBlockReason, InviteValidation, InvoiceActions, InvoiceStatus, InvoiceStatusType, MaxUsersConfig, McpServerCard, MintAgentTokenOptions, NotificationData, NotificationEvent, NotificationResult, OnWorkspaceChangeParams, PermissionActions, PermissionContext, PermissionKey, PlanActions, PlanVersionWithPricingVariants, QuotaDisplayValue, QuotaDisplayWithOverage, RedirectValidationOptions, RobotsConfig, RobotsPolicy, RolePermissionMap, ScopedActions, SessionRefCrypto, SettingsActions, SitemapUrl, SubscriptionActions, SubscriptionItemTypeValue, SubscriptionStatusType, TranslationKey, UsageActions, UserActions, UserCreatedEventData, UserUpdatedEventData, WebMcpTool, WorkspaceActions, WorkspaceChangedEventData, WorkspaceCreatedEventData, WorkspaceDeletedEventData, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };