@xenide-io/suite-client 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { ConfigDefaults } from 'posthog-js';
+
 declare const ERROR_CODES: {
     readonly AUTH_001: "E-AUTH-001";
     readonly AUTH_002: "E-AUTH-002";
@@ -45,9 +47,54 @@ declare function normalizeThrown(input: unknown, capability?: string): AppError;
 /** Display string for a failure surface: capability copy plus the code. */
 declare function formatAppError(error: AppError): string;
 
+/**
+ * Global super-properties and event properties accepted by the analytics client.
+ * Values may be `null` to clear a previously registered super-property.
+ */
+type AnalyticsProperties = Record<string, unknown>;
+/** Headers forwarded on every API request so server events share the web identity. */
+type AnalyticsContextHeaders = Record<string, string>;
+interface AnalyticsClientConfig {
+    /** `NEXT_PUBLIC_POSTHOG_KEY`. A missing key makes the client a no-op. */
+    apiKey?: string;
+    /** `NEXT_PUBLIC_POSTHOG_HOST`, e.g. `https://us.i.posthog.com`. */
+    host?: string;
+    /** Global `app` super-property, e.g. `turtletime`. */
+    app: string;
+    /** Global `environment` super-property; defaults to `NODE_ENV`. */
+    environment?: string;
+    /** PostHog config defaults date. Defaults to `2026-05-30`. */
+    defaults?: ConfigDefaults;
+}
+type AnalyticsClient = ReturnType<typeof createAnalyticsClient>;
+/** Domain half of an email — safe to send; the raw address is not. */
+declare function emailDomain(email: string | null | undefined): string | undefined;
+/**
+ * Browser analytics client shared across ShellStack apps.
+ *
+ * Wraps `posthog-js` so every app initialises the same way, registers the same
+ * global super-properties, and forwards the browser identity/session ids to the
+ * API. The SDK keeps PostHog's defaults (autocapture, pageviews, UTM, browser/OS,
+ * referrer) — nothing here disables them.
+ */
+declare function createAnalyticsClient(config: AnalyticsClientConfig): {
+    init: () => void;
+    identify: (userId: string, props?: AnalyticsProperties, setOnceProps?: AnalyticsProperties) => void;
+    group: (groupType: string, groupKey: string, props?: AnalyticsProperties) => void;
+    capture: (event: string, props?: AnalyticsProperties) => void;
+    reset: () => void;
+    getDistinctId: () => string | undefined;
+    getSessionId: () => string | undefined;
+    pageview: () => void;
+    registerSuperProperties: (props: AnalyticsProperties) => void;
+    getContextHeaders: () => AnalyticsContextHeaders;
+};
+
 type ApiFetchInit = RequestInit & {
     skipAuth?: boolean;
 };
+/** Optional analytics sink forwarded client lifecycle events (e.g. `analytics.capture`). */
+type ApiAnalyticsEventSink = (event: string, properties?: Record<string, unknown>) => void;
 interface ApiClientConfig {
     /** localStorage key namespace, e.g. `tt` or `tides`. */
     storagePrefix: string;
@@ -74,6 +121,18 @@ interface ApiClientConfig {
     sessionStorageClearPrefixes?: string[];
     /** Refuse to send the session to an unexpected absolute origin. */
     enforceSameOrigin?: boolean;
+    /**
+     * Extra headers to attach to every request. Used to forward the PostHog
+     * identity/session ids (`X-POSTHOG-DISTINCT-ID` / `X-POSTHOG-SESSION-ID`)
+     * so server-side events share the browser identity. Empty values are dropped.
+     */
+    getContextHeaders?: () => Record<string, string>;
+    /**
+     * Forward client lifecycle events (`Session Expired`, `Workspace Switched`,
+     * `User Logged Out`) to the app's analytics client. Kept as a plain callback
+     * so this package never imports an analytics implementation.
+     */
+    onAnalyticsEvent?: ApiAnalyticsEventSink;
 }
 /**
  * Build a browser API client scoped to one ShellStack app. Every app shares the
@@ -92,7 +151,9 @@ declare function createApiClient(config: ApiClientConfig): {
     }) => void;
     getActiveWorkspaceId: () => string | null;
     restoreWorkspace: () => void;
-    clearAuth: () => void;
+    clearAuth: (options?: {
+        origin?: "user" | "session_expired";
+    }) => void;
     restoreTokens: () => void;
     refreshAccessToken: () => Promise<boolean>;
     parseApiError: (res: Response) => Promise<string>;
@@ -104,7 +165,9 @@ declare function createApiClient(config: ApiClientConfig): {
         delete: (path: string, init?: ApiFetchInit) => Promise<Response>;
     };
     restoreSession: () => void;
-    clearSession: () => void;
+    clearSession: (options?: {
+        origin?: "user" | "session_expired";
+    }) => void;
 };
 type ApiClient = ReturnType<typeof createApiClient>;
 type Api = ApiClient['api'];
@@ -117,6 +180,8 @@ interface AuthReturnPathConfig {
     defaultNext?: string;
     portalCallbackPath?: string;
     redeemPath?: string;
+    /** Forward the completed cross-app switch to the app's analytics client. */
+    onAnalyticsEvent?: (event: string, properties?: Record<string, unknown>) => void;
 }
 interface PortalHandoffPayload {
     code?: string;
@@ -262,6 +327,88 @@ declare function createWorkspaceAppearanceApi(config: WorkspaceAppearanceApiConf
     cacheWorkspaceAppearanceLocally: (appearance: WorkspaceAppearance) => void;
 };
 
+/** How long a persisted read-model snapshot may be shown after a reload. */
+declare const SUITE_QUERY_CACHE_MAX_AGE_MS: number;
+type QueryKeyPart = string | readonly string[];
+interface PersistableQuery {
+    queryKey: readonly unknown[];
+    state: {
+        status: string;
+        data: unknown;
+    };
+}
+interface PersistableQueryClient {
+    getQueryCache(): {
+        getAll(): PersistableQuery[];
+        subscribe(listener: () => void): () => void;
+    };
+    setQueryData(queryKey: readonly unknown[], data: unknown): unknown;
+    invalidateQueries(filters: {
+        queryKey: readonly unknown[];
+        refetchType: 'none';
+    }): Promise<unknown>;
+}
+interface PersistSuiteQueriesOptions {
+    /** localStorage key, including a version. */
+    storageKey: string;
+    /** Access-token localStorage key. The JWT `sub` is the user half of the buster. */
+    tokenKey: string;
+    /** Active workspace localStorage key. */
+    workspaceKey: string;
+    /**
+     * Query keys to keep. A string matches `queryKey[0]`. A list matches a prefix,
+     * so `['tt', 'tracker-catalog']` does not keep `['tt', 'time-entries']`.
+     */
+    allow: readonly QueryKeyPart[];
+    maxAgeMs?: number;
+}
+/**
+ * User and workspace identity for a snapshot. Empty when the tab is signed out,
+ * which refuses both restore and write.
+ */
+declare function suiteCacheBuster(tokenKey: string, workspaceKey: string): string;
+declare function readJsonSnapshot<T>(key: string, buster: string, maxAgeMs: number): T | null;
+declare function writeJsonSnapshot(key: string, buster: string, value: unknown): void;
+/**
+ * Restore an allow-listed query cache, then keep writing it. Restored queries
+ * are marked stale so the next mount refetches without hiding the snapshot.
+ * Returns an unsubscribe.
+ */
+declare function persistSuiteQueries(queryClient: PersistableQueryClient, options: PersistSuiteQueriesOptions): () => void;
+/** Per-app browser cache. Live operational keys are intentionally absent. */
+declare const SUITE_APP_QUERY_CACHES: {
+    readonly kraken: {
+        readonly storageKey: "kraken-query-cache:v1";
+        readonly tokenKey: "kraken_access_token";
+        readonly workspaceKey: "kraken_active_workspace_id";
+        readonly allow: readonly ["kraken-sidebar"];
+    };
+    readonly shellstack: {
+        readonly storageKey: "shellstack-query-cache:v1";
+        readonly tokenKey: "portal_access_token";
+        readonly workspaceKey: "portal_active_workspace_id";
+        readonly allow: readonly ["calendar-events", "org-workspaces", "organisation", "org-team", "directory"];
+    };
+    readonly tides: {
+        readonly storageKey: "tides-query-cache:v1";
+        readonly tokenKey: "tides_access_token";
+        readonly workspaceKey: "tides_active_workspace_id";
+        readonly allow: readonly [readonly ["tides", "projects"], readonly ["tides", "clients"], readonly ["tides", "workspace-members"], readonly ["tides", "workspace-tags"], readonly ["tides", "project-statuses"]];
+    };
+    readonly turtletime: {
+        readonly storageKey: "tt-query-cache:v1";
+        readonly tokenKey: "tt_access_token";
+        readonly workspaceKey: "tt_active_workspace_id";
+        readonly allow: readonly [readonly ["tt", "tracker-catalog"], readonly ["tt", "projects"], readonly ["tt", "clients"], readonly ["tt", "categories"]];
+    };
+    readonly shelly: {
+        readonly storageKey: "shelly-query-cache:v1";
+        readonly tokenKey: "shelly_access_token";
+        readonly workspaceKey: "shelly_active_workspace_id";
+        readonly allow: readonly [readonly ["shelly", "skills"], readonly ["shelly", "crews"], readonly ["shelly", "mcp-servers"], readonly ["shelly", "models"]];
+    };
+};
+
 type CrossAppSyncTopic = 'time' | 'integration' | 'tasks';
 interface CrossAppSyncConfig {
     api: Api;
@@ -296,6 +443,37 @@ declare function createLiveRefresh(sync: CrossAppSync): {
     hasPendingCrossAppSync: (topic: CrossAppSyncTopic | undefined, since: number) => boolean;
 };
 
+interface SuiteRevisionMap {
+    documents: number;
+    calendar: number;
+    notifications: number;
+    tasks: number;
+    time: number;
+    catalogue: number;
+}
+/**
+ * First successful poll is the baseline and refreshes nothing. Later polls
+ * report only topics whose integer moved, so unchanged lists are not refetched.
+ */
+declare function nextRevisionTick(seen: Record<string, number>, ready: boolean, data: Partial<SuiteRevisionMap> | null): {
+    seen: Record<string, number>;
+    ready: boolean;
+    changed: string[];
+};
+/**
+ * Poll workspace revisions and report topics whose integer moved.
+ * The first successful read is the baseline, so a reload does not refetch
+ * everything the snapshot already painted.
+ */
+declare function useSuiteRevisions(options: {
+    enabled: boolean;
+    /** Workspace (or other) id. Changing it refetches, so the previous workspace cannot stay on screen. */
+    scope?: string;
+    load: () => Promise<Partial<SuiteRevisionMap> | null>;
+    onTopic: (topic: string) => void;
+    pollMs?: number;
+}): void;
+
 /** Cross-app (suite) notification from `/api/notifications/` — shared across ShellStack apps. */
 interface SuiteNotification {
     id: string;
@@ -356,6 +534,18 @@ declare function createWebPushClient(config: WebPushClientConfig): {
     disable: () => Promise<void>;
 };
 
+interface EmailNotificationPreference {
+    enabled: boolean;
+    busy: boolean;
+    error: string;
+    onChange: (enabled: boolean) => void;
+}
+/**
+ * Loads and saves the signed-in person's email notification preference.
+ * The preference is shared across suite apps.
+ */
+declare function useEmailNotificationPreference(api: Api, parseApiError: (res: Response) => Promise<string>): EmailNotificationPreference;
+
 type SuiteAiJobEvent = {
     sequence: number;
     event_type: 'queued' | 'started' | 'progress' | 'tool' | 'completed' | 'failed' | 'cancelled';
@@ -416,4 +606,4 @@ declare function createJsonLd(config: JsonLdConfig): string;
 
 declare function useIsNight(): boolean;
 
-export { type Api, type ApiClient, type ApiClientConfig, type ApiFetchInit, type AppError, type AuthReturnPath, type AuthReturnPathConfig, type BrandSettings, type BrandSettingsConfig, type CrossAppSync, type CrossAppSyncConfig, type CrossAppSyncTopic, DEFAULT_ERROR_CODE, ERROR_CODES, ERROR_COPY, ERROR_RETRYABLE, type ErrorCode, FREE_PLAN_SEAT_HELP, type JsonLdConfig, type LiveRefresh, type LiveRefreshOptions, type NotificationsClient, type NotificationsClientConfig, ORGANISATION_SEAT_HELP, type PortalHandoffPayload, type PortalHandoffRead, type SeatType, type SubscriptionTier, type SuiteAiJob, type SuiteAiJobEvent, type SuiteNotification, type SuiteNotificationsResponse, TIDES_ACCESS_HELP, TURTLETIME_ACCESS_HELP, WEBHOOK_ACTIVITY_ACTIONS, WORKSPACE_SEAT_HELP, type WebPushClient, type WebPushClientConfig, type WebPushConfig, type WebPushState, type WorkspaceAppearance, type WorkspaceAppearanceApiConfig, type WorkspaceAppearanceConfig, WorkspaceAppearanceError, type WorkspaceAppearanceHelpers, type WorkspaceAppearancePatch, type WorkspaceBrandPayload, type WorkspaceSubscription, type WorkspaceTheme, activeSuiteAiJobs, appErrorFromResponse, canDisableAppAccess, codeForStatus, copyFor, createApiClient, createAuthReturnPath, createBrandSettings, createCrossAppSync, createJsonLd, createLiveRefresh, createNotificationsClient, createWebPushClient, createWorkspaceAppearance, createWorkspaceAppearanceApi, defaultInviteSeatType, flagsFromSeatType, formatAppError, hasAppAccess, isErrorCode, normalizeError, normalizeThrown, planSeatSummary, resolveSubscriptionTier, seatTypeDescription, seatTypeFromFlags, seatTypeLabel, selectedToWebhookActions, sortedSuiteAiEvents, suiteAiEventSummary, tierAllowsTidesOnlySeats, tierAllowsTurtletime, tierLabel, useIsNight, webhookActionsToSelected };
+export { type AnalyticsClient, type AnalyticsClientConfig, type AnalyticsContextHeaders, type AnalyticsProperties, type Api, type ApiAnalyticsEventSink, type ApiClient, type ApiClientConfig, type ApiFetchInit, type AppError, type AuthReturnPath, type AuthReturnPathConfig, type BrandSettings, type BrandSettingsConfig, type CrossAppSync, type CrossAppSyncConfig, type CrossAppSyncTopic, DEFAULT_ERROR_CODE, ERROR_CODES, ERROR_COPY, ERROR_RETRYABLE, type EmailNotificationPreference, type ErrorCode, FREE_PLAN_SEAT_HELP, type JsonLdConfig, type LiveRefresh, type LiveRefreshOptions, type NotificationsClient, type NotificationsClientConfig, ORGANISATION_SEAT_HELP, type PersistSuiteQueriesOptions, type PersistableQuery, type PersistableQueryClient, type PortalHandoffPayload, type PortalHandoffRead, type QueryKeyPart, SUITE_APP_QUERY_CACHES, SUITE_QUERY_CACHE_MAX_AGE_MS, type SeatType, type SubscriptionTier, type SuiteAiJob, type SuiteAiJobEvent, type SuiteNotification, type SuiteNotificationsResponse, type SuiteRevisionMap, TIDES_ACCESS_HELP, TURTLETIME_ACCESS_HELP, WEBHOOK_ACTIVITY_ACTIONS, WORKSPACE_SEAT_HELP, type WebPushClient, type WebPushClientConfig, type WebPushConfig, type WebPushState, type WorkspaceAppearance, type WorkspaceAppearanceApiConfig, type WorkspaceAppearanceConfig, WorkspaceAppearanceError, type WorkspaceAppearanceHelpers, type WorkspaceAppearancePatch, type WorkspaceBrandPayload, type WorkspaceSubscription, type WorkspaceTheme, activeSuiteAiJobs, appErrorFromResponse, canDisableAppAccess, codeForStatus, copyFor, createAnalyticsClient, createApiClient, createAuthReturnPath, createBrandSettings, createCrossAppSync, createJsonLd, createLiveRefresh, createNotificationsClient, createWebPushClient, createWorkspaceAppearance, createWorkspaceAppearanceApi, defaultInviteSeatType, emailDomain, flagsFromSeatType, formatAppError, hasAppAccess, isErrorCode, nextRevisionTick, normalizeError, normalizeThrown, persistSuiteQueries, planSeatSummary, readJsonSnapshot, resolveSubscriptionTier, seatTypeDescription, seatTypeFromFlags, seatTypeLabel, selectedToWebhookActions, sortedSuiteAiEvents, suiteAiEventSummary, suiteCacheBuster, tierAllowsTidesOnlySeats, tierAllowsTurtletime, tierLabel, useEmailNotificationPreference, useIsNight, useSuiteRevisions, webhookActionsToSelected, writeJsonSnapshot };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { ConfigDefaults } from 'posthog-js';
+
 declare const ERROR_CODES: {
     readonly AUTH_001: "E-AUTH-001";
     readonly AUTH_002: "E-AUTH-002";
@@ -45,9 +47,54 @@ declare function normalizeThrown(input: unknown, capability?: string): AppError;
 /** Display string for a failure surface: capability copy plus the code. */
 declare function formatAppError(error: AppError): string;
 
+/**
+ * Global super-properties and event properties accepted by the analytics client.
+ * Values may be `null` to clear a previously registered super-property.
+ */
+type AnalyticsProperties = Record<string, unknown>;
+/** Headers forwarded on every API request so server events share the web identity. */
+type AnalyticsContextHeaders = Record<string, string>;
+interface AnalyticsClientConfig {
+    /** `NEXT_PUBLIC_POSTHOG_KEY`. A missing key makes the client a no-op. */
+    apiKey?: string;
+    /** `NEXT_PUBLIC_POSTHOG_HOST`, e.g. `https://us.i.posthog.com`. */
+    host?: string;
+    /** Global `app` super-property, e.g. `turtletime`. */
+    app: string;
+    /** Global `environment` super-property; defaults to `NODE_ENV`. */
+    environment?: string;
+    /** PostHog config defaults date. Defaults to `2026-05-30`. */
+    defaults?: ConfigDefaults;
+}
+type AnalyticsClient = ReturnType<typeof createAnalyticsClient>;
+/** Domain half of an email — safe to send; the raw address is not. */
+declare function emailDomain(email: string | null | undefined): string | undefined;
+/**
+ * Browser analytics client shared across ShellStack apps.
+ *
+ * Wraps `posthog-js` so every app initialises the same way, registers the same
+ * global super-properties, and forwards the browser identity/session ids to the
+ * API. The SDK keeps PostHog's defaults (autocapture, pageviews, UTM, browser/OS,
+ * referrer) — nothing here disables them.
+ */
+declare function createAnalyticsClient(config: AnalyticsClientConfig): {
+    init: () => void;
+    identify: (userId: string, props?: AnalyticsProperties, setOnceProps?: AnalyticsProperties) => void;
+    group: (groupType: string, groupKey: string, props?: AnalyticsProperties) => void;
+    capture: (event: string, props?: AnalyticsProperties) => void;
+    reset: () => void;
+    getDistinctId: () => string | undefined;
+    getSessionId: () => string | undefined;
+    pageview: () => void;
+    registerSuperProperties: (props: AnalyticsProperties) => void;
+    getContextHeaders: () => AnalyticsContextHeaders;
+};
+
 type ApiFetchInit = RequestInit & {
     skipAuth?: boolean;
 };
+/** Optional analytics sink forwarded client lifecycle events (e.g. `analytics.capture`). */
+type ApiAnalyticsEventSink = (event: string, properties?: Record<string, unknown>) => void;
 interface ApiClientConfig {
     /** localStorage key namespace, e.g. `tt` or `tides`. */
     storagePrefix: string;
@@ -74,6 +121,18 @@ interface ApiClientConfig {
     sessionStorageClearPrefixes?: string[];
     /** Refuse to send the session to an unexpected absolute origin. */
     enforceSameOrigin?: boolean;
+    /**
+     * Extra headers to attach to every request. Used to forward the PostHog
+     * identity/session ids (`X-POSTHOG-DISTINCT-ID` / `X-POSTHOG-SESSION-ID`)
+     * so server-side events share the browser identity. Empty values are dropped.
+     */
+    getContextHeaders?: () => Record<string, string>;
+    /**
+     * Forward client lifecycle events (`Session Expired`, `Workspace Switched`,
+     * `User Logged Out`) to the app's analytics client. Kept as a plain callback
+     * so this package never imports an analytics implementation.
+     */
+    onAnalyticsEvent?: ApiAnalyticsEventSink;
 }
 /**
  * Build a browser API client scoped to one ShellStack app. Every app shares the
@@ -92,7 +151,9 @@ declare function createApiClient(config: ApiClientConfig): {
     }) => void;
     getActiveWorkspaceId: () => string | null;
     restoreWorkspace: () => void;
-    clearAuth: () => void;
+    clearAuth: (options?: {
+        origin?: "user" | "session_expired";
+    }) => void;
     restoreTokens: () => void;
     refreshAccessToken: () => Promise<boolean>;
     parseApiError: (res: Response) => Promise<string>;
@@ -104,7 +165,9 @@ declare function createApiClient(config: ApiClientConfig): {
         delete: (path: string, init?: ApiFetchInit) => Promise<Response>;
     };
     restoreSession: () => void;
-    clearSession: () => void;
+    clearSession: (options?: {
+        origin?: "user" | "session_expired";
+    }) => void;
 };
 type ApiClient = ReturnType<typeof createApiClient>;
 type Api = ApiClient['api'];
@@ -117,6 +180,8 @@ interface AuthReturnPathConfig {
     defaultNext?: string;
     portalCallbackPath?: string;
     redeemPath?: string;
+    /** Forward the completed cross-app switch to the app's analytics client. */
+    onAnalyticsEvent?: (event: string, properties?: Record<string, unknown>) => void;
 }
 interface PortalHandoffPayload {
     code?: string;
@@ -262,6 +327,88 @@ declare function createWorkspaceAppearanceApi(config: WorkspaceAppearanceApiConf
     cacheWorkspaceAppearanceLocally: (appearance: WorkspaceAppearance) => void;
 };
 
+/** How long a persisted read-model snapshot may be shown after a reload. */
+declare const SUITE_QUERY_CACHE_MAX_AGE_MS: number;
+type QueryKeyPart = string | readonly string[];
+interface PersistableQuery {
+    queryKey: readonly unknown[];
+    state: {
+        status: string;
+        data: unknown;
+    };
+}
+interface PersistableQueryClient {
+    getQueryCache(): {
+        getAll(): PersistableQuery[];
+        subscribe(listener: () => void): () => void;
+    };
+    setQueryData(queryKey: readonly unknown[], data: unknown): unknown;
+    invalidateQueries(filters: {
+        queryKey: readonly unknown[];
+        refetchType: 'none';
+    }): Promise<unknown>;
+}
+interface PersistSuiteQueriesOptions {
+    /** localStorage key, including a version. */
+    storageKey: string;
+    /** Access-token localStorage key. The JWT `sub` is the user half of the buster. */
+    tokenKey: string;
+    /** Active workspace localStorage key. */
+    workspaceKey: string;
+    /**
+     * Query keys to keep. A string matches `queryKey[0]`. A list matches a prefix,
+     * so `['tt', 'tracker-catalog']` does not keep `['tt', 'time-entries']`.
+     */
+    allow: readonly QueryKeyPart[];
+    maxAgeMs?: number;
+}
+/**
+ * User and workspace identity for a snapshot. Empty when the tab is signed out,
+ * which refuses both restore and write.
+ */
+declare function suiteCacheBuster(tokenKey: string, workspaceKey: string): string;
+declare function readJsonSnapshot<T>(key: string, buster: string, maxAgeMs: number): T | null;
+declare function writeJsonSnapshot(key: string, buster: string, value: unknown): void;
+/**
+ * Restore an allow-listed query cache, then keep writing it. Restored queries
+ * are marked stale so the next mount refetches without hiding the snapshot.
+ * Returns an unsubscribe.
+ */
+declare function persistSuiteQueries(queryClient: PersistableQueryClient, options: PersistSuiteQueriesOptions): () => void;
+/** Per-app browser cache. Live operational keys are intentionally absent. */
+declare const SUITE_APP_QUERY_CACHES: {
+    readonly kraken: {
+        readonly storageKey: "kraken-query-cache:v1";
+        readonly tokenKey: "kraken_access_token";
+        readonly workspaceKey: "kraken_active_workspace_id";
+        readonly allow: readonly ["kraken-sidebar"];
+    };
+    readonly shellstack: {
+        readonly storageKey: "shellstack-query-cache:v1";
+        readonly tokenKey: "portal_access_token";
+        readonly workspaceKey: "portal_active_workspace_id";
+        readonly allow: readonly ["calendar-events", "org-workspaces", "organisation", "org-team", "directory"];
+    };
+    readonly tides: {
+        readonly storageKey: "tides-query-cache:v1";
+        readonly tokenKey: "tides_access_token";
+        readonly workspaceKey: "tides_active_workspace_id";
+        readonly allow: readonly [readonly ["tides", "projects"], readonly ["tides", "clients"], readonly ["tides", "workspace-members"], readonly ["tides", "workspace-tags"], readonly ["tides", "project-statuses"]];
+    };
+    readonly turtletime: {
+        readonly storageKey: "tt-query-cache:v1";
+        readonly tokenKey: "tt_access_token";
+        readonly workspaceKey: "tt_active_workspace_id";
+        readonly allow: readonly [readonly ["tt", "tracker-catalog"], readonly ["tt", "projects"], readonly ["tt", "clients"], readonly ["tt", "categories"]];
+    };
+    readonly shelly: {
+        readonly storageKey: "shelly-query-cache:v1";
+        readonly tokenKey: "shelly_access_token";
+        readonly workspaceKey: "shelly_active_workspace_id";
+        readonly allow: readonly [readonly ["shelly", "skills"], readonly ["shelly", "crews"], readonly ["shelly", "mcp-servers"], readonly ["shelly", "models"]];
+    };
+};
+
 type CrossAppSyncTopic = 'time' | 'integration' | 'tasks';
 interface CrossAppSyncConfig {
     api: Api;
@@ -296,6 +443,37 @@ declare function createLiveRefresh(sync: CrossAppSync): {
     hasPendingCrossAppSync: (topic: CrossAppSyncTopic | undefined, since: number) => boolean;
 };
 
+interface SuiteRevisionMap {
+    documents: number;
+    calendar: number;
+    notifications: number;
+    tasks: number;
+    time: number;
+    catalogue: number;
+}
+/**
+ * First successful poll is the baseline and refreshes nothing. Later polls
+ * report only topics whose integer moved, so unchanged lists are not refetched.
+ */
+declare function nextRevisionTick(seen: Record<string, number>, ready: boolean, data: Partial<SuiteRevisionMap> | null): {
+    seen: Record<string, number>;
+    ready: boolean;
+    changed: string[];
+};
+/**
+ * Poll workspace revisions and report topics whose integer moved.
+ * The first successful read is the baseline, so a reload does not refetch
+ * everything the snapshot already painted.
+ */
+declare function useSuiteRevisions(options: {
+    enabled: boolean;
+    /** Workspace (or other) id. Changing it refetches, so the previous workspace cannot stay on screen. */
+    scope?: string;
+    load: () => Promise<Partial<SuiteRevisionMap> | null>;
+    onTopic: (topic: string) => void;
+    pollMs?: number;
+}): void;
+
 /** Cross-app (suite) notification from `/api/notifications/` — shared across ShellStack apps. */
 interface SuiteNotification {
     id: string;
@@ -356,6 +534,18 @@ declare function createWebPushClient(config: WebPushClientConfig): {
     disable: () => Promise<void>;
 };
 
+interface EmailNotificationPreference {
+    enabled: boolean;
+    busy: boolean;
+    error: string;
+    onChange: (enabled: boolean) => void;
+}
+/**
+ * Loads and saves the signed-in person's email notification preference.
+ * The preference is shared across suite apps.
+ */
+declare function useEmailNotificationPreference(api: Api, parseApiError: (res: Response) => Promise<string>): EmailNotificationPreference;
+
 type SuiteAiJobEvent = {
     sequence: number;
     event_type: 'queued' | 'started' | 'progress' | 'tool' | 'completed' | 'failed' | 'cancelled';
@@ -416,4 +606,4 @@ declare function createJsonLd(config: JsonLdConfig): string;
 
 declare function useIsNight(): boolean;
 
-export { type Api, type ApiClient, type ApiClientConfig, type ApiFetchInit, type AppError, type AuthReturnPath, type AuthReturnPathConfig, type BrandSettings, type BrandSettingsConfig, type CrossAppSync, type CrossAppSyncConfig, type CrossAppSyncTopic, DEFAULT_ERROR_CODE, ERROR_CODES, ERROR_COPY, ERROR_RETRYABLE, type ErrorCode, FREE_PLAN_SEAT_HELP, type JsonLdConfig, type LiveRefresh, type LiveRefreshOptions, type NotificationsClient, type NotificationsClientConfig, ORGANISATION_SEAT_HELP, type PortalHandoffPayload, type PortalHandoffRead, type SeatType, type SubscriptionTier, type SuiteAiJob, type SuiteAiJobEvent, type SuiteNotification, type SuiteNotificationsResponse, TIDES_ACCESS_HELP, TURTLETIME_ACCESS_HELP, WEBHOOK_ACTIVITY_ACTIONS, WORKSPACE_SEAT_HELP, type WebPushClient, type WebPushClientConfig, type WebPushConfig, type WebPushState, type WorkspaceAppearance, type WorkspaceAppearanceApiConfig, type WorkspaceAppearanceConfig, WorkspaceAppearanceError, type WorkspaceAppearanceHelpers, type WorkspaceAppearancePatch, type WorkspaceBrandPayload, type WorkspaceSubscription, type WorkspaceTheme, activeSuiteAiJobs, appErrorFromResponse, canDisableAppAccess, codeForStatus, copyFor, createApiClient, createAuthReturnPath, createBrandSettings, createCrossAppSync, createJsonLd, createLiveRefresh, createNotificationsClient, createWebPushClient, createWorkspaceAppearance, createWorkspaceAppearanceApi, defaultInviteSeatType, flagsFromSeatType, formatAppError, hasAppAccess, isErrorCode, normalizeError, normalizeThrown, planSeatSummary, resolveSubscriptionTier, seatTypeDescription, seatTypeFromFlags, seatTypeLabel, selectedToWebhookActions, sortedSuiteAiEvents, suiteAiEventSummary, tierAllowsTidesOnlySeats, tierAllowsTurtletime, tierLabel, useIsNight, webhookActionsToSelected };
+export { type AnalyticsClient, type AnalyticsClientConfig, type AnalyticsContextHeaders, type AnalyticsProperties, type Api, type ApiAnalyticsEventSink, type ApiClient, type ApiClientConfig, type ApiFetchInit, type AppError, type AuthReturnPath, type AuthReturnPathConfig, type BrandSettings, type BrandSettingsConfig, type CrossAppSync, type CrossAppSyncConfig, type CrossAppSyncTopic, DEFAULT_ERROR_CODE, ERROR_CODES, ERROR_COPY, ERROR_RETRYABLE, type EmailNotificationPreference, type ErrorCode, FREE_PLAN_SEAT_HELP, type JsonLdConfig, type LiveRefresh, type LiveRefreshOptions, type NotificationsClient, type NotificationsClientConfig, ORGANISATION_SEAT_HELP, type PersistSuiteQueriesOptions, type PersistableQuery, type PersistableQueryClient, type PortalHandoffPayload, type PortalHandoffRead, type QueryKeyPart, SUITE_APP_QUERY_CACHES, SUITE_QUERY_CACHE_MAX_AGE_MS, type SeatType, type SubscriptionTier, type SuiteAiJob, type SuiteAiJobEvent, type SuiteNotification, type SuiteNotificationsResponse, type SuiteRevisionMap, TIDES_ACCESS_HELP, TURTLETIME_ACCESS_HELP, WEBHOOK_ACTIVITY_ACTIONS, WORKSPACE_SEAT_HELP, type WebPushClient, type WebPushClientConfig, type WebPushConfig, type WebPushState, type WorkspaceAppearance, type WorkspaceAppearanceApiConfig, type WorkspaceAppearanceConfig, WorkspaceAppearanceError, type WorkspaceAppearanceHelpers, type WorkspaceAppearancePatch, type WorkspaceBrandPayload, type WorkspaceSubscription, type WorkspaceTheme, activeSuiteAiJobs, appErrorFromResponse, canDisableAppAccess, codeForStatus, copyFor, createAnalyticsClient, createApiClient, createAuthReturnPath, createBrandSettings, createCrossAppSync, createJsonLd, createLiveRefresh, createNotificationsClient, createWebPushClient, createWorkspaceAppearance, createWorkspaceAppearanceApi, defaultInviteSeatType, emailDomain, flagsFromSeatType, formatAppError, hasAppAccess, isErrorCode, nextRevisionTick, normalizeError, normalizeThrown, persistSuiteQueries, planSeatSummary, readJsonSnapshot, resolveSubscriptionTier, seatTypeDescription, seatTypeFromFlags, seatTypeLabel, selectedToWebhookActions, sortedSuiteAiEvents, suiteAiEventSummary, suiteCacheBuster, tierAllowsTidesOnlySeats, tierAllowsTurtletime, tierLabel, useEmailNotificationPreference, useIsNight, useSuiteRevisions, webhookActionsToSelected, writeJsonSnapshot };