@xenide-io/suite-client 0.5.0 → 0.6.1

package/dist/index.d.mts

@@ -327,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;
@@ -334,6 +416,8 @@ interface CrossAppSyncConfig {
     checkpointPath: string;
     /** Poll interval while the tab is visible (ms). */
     pollMs?: number;
+    /** Reset the checkpoint baseline when the active workspace changes. */
+    getScope?: () => string | null;
 }
 type CrossAppSync = ReturnType<typeof createCrossAppSync>;
 /**
@@ -361,6 +445,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;
@@ -421,6 +536,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';
@@ -481,4 +608,4 @@ declare function createJsonLd(config: JsonLdConfig): string;
 
 declare function useIsNight(): boolean;
 
-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 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, createAnalyticsClient, createApiClient, createAuthReturnPath, createBrandSettings, createCrossAppSync, createJsonLd, createLiveRefresh, createNotificationsClient, createWebPushClient, createWorkspaceAppearance, createWorkspaceAppearanceApi, defaultInviteSeatType, emailDomain, 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

@@ -327,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;
@@ -334,6 +416,8 @@ interface CrossAppSyncConfig {
     checkpointPath: string;
     /** Poll interval while the tab is visible (ms). */
     pollMs?: number;
+    /** Reset the checkpoint baseline when the active workspace changes. */
+    getScope?: () => string | null;
 }
 type CrossAppSync = ReturnType<typeof createCrossAppSync>;
 /**
@@ -361,6 +445,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;
@@ -421,6 +536,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';
@@ -481,4 +608,4 @@ declare function createJsonLd(config: JsonLdConfig): string;
 
 declare function useIsNight(): boolean;
 
-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 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, createAnalyticsClient, createApiClient, createAuthReturnPath, createBrandSettings, createCrossAppSync, createJsonLd, createLiveRefresh, createNotificationsClient, createWebPushClient, createWorkspaceAppearance, createWorkspaceAppearanceApi, defaultInviteSeatType, emailDomain, 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 };