@buildbase/sdk 0.0.71 → 0.0.74

package/dist/index.d.ts

@@ -1102,6 +1102,16 @@ interface ISettings {
         canInviteMembers: boolean | 'admin-only';
         /** Custom role→permission mapping. Overrides SDK defaults when provided by backend. */
         permissions?: Record<string, string[]>;
+        /**
+         * The organization's own permissions, defined in the BuildBase console:
+         * `{ key: 'app:reports:export', label: 'Export reports', group: 'Reports' }`.
+         * Absent on a server from before release 23.
+         */
+        customPermissions?: {
+            key: string;
+            label: string;
+            group?: string;
+        }[];
         /** Show workspace switcher in the UI */
         showSwitcher: boolean;
         /** Max workspaces a user can own. 0 = unlimited */
@@ -1304,6 +1314,18 @@ interface AuthRequestParams {
      * Populated automatically from the tracking provider when one is mounted.
      * Omitted means unanswered, which is not the same as refused.
      */
+    /**
+     * Where the visitor came from - the click ids and campaign fields captured
+     * on their landing page, when, and where. Stored on the user the hosted
+     * pages create, so a conversion that happens later with no browser (a trial
+     * converting, a renewal) can still be joined to the ad click. Populated
+     * automatically from the attribution cookie when tracking is mounted.
+     */
+    trackingAttribution?: {
+        params: Record<string, string>;
+        capturedAt?: number;
+        landingUrl?: string;
+    };
     trackingConsent?: {
         analytics: boolean;
         marketing: boolean;
@@ -1682,6 +1704,15 @@ declare class UserApi extends BaseApi {
     getFeatures(signal?: AbortSignal): Promise<Record<string, boolean>>;
 }
 
+/** What a member may do in a workspace, as the server resolved it. */
+interface WorkspaceMemberPermissions {
+    /** The member's role, or null when they are not a member. */
+    role: string | null;
+    /** The workspace's owner holds every permission. */
+    isOwner: boolean;
+    /** Platform keys (`workspace:*`) and the organization's own keys. */
+    permissions: string[];
+}
 /** Data passed to a notification template for merge tag replacement. */
 interface NotificationData {
     /** Push notification title. Falls back to the event name if not provided. */
@@ -1790,6 +1821,12 @@ declare class WorkspaceApi extends BaseApi {
     createWorkspace(data: {
         name: string;
         image?: string;
+        /** Where the creator came from. Stored on the workspace for conversions recorded later. */
+        trackingAttribution?: {
+            params: Record<string, string>;
+            capturedAt?: number;
+            landingUrl?: string;
+        };
     }, signal?: AbortSignal): Promise<IWorkspace>;
     updateWorkspace(id: string, data: Partial<IWorkspace>, signal?: AbortSignal): Promise<IWorkspace>;
     deleteWorkspace(id: string, signal?: AbortSignal): Promise<{
@@ -1873,6 +1910,12 @@ declare class WorkspaceApi extends BaseApi {
         permissions: Record<string, string[]>;
     }, signal?: AbortSignal): Promise<any>;
     updateWorkspacePermissions(workspaceId: string, permissions: Record<string, string[]>, signal?: AbortSignal): Promise<any>;
+    /**
+     * What the signed-in member may do in a workspace, as the server resolves
+     * it: the platform's permissions and the organization's own. A backend asks
+     * this rather than trusting a flag the browser sent.
+     */
+    getMyPermissions(workspaceId: string, signal?: AbortSignal): Promise<WorkspaceMemberPermissions>;
     getFeatures(signal?: AbortSignal): Promise<IWorkspaceFeature[]>;
     updateFeature(workspaceId: string, key: string, value: boolean, signal?: AbortSignal): Promise<IWorkspace>;
     getWorkspace(workspaceId: string, signal?: AbortSignal): Promise<IWorkspace>;
@@ -2730,17 +2773,45 @@ declare const Permission: {
     readonly WORKSPACE_BILLING_VIEW: "workspace:billing:view";
     readonly WORKSPACE_BILLING_MANAGE: "workspace:billing:manage";
     readonly WORKSPACE_USAGE_VIEW: "workspace:usage:view";
+    /** Record usage and spend the workspace's credits. Withheld from viewers. */
+    readonly WORKSPACE_USAGE_RECORD: "workspace:usage:record";
 };
 type PermissionKey = (typeof Permission)[keyof typeof Permission];
 type RolePermissionMap = Record<string, string[]>;
+/**
+ * Defaults for the three roles every org is seeded with, the same lists the
+ * server enforces. Servers now send each role's effective permissions in the
+ * public settings, so these apply only to a server that does not. There is no
+ * `member` entry: no one can hold that role, and `editor` had none, so an
+ * editor was shown nothing the server let them do.
+ */
 declare const DEFAULT_ROLE_PERMISSIONS: RolePermissionMap;
+/** The least privileged built-in role, used when no default is usable. */
+declare const FALLBACK_WORKSPACE_ROLE = "viewer";
+/**
+ * The role to preselect for someone joining: the org's default role when it
+ * is on the list, but never `admin`, which must be a deliberate choice. Then
+ * viewer, then any role other than admin.
+ */
+declare function pickDefaultRole(roles: readonly string[], defaultRole?: string | null): string;
 interface WorkspaceLike extends WorkspaceLike$1 {
     permissions?: Record<string, string[]>;
 }
+/**
+ * A permission the organization defined for its own application, in the
+ * BuildBase console. The server stores and resolves it exactly like a platform
+ * permission; what it means is the application's business.
+ */
+interface WorkspacePermissionDefinition {
+    key: string;
+    label: string;
+    group?: string;
+}
 interface SettingsLike {
     workspace?: {
         defaultRole?: string;
         permissions?: Record<string, string[]>;
+        customPermissions?: WorkspacePermissionDefinition[];
         canInviteMembers?: boolean | 'admin-only';
         canCreateWorkspace?: boolean | 'owner-only';
     };
@@ -2770,12 +2841,31 @@ interface PermissionContext {
  * 7. Apply setting restrictions (canInviteMembers)
  */
 declare function resolvePermissions(ctx: PermissionContext): Set<string>;
+/**
+ * What one role may do in a workspace, by the same tiers the server uses.
+ * `resolvePermissions` answers for a user; this answers for a role, which is
+ * what a screen editing the matrix needs. `applyRestrictions: false` leaves
+ * out the org's live switches (who may invite), so a screen does not write a
+ * switch's current effect into a saved override.
+ */
+declare function resolveRolePermissions(role: string, ctx: Pick<PermissionContext, 'workspace' | 'settings' | 'appPermissions'>, options?: {
+    applyRestrictions?: boolean;
+}): Set<string>;
 /**
  * Check if a user has a specific permission (or all of an array).
  * Works with both platform permissions (Permission.WORKSPACE_*) and
  * app permissions (any custom string).
  */
 declare function hasPermission(permission: string | string[], ctx: PermissionContext): boolean;
+/** Where a permission the app checks was defined. */
+declare const APP_PERMISSION_FALLBACK_GROUP = "App";
+/**
+ * Every permission this application defines, for a UI that lists them: the
+ * organization's catalogue from the console, plus any key the app passed
+ * through `defaultPermissions` that the catalogue does not name yet. Keys from
+ * the prop keep working, so adopting the console costs nothing.
+ */
+declare function appPermissionCatalogue(settings?: SettingsLike | null, appPermissions?: Record<string, string[]> | null): WorkspacePermissionDefinition[];
 
 /**
  * Push notification service worker source code.
@@ -4627,6 +4717,17 @@ interface WorkspaceActions {
     delete(workspaceId: string): Promise<{
         success: boolean;
     }>;
+    /**
+     * What the session's user may do in a workspace, resolved by the server:
+     * `{ role, isOwner, permissions }`. Use it in your backend before acting,
+     * instead of trusting the browser's answer.
+     */
+    permissions(workspaceId: string): Promise<WorkspaceMemberPermissions>;
+    /**
+     * Whether the session's user holds a permission (or every one of a list)
+     * in a workspace, platform or your own: `can(id, 'app:reports:export')`.
+     */
+    can(workspaceId: string, permission: string | string[]): Promise<boolean>;
 }
 interface UserActions {
     list(workspaceId: string): Promise<IWorkspaceUser[]>;
@@ -5076,5 +5177,5 @@ declare function buildbaseAuth(options: BuildBaseAuthOptions): {
     resourceMetadataUrl?: string;
 };
 
-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, INVITATION_ERROR_CODE, InvoiceStatuses, NotificationsApi, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UserApi, WorkspaceApi, actionableInvitations, 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, clearPendingInvite, 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, inviterNameOf, isInvitationActionable, isInvitationError, isInvitationLapsed, isZeroDecimalCurrency, minorAmountToDisplay, mintAgentToken, negotiateMarkdown, parkPendingInvite, parseWebhookEvent, provideWebMcpTools, readBBParams, readPendingInvite, resendCooldownSeconds, resolveAgentPath, resolveMaxUsers, resolvePermissions, resolveWellKnown, safeRedirect, saveAuthIntent, sha256Digest, signClientJwt, sortInvitations, validateInvite, validateRedirectUrl, verifyAppRevokeRequest, verifyAppTokenRequest, verifyClientJwt, verifyWebhookSignature, wantsMarkdown, workspaceIdOf, workspaceNameOf };
-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, INotificationItem, 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, IWorkspaceInvitation, IWorkspaceInvitationPreview, IWorkspaceInvitationStatus, InvitationActions, InvitationError, InvitationErrorCode, InvitationErrorFields, InviteBlockReason, InviteValidation, InvoiceActions, InvoiceStatus, InvoiceStatusType, MaxUsersConfig, McpServerCard, MintAgentTokenOptions, MyNotificationPreferences, NotificationChannelPreference, NotificationCounts, NotificationData, NotificationEvent, NotificationListParams, NotificationPage, NotificationResult, NotificationScope, 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, WorkspaceInvitationAcceptedEventData, WorkspaceInvitationDeclinedEventData, WorkspaceInvitationRevokedEventData, WorkspaceInvitationSentEventData, WorkspaceNotificationDefault, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };
+export { AI_BOT_USER_AGENTS, APP_PERMISSION_FALLBACK_GROUP, 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, FALLBACK_WORKSPACE_ROLE, INVITATION_ERROR_CODE, InvoiceStatuses, NotificationsApi, PLAN_CURRENCY_CODES, PLAN_CURRENCY_OPTIONS, PUSH_SERVICE_WORKER_SCRIPT, Permission, PushApi, SDKEvent, SettingsApi, SubscriptionItemType, SubscriptionStatus, UserApi, WorkspaceApi, actionableInvitations, appPermissionCatalogue, 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, clearPendingInvite, 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, inviterNameOf, isInvitationActionable, isInvitationError, isInvitationLapsed, isZeroDecimalCurrency, minorAmountToDisplay, mintAgentToken, negotiateMarkdown, parkPendingInvite, parseWebhookEvent, pickDefaultRole, provideWebMcpTools, readBBParams, readPendingInvite, resendCooldownSeconds, resolveAgentPath, resolveMaxUsers, resolvePermissions, resolveRolePermissions, resolveWellKnown, safeRedirect, saveAuthIntent, sha256Digest, signClientJwt, sortInvitations, validateInvite, validateRedirectUrl, verifyAppRevokeRequest, verifyAppTokenRequest, verifyClientJwt, verifyWebhookSignature, wantsMarkdown, workspaceIdOf, workspaceNameOf };
+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, INotificationItem, 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, IWorkspaceInvitation, IWorkspaceInvitationPreview, IWorkspaceInvitationStatus, InvitationActions, InvitationError, InvitationErrorCode, InvitationErrorFields, InviteBlockReason, InviteValidation, InvoiceActions, InvoiceStatus, InvoiceStatusType, MaxUsersConfig, McpServerCard, MintAgentTokenOptions, MyNotificationPreferences, NotificationChannelPreference, NotificationCounts, NotificationData, NotificationEvent, NotificationListParams, NotificationPage, NotificationResult, NotificationScope, 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, WorkspaceInvitationAcceptedEventData, WorkspaceInvitationDeclinedEventData, WorkspaceInvitationRevokedEventData, WorkspaceInvitationSentEventData, WorkspaceMemberPermissions, WorkspaceNotificationDefault, WorkspacePermissionDefinition, WorkspaceUpdatedEventData, WorkspaceUserAddedEventData, WorkspaceUserRemovedEventData, WorkspaceUserRoleChangedEventData };