ptech-shell-dev 0.1.0 → 1.6.3

package/README.md

@@ -14,4 +14,23 @@ npm i ptech-shell-dev ptech-shell-sdk
 import { initStandaloneServices } from 'ptech-shell-dev';
 
 initStandaloneServices();
-```
+```
+
+## MSAL adapter
+
+```ts
+import { registerService, TOKENS } from 'ptech-shell-sdk';
+import { PublicClientApplication } from '@azure/msal-browser';
+import { createMsalUserService } from 'ptech-shell-dev';
+
+const msal = new PublicClientApplication(msalConfig);
+
+registerService(
+  TOKENS.userService,
+  createMsalUserService({
+    msal,
+    defaultScopes: ['User.Read'],
+    loginMode: 'popup',
+  }),
+);
+```

package/dist/index.d.ts

@@ -1,4 +1,65 @@
-import { Lang, User, I18nService, UserService, ApiClient, NavigationService, ConfigService, PermissionService, SharedStateService, ObservabilityService, NotificationService, AnalyticsService } from 'ptech-shell-sdk';
+import { LogLevel, RealtimeEnvelope, UserService, RequestContextService, RealtimeService, Lang, User, I18nService, ApiClient, NavigationService, ConfigService, PermissionService, SharedStateService, ObservabilityService, NotificationService, AnalyticsService, ObservabilityConfigPatch, ApiErrorPayload, ApiValidationErrors, ApiRetryOptions, MsalAccountInfoLike, NavigationAction, NavigationTo, NavigationNavigateOptions } from 'ptech-shell-sdk';
+
+type ObservabilityTelemetryEvent = {
+    level: LogLevel;
+    source: string;
+    message: string;
+    timestamp: number;
+    traceId?: string;
+    correlationId?: string;
+    data?: unknown;
+};
+type ObservabilityTelemetrySink = {
+    track: (event: ObservabilityTelemetryEvent) => void | Promise<void>;
+};
+type CreateStandaloneObservabilityServiceOptions = {
+    telemetrySink?: ObservabilityTelemetrySink;
+    redact?: (data: unknown) => unknown;
+    getTraceContext?: () => {
+        traceId?: string;
+        correlationId?: string;
+    };
+};
+
+type RealtimeEventListener = (envelope: RealtimeEnvelope<unknown>) => void;
+type RealtimeReconnectOptions = {
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    maxAttempts?: number;
+};
+type RealtimeTransportConnectContext = {
+    accessToken?: string;
+    traceId?: string;
+    correlationId?: string;
+};
+type RealtimeTransport = {
+    start: (context: RealtimeTransportConnectContext) => Promise<void>;
+    stop: () => Promise<void>;
+    onMessage: (listener: RealtimeEventListener) => () => void;
+    onDisconnect?: (listener: () => void) => () => void;
+    send?: (event: string, payload: unknown) => Promise<void>;
+};
+type CreateStandaloneRealtimeServiceOptions = {
+    createTransport?: () => RealtimeTransport;
+    reconnect?: RealtimeReconnectOptions;
+    getUserService?: () => UserService | undefined;
+    userService?: UserService;
+    getRequestContext?: () => RequestContextService | undefined;
+    requestContext?: RequestContextService;
+};
+/**
+ * WHY:
+ * - Creates a standalone realtime service with reconnect, listener fan-out, and trace propagation.
+ * WHEN TO USE:
+ * - Use in shell/host apps that need lightweight realtime orchestration independent from framework lifecycle.
+ * WHEN NOT TO USE:
+ * - Do not call repeatedly for the same logical channel unless isolation is required.
+ * INVARIANTS:
+ * - Connection state transitions are serialized through internal guards.
+ * - `start()` is idempotent while already connected/connecting/reconnecting.
+ * - `stop()` always leaves state at `disconnected` and clears timers/listeners.
+ */
+declare function createStandaloneRealtimeService(options?: CreateStandaloneRealtimeServiceOptions): RealtimeService;
 
 type StandaloneServices = {
     i18n: I18nService;
@@ -8,6 +69,8 @@ type StandaloneServices = {
     configService: ConfigService;
     permissionService: PermissionService;
     sharedState: SharedStateService;
+    requestContext: RequestContextService;
+    realtime: RealtimeService;
     observability: ObservabilityService;
     notification: NotificationService;
     analytics: AnalyticsService;
@@ -32,6 +95,21 @@ type StandaloneInitOptions = {
      * This is useful when each remote wants slightly different mock behavior.
      */
     customize?: (services: StandaloneServices) => void;
+    /**
+     * Optional observability log filter.
+     * Example:
+     * - dev: { minLevel: 'debug' }
+     * - production: { minLevel: 'error' }
+     */
+    observability?: ObservabilityConfigPatch;
+    /**
+     * Optional observability adapters (for App Insights/OpenTelemetry bridges).
+     */
+    observabilityOptions?: Omit<CreateStandaloneObservabilityServiceOptions, 'getTraceContext'>;
+    /**
+     * Realtime bootstrap options.
+     */
+    realtime?: Omit<CreateStandaloneRealtimeServiceOptions, 'getUserService' | 'userService' | 'getRequestContext' | 'requestContext'>;
     /**
      * Service registration strategy for standalone init.
      * - if-missing (default): only register when token has no service yet.
@@ -48,10 +126,254 @@ type StandaloneInitOptions = {
  */
 declare function initStandaloneServices(options?: StandaloneInitOptions): void;
 
-declare function createStandaloneApiClient(apiBase: string): ApiClient;
+type CreateStandaloneApiClientOptions = {
+    apiBase: string;
+    userService?: UserService;
+    notificationService?: NotificationService;
+    /**
+     * Optional dynamic lookup. Useful if the user service can be replaced after initialization.
+     */
+    getUserService?: () => UserService | undefined;
+    /**
+     * Optional dynamic lookup. Useful if the notification service can be replaced after initialization.
+     */
+    getNotificationService?: () => NotificationService | undefined;
+    /**
+     * Optional dynamic lookup. Useful if request context service can be replaced after initialization.
+     */
+    getRequestContext?: () => RequestContextService | undefined;
+    requestContext?: RequestContextService;
+    defaultAuthScopes?: string[];
+    defaultTimeoutMs?: number;
+    defaultRetries?: ApiRetryOptions | false;
+};
+/**
+ * WHY:
+ * - Standardized API error object carrying HTTP/network/auth/trace context for UI and logging.
+ * WHEN TO USE:
+ * - Throw from API client internals whenever request/response contract fails.
+ * WHEN NOT TO USE:
+ * - Do not throw raw unknown errors across service boundary when this shape is expected.
+ * INVARIANTS:
+ * - Flags (`isNetworkError`, `isAuthError`, `isTimeoutError`) are always explicitly set.
+ * - Optional diagnostics (`traceId`, `correlationId`, `validationErrors`) are preserved when available.
+ */
+declare class ApiError extends Error implements ApiErrorPayload {
+    readonly status?: number;
+    readonly code?: string;
+    readonly traceId?: string;
+    readonly correlationId?: string;
+    readonly isNetworkError: boolean;
+    readonly isAuthError: boolean;
+    readonly isTimeoutError: boolean;
+    readonly validationErrors?: ApiValidationErrors;
+    readonly cause?: unknown;
+    constructor(details: ApiErrorPayload, cause?: unknown);
+}
+/**
+ * WHY:
+ * - Narrowing utility for callers handling mixed thrown values.
+ * WHEN TO USE:
+ * - Use in catch blocks to branch on structured `ApiError`.
+ * WHEN NOT TO USE:
+ * - Do not use for cross-realm error checks where `instanceof` may fail.
+ * INVARIANTS:
+ * - Returns true only for instances created from this `ApiError` class.
+ */
+declare function isApiError(value: unknown): value is ApiError;
+/**
+ * WHY:
+ * - Factory for standalone API client with shared auth, retry, tracing, and error normalization policies.
+ * WHEN TO USE:
+ * - Use as the single HTTP entrypoint for shell modules to keep behavior consistent.
+ * WHEN NOT TO USE:
+ * - Do not bypass with direct `fetch` for domain calls that require standard error/context handling.
+ * INVARIANTS:
+ * - All request methods delegate to common execution pipeline.
+ * - Returned client honors configured defaults unless request overrides them.
+ */
+declare function createStandaloneApiClient(options: string | CreateStandaloneApiClientOptions): ApiClient;
 
+type UiApiError = {
+    i18nKey: string;
+    params: Record<string, string | number>;
+    supportTraceId?: string;
+    severity: 'error' | 'warning';
+};
+/**
+ * WHY:
+ * - Converts transport/domain API errors into a stable UI error contract based on i18n keys.
+ * WHEN TO USE:
+ * - Use at UI boundary (toasts, banners, inline errors) after API layer has produced `ApiErrorPayload`.
+ * WHEN NOT TO USE:
+ * - Do not bypass this mapper with raw server messages in user-facing UI.
+ * INVARIANTS:
+ * - Always returns a defined `i18nKey`, `params`, and `severity`.
+ * - Prefer traceability by forwarding `traceId` or `correlationId` when available.
+ * - Auth/network/timeout/validation precedence is deterministic.
+ */
+declare function mapApiErrorToUiError(error: ApiErrorPayload): UiApiError;
+
+/**
+ * WHY:
+ * - Implements a simple namespaced i18n store for standalone shell environments.
+ * WHEN TO USE:
+ * - Use when features need runtime language switching and message registration in dev shell.
+ * WHEN NOT TO USE:
+ * - Do not use as a full ICU/message-format engine.
+ * INVARIANTS:
+ * - Translation lookup is deterministic by namespace insertion order.
+ * - Missing key falls back to the key itself.
+ * - Base namespace (`shell-dev`) cannot be unregistered.
+ */
 declare function createStandaloneI18nService(initialLang: Lang): I18nService;
 
-declare function createStandaloneUserService(user: User | null): UserService;
+type Claims = Record<string, unknown>;
+type MsalEventMessageLike = {
+    eventType?: string;
+    payload?: unknown;
+    error?: unknown;
+};
+type MsalLoginRequestLike = {
+    scopes?: string[];
+    loginHint?: string;
+    prompt?: string;
+    claims?: string;
+};
+type MsalSilentTokenRequestLike = {
+    scopes: string[];
+    account?: MsalAccountInfoLike;
+    forceRefresh?: boolean;
+    claims?: string;
+};
+type MsalPopupTokenRequestLike = {
+    scopes: string[];
+    account?: MsalAccountInfoLike;
+    claims?: string;
+    loginHint?: string;
+};
+type MsalTokenResponseLike = {
+    accessToken: string;
+    tokenType?: string;
+    scopes?: string[];
+    expiresOn?: Date | null;
+    idToken?: string;
+    idTokenClaims?: Claims;
+    account?: MsalAccountInfoLike | null;
+};
+type MsalLoginResponseLike = {
+    account?: MsalAccountInfoLike | null;
+    idToken?: string;
+    idTokenClaims?: Claims;
+};
+type MsalLogoutRequestLike = {
+    account?: MsalAccountInfoLike;
+    postLogoutRedirectUri?: string;
+};
+type MsalBrowserInstanceLike = {
+    getActiveAccount: () => MsalAccountInfoLike | null;
+    setActiveAccount?: (account: MsalAccountInfoLike | null) => void;
+    getAllAccounts: () => MsalAccountInfoLike[];
+    addEventCallback?: (callback: (message: MsalEventMessageLike) => void) => string | null;
+    removeEventCallback?: (callbackId: string) => void;
+    loginPopup?: (request?: MsalLoginRequestLike) => Promise<MsalLoginResponseLike>;
+    loginRedirect?: (request?: MsalLoginRequestLike) => Promise<void>;
+    logoutPopup?: (request?: MsalLogoutRequestLike) => Promise<void>;
+    logoutRedirect?: (request?: MsalLogoutRequestLike) => Promise<void>;
+    acquireTokenSilent: (request: MsalSilentTokenRequestLike) => Promise<MsalTokenResponseLike>;
+    acquireTokenPopup?: (request: MsalPopupTokenRequestLike) => Promise<MsalTokenResponseLike>;
+};
+type MsalInteractionMode = 'popup' | 'redirect';
+type CreateMsalUserServiceOptions = {
+    msal: MsalBrowserInstanceLike;
+    defaultScopes?: string[];
+    loginMode?: MsalInteractionMode;
+    logoutMode?: MsalInteractionMode;
+    mapUser?: (account: MsalAccountInfoLike) => User;
+    resolveAccount?: (accounts: MsalAccountInfoLike[]) => MsalAccountInfoLike | null;
+};
+/**
+ * WHY:
+ * - Implements shell `UserService` on top of MSAL browser APIs.
+ * WHEN TO USE:
+ * - Use in host shells that authenticate with Microsoft Entra/MSAL.
+ * WHEN NOT TO USE:
+ * - Do not use without valid MSAL instance contract implementation.
+ * INVARIANTS:
+ * - Access token acquisition prefers silent flow and falls back to popup when available.
+ * - Session snapshot always derives from current active/resolved account.
+ * - Event callback is attached only while there is at least one subscriber.
+ */
+declare function createMsalUserService(options: CreateMsalUserServiceOptions): UserService;
+
+type ReactRouterLocationLike = {
+    pathname: string;
+    search?: string;
+    hash?: string;
+    state?: unknown;
+    key?: string;
+};
+type ReactRouterNavigateFunctionLike = (to: NavigationTo | number, options?: Omit<NavigationNavigateOptions, 'source'>) => void;
+type ReactRouterCreateHrefFunctionLike = (to: NavigationTo) => string;
+type ReactRouterNavigationCapabilities = {
+    canGoBack?: boolean;
+    canGoForward?: boolean;
+    historyIndex?: number;
+};
+type CreateReactRouterNavigationAdapterOptions = {
+    initialLocation?: ReactRouterLocationLike;
+    initialAction?: NavigationAction;
+};
+type ReactRouterNavigationAdapter = {
+    service: NavigationService;
+    bindNavigator: (navigate: ReactRouterNavigateFunctionLike, createHref?: ReactRouterCreateHrefFunctionLike) => void;
+    clearNavigator: () => void;
+    syncFromRouter: (location: ReactRouterLocationLike, action: NavigationAction, capabilities?: ReactRouterNavigationCapabilities) => void;
+};
+/**
+ * WHY:
+ * - Bridges React Router navigation primitives into the shell `NavigationService` contract.
+ * WHEN TO USE:
+ * - Use when host app runs React Router and remote modules consume shell navigation service.
+ * WHEN NOT TO USE:
+ * - Do not use when navigation source is not React Router-like.
+ * INVARIANTS:
+ * - Adapter never throws when navigator functions are temporarily unavailable.
+ * - Snapshot updates emit only on meaningful state/location changes.
+ * - Location fields remain normalized for cross-module consistency.
+ */
+declare function createReactRouterNavigationAdapter(options?: CreateReactRouterNavigationAdapterOptions): ReactRouterNavigationAdapter;
+
+type CreateRequestContextServiceOptions = {
+    traceId?: string;
+    correlationId?: string;
+};
+/**
+ * WHY:
+ * - Holds request-scoped trace/correlation IDs and notifies consumers on mutation.
+ * WHEN TO USE:
+ * - Use as shared context service for API/realtime observability correlation.
+ * WHEN NOT TO USE:
+ * - Do not use as distributed trace store across processes.
+ * INVARIANTS:
+ * - `getSnapshot` returns a copy, never the mutable internal reference.
+ * - `update` emits only when values actually change.
+ * - `rotate` always regenerates both IDs.
+ */
+declare function createRequestContextService(options?: CreateRequestContextServiceOptions): RequestContextService;
+
+/**
+ * WHY:
+ * - Provides mock user/session/auth token behavior for standalone shell development.
+ * WHEN TO USE:
+ * - Use when integrating features against `UserService` without real identity provider.
+ * WHEN NOT TO USE:
+ * - Do not use as secure authentication provider in production.
+ * INVARIANTS:
+ * - Session state is derived directly from `currentUser` presence.
+ * - `login` is no-op when already authenticated.
+ * - `logout` clears user state and notifies subscribers.
+ */
+declare function createStandaloneUserService(seedUser: User | null): UserService;
 
-export { type ServiceRegisterMode, type StandaloneInitOptions, type StandaloneServices, createStandaloneApiClient, createStandaloneI18nService, createStandaloneUserService, initStandaloneServices };
+export { ApiError, type CreateMsalUserServiceOptions, type CreateReactRouterNavigationAdapterOptions, type CreateStandaloneApiClientOptions, type CreateStandaloneObservabilityServiceOptions, type CreateStandaloneRealtimeServiceOptions, type MsalBrowserInstanceLike, type ObservabilityTelemetryEvent, type ObservabilityTelemetrySink, type ReactRouterCreateHrefFunctionLike, type ReactRouterLocationLike, type ReactRouterNavigateFunctionLike, type ReactRouterNavigationAdapter, type ReactRouterNavigationCapabilities, type RealtimeReconnectOptions, type RealtimeTransport, type RealtimeTransportConnectContext, type ServiceRegisterMode, type StandaloneInitOptions, type StandaloneServices, type UiApiError, createMsalUserService, createReactRouterNavigationAdapter, createRequestContextService, createStandaloneApiClient, createStandaloneI18nService, createStandaloneRealtimeService, createStandaloneUserService, initStandaloneServices, isApiError, mapApiErrorToUiError };