@buildbase/sdk 0.0.70 → 0.0.73

package/dist/index.d.ts

@@ -852,6 +852,59 @@ interface IWorkspaceUser {
     role: string;
 }
 
+/** Mirrors the server enum, string-typed so an app can compare without an import. */
+type IWorkspaceInvitationStatus = 'invited' | 'accepted' | 'rejected' | 'expired';
+/**
+ * A workspace invitation: an email address a member invited, before (or
+ * after) the person behind it accepted. A pending row bills a seat until it is
+ * accepted, declined, revoked or expired.
+ */
+interface IWorkspaceInvitation {
+    _id: string;
+    /** The workspace, populated with `name` and `image` on the invitee's list. */
+    workspace: string | Pick<IWorkspace, '_id' | 'name' | 'image'>;
+    email: string;
+    role: string;
+    status: IWorkspaceInvitationStatus;
+    invitedAt: string;
+    /** When last emailed; absent until the first resend. Read `lastSentAt ?? invitedAt`. */
+    lastSentAt?: string;
+    /**
+     * When a resend stops being refused. The server derives it from the last
+     * send and its own cooldown, so a countdown here cannot disagree with the
+     * 429 that enforces it. Null unless the row is pending; absent from a
+     * server older than this field, which `resendCooldownSeconds` reads as
+     * "no cooldown known".
+     */
+    resendAvailableAt?: string | null;
+    /** The inviter, populated with `name`, `email` and `image`; null when their account is gone. */
+    invitedBy: string | (Pick<IUser, '_id' | 'name' | 'email'> & {
+        image?: string;
+    }) | null;
+    /** Null once accepted: the link no longer has anything to expire. */
+    validTill: string | null;
+    acceptedAt?: string;
+    rejectedAt?: string;
+    /** The app URL the emailed link lands on. */
+    landingUrl?: string;
+    clientId?: string;
+}
+/** What the public preview returns for a link token. The email is scrambled. */
+interface IWorkspaceInvitationPreview {
+    id: string;
+    workspaceName: string;
+    inviterName: string;
+    role: string;
+    email: string;
+    expiresAt: string | null;
+    status: IWorkspaceInvitationStatus;
+    /**
+     * False when the organization has switched invitations off, so accepting
+     * cannot succeed. Absent from older servers, which is read as joinable.
+     */
+    joinable?: boolean;
+}
+
 /** Event type constants */
 declare const SDKEvent: {
     readonly UserCreated: "user:created";
@@ -863,6 +916,10 @@ declare const SDKEvent: {
     readonly WorkspaceUserRoleChanged: "workspace:user-role-changed";
     readonly WorkspaceCreated: "workspace:created";
     readonly WorkspaceDeleted: "workspace:deleted";
+    readonly WorkspaceInvitationSent: "workspace:invitation-sent";
+    readonly WorkspaceInvitationAccepted: "workspace:invitation-accepted";
+    readonly WorkspaceInvitationDeclined: "workspace:invitation-declined";
+    readonly WorkspaceInvitationRevoked: "workspace:invitation-revoked";
 };
 type EventType = (typeof SDKEvent)[keyof typeof SDKEvent];
 /**
@@ -904,10 +961,27 @@ interface WorkspaceCreatedEventData {
 interface WorkspaceDeletedEventData {
     workspace: IWorkspace;
 }
+/** An invitation was sent from this client. The invitee may have no account yet. */
+interface WorkspaceInvitationSentEventData {
+    invitation: IWorkspaceInvitation;
+    workspaceId: string;
+}
+/** The signed-in user accepted an invitation; `WorkspaceUserAdded` fires too. */
+interface WorkspaceInvitationAcceptedEventData {
+    invitation: IWorkspaceInvitation;
+    workspace: IWorkspace;
+}
+interface WorkspaceInvitationDeclinedEventData {
+    invitation: IWorkspaceInvitation;
+}
+interface WorkspaceInvitationRevokedEventData {
+    invitationId: string;
+    workspaceId: string;
+}
 /**
  * Union type for all event data
  */
-type EventData = UserCreatedEventData | UserUpdatedEventData | WorkspaceChangedEventData | WorkspaceUpdatedEventData | WorkspaceUserAddedEventData | WorkspaceUserRemovedEventData | WorkspaceUserRoleChangedEventData | WorkspaceCreatedEventData | WorkspaceDeletedEventData;
+type EventData = UserCreatedEventData | UserUpdatedEventData | WorkspaceChangedEventData | WorkspaceUpdatedEventData | WorkspaceUserAddedEventData | WorkspaceUserRemovedEventData | WorkspaceUserRoleChangedEventData | WorkspaceCreatedEventData | WorkspaceDeletedEventData | WorkspaceInvitationSentEventData | WorkspaceInvitationAcceptedEventData | WorkspaceInvitationDeclinedEventData | WorkspaceInvitationRevokedEventData;
 /**
  * Single event callback function
  * Handles all events with conditional logic based on event type
@@ -1028,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 */
@@ -1230,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;
@@ -1416,6 +1512,111 @@ declare class DevicesApi extends BaseApi {
     }>;
 }
 
+/**
+ * API client for the signed-in user's notification inbox. Session-authed
+ * (x-session-id) and scoped to the current user by the server: every call
+ * reads or changes only their own items. Extends BaseApi for shared
+ * URL/auth/request handling.
+ *
+ * One item is one notification, however it was delivered: an event sent by
+ * email and push is a single item whose `channels` say what each did.
+ */
+
+type NotificationChannelStatus = 'none' | 'queued' | 'sent' | 'failed' | 'skipped';
+type NotificationSource = 'system' | 'custom' | 'workflow' | 'campaign' | 'console';
+/** How an item was first read: in the inbox, or by clicking its email or push link. */
+type NotificationReadVia = 'inbox' | 'email_click' | 'push_click';
+/** One notification in the signed-in user's inbox. Dates are ISO strings. */
+interface INotificationItem {
+    id: string;
+    /** The workspace it is about, or null for an account notice. */
+    workspaceId: string | null;
+    /** The event slug that sent it. */
+    event: string;
+    source: NotificationSource;
+    title: string;
+    body: string;
+    /** The destination as the app set it, for display. */
+    url: string | null;
+    /**
+     * What to open when the item is clicked: an absolute destination routed
+     * through the server's link check (which also marks the item read), a path
+     * inside the app as it is, or null when there is nothing safe to open.
+     */
+    link: string | null;
+    icon: string | null;
+    channels: {
+        /** An open is recorded but does not read the item; a click does. */
+        email: {
+            status: NotificationChannelStatus;
+            openedAt: string | null;
+            clickedAt: string | null;
+        };
+        push: {
+            status: NotificationChannelStatus;
+            clickedAt: string | null;
+        };
+    };
+    createdAt: string | null;
+    /** The inbox was opened while this was in it. Not the same as read. */
+    seenAt: string | null;
+    readAt: string | null;
+    readVia: NotificationReadVia | null;
+    archivedAt: string | null;
+}
+/**
+ * Which items: one workspace's, `'none'` for the account notices that belong
+ * to no workspace, or omitted for everything.
+ */
+type NotificationScope = string | 'none' | undefined;
+interface NotificationListParams {
+    workspaceId?: NotificationScope;
+    /** Only unread items. */
+    unread?: boolean;
+    /** Include archived items, which the default list leaves out. */
+    archived?: boolean;
+    page?: number;
+    /** At most 100. */
+    limit?: number;
+}
+interface NotificationPage {
+    notifications: INotificationItem[];
+    page: number;
+    limit: number;
+    total: number;
+    hasNextPage: boolean;
+}
+interface NotificationCounts {
+    /** Unread and not archived: the number on the bell. */
+    unread: number;
+    /** Unread and never seen: whether anything is new since the inbox was last opened. */
+    unseen: number;
+}
+declare class NotificationsApi extends BaseApi {
+    constructor(config: Pick<IOsConfig, 'serverUrl' | 'version'> & {
+        sessionId?: string;
+    });
+    /** A page of the current user's items, newest first. */
+    list(params?: NotificationListParams, signal?: AbortSignal): Promise<NotificationPage>;
+    /** Unread and unseen counts, for a badge. */
+    counts(workspaceId?: NotificationScope, signal?: AbortSignal): Promise<NotificationCounts>;
+    /**
+     * Mark one item read. Returns it as it now stands. Sent with `keepalive`,
+     * because it is usually followed at once by opening the item's link, and a
+     * page that navigates away would otherwise cancel it.
+     */
+    markRead(id: string): Promise<INotificationItem>;
+    markUnread(id: string): Promise<INotificationItem>;
+    /** Move an item out of the default list. It stays in history (`archived: true`). */
+    archive(id: string): Promise<INotificationItem>;
+    unarchive(id: string): Promise<INotificationItem>;
+    /** Read everything in scope. */
+    markAllRead(workspaceId?: NotificationScope): Promise<void>;
+    /** The inbox was opened: clears "new" without reading anything. */
+    markSeen(workspaceId?: NotificationScope): Promise<void>;
+    private itemAction;
+}
+
 declare class PushApi extends BaseApi {
     constructor(config: Pick<IBaseApiConfig, 'serverUrl' | 'version' | 'orgId' | 'sessionId'>);
     getVapidPublicKey(): Promise<{
@@ -1503,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. */
@@ -1585,6 +1795,23 @@ interface NotificationEvent {
         push: boolean;
     };
 }
+/** One event's channels. A channel left out is on. */
+interface NotificationChannelPreference {
+    email?: boolean;
+    push?: boolean;
+}
+/** The workspace's setting for one event: the default, and whether members may change it. */
+interface WorkspaceNotificationDefault extends NotificationChannelPreference {
+    /** Members cannot change this event: the default is what they get. */
+    required?: boolean;
+}
+/** The signed-in member's notification settings in one workspace. */
+interface MyNotificationPreferences {
+    /** The workspace's defaults, by event slug. */
+    defaults: Record<string, WorkspaceNotificationDefault>;
+    /** The member's own choices over them, by event slug. */
+    mine: Record<string, NotificationChannelPreference>;
+}
 declare class WorkspaceApi extends BaseApi {
     constructor(config: IOsConfig & {
         sessionId?: string;
@@ -1594,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<{
@@ -1608,6 +1841,61 @@ declare class WorkspaceApi extends BaseApi {
         workspace: IWorkspace;
         message: string;
     }>;
+    private fetchInvitation;
+    /** The workspace's invitations, pending first. Needs `MEMBERS_VIEW`. */
+    listInvitations(workspaceId: string, signal?: AbortSignal): Promise<IWorkspaceInvitation[]>;
+    /**
+     * Invite an email address to a workspace. The person need not have an
+     * account: they get a link that lands on the app's own auth redirect URL
+     * (or on `landingUrl`, which must be one of the auth client's allowed
+     * redirect URLs). Needs `MEMBERS_INVITE`. A pending invitation bills a seat.
+     */
+    inviteMember(workspaceId: string, config: {
+        email: string;
+        role: string;
+        landingUrl?: string;
+    }, signal?: AbortSignal): Promise<IWorkspaceInvitation & {
+        message: string;
+    }>;
+    /** Send the same invitation again (five-minute cooldown). Revives an expired one. */
+    resendInvitation(workspaceId: string, invitationId: string, signal?: AbortSignal): Promise<IWorkspaceInvitation & {
+        message: string;
+    }>;
+    /** Withdraw a pending invitation. The invitee is told; the seat is released. */
+    revokeInvitation(workspaceId: string, invitationId: string, signal?: AbortSignal): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /** The signed-in user's own pending invitations, across workspaces. */
+    myInvitations(signal?: AbortSignal): Promise<IWorkspaceInvitation[]>;
+    /**
+     * Accept an invitation addressed to the signed-in user's email.
+     *
+     * Pass the `token` from the invitation link when the user arrived by
+     * following it: the token was mailed to that address and to nowhere else, so
+     * it proves the mailbox and the account does not have to be verified
+     * separately first. Without it, the server requires a verified email, which
+     * is the case when accepting from the in-app list.
+     */
+    acceptInvitation(invitationId: string, options?: {
+        token?: string;
+    }, signal?: AbortSignal): Promise<{
+        invitation: IWorkspaceInvitation;
+        /** Null only when another tab accepted a moment earlier and its membership write is still in flight. */
+        workspace: IWorkspace | null;
+        message: string;
+    }>;
+    /** Decline an invitation addressed to the signed-in user's email. */
+    declineInvitation(invitationId: string, signal?: AbortSignal): Promise<{
+        invitation: IWorkspaceInvitation;
+        message: string;
+    }>;
+    /**
+     * What an invitation link resolves to, before sign-in. Public: keyed by the
+     * link's token, answers with the workspace name, the inviter, the role, the
+     * scrambled address and the status. 404 for an unknown or revoked token.
+     */
+    previewInvitation(token: string, signal?: AbortSignal): Promise<IWorkspaceInvitationPreview>;
     removeUser(workspaceId: string, userId: string, signal?: AbortSignal): Promise<{
         userId: string;
         workspace: IWorkspace;
@@ -1622,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>;
@@ -1832,17 +2126,24 @@ declare class WorkspaceApi extends BaseApi {
      */
     sendNotification(workspaceId: string, event: string, userId?: string, data?: NotificationData, signal?: AbortSignal): Promise<NotificationResult>;
     getNotificationEvents(workspaceId: string, signal?: AbortSignal): Promise<NotificationEvent[]>;
-    getNotificationPreferences(workspaceId: string, signal?: AbortSignal): Promise<Record<string, {
-        email?: boolean;
-        push?: boolean;
-    }>>;
-    updateNotificationPreferences(workspaceId: string, preferences: Record<string, {
-        email?: boolean;
-        push?: boolean;
-    }>, signal?: AbortSignal): Promise<Record<string, {
-        email?: boolean;
-        push?: boolean;
-    }>>;
+    /** The workspace's defaults for every member. Needs `SETTINGS_VIEW`. */
+    getNotificationPreferences(workspaceId: string, signal?: AbortSignal): Promise<Record<string, WorkspaceNotificationDefault>>;
+    /**
+     * Change the workspace's defaults (and `required`) for every member. Needs
+     * `SETTINGS_EDIT`. Merged per event: send only what changes.
+     */
+    updateNotificationPreferences(workspaceId: string, preferences: Record<string, WorkspaceNotificationDefault>, signal?: AbortSignal): Promise<Record<string, WorkspaceNotificationDefault>>;
+    /** The signed-in member's own settings here, and the defaults they sit over. Any member. */
+    getMyNotificationPreferences(workspaceId: string, signal?: AbortSignal): Promise<MyNotificationPreferences>;
+    /**
+     * Change the signed-in member's own settings. `null` for a channel goes back
+     * to the workspace default. A required event answers 409 with
+     * `code: 'NOTIFICATION_PREFERENCE_REQUIRED'`.
+     */
+    updateMyNotificationPreferences(workspaceId: string, preferences: Record<string, {
+        email?: boolean | null;
+        push?: boolean | null;
+    }>, signal?: AbortSignal): Promise<MyNotificationPreferences>;
     /**
      * Get credit balance for a workspace.
      * @param workspaceId - The workspace ID
@@ -1962,6 +2263,14 @@ declare class EventEmitter {
      * @param role - The role assigned to the user
      */
     emitWorkspaceUserAdded(userId: string, workspace: IWorkspace, role: string): Promise<void>;
+    /** An invitation was sent from this client. */
+    emitWorkspaceInvitationSent(invitation: IWorkspaceInvitation, workspaceId: string): Promise<void>;
+    /** The signed-in user accepted an invitation and joined `workspace`. */
+    emitWorkspaceInvitationAccepted(invitation: IWorkspaceInvitation, workspace: IWorkspace): Promise<void>;
+    /** The signed-in user declined an invitation. */
+    emitWorkspaceInvitationDeclined(invitation: IWorkspaceInvitation): Promise<void>;
+    /** A pending invitation was withdrawn from this client. */
+    emitWorkspaceInvitationRevoked(invitationId: string, workspaceId: string): Promise<void>;
     /**
      * Trigger workspace user removed event
      * @param userId - The ID of the user that was removed
@@ -2464,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';
     };
@@ -2504,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.
@@ -2848,6 +3204,60 @@ interface SDKMessages {
         memberLimitMessage: string;
         selectRole: string;
         inviteAs: string;
+        invitations: {
+            title: string;
+            pendingCount: string;
+            sent: string;
+            resend: string;
+            resendIn: string;
+            revoke: string;
+            /** Title of the revoke confirmation. */
+            revokeTitle: string;
+            revokeConfirm: string;
+            sentAt: string;
+            expiresAt: string;
+            seatNote: string;
+            formerMember: string;
+            loadFailed: string;
+            resendFailed: string;
+            revokeFailed: string;
+            status: {
+                invited: string;
+                accepted: string;
+                rejected: string;
+                expired: string;
+            };
+        };
+    };
+    invitations: {
+        title: string;
+        description: string;
+        /** The list of the caller's own invitations, above the rows. */
+        listDescription: string;
+        /** Dialog title once the invitee has joined. */
+        titleJoined: string;
+        /** Dialog title for a link that can no longer be used: revoked, expired, switched off. */
+        titleUnavailable: string;
+        sentTo: string;
+        invitedAs: string;
+        accept: string;
+        decline: string;
+        accepted: string;
+        declined: string;
+        expired: string;
+        revoked: string;
+        alreadyAccepted: string;
+        wrongAccount: string;
+        verifyFirst: string;
+        workspaceFull: string;
+        disabled: string;
+        empty: string;
+        signInToAccept: string;
+        dismiss: string;
+        signOut: string;
+        loadFailed: string;
+        acceptFailed: string;
+        declineFailed: string;
     };
     invoices: {
         title: string;
@@ -2961,6 +3371,28 @@ interface SDKMessages {
         failedToDelete: string;
     };
     notifications: {
+        inbox: {
+            title: string;
+            description: string;
+            bellLabel: string;
+            bellUnread: string;
+            filterAll: string;
+            filterUnread: string;
+            markAllRead: string;
+            markRead: string;
+            markUnread: string;
+            archive: string;
+            loadMore: string;
+            empty: string;
+            emptyUnread: string;
+            loadFailed: string;
+            updateFailed: string;
+            channelEmail: string;
+            channelPush: string;
+            opened: string;
+            clicked: string;
+            notDelivered: string;
+        };
         title: string;
         permissionDenied: string;
         notSupported: string;
@@ -2978,6 +3410,13 @@ interface SDKMessages {
         pushDescription: string;
         deviceNote: string;
         prefsSaved: string;
+        prefsSaveFailed: string;
+        yourTitle: string;
+        yourDescription: string;
+        defaultsTitle: string;
+        defaultsDescription: string;
+        requiredLabel: string;
+        requiredHint: string;
         loadingPrefs: string;
         categories: {
             workspace: string;
@@ -3235,6 +3674,97 @@ type Level4 = {
 /** Union of all valid translation key paths (e.g. "settings.titles.profile") */
 type TranslationKey = Level2 | Level3 | Level4;
 
+/**
+ * The error an invitation call throws. A plain `Error` (so every existing
+ * `catch (err) { err.message }` keeps working) carrying the server's fields
+ * as properties, so a screen can act on the shape of the refusal: open the
+ * plan picker on a seat limit, count down a resend cooldown, show which
+ * address the invitation was for.
+ */
+declare const INVITATION_ERROR_CODE: {
+    readonly NOT_FOUND: "INVITATION_NOT_FOUND";
+    readonly EXPIRED: "INVITATION_EXPIRED";
+    readonly ALREADY_HANDLED: "INVITATION_ALREADY_HANDLED";
+    readonly EMAIL_MISMATCH: "INVITATION_EMAIL_MISMATCH";
+    readonly EMAIL_NOT_VERIFIED: "EMAIL_NOT_VERIFIED";
+    readonly INVITES_DISABLED: "WORKSPACE_INVITES_DISABLED";
+    readonly RATE_LIMITED: "INVITATION_RATE_LIMITED";
+    readonly EMAIL_FAILED: "INVITATION_EMAIL_FAILED";
+    readonly SEAT_LIMIT: "SEAT_LIMIT_REACHED";
+    /** The invited or accepting account is blocked. */
+    readonly USER_BLOCKED: "USER_BLOCKED";
+    /**
+     * The organization has no usable email sender, so no invitation can be sent.
+     *
+     * This one is refused by the server's `requireEmailSender` middleware rather
+     * than by the invitation route, so the string is that middleware's
+     * (`EMAIL_SENDER_CODE.NO_SENDER_CONFIGURED`), not an invitation code. Named
+     * after it on purpose: the value is what arrives, and a prettier alias here
+     * would simply never match.
+     */
+    readonly NO_SENDER_CONFIGURED: "NO_SENDER_CONFIGURED";
+};
+type InvitationErrorCode = (typeof INVITATION_ERROR_CODE)[keyof typeof INVITATION_ERROR_CODE];
+interface InvitationErrorFields {
+    /** The HTTP status the server answered with. */
+    status: number;
+    /** A stable code, from the body when the server sent one, else derived from the status. */
+    code: string;
+    /** On a 402: members plus pending invitations, and the ceiling they hit. */
+    currentUserCount?: number;
+    limit?: number;
+    /** On a resend's 429: seconds until the cooldown ends. */
+    retryAfterSeconds?: number;
+    /** On an email mismatch: the invited address, scrambled. */
+    invitedEmail?: string;
+    /** On "already invited": the live invitation, so the caller can offer resend. */
+    invitationId?: string;
+    /** On "already handled": the row's status. */
+    invitationStatus?: string;
+}
+type InvitationError = Error & InvitationErrorFields;
+/** True when an unknown thrown value is an invitation error carrying a status. */
+declare function isInvitationError(err: unknown): err is InvitationError;
+
+/**
+ * The admin's ordering: pending first, then newest first within a status. An
+ * admin should see what lapsed, so nothing is dropped here.
+ */
+declare function sortInvitations(rows: IWorkspaceInvitation[]): IWorkspaceInvitation[];
+/** Pending and not past its expiry: something the invitee can still accept or decline. */
+declare function isInvitationActionable(row: IWorkspaceInvitation, now?: Date): boolean;
+/**
+ * The invitee's list: "a list of things you can act on should contain only
+ * things you can act on". The server already filters, this keeps a stale
+ * client list honest between refreshes.
+ */
+declare function actionableInvitations(rows: IWorkspaceInvitation[], now?: Date): IWorkspaceInvitation[];
+/** Pending, past its expiry, not yet swept: shown as expired by the admin's list. */
+declare function isInvitationLapsed(row: IWorkspaceInvitation, now?: Date): boolean;
+declare function workspaceNameOf(row: IWorkspaceInvitation): string;
+declare function workspaceIdOf(row: IWorkspaceInvitation): string;
+/** The inviter's display name, or null when their account is gone. */
+declare function inviterNameOf(row: IWorkspaceInvitation): string | null;
+/**
+ * Seconds until a row may be resent, zero when it may. The cooldown itself is
+ * the server's rule and stays there: this counts down to the `resendAvailableAt`
+ * the server puts on every pending row, so the button cannot unlock a second
+ * before the endpoint stops answering 429. A row without the field (a server
+ * older than it) reports zero, leaving that 429 as the only authority.
+ */
+declare function resendCooldownSeconds(row: IWorkspaceInvitation, now?: Date): number;
+
+/** Park a token for `orgId`. A malformed token is ignored rather than stored. */
+declare function parkPendingInvite(token: string, orgId: string): void;
+/**
+ * The parked token for `orgId`, or null when there is none, it is older than a
+ * day, or it belongs to another org. Does not clear: the flow clears it on a
+ * terminal answer (accepted, declined, expired, handled), never on a network
+ * error, so a retry stays possible.
+ */
+declare function readPendingInvite(orgId: string, now?: number): string | null;
+declare function clearPendingInvite(): void;
+
 /**
  * Verify that a webhook request came from BuildBase.
  *
@@ -4187,9 +4717,25 @@ 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[]>;
+    /**
+     * Add an EXISTING account to the workspace at once. Answers 404 when the
+     * address has no account. To reach someone with no account, send an
+     * invitation with `invitations.create`.
+     */
     invite(workspaceId: string, email: string, role: string): Promise<{
         userId: string;
         workspace: IWorkspace;
@@ -4338,9 +4884,38 @@ interface CreditActions {
     getPublicPackages(): Promise<IPublicCreditPackagesResponse>;
 }
 /** All action modules bound to a specific session. Returned by `withSession()`. */
+/**
+ * Workspace invitations: reach an address that may have no account. A
+ * pending invitation bills a seat until accepted, declined, revoked or
+ * expired. The accept and decline side belongs to the invitee's own session,
+ * so it lives on the client (`useMyInvitations`, `<PendingInvitations />`).
+ */
+interface InvitationActions {
+    /** The workspace's invitations, pending first. */
+    list(workspaceId: string): Promise<IWorkspaceInvitation[]>;
+    /**
+     * Invite an email address. `landingUrl` is where the emailed link lands;
+     * left out, the first allowed redirect URL of the auth client the session
+     * signed in through. A session minted from an API token has no client, so
+     * pass it: one of the allowed redirect URLs of an auth client in the org.
+     */
+    create(workspaceId: string, email: string, role: string, landingUrl?: string): Promise<IWorkspaceInvitation & {
+        message: string;
+    }>;
+    /** Send it again (five-minute cooldown). Revives an expired invitation. */
+    resend(workspaceId: string, invitationId: string): Promise<IWorkspaceInvitation & {
+        message: string;
+    }>;
+    /** Withdraw a pending invitation. */
+    revoke(workspaceId: string, invitationId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
 interface ScopedActions {
     workspace: WorkspaceActions;
     users: UserActions;
+    invitations: InvitationActions;
     subscription: SubscriptionActions;
     plans: PlanActions;
     invoices: InvoiceActions;
@@ -4602,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, 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 };
-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 };
+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 };