@ezychat/web 0.0.0-stage → 0.1.38

package/dist-lib/types/create-app.d.ts

@@ -0,0 +1,20 @@
+import { type WebExtension } from './extensions';
+import { type AppLinks } from './lib/links';
+export interface CreateInboxAppOptions {
+    /** UI added by another product build. Lite passes `[]`. */
+    extensions?: readonly WebExtension[];
+    /** Element to render into; defaults to `#root`. */
+    root?: HTMLElement;
+    /** Product name shown wherever the UI names the app; defaults to "EzyChat Lite". */
+    productName?: string;
+    /**
+     * Outside links (About, Report an issue, release notes, feedback, support email). Missing
+     * entries keep Lite's links; an explicit `null` hides that link.
+     */
+    links?: Partial<AppLinks>;
+}
+/**
+ * Renders the inbox app. Extensions are validated first (a bad extension throws before anything
+ * renders) and their catalogs are merged on top of the core catalogs.
+ */
+export declare function createInboxApp({ extensions, root, productName, links, }?: CreateInboxAppOptions): Promise<void>;

package/dist-lib/types/extensions/context.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from 'react';
+import type { WebExtension } from './types';
+/** Makes the (already validated) extensions available to the app shell. Lite passes none. */
+export declare function WebExtensionsProvider({ extensions, children, }: {
+    extensions: readonly WebExtension[];
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useWebExtensions(): readonly WebExtension[];

package/dist-lib/types/extensions/i18n.d.ts

@@ -0,0 +1,15 @@
+import type { WebExtension } from './types';
+/**
+ * Adds extension catalogs to the `common` namespace (the default one), on top of the core
+ * catalogs. Keys are `ext.<name>.…`, so they never overwrite a core key; a key missing in one
+ * language falls back to English the same way core keys do. Call after `validateWebExtensions`.
+ */
+export declare function registerExtensionCatalogs(extensions: readonly WebExtension[]): Promise<void>;
+/** Translates a key that is not in the typed core catalogs. */
+export type ExtensionTranslate = (key: string, options?: Record<string, unknown>) => string;
+/**
+ * `t` for extension keys (`ext.<name>.…`, `common` namespace). Core keys are type-checked against
+ * the bundled catalogs, which extension keys are not part of; this hook takes any string and
+ * re-renders on a language change like `useTranslation`.
+ */
+export declare function useExtensionTranslation(): ExtensionTranslate;

package/dist-lib/types/extensions/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export { WebExtensionsProvider, useWebExtensions } from './context';
+export { registerExtensionCatalogs, useExtensionTranslation, type ExtensionTranslate, } from './i18n';
+export { ExtensionBoundary, extensionRoutes } from './routes';

package/dist-lib/types/extensions/routes.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+import type { WebExtension } from './types';
+/** Wraps one extension element so a crash inside it never blanks the rest of the app. */
+export declare function ExtensionBoundary({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * `<Route>` elements for the extensions' routes of one kind. User routes are absolute
+ * (`/ext/<name>/<path>`); admin routes are relative to the admin shell (`ext/<name>/<path>`).
+ * The fixed `ext/<name>/` prefix means an extension route can never match a core path.
+ */
+export declare function extensionRoutes(extensions: readonly WebExtension[], admin: boolean): ReactNode[];

package/dist-lib/types/extensions/types.d.ts

@@ -0,0 +1,116 @@
+import type { ComponentType, ReactNode } from 'react';
+import { type Locale } from '@ezychat/shared';
+/**
+ * Web extension API: lets another product build (e.g. Enterprise) add UI without forking Lite.
+ *
+ * - `routes` mount only under `/ext/<name>/<path>` (signed-in users) or, with `admin: true`, under
+ *   `/admin/ext/<name>/<path>` inside the admin shell. They can never replace a core route.
+ * - `adminNav` links point at the extension's admin routes (`/admin/ext/<name>/<path>`).
+ * - `settingsSections` render in Settings → Integrations, below the core sections.
+ * - `agentSections` render as rows on an AI agent's page (`/admin/members/ai` for the Sales
+ *   Agent), right under Business context.
+ * - An admin route may declare the core admin `section` it belongs to (e.g. `members` for an
+ *   agent sub-page): that nav item is highlighted and the phone header shows its label.
+ * - An admin nav item may show a small badge (a count or "needs attention") from `useBadge`.
+ * - `banners` render in one slim bar at the top of the signed-in shell (inbox and admin); the
+ *   first banner that renders something wins, the others stay hidden.
+ * - `lockScreen` replaces the core "paused" screen while the server's access gate is closed
+ *   (GET /api/access, or any API call answering 403 with the gate code). It is shown without
+ *   sign-in; `recheck()` reads the gate again and the app reloads once it is open.
+ * - `catalogs` add translation keys to the `common` namespace; every key must start with
+ *   `ext.<name>.`. A key missing in one language falls back to English like core keys.
+ *
+ * Every extension element is wrapped in the app's ErrorBoundary.
+ */
+export interface WebExtensionRoute {
+    /** Relative path below the extension's prefix, e.g. `reports` or `reports/:id`. */
+    path: string;
+    element: ReactNode;
+    /** Mount in the admin shell (admins only) instead of the signed-in user area. */
+    admin?: boolean;
+    /**
+     * Admin routes only: the core admin section this page sits under (e.g. `members` for
+     * `/admin/ext/<name>/agents/ai`). Highlights that nav item and names it in the phone header.
+     * The page still renders its own breadcrumb.
+     */
+    section?: WebExtensionAdminSection;
+}
+/** Core admin sections an extension admin route may sit under (the `ADMIN_NAV` paths). */
+export declare const WEB_EXTENSION_ADMIN_SECTIONS: readonly ["members", "quick-replies", "whatsapp", "tunnel", "settings", "audit"];
+export type WebExtensionAdminSection = (typeof WEB_EXTENSION_ADMIN_SECTIONS)[number];
+/** A small badge on an admin nav link: a count, or a dot that asks for attention. */
+export interface WebExtensionNavBadge {
+    /** Shown when above 0 (99+ above 99). */
+    count?: number;
+    /** A dot when there is no count, e.g. a connector that needs signing in again. */
+    attention?: boolean;
+    /** Translation key (`ext.<name>.…`) read by screen readers, e.g. "2 need attention". */
+    labelKey?: string;
+    /** Values for `labelKey`'s placeholders. */
+    labelValues?: Record<string, string | number>;
+}
+export interface WebExtensionNavItem {
+    /** Path of one of this extension's admin routes (relative, as in `routes[].path`). */
+    path: string;
+    /** Translation key (`ext.<name>.…`) of the link label. */
+    labelKey: string;
+    icon?: ComponentType<{
+        className?: string;
+        'aria-hidden'?: boolean;
+    }>;
+    /**
+     * React hook (called on every admin render, so keep it cheap: read a cached query) returning
+     * the badge to show, or null for none. Errors in it hide the badge, never the nav.
+     */
+    useBadge?: () => WebExtensionNavBadge | null;
+}
+/** The AI agents whose page can hold extension rows. Only the Sales Agent exists today. */
+export type WebExtensionAgent = 'sales';
+export interface WebExtensionAgentSection {
+    agent: WebExtensionAgent;
+    /** Unique within the extension; lowercase letters, digits and dashes. */
+    id: string;
+    /** One compact row (e.g. "Connectors · 2 connected · Manage ›"); details on its own page. */
+    element: ReactNode;
+}
+export interface WebExtensionSettingsSection {
+    /** Unique within the extension; lowercase letters, digits and dashes. */
+    id: string;
+    /** Translation key (`ext.<name>.…`) of the section heading. */
+    titleKey: string;
+    element: ReactNode;
+}
+/** Props of an extension's lock screen. */
+export interface WebExtensionLockScreenProps {
+    /** The gate code from the server, e.g. `license_required`. */
+    code: string;
+    /** Read GET /api/access again now (the app reloads when access is open). */
+    recheck: () => void;
+}
+export type WebExtensionCatalogs = Partial<Record<Locale, Record<string, string>>>;
+export interface WebExtension {
+    /** Lowercase id, 2–32 characters: `/^[a-z][a-z0-9-]{1,31}$/`; not `lite` or `core`. */
+    name: string;
+    routes?: WebExtensionRoute[];
+    adminNav?: WebExtensionNavItem[];
+    settingsSections?: WebExtensionSettingsSection[];
+    agentSections?: WebExtensionAgentSection[];
+    /** Slim one-line bars for the top of the signed-in shell; the first non-empty one is shown. */
+    banners?: ComponentType[];
+    /** Full-page screen while access is closed; the first extension that has one wins. */
+    lockScreen?: ComponentType<WebExtensionLockScreenProps>;
+    catalogs?: WebExtensionCatalogs;
+}
+export declare const EXTENSION_NAME_PATTERN: RegExp;
+export declare class WebExtensionError extends Error {
+    name: string;
+}
+/** Prefix that every catalog, nav and section key of an extension must start with. */
+export declare function extensionKeyPrefix(name: string): string;
+/** URL of an extension route. */
+export declare function extensionPath(name: string, path: string, admin?: boolean): string;
+/**
+ * Checks a list of extensions and throws a `WebExtensionError` naming the first problem.
+ * Returns the same list so callers can write `validateWebExtensions(list)` inline.
+ */
+export declare function validateWebExtensions(extensions: readonly WebExtension[]): readonly WebExtension[];

package/dist-lib/types/i18n/LanguageSelect.d.ts

@@ -0,0 +1,4 @@
+/** Compact language picker for screens without the account menu (sign-in, setup). */
+export declare function LanguageSelect({ className }: {
+    className?: string;
+}): import("react").JSX.Element;

package/dist-lib/types/i18n/LocaleSync.d.ts

@@ -0,0 +1,2 @@
+/** Applies the signed-in user's saved language (it follows them across browsers and devices). */
+export declare function LocaleSync(): null;

package/dist-lib/types/i18n/date-locale.d.ts

@@ -0,0 +1,5 @@
+import type { Locale as DateFnsLocale } from 'date-fns';
+import type { Locale } from '@ezychat/shared';
+export declare function loadDateLocale(locale: Locale): Promise<void>;
+/** date-fns locale of the active UI language (English until another one has loaded). */
+export declare function dateLocale(): DateFnsLocale;

package/dist-lib/types/i18n/index.d.ts

@@ -0,0 +1,17 @@
+import i18n from 'i18next';
+import { type Locale } from '@ezychat/shared';
+/** Product name used by catalog strings through `{{product}}`; another edition replaces it. */
+export declare const DEFAULT_PRODUCT_NAME = "EzyChat Lite";
+/**
+ * Sets the product name every `{{product}}` in the catalogs shows (e.g. "EzyChat Enterprise").
+ * i18next reads default variables on each translation, so this also applies after init.
+ */
+export declare function setProductName(name: string): void;
+/** Initializes i18next once with the English catalogs bundled. */
+export declare function initI18n(): Promise<unknown>;
+/**
+ * Loads a language's catalogs and date-fns locale, then switches to it. When calls overlap, only
+ * the most recent one is applied.
+ */
+export declare function activateLocale(locale: Locale): Promise<void>;
+export { i18n };

package/dist-lib/types/i18n/locale-store.d.ts

@@ -0,0 +1,26 @@
+import { type Locale } from '@ezychat/shared';
+export declare const LOCALE_STORAGE_KEY = "wati.locale";
+/**
+ * The active UI language. Order: the signed-in user's saved choice (applied by `LocaleSync`),
+ * then this browser's last choice (`wati.locale`), then the browser languages, then English.
+ * Changes are shared with other tabs through the storage event.
+ */
+export declare function createLocaleStore(target?: Window): {
+    getSnapshot: () => "en" | "ms" | "zh-CN";
+    subscribe(listener: () => void): () => boolean;
+    /** Applies the initial language; on failure the UI (and snapshot) stay English. */
+    ready(): Promise<void>;
+    /** Resolves once the language is active; rejects (keeping the current one) if it can't load. */
+    setLocale(next: Locale): Promise<void>;
+    dispose(): void;
+};
+export declare const localeStore: {
+    getSnapshot: () => "en" | "ms" | "zh-CN";
+    subscribe(listener: () => void): () => boolean;
+    /** Applies the initial language; on failure the UI (and snapshot) stay English. */
+    ready(): Promise<void>;
+    /** Resolves once the language is active; rejects (keeping the current one) if it can't load. */
+    setLocale(next: Locale): Promise<void>;
+    dispose(): void;
+};
+export declare function useLocale(): Locale;