@xenide-io/suite-client 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Xenide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @xenide-io/suite-client
+
+Framework-agnostic platform layer shared across the Xenide ShellStack apps
+(TurtleTime, Tides, ShellStack, Kraken, Shelly). The UI counterpart lives in
+[`@xenide-io/the-old-ui-theme`](https://www.npmjs.com/package/@xenide-io/the-old-ui-theme);
+this package deliberately contains **no visual components**.
+
+## What's here
+
+| Area | Exports |
+| --- | --- |
+| Errors | `ERROR_CODES`, `normalizeError`, `appErrorFromResponse`, `formatAppError` |
+| API client | `createApiClient(config)` — fetch, JWT refresh, `X-Active-Workspace-Id`, shared workspace cookie |
+| Auth | `createAuthReturnPath(config)` — return paths, portal handoff, redeem |
+| Workspace | `createBrandSettings`, `createWorkspaceAppearance`, `createWorkspaceAppearanceApi`, seat/subscription helpers |
+| Cross-app sync | `createCrossAppSync(config)`, `createLiveRefresh(sync)` |
+| Notifications | `createNotificationsClient({ api, parseApiError })` |
+| AI jobs | `activeSuiteAiJobs`, `sortedSuiteAiEvents`, `suiteAiEventSummary` |
+| Webhooks | `WEBHOOK_ACTIVITY_ACTIONS`, `webhookActionsToSelected`, `selectedToWebhookActions` |
+| SEO | `createJsonLd(config)` |
+| Hooks | `useIsNight()` |
+
+## Usage
+
+Each app owns a thin `lib/api-client.ts` that configures the shared factory, so
+existing imports keep working:
+
+```ts
+import { createApiClient } from '@xenide-io/suite-client';
+
+export const {
+  api,
+  parseApiError,
+  getAccessToken,
+  setTokens,
+  // ...
+} = createApiClient({
+  storagePrefix: 'tt',
+  refreshPath: '/api/turtletime/auth/refresh/',
+});
+```
+
+## Scripts
+
+```bash
+bun run typecheck
+bun run lint
+bun run test
+bun run build
+```
+
+## Releasing
+
+Publishing runs from GitHub Actions on a published GitHub Release using npm
+trusted publishing (OIDC) — see `.github/workflows/release.yml`. Bump
+`version`, tag `vX.Y.Z`, publish the release.

package/dist/index.d.mts

@@ -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 };