@xenide-io/suite-client 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,376 @@
+declare const ERROR_CODES: {
+    readonly AUTH_001: "E-AUTH-001";
+    readonly AUTH_002: "E-AUTH-002";
+    readonly AUTH_003: "E-AUTH-003";
+    readonly VALID_001: "E-VALID-001";
+    readonly DATA_001: "E-DATA-001";
+    readonly DATA_002: "E-DATA-002";
+    readonly LIMIT_001: "E-LIMIT-001";
+    readonly NET_001: "E-NET-001";
+    readonly EXT_001: "E-EXT-001";
+    readonly EXT_002: "E-EXT-002";
+    readonly SYS_001: "E-SYS-001";
+    readonly SYS_002: "E-SYS-002";
+    readonly CLIENT_001: "E-CLIENT-001";
+    readonly CLIENT_002: "E-CLIENT-002";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+declare const DEFAULT_ERROR_CODE: ErrorCode;
+declare const ERROR_COPY: Record<ErrorCode, string>;
+declare const ERROR_RETRYABLE: Record<ErrorCode, boolean>;
+declare function isErrorCode(value: unknown): value is ErrorCode;
+declare function copyFor(code: ErrorCode, capability?: string): string;
+
+/**
+ * The single normalised shape every caught failure is reduced to before any
+ * component sees it. `message` is always resolved from the local registry;
+ * upstream text is never carried through.
+ */
+type AppError = {
+    code: ErrorCode;
+    message: string;
+    correlationId?: string;
+    retryable: boolean;
+};
+declare function codeForStatus(status: number): ErrorCode;
+/**
+ * Reduce an unknown value to an `AppError`. Accepts only the envelope shape;
+ * every other key on the input is discarded. Unknown or absent codes fall back.
+ */
+declare function normalizeError(input: unknown, fallback?: ErrorCode, capability?: string): AppError;
+/** Normalise a non-2xx `Response` without ever reading its raw message. */
+declare function appErrorFromResponse(response: Response, capability?: string): Promise<AppError>;
+/** Normalise a thrown fetch failure: offline, aborted, or unreachable. */
+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;
+
+interface ApiClientConfig {
+    /** localStorage key namespace, e.g. `tt` or `tides`. */
+    storagePrefix: string;
+    /** Backend refresh endpoint, e.g. `/api/turtletime/auth/refresh/`. */
+    refreshPath: string;
+    /** Overrides `NEXT_PUBLIC_API_URL` / `http://localhost:8000`. */
+    baseUrl?: string;
+    accessTokenKey?: string;
+    refreshTokenKey?: string;
+    workspaceKey?: string;
+    /** Suite-wide workspace cookie name. */
+    workspaceCookieName?: string;
+    /** Overrides `NEXT_PUBLIC_WORKSPACE_COOKIE_DOMAIN`. */
+    workspaceCookieDomain?: string;
+    /** Fired when the active workspace changes in this tab. */
+    onWorkspaceChange?: (id: string | null) => void;
+    /** sessionStorage key prefixes to clear on sign-out. */
+    sessionStorageClearPrefixes?: string[];
+}
+type ApiFetch = (path: string, options?: RequestInit) => Promise<Response>;
+/**
+ * Build a browser API client scoped to one ShellStack app. Every app shares the
+ * same fetch/refresh/workspace behaviour; only the storage namespace and
+ * refresh path differ.
+ */
+declare function createApiClient(config: ApiClientConfig): {
+    API_URL: string;
+    onAuthFailure: (handler: () => void) => void;
+    setTokens: (access: string, refresh: string) => void;
+    getAccessToken: () => string | null;
+    getRefreshToken: () => string | null;
+    setActiveWorkspaceId: (id: string | null, options?: {
+        share?: boolean;
+    }) => void;
+    getActiveWorkspaceId: () => string | null;
+    restoreWorkspace: () => void;
+    clearAuth: () => void;
+    restoreTokens: () => void;
+    refreshAccessToken: () => Promise<boolean>;
+    parseApiError: (res: Response) => Promise<string>;
+    api: {
+        get: (path: string) => Promise<Response>;
+        post: (path: string, body?: unknown, options?: RequestInit) => Promise<Response>;
+        put: (path: string, body?: unknown) => Promise<Response>;
+        patch: (path: string, body?: unknown) => Promise<Response>;
+        delete: (path: string) => Promise<Response>;
+    };
+};
+type ApiClient = ReturnType<typeof createApiClient>;
+type Api = ApiClient['api'];
+
+interface AuthReturnPathConfig {
+    /** sessionStorage key holding the in-app return path, e.g. `tt_auth_return_to`. */
+    returnKey: string;
+    /** sessionStorage key caching the portal handoff payload. */
+    handoffKey?: string;
+    defaultNext?: string;
+    portalCallbackPath?: string;
+    redeemPath?: string;
+}
+interface PortalHandoffPayload {
+    code?: string;
+    token?: string;
+    access?: string;
+    refresh?: string;
+}
+interface PortalHandoffRead {
+    code: string | null;
+    token: string | null;
+    refresh: string | null;
+    next: string;
+}
+type AuthReturnPath = ReturnType<typeof createAuthReturnPath>;
+declare function createAuthReturnPath(config: AuthReturnPathConfig): {
+    isSafeAuthReturnPath: (path: string | null | undefined) => path is string;
+    stashAuthReturnPath: (path: string | null | undefined) => void;
+    portalHandoffUrl: (base: string, data: PortalHandoffPayload, next?: string, fallbackNext?: string) => string;
+    readPortalHandoff: (fallbackNext?: string) => PortalHandoffRead;
+    redeemPortalHandoff: (apiUrl: string, fallbackNext?: string) => Promise<PortalHandoffRead>;
+    readAuthReturnPath: () => string | null;
+    signInHrefWithReturn: (fallbackRedirect?: string | null) => string;
+    registerHrefWithReturn: (returnPath: string) => string;
+};
+
+/** Copy and helpers for workspace seats vs per-app access (shared core model). */
+declare const WORKSPACE_SEAT_HELP = "Each member uses one workspace seat. Inviting someone reserves a seat until the invite is revoked or accepted.";
+declare const ORGANISATION_SEAT_HELP = "Each organisation member uses one seat across all your workspaces. One invite gives them access to every workspace in your organisation.";
+declare const TIDES_ACCESS_HELP = "Tides \u2014 project management.";
+declare const TURTLETIME_ACCESS_HELP = "TurtleTime \u2014 time tracking add-on (Basic plan and above).";
+declare const FREE_PLAN_SEAT_HELP = "Free personal workspaces include one product app only. Create an organisation on ShellStack for both apps and integration.";
+declare function hasAppAccess(canAccessTurtletime: boolean, canAccessTides: boolean): boolean;
+declare function canDisableAppAccess(app: 'turtletime' | 'tides', canAccessTurtletime: boolean, canAccessTides: boolean): boolean;
+
+/** Per-workspace subscription tier helpers (mirrors core/subscriptions.py). */
+type SubscriptionTier = 'free' | 'plus' | 'ai_plus' | 'basic' | 'pro' | 'enterprise';
+interface WorkspaceSubscription {
+    tier: SubscriptionTier;
+    tier_label: string;
+    limits: {
+        seats?: number | null;
+        integrated_seats: number | null;
+        tides_only_seats: number | null;
+    };
+    usage: {
+        seats?: number;
+        integrated_seats: number;
+        tides_only_seats: number;
+    };
+}
+type SeatType = 'tides' | 'integrated';
+declare function tierLabel(tier: SubscriptionTier): string;
+declare function resolveSubscriptionTier(workspace: {
+    subscription?: {
+        tier?: string;
+    } | null;
+    subscription_tier?: string | null;
+} | null | undefined): SubscriptionTier;
+declare function tierAllowsTurtletime(tier: SubscriptionTier): boolean;
+declare function defaultInviteSeatType(tier: SubscriptionTier): SeatType;
+declare function tierAllowsTidesOnlySeats(): boolean;
+declare function seatTypeFromFlags(canAccessTurtletime: boolean, canAccessTides: boolean): SeatType;
+declare function flagsFromSeatType(seatType: SeatType): {
+    can_access_turtletime: boolean;
+    can_access_tides: boolean;
+};
+declare function seatTypeLabel(seatType: SeatType): string;
+declare function seatTypeDescription(tier: SubscriptionTier, seatType: SeatType): string;
+declare function planSeatSummary(subscription: WorkspaceSubscription | null | undefined): string;
+
+interface BrandSettingsConfig {
+    /** Fallback title when the workspace has not customised one. */
+    defaultTitle: string;
+    /** Window event dispatched when the brand changes. */
+    changedEvent: string;
+}
+interface WorkspaceBrandPayload {
+    brand_logo?: string | null;
+    brand_title?: string | null;
+    brand_show_title?: boolean;
+}
+type BrandSettings = ReturnType<typeof createBrandSettings>;
+declare function createBrandSettings(config: BrandSettingsConfig): {
+    DEFAULT_BRAND_TITLE: string;
+    BRAND_SETTINGS_CHANGED: string;
+    /** @deprecated Use BRAND_SETTINGS_CHANGED */
+    BRAND_LOGO_CHANGED: string;
+    applyWorkspaceBrand: (payload: WorkspaceBrandPayload) => void;
+    getBrandLogo: () => string | null;
+    getCustomBrandTitle: () => string | null;
+    getBrandShowTitle: () => boolean;
+    getDisplayBrandTitle: () => string | null;
+    setBrandLogo: (dataUrl: string | null) => void;
+    setCustomBrandTitle: (title: string | null) => void;
+    setBrandShowTitle: (show: boolean) => void;
+    resetBrandTitle: () => void;
+};
+
+interface WorkspaceAppearanceConfig {
+    /** Window event dispatched when the active workspace changes. */
+    changedEvent: string;
+    /** localStorage base key for the theme. */
+    themeStorageBase: string;
+    /** Reads the active workspace id from the app's API client. */
+    getActiveWorkspaceId: () => string | null;
+}
+type WorkspaceAppearanceHelpers = ReturnType<typeof createWorkspaceAppearance>;
+declare function createWorkspaceAppearance(config: WorkspaceAppearanceConfig): {
+    WORKSPACE_CHANGED: string;
+    THEME_STORAGE_BASE: string;
+    notifyWorkspaceChanged: () => void;
+    scopedStorageKey: (base: string, workspaceId?: string | null) => string;
+    getScopedStorageItem: (base: string, workspaceId?: string | null) => string | null;
+    setScopedStorageItem: (base: string, value: string | null, workspaceId?: string | null) => void;
+};
+
+interface WorkspaceAppearanceApiConfig {
+    api: Api;
+    parseApiError: (res: Response) => Promise<string>;
+    /** Endpoint base, e.g. `/api/turtletime/workspaces/current/appearance/`. */
+    basePath: string;
+    applyWorkspaceBrand: (payload: WorkspaceBrandPayload) => void;
+}
+type WorkspaceTheme = 'light' | 'dark';
+interface WorkspaceAppearance {
+    theme: WorkspaceTheme;
+    brand_logo: string | null;
+    brand_title: string | null;
+    brand_show_title: boolean;
+}
+type WorkspaceAppearancePatch = Partial<Pick<WorkspaceAppearance, 'theme' | 'brand_title' | 'brand_show_title'>> & {
+    brand_logo_file?: File;
+    clear_brand_logo?: boolean;
+};
+declare class WorkspaceAppearanceError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+declare function createWorkspaceAppearanceApi(config: WorkspaceAppearanceApiConfig): {
+    WorkspaceAppearanceError: typeof WorkspaceAppearanceError;
+    fetchWorkspaceAppearance: () => Promise<WorkspaceAppearance>;
+    updateWorkspaceAppearance: (patch: WorkspaceAppearancePatch) => Promise<WorkspaceAppearance>;
+    cacheWorkspaceAppearanceLocally: (appearance: WorkspaceAppearance) => void;
+};
+
+type CrossAppSyncTopic = 'time' | 'integration' | 'tasks';
+interface CrossAppSyncConfig {
+    api: Api;
+    /** Checkpoint endpoint, e.g. `/api/turtletime/sync-checkpoint/`. */
+    checkpointPath: string;
+    /** Poll interval while the tab is visible (ms). */
+    pollMs?: number;
+}
+type CrossAppSync = ReturnType<typeof createCrossAppSync>;
+/**
+ * Poll backend checkpoints so sibling apps refresh when data mutates
+ * elsewhere. Same-tab instant updates stay the app's responsibility via its
+ * own window events.
+ */
+declare function createCrossAppSync(config: CrossAppSyncConfig): {
+    broadcastCrossAppSync: (_topic: CrossAppSyncTopic) => void;
+    subscribeCrossAppSync: (onSync: () => void, topic?: CrossAppSyncTopic) => () => void;
+    lastCrossAppSyncTime: (topic?: CrossAppSyncTopic) => number;
+};
+
+interface LiveRefreshOptions {
+    /** Same-tab custom events (e.g. `tt-timer-mutated`). */
+    localEvents?: string[];
+    /** Gentle poll while the tab is visible (ms). */
+    pollMs?: number;
+    /** Limit cross-tab refreshes to one mutation topic. */
+    crossAppTopic?: CrossAppSyncTopic;
+}
+type LiveRefresh = ReturnType<typeof createLiveRefresh>;
+declare function createLiveRefresh(sync: CrossAppSync): {
+    subscribeLiveRefresh: (refresh: () => void, options?: LiveRefreshOptions) => () => void;
+    hasPendingCrossAppSync: (topic: CrossAppSyncTopic | undefined, since: number) => boolean;
+};
+
+/** Cross-app (suite) notification from `/api/notifications/` — shared across ShellStack apps. */
+interface SuiteNotification {
+    id: string;
+    title: string;
+    body: string;
+    href: string;
+    kind: string;
+    source_app: string;
+    read_at: string | null;
+    created_at: string;
+    workspace: string | null;
+    organisation: string | null;
+}
+interface SuiteNotificationsResponse {
+    notifications: SuiteNotification[];
+    unread_count: number;
+}
+interface NotificationsClientConfig {
+    api: Api;
+    parseApiError: (res: Response) => Promise<string>;
+    cacheMs?: number;
+    listPath?: string;
+}
+type NotificationsClient = ReturnType<typeof createNotificationsClient>;
+declare function createNotificationsClient(config: NotificationsClientConfig): {
+    fetchSuiteNotifications: () => Promise<SuiteNotificationsResponse>;
+    markSuiteNotificationRead: (id: string) => Promise<void>;
+    markAllSuiteNotificationsRead: () => Promise<void>;
+};
+
+type SuiteAiJobEvent = {
+    sequence: number;
+    event_type: 'queued' | 'started' | 'progress' | 'tool' | 'completed' | 'failed' | 'cancelled';
+    summary: string;
+    payload: Record<string, unknown>;
+    created_at: string;
+};
+type SuiteAiJob = {
+    id: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    events: SuiteAiJobEvent[];
+};
+declare function activeSuiteAiJobs(jobs: SuiteAiJob[]): SuiteAiJob[];
+declare function sortedSuiteAiEvents(events: SuiteAiJobEvent[]): SuiteAiJobEvent[];
+declare function suiteAiEventSummary(event?: SuiteAiJobEvent): string;
+
+declare const WEBHOOK_ACTIVITY_ACTIONS: readonly [{
+    readonly id: "created";
+    readonly label: "Task created";
+}, {
+    readonly id: "updated";
+    readonly label: "Task updated";
+}, {
+    readonly id: "status_changed";
+    readonly label: "Task status changed";
+}, {
+    readonly id: "assigned";
+    readonly label: "Task assigned";
+}, {
+    readonly id: "commented";
+    readonly label: "Comment posted";
+}, {
+    readonly id: "project_renamed";
+    readonly label: "Project renamed";
+}, {
+    readonly id: "project_status_changed";
+    readonly label: "Project archived or restored";
+}];
+declare function webhookActionsToSelected(stored: string[] | null | undefined): Set<string>;
+declare function selectedToWebhookActions(selected: Set<string>): string[];
+
+interface JsonLdConfig {
+    name: string;
+    url: string;
+    description: string;
+    applicationCategory?: string;
+    applicationSubCategory?: string;
+    operatingSystem?: string;
+    softwareVersion?: string;
+    price?: string;
+    priceCurrency?: string;
+    inLanguage?: string;
+    publisherName?: string;
+    publisherUrl?: string;
+}
+/** Build a schema.org SoftwareApplication JSON-LD string for a product page. */
+declare function createJsonLd(config: JsonLdConfig): string;
+
+declare function useIsNight(): boolean;
+
+export { type Api, type ApiClient, type ApiClientConfig, type ApiFetch, 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 };