@xenide-io/suite-client 0.3.2 → 0.5.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;
@@ -326,6 +391,36 @@ declare function createNotificationsClient(config: NotificationsClientConfig): {
     markAllSuiteNotificationsRead: () => Promise<void>;
 };
 
+/** Browser push state surfaced to settings UI. */
+type WebPushState = 'unsupported' | 'unconfigured' | 'default' | 'granted' | 'denied' | 'subscribed';
+interface WebPushConfig {
+    enabled: boolean;
+    public_key: string;
+}
+interface WebPushClientConfig {
+    api: Api;
+    parseApiError: (res: Response) => Promise<string>;
+    publicKeyPath?: string;
+    subscribePath?: string;
+    unsubscribePath?: string;
+    serviceWorkerPath?: string;
+    serviceWorkerScope?: string;
+}
+type WebPushClient = ReturnType<typeof createWebPushClient>;
+/**
+ * Browser Web Push client shared across ShellStack apps.
+ *
+ * Registration is per origin: each app ships its own `/sw.js` and manifest,
+ * but all talk to the same suite endpoints, so a subscription made in one app
+ * receives notifications for the whole suite.
+ */
+declare function createWebPushClient(config: WebPushClientConfig): {
+    supported: () => boolean;
+    getState: () => Promise<WebPushState>;
+    enable: () => Promise<void>;
+    disable: () => Promise<void>;
+};
+
 type SuiteAiJobEvent = {
     sequence: number;
     event_type: 'queued' | 'started' | 'progress' | 'tool' | 'completed' | 'failed' | 'cancelled';
@@ -386,4 +481,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 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, 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 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 };

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;
@@ -326,6 +391,36 @@ declare function createNotificationsClient(config: NotificationsClientConfig): {
     markAllSuiteNotificationsRead: () => Promise<void>;
 };
 
+/** Browser push state surfaced to settings UI. */
+type WebPushState = 'unsupported' | 'unconfigured' | 'default' | 'granted' | 'denied' | 'subscribed';
+interface WebPushConfig {
+    enabled: boolean;
+    public_key: string;
+}
+interface WebPushClientConfig {
+    api: Api;
+    parseApiError: (res: Response) => Promise<string>;
+    publicKeyPath?: string;
+    subscribePath?: string;
+    unsubscribePath?: string;
+    serviceWorkerPath?: string;
+    serviceWorkerScope?: string;
+}
+type WebPushClient = ReturnType<typeof createWebPushClient>;
+/**
+ * Browser Web Push client shared across ShellStack apps.
+ *
+ * Registration is per origin: each app ships its own `/sw.js` and manifest,
+ * but all talk to the same suite endpoints, so a subscription made in one app
+ * receives notifications for the whole suite.
+ */
+declare function createWebPushClient(config: WebPushClientConfig): {
+    supported: () => boolean;
+    getState: () => Promise<WebPushState>;
+    enable: () => Promise<void>;
+    disable: () => Promise<void>;
+};
+
 type SuiteAiJobEvent = {
     sequence: number;
     event_type: 'queued' | 'started' | 'progress' | 'tool' | 'completed' | 'failed' | 'cancelled';
@@ -386,4 +481,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 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, 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 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 };