@dataemergencia/emergency 0.0.0-stage → 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,433 @@
+import { AxiosInstance } from "axios";
+import { StoreApi } from "zustand/vanilla";
+type EmergencyPhaseName = 'idle' | 'initializing' | 'ready' | 'activating' | 'simulating' | 'active' | 'refreshing' | 'aborting' | 'error';
+/**
+ * The lifecycle phase. It is a discriminated union so consumers can switch on
+ * `kind` and read the data that belongs to that phase without casting.
+ */
+type EmergencyPhase = {
+  kind: 'idle';
+} | {
+  kind: 'initializing';
+} | {
+  kind: 'ready';
+} | {
+  kind: 'activating';
+} | {
+  kind: 'simulating';
+} | {
+  kind: 'active';
+  emergencyId: string;
+  simulated: boolean;
+} | {
+  kind: 'refreshing';
+  emergencyId: string;
+} | {
+  kind: 'aborting';
+  emergencyId: string;
+} | {
+  kind: 'error';
+  error: EmergencyError;
+};
+type ResponderStatus = 'pending' | 'sent' | 'delivered' | 'read' | 'failed';
+interface ResponderMessage {
+  readonly content: string;
+  readonly sentAt: string | null;
+}
+interface Responder {
+  readonly phone: string;
+  readonly name: string;
+  readonly status: ResponderStatus;
+  readonly sent: boolean;
+  readonly delivered: boolean;
+  readonly read: boolean;
+  readonly failed: boolean;
+  readonly messageId: string | null;
+  readonly sentAt: string | null;
+  readonly deliveredAt: string | null;
+  readonly readAt: string | null;
+  readonly lastMessage: ResponderMessage | null;
+}
+interface EmergencyFailure {
+  readonly phone: string;
+  readonly message: string;
+  readonly status: number | null;
+}
+type MessageKind = 'info' | 'success' | 'warning' | 'error';
+interface Message {
+  readonly id: string;
+  readonly kind: MessageKind;
+  readonly text: string;
+  readonly createdAt: number;
+}
+declare const EMERGENCY_ERROR_CODES: readonly ["configuration", "network", "cancelled", "invalid_response", "invalid_transition", "destroyed", "geolocation_denied", "geolocation_unavailable", "geolocation_timeout", "geolocation_unsupported", "validation_failed", "invalid_code", "inactive_code", "unauthenticated", "csrf_failed", "cross_origin_denied", "rate_limited", "not_found", "method_not_allowed", "emergency_already_active", "emergency_forbidden", "emergency_not_found", "missing_emergency_contacts", "missing_medical_profile", "whatsapp_delivery_failed", "upstream_error", "internal_error", "emergency_error", "unknown"];
+type EmergencyErrorCode = (typeof EMERGENCY_ERROR_CODES)[number];
+interface EmergencyError {
+  readonly code: EmergencyErrorCode;
+  readonly message: string;
+  readonly status: number | null;
+  readonly requestId: string | null;
+  readonly details: unknown;
+  readonly cause: unknown;
+}
+interface EmergencyFallback {
+  readonly phone: string;
+  readonly label: string;
+}
+interface EmergencyTheme {
+  readonly accent?: string;
+  readonly accentContrast?: string;
+  readonly surface?: string;
+  readonly text?: string;
+  readonly muted?: string;
+  readonly radius?: string;
+}
+interface EmergencyFontFamilyFlags {
+  /** Loads the Google Sans family. Defaults to `true`. */
+  readonly googleSans?: boolean;
+  /** Loads the Montserrat family. Defaults to `true`. */
+  readonly montserrat?: boolean;
+  /** Loads the Poppins family. Defaults to `true`. */
+  readonly poppins?: boolean;
+}
+interface EmergencyFontLoading {
+  /** Master switch for the runtime font request. Defaults to `true`. */
+  readonly load?: boolean;
+  /** Per-family switches. Every family defaults to `true`. */
+  readonly fonts?: EmergencyFontFamilyFlags;
+}
+interface EmergencyGeolocation {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly accuracy?: number;
+}
+interface EmergencyConfig {
+  /** Full BFF route prefix, for example `https://example.com/de-bff/emergency`. */
+  readonly bffBaseUrl: string;
+  /** 6-character identity code supplied by the host. */
+  readonly code: string;
+  /** Optional phone number shown when geolocation or activation fails. */
+  readonly fallback?: EmergencyFallback;
+  /** Optional theme values mapped to `--de-emergency-*` CSS variables. */
+  readonly theme?: EmergencyTheme;
+  /**
+   * Optional runtime loading of the panel's Google Fonts. The client injects
+   * the stylesheet once, before the first paint. Defaults to loading every
+   * family.
+   */
+  readonly fontLoading?: EmergencyFontLoading;
+  /** BCP 47 locale used for dates and numbers. Defaults to `es`. */
+  readonly locale?: string;
+  /** Geolocation timeout in milliseconds. Defaults to 8000. */
+  readonly geolocationTimeoutMs?: number;
+  /** Request timeout in milliseconds. Defaults to 15000. */
+  readonly requestTimeoutMs?: number;
+}
+interface EmergencySnapshot {
+  readonly emergencyId: string;
+  readonly code: string | null;
+  readonly active: boolean;
+  readonly simulated: boolean;
+  readonly responders: readonly Responder[];
+  readonly createdAt: string | null;
+  readonly updatedAt: string | null;
+  readonly raw: Readonly<Record<string, unknown>>;
+}
+type EmergencyOperation = 'mount' | 'session' | 'resume' | 'activate' | 'simulate' | 'refresh' | 'abort' | 'geolocation' | 'realtime';
+type PanelOpenReason = 'trigger' | 'activate' | 'resume' | 'manual';
+type PanelCloseReason = 'escape' | 'close' | 'abort' | 'destroy' | 'manual';
+interface EmergencyEventMap {
+  'session:ready': {
+    readonly code: string;
+    readonly expiresIn: number;
+  };
+  'emergency:activated': {
+    readonly snapshot: EmergencySnapshot;
+  };
+  'emergency:simulated': {
+    readonly responders: readonly Responder[];
+    readonly failures: readonly EmergencyFailure[];
+  };
+  'emergency:resumed': {
+    readonly snapshot: EmergencySnapshot;
+  };
+  'emergency:updated': {
+    readonly snapshot: EmergencySnapshot;
+  };
+  'emergency:aborted': {
+    readonly emergencyId: string;
+    readonly responders: readonly Responder[];
+  };
+  'emergency:failed': {
+    readonly error: EmergencyError;
+    readonly operation: EmergencyOperation;
+  };
+  'emergency:fallback': {
+    readonly error: EmergencyError;
+    readonly fallback: EmergencyFallback | null;
+  };
+  'panel:opened': {
+    readonly reason: PanelOpenReason;
+  };
+  'panel:closed': {
+    readonly reason: PanelCloseReason;
+  };
+}
+type EmergencyEventName = keyof EmergencyEventMap;
+type EmergencyEventHandler<K extends EmergencyEventName> = (payload: EmergencyEventMap[K]) => void;
+type RealtimeStatus = 'idle' | 'connecting' | 'connected' | 'disconnected' | 'unavailable';
+interface AbortResult {
+  readonly ok: boolean;
+  readonly message: string;
+  readonly at: number;
+}
+interface SimulationResult {
+  readonly ok: boolean;
+  readonly message: string;
+  readonly at: number;
+}
+interface EmergencyClientState {
+  readonly config: EmergencyConfig;
+  readonly phase: EmergencyPhase;
+  readonly panelOpen: boolean;
+  readonly sessionReady: boolean;
+  readonly resumeAvailable: boolean;
+  readonly snapshot: EmergencySnapshot | null;
+  readonly responders: readonly Responder[];
+  readonly failures: readonly EmergencyFailure[];
+  readonly messages: readonly Message[];
+  readonly lastError: EmergencyError | null;
+  readonly geolocation: EmergencyGeolocation | null;
+  readonly geolocationError: EmergencyError | null;
+  readonly realtimeStatus: RealtimeStatus;
+  readonly abortResult: AbortResult | null;
+  readonly simulationResult: SimulationResult | null;
+  readonly abortConfirmation: boolean;
+  readonly simulationConfirmation: boolean;
+  readonly destroyed: boolean;
+}
+interface EmergencyClient {
+  open(reason?: PanelOpenReason): void;
+  close(reason?: PanelCloseReason): void;
+  destroy(): void;
+  getState(): EmergencyClientState;
+  subscribe(listener: (state: EmergencyClientState) => void): () => void;
+  on<K extends EmergencyEventName>(event: K, handler: EmergencyEventHandler<K>): () => void;
+  off<K extends EmergencyEventName>(event: K, handler: EmergencyEventHandler<K>): void;
+  ensureSession(): Promise<void>;
+  resume(): Promise<void>;
+  dismissResume(): void;
+  activate(): Promise<void>;
+  simulate(): Promise<void>;
+  refresh(): Promise<void>;
+  abort(): Promise<void>;
+  requestAbortConfirmation(): void;
+  cancelAbortConfirmation(): void;
+  requestSimulationConfirmation(): void;
+  cancelSimulationConfirmation(): void;
+  dismissFeedback(): void;
+}
+type EmergencyTrigger = string | HTMLElement | ((open: () => void) => void | (() => void));
+interface EmergencyMountOptions extends EmergencyConfig {
+  readonly root: HTMLElement | string;
+  readonly trigger?: EmergencyTrigger;
+  readonly onEvent?: <K extends EmergencyEventName>(event: K, payload: EmergencyEventMap[K]) => void;
+}
+/**
+ * Mounts the emergency client into a host element. Validation failures never
+ * throw into the host page: they produce a typed configuration error, a console
+ * message, and an inert client.
+ */
+export declare function mount(options: EmergencyMountOptions): EmergencyClient;
+interface RealtimePusherConfig {
+  readonly key: string;
+  readonly cluster: string;
+  readonly channel_pattern: string;
+}
+interface RealtimePublicConfig {
+  readonly mode: 'public';
+  readonly pusher: RealtimePusherConfig;
+}
+interface ConfigResponse {
+  readonly route_prefix: string;
+  readonly realtime: RealtimePublicConfig;
+  readonly csrf_token: string;
+}
+interface SessionResponse {
+  readonly code: string;
+  readonly csrf_token: string;
+  readonly expires_in: number;
+}
+interface ResponderMessagePayload {
+  readonly content?: string | null;
+  readonly sent_at?: string | null;
+}
+interface ResponderPayload {
+  readonly phone: string;
+  readonly name: string;
+  readonly sent: boolean;
+  readonly delivered: boolean;
+  readonly read: boolean;
+  readonly failed: boolean;
+  readonly message_id: string | null;
+  readonly sent_at?: string | null;
+  readonly delivered_at?: string | null;
+  readonly read_at?: string | null;
+  readonly last_messages?: readonly ResponderMessagePayload[] | null;
+}
+interface FailurePayload {
+  readonly phone: string;
+  readonly message: string;
+  readonly status?: number | null;
+}
+interface EmergencyResultPayload {
+  readonly emergency_id: string | null;
+  readonly simulated: boolean;
+  readonly responders: readonly ResponderPayload[];
+  readonly failures: readonly FailurePayload[];
+  readonly partial_failure?: boolean;
+  readonly total_failure?: boolean;
+}
+type EmergencyPayload = Readonly<Record<string, unknown>>;
+interface CurrentResponse {
+  readonly active: boolean;
+  readonly emergency: EmergencyPayload | null;
+  readonly realtime: RealtimePublicConfig;
+}
+interface GeolocationRequest {
+  readonly latitude: number;
+  readonly longitude: number;
+  readonly accuracy?: number;
+}
+interface ActivateRequest {
+  readonly geolocation?: GeolocationRequest;
+}
+interface RefreshResponse {
+  readonly emergency: EmergencyPayload;
+  readonly responders: readonly ResponderPayload[];
+}
+interface AbortResponse extends EmergencyResultPayload {
+  readonly deleted: boolean;
+}
+interface BffClient {
+  config(signal?: AbortSignal): Promise<ConfigResponse>;
+  session(code: string, signal?: AbortSignal): Promise<SessionResponse>;
+  current(signal?: AbortSignal): Promise<CurrentResponse>;
+  activate(request: ActivateRequest, signal?: AbortSignal, idempotencyKey?: string): Promise<EmergencyResultPayload>;
+  simulacrum(signal?: AbortSignal, idempotencyKey?: string): Promise<EmergencyResultPayload>;
+  refresh(emergencyId: string, signal?: AbortSignal): Promise<RefreshResponse>;
+  abort(emergencyId: string, signal?: AbortSignal): Promise<AbortResponse>;
+  destroy(): void;
+}
+interface CsrfStrategy {
+  readonly headerName: string;
+  read(): string | null;
+}
+interface MemoryCsrfStrategy extends CsrfStrategy {
+  setToken(token: string | null): void;
+}
+interface BffClientOptions {
+  /** Full BFF route prefix, for example `https://example.com/de-bff/emergency`. */
+  readonly bffBaseUrl: string;
+  readonly timeoutMs?: number;
+  readonly withCredentials?: boolean;
+  readonly csrf?: CsrfStrategy;
+  /**
+   * Redirects are disabled by default: the client sends the CSRF token on every
+   * request, and following a cross-origin redirect would hand it to another
+   * host.
+   */
+  readonly maxRedirects?: number;
+  /** Injection point for tests; the default is a configured axios instance. */
+  readonly axiosInstance?: AxiosInstance;
+  readonly generateIdempotencyKey?: () => string;
+}
+export declare function createMemoryCsrfStrategy(): MemoryCsrfStrategy;
+/**
+ * Laravel-compatible adapter. The core never assumes Laravel; a host that uses
+ * the `XSRF-TOKEN` cookie opts in by passing this strategy.
+ */
+export declare function createCookieCsrfStrategy(cookieName?: string): CsrfStrategy;
+export declare function createBffClient(options: BffClientOptions): BffClient;
+/**
+ * Typed, dependency-free event bus used by the controller and by `mount()`.
+ * DOM custom events are not used so the core stays framework agnostic.
+ */
+export declare const EMERGENCY_EVENT_NAMES: readonly EmergencyEventName[];
+declare class EmergencyEventEmitter {
+  private readonly handlers;
+  on<K extends EmergencyEventName>(event: K, handler: EmergencyEventHandler<K>): () => void;
+  off<K extends EmergencyEventName>(event: K, handler: EmergencyEventHandler<K>): void;
+  emit<K extends EmergencyEventName>(event: K, payload: EmergencyEventMap[K]): void;
+  clear(): void;
+}
+interface GeolocationProvider {
+  getCurrentPosition(timeoutMs: number): Promise<EmergencyGeolocation>;
+}
+export declare function createBrowserGeolocationProvider(): GeolocationProvider;
+interface RealtimeHandlers {
+  readonly onEvent: (channel: string, event: string, data: unknown) => void;
+  readonly onStatus: (status: RealtimeStatus) => void;
+}
+interface RealtimeSubscription {
+  disconnect(): void;
+}
+interface RealtimeProvider {
+  /**
+   * Subscribes to the public channels for the given responder phone numbers.
+   * Returns `null` when the realtime configuration is unusable, in which case
+   * the client keeps working in pull mode.
+   */
+  subscribe(config: RealtimePublicConfig, phones: readonly string[], handlers: RealtimeHandlers): RealtimeSubscription | null;
+}
+export declare function createPusherRealtimeProvider(): RealtimeProvider;
+type EmergencyStore = StoreApi<EmergencyClientState>;
+interface EmergencyControllerDeps {
+  readonly config: EmergencyConfig;
+  readonly bff?: ReturnType<typeof createBffClient>;
+  readonly geolocation?: GeolocationProvider;
+  readonly realtime?: RealtimeProvider;
+  readonly events?: EmergencyEventEmitter;
+}
+interface EmergencyController {
+  readonly client: EmergencyClient;
+  readonly store: EmergencyStore;
+  readonly events: EmergencyEventEmitter;
+}
+export declare function createEmergencyController(deps: EmergencyControllerDeps): EmergencyController;
+export declare const EMERGENCY_PHASE_NAMES: readonly EmergencyPhaseName[];
+/**
+ * Every allowed transition. `idle` is reachable from every phase so `destroy()`
+ * and a hard reset always leave the store in a known state.
+ */
+export declare const EMERGENCY_TRANSITIONS: Readonly<Record<EmergencyPhaseName, readonly EmergencyPhaseName[]>>;
+export declare function canTransition(from: EmergencyPhaseName, to: EmergencyPhaseName): boolean;
+export declare const EMERGENCY_CODE_PATTERN: RegExp;
+export declare function isValidEmergencyCode(code: string): boolean;
+export declare function normalizeBaseUrl(baseUrl: string): string;
+interface ConfigValidationResult {
+  readonly ok: boolean;
+  readonly error: EmergencyError | null;
+  readonly config: EmergencyConfig | null;
+}
+export declare function validateConfig(config: EmergencyConfig): ConfigValidationResult;
+export declare function themeToCssVariables(theme: EmergencyTheme | undefined): Record<string, string>;
+interface EmergencyErrorOptions {
+  status?: number | null;
+  requestId?: string | null;
+  details?: unknown;
+  cause?: unknown;
+}
+export declare function createEmergencyError(code: EmergencyErrorCode, message: string, options?: EmergencyErrorOptions): EmergencyError;
+export declare function isEmergencyError(value: unknown): value is EmergencyError;
+export declare function toEmergencyError(value: unknown, fallbackCode?: EmergencyErrorCode): EmergencyError;
+/**
+ * Error object accepted by host integrations that prefer `throw`/`catch` while
+ * the library still exposes the typed error through `.error`.
+ */
+export declare class EmergencyClientError extends Error {
+  readonly error: EmergencyError;
+  constructor(error: EmergencyError);
+}
+export type { AbortResponse, AbortResult, ActivateRequest, BffClient, BffClientOptions, ConfigResponse, CsrfStrategy, CurrentResponse, EmergencyClient, EmergencyClientState, EmergencyConfig, EmergencyController, EmergencyControllerDeps, EmergencyError, EmergencyErrorCode, EmergencyEventEmitter, EmergencyEventMap, EmergencyEventName, EmergencyFailure, EmergencyFallback, EmergencyFontFamilyFlags, EmergencyFontLoading, EmergencyGeolocation, EmergencyMountOptions, EmergencyOperation, EmergencyPhase, EmergencyPhaseName, EmergencyResultPayload, EmergencySnapshot, EmergencyStore, EmergencyTheme, EmergencyTrigger, FailurePayload, Message, MessageKind, PanelCloseReason, PanelOpenReason, RealtimeStatus, RefreshResponse, Responder, ResponderPayload, ResponderStatus, SessionResponse, SimulationResult };
+//# sourceMappingURL=index.d.cts.map