@arqel-dev/realtime 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arqel Contributors
+
+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,49 @@
+# @arqel-dev/realtime
+
+Helper de bootstrap do Laravel Echo para apps Arqel — configura WebSockets
+contra um servidor Laravel Reverb.
+
+## Instalação
+
+```bash
+pnpm add @arqel-dev/realtime
+```
+
+`laravel-echo` e `pusher-js` já vêm como dependências diretas.
+
+## Uso
+
+```ts
+// resources/js/app.tsx
+import { createArqelApp } from '@arqel-dev/react';
+import { setupEcho } from '@arqel-dev/realtime';
+
+setupEcho({
+  key: import.meta.env.VITE_REVERB_APP_KEY,
+  wsHost: import.meta.env.VITE_REVERB_HOST,
+  wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
+  wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
+  forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
+});
+
+createArqelApp();
+```
+
+Após o `setupEcho`, hooks de `@arqel-dev/hooks` (`useResourceUpdates`,
+`useResourcePresence`, etc.) usam o `window.Echo` automaticamente.
+
+## Características
+
+- **Idempotente** — pode ser chamado múltiplas vezes (útil para HMR).
+- **SSR-safe** — sem `window`, retorna no-op com warning.
+- **Tipos exportados** — `EchoLike`, `EchoChannelLike`,
+  `PresenceChannelLike` para uso em hooks customizados.
+
+## Documentação
+
+Veja `SKILL.md` neste pacote e o ticket RT-008 em
+`PLANNING/10-fase-3-avancadas.md`.
+
+## Licença
+
+MIT.

package/SKILL.md

@@ -0,0 +1,135 @@
+# SKILL.md — arqel-dev/realtime (JS)
+
+## Purpose
+
+Bootstrap do pipeline realtime do Arqel. Expõe `setupEcho(config)` —
+helper que instancia o Laravel Echo apontando para o broadcaster
+**Reverb** e anexa Pusher no `window`. É a única peça que conhece os
+pacotes `laravel-echo` e `pusher-js`; consumidores (apps Inertia, hooks
+em `@arqel-dev/hooks`) lidam apenas com o tipo `EchoLike`.
+
+O pacote **não** re-exporta hooks do `@arqel-dev/hooks`. Mantemos separado
+para code-splitting: quem só precisa de tipos não baixa Echo.
+
+## Key Contracts
+
+```ts
+import { setupEcho } from '@arqel-dev/realtime';
+
+setupEcho({
+  key: import.meta.env.VITE_REVERB_APP_KEY,
+  wsHost: import.meta.env.VITE_REVERB_HOST,
+  wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
+  wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
+  forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
+});
+```
+
+Tipos públicos exportados:
+
+- `EchoConfig` — shape aceito por `setupEcho`.
+- `EchoLike` — subset da instância Echo consumida pelos hooks.
+- `EchoChannelLike`, `PresenceChannelLike`, `PresenceMember` — formas
+  de canal que hooks (`useResourceUpdates`, `useResourcePresence`,
+  `useActionProgress`, `useWidgetRealtime`) podem assumir.
+- `EchoEventListener`, `EchoConnectorLike` — auxiliares.
+
+## Conventions
+
+- **Idempotente**: chamar `setupEcho` duas vezes não recria a instância
+  e emite `console.warn`. Útil para HMR.
+- **SSR-safe**: em ambientes sem `window` (Node SSR), retorna sem efeito
+  com warning — não lança.
+- **Broadcaster fixo em `'reverb'`**: o helper foi desenhado para
+  Reverb (que fala protocolo Pusher). Para usar Pusher hospedado direto,
+  consumidor pode instanciar Echo manualmente — `@arqel-dev/realtime` é
+  intencionalmente opinionated.
+- **Sem hooks aqui**: hooks moram em `@arqel-dev/hooks` para permitir que o
+  bundle do app só importe `setupEcho` se quiser.
+- TypeScript strict, sem `any` (apenas asserts pontuais nos pontos onde
+  o tipo do `laravel-echo` é overloaded e não casa com `EchoConfig`).
+- Lint: Biome (`pnpm lint`); testes: Vitest; build: tsup.
+
+## Examples
+
+```tsx
+// resources/js/app.tsx
+import { createArqelApp } from '@arqel-dev/react';
+import { setupEcho } from '@arqel-dev/realtime';
+
+setupEcho({
+  key: import.meta.env.VITE_REVERB_APP_KEY,
+  wsHost: import.meta.env.VITE_REVERB_HOST,
+  wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
+  wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
+  forceTLS: import.meta.env.VITE_REVERB_SCHEME === 'https',
+});
+
+createArqelApp();
+```
+
+Consumir o `window.Echo` em um hook custom usando os tipos publicados:
+
+```ts
+import type { EchoLike } from '@arqel-dev/realtime';
+
+function getEcho(): EchoLike | null {
+  if (typeof window === 'undefined') return null;
+  return (window as unknown as { Echo?: EchoLike }).Echo ?? null;
+}
+```
+
+## Anti-patterns
+
+- Chamar `setupEcho` dentro de componente React — deve ser invocado
+  uma única vez no bootstrap (`app.tsx`).
+- Importar `laravel-echo` ou `pusher-js` diretamente em código de app —
+  use o helper. Mantém upgrade path centralizado.
+- Re-exportar hooks aqui — quebra code-splitting; hooks ficam em
+  `@arqel-dev/hooks`.
+- Trocar o `broadcaster` para algo diferente de `'reverb'` neste helper —
+  se precisar Pusher direto, instancie Echo manualmente.
+
+## Connection resilience (RT-010)
+
+Além do `setupEcho`, o pacote expõe três utilitários para UX graceful
+quando o WebSocket cai:
+
+- `useConnectionStatus()` — hook que devolve
+  `{ status, lastConnectedAt, retryCount }` lendo os eventos do
+  `window.Echo.connector.pusher.connection`. SSR-safe (degrada para
+  `'unavailable'` quando `window.Echo` não aparece em até ~5s).
+- `useFallbackPolling({ enabled, intervalMs, only })` — quando
+  `enabled` é `true`, dispara `router.reload({ only })` periodicamente.
+  Útil para acionar durante disconnect e manter "near-realtime".
+- `<ConnectionStatusBanner />` — componente que combina ambos. Renderiza
+  `null` para `connected` e `unavailable`; em `disconnected` /
+  `connecting` / `failed` mostra um banner inline com `role="status"`
+  e `aria-live="polite"`.
+
+Exemplo típico no layout do panel:
+
+```tsx
+import { ConnectionStatusBanner } from '@arqel-dev/realtime';
+
+export function PanelLayout({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <ConnectionStatusBanner pollOnDisconnect pollOnly={['records']} />
+      {children}
+    </>
+  );
+}
+```
+
+`pollOnDisconnect` ativa o fallback Inertia apenas durante o estado
+`'disconnected'` (em `'connecting'` o Pusher já está negociando; em
+`'failed'` polling não resolve — usuário precisa de refresh).
+
+## Related
+
+- Tickets: `PLANNING/10-fase-3-avancadas.md` → RT-008, RT-010.
+- Hooks consumidores: `packages-js/hooks/src/useResource*` e
+  `useAction*`.
+- PHP backend: `packages/realtime` (RT-001 — broadcasting service
+  provider + Reverb config).

package/dist/index.d.ts

@@ -0,0 +1,192 @@
+import { ReactNode } from 'react';
+
+/**
+ * Estados possíveis da conexão WebSocket reportados pelo Pusher protocol
+ * (Reverb fala o mesmo protocolo).
+ *
+ * - `connected`    — handshake OK, recebendo eventos.
+ * - `connecting`   — tentando conectar (incluindo reconnect attempts).
+ * - `disconnected` — perdeu conexão temporariamente; Pusher tentará reconectar.
+ * - `failed`       — falhou definitivamente; navegador/transporte incompatível.
+ * - `unavailable`  — `window.Echo` ausente (SSR ou pacote não bootstrapado).
+ */
+type ConnectionStatus = 'connected' | 'connecting' | 'disconnected' | 'failed' | 'unavailable';
+interface ConnectionStatusValue {
+    status: ConnectionStatus;
+    /** Timestamp (ms) da última transição para `connected`. */
+    lastConnectedAt: number | null;
+    /** Quantas vezes a conexão saiu de `connected` desde o mount. */
+    retryCount: number;
+}
+/**
+ * Hook React que expõe o status atual da conexão WebSocket.
+ *
+ * SSR-safe: sem `window` ou sem `window.Echo`, retorna `'unavailable'`
+ * permanente. Quando `window.Echo` aparece tarde (boot async), o hook
+ * faz polling curto (≤5s) para se inscrever assim que disponível.
+ */
+declare function useConnectionStatus(): ConnectionStatusValue;
+
+interface ConnectionStatusBannerProps {
+    /**
+     * Quando `true` e o status é `'disconnected'`, ativa polling Inertia
+     * via `router.reload({ only: pollOnly })` enquanto durar o disconnect.
+     */
+    pollOnDisconnect?: boolean;
+    /** Intervalo do fallback polling (default 30s). */
+    pollIntervalMs?: number;
+    /** Props parciais a recarregar via Inertia. */
+    pollOnly?: string[];
+    /**
+     * Render customizado. Recebe o status atual e o número de retries desde
+     * o mount. Quando fornecido, substitui o banner default — mas o componente
+     * ainda retorna `null` para `connected` e `unavailable` antes de chamar
+     * `renderBanner`.
+     */
+    renderBanner?: (status: ConnectionStatus, retryCount: number) => ReactNode;
+    /** Classe CSS aplicada ao container default. */
+    className?: string;
+}
+/**
+ * Banner inline que mostra o estado da conexão WebSocket e (opcionalmente)
+ * dispara fallback polling Inertia quando o canal cai.
+ *
+ * Render rules:
+ * - `connected`   → null
+ * - `unavailable` → null (Echo não configurado; ignora silenciosamente)
+ * - outros        → `<Alert>` com variant mapeada por status
+ *
+ * O fallback polling só é ativado quando `pollOnDisconnect === true` e
+ * `status === 'disconnected'`. Em `connecting` / `failed` não polleamos
+ * (em `connecting` Pusher já está negociando; em `failed` polling não
+ * resolve — usuário precisa refresh).
+ */
+declare function ConnectionStatusBanner(props: ConnectionStatusBannerProps): ReactNode;
+
+/**
+ * Tipos públicos do Echo expostos para consumidores do `@arqel-dev/realtime`.
+ *
+ * Esses tipos são intencionalmente shape-based (não estruturais aos pacotes
+ * `laravel-echo` / `pusher-js`) para evitar acoplar a API pública do Arqel
+ * a versões internas. Hooks em `@arqel-dev/hooks` podem importar esses tipos
+ * sem precisar redeclarar `Window`.
+ */
+/**
+ * Listener handler usado em todas as subscrições de canal.
+ */
+type EchoEventListener = (payload: unknown) => void;
+/**
+ * Canal público / privado básico — o suficiente para `useResourceUpdates`,
+ * `useActionProgress`, `useWidgetRealtime`.
+ */
+interface EchoChannelLike {
+    listen: (event: string, callback: EchoEventListener) => EchoChannelLike;
+    stopListening: (event: string) => EchoChannelLike;
+    notification?: (callback: EchoEventListener) => EchoChannelLike;
+}
+/**
+ * Membro genérico de canal de presença.
+ */
+interface PresenceMember {
+    id: string | number;
+    info?: Record<string, unknown>;
+}
+/**
+ * Canal de presença — superset do canal privado.
+ */
+interface PresenceChannelLike extends EchoChannelLike {
+    here: (callback: (members: PresenceMember[]) => void) => PresenceChannelLike;
+    joining: (callback: (member: PresenceMember) => void) => PresenceChannelLike;
+    leaving: (callback: (member: PresenceMember) => void) => PresenceChannelLike;
+}
+/**
+ * Conector low-level — usado para hooks de auto-reconnect.
+ */
+interface EchoConnectorLike {
+    pusher?: {
+        connection?: {
+            bind: (event: string, callback: EchoEventListener) => void;
+            unbind?: (event: string, callback?: EchoEventListener) => void;
+            state?: string;
+        };
+    };
+}
+/**
+ * Subset minimo da instância do Laravel Echo que o Arqel consome.
+ *
+ * Hooks devem aceitar `EchoLike` e nunca depender de tipos internos do
+ * pacote `laravel-echo` — assim consumidores podem fornecer mocks ou
+ * implementações alternativas (por exemplo Soketi).
+ */
+interface EchoLike {
+    channel: (name: string) => EchoChannelLike;
+    private: (name: string) => EchoChannelLike;
+    join: (name: string) => PresenceChannelLike;
+    leave: (name: string) => void;
+    leaveChannel: (name: string) => void;
+    disconnect: () => void;
+    connector?: EchoConnectorLike;
+}
+/**
+ * Configuração aceita por `setupEcho`. Espelha a forma do construtor do
+ * Laravel Echo focada no broadcaster Reverb (que usa o protocolo Pusher).
+ */
+interface EchoConfig {
+    /** App key da Reverb / Pusher. */
+    key: string;
+    /** Host WebSocket (default `window.location.hostname`). */
+    wsHost?: string;
+    /** Porta WebSocket plain. */
+    wsPort?: number | string;
+    /** Porta WebSocket TLS. */
+    wssPort?: number | string;
+    /** Força TLS na conexão. */
+    forceTLS?: boolean;
+    /** Alias legacy de `forceTLS`. */
+    encrypted?: boolean;
+    /** Cluster Pusher (não usado pelo Reverb, mas aceito). */
+    cluster?: string;
+    /** Endpoint Laravel para auth de canais privados/presence. */
+    authEndpoint?: string;
+}
+
+/**
+ * Bootstrapa Laravel Echo + Pusher no `window`, configurado para o broadcaster
+ * Reverb (que fala o protocolo Pusher). Idempotente: chamadas subsequentes
+ * com `window.Echo` já populado são silenciosamente ignoradas (warning).
+ *
+ * Em ambiente SSR (sem `window`), retorna sem efeito — útil para builds
+ * Inertia que renderizam server-side.
+ *
+ * Uso típico em `resources/js/app.tsx`:
+ *
+ * ```ts
+ * setupEcho({
+ *   key: import.meta.env.VITE_REVERB_APP_KEY,
+ *   wsHost: import.meta.env.VITE_REVERB_HOST,
+ *   wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,
+ *   wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,
+ *   forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',
+ * });
+ * ```
+ */
+declare function setupEcho(config: EchoConfig): void;
+
+interface UseFallbackPollingOptions {
+    /** Quando `false` (default), o hook não faz nada. */
+    enabled?: boolean;
+    /** Intervalo entre `router.reload`s. Default 30s. */
+    intervalMs?: number;
+    /** Lista de props parciais para `router.reload({ only })`. */
+    only?: string[];
+}
+/**
+ * Hook que dispara `router.reload({ only })` periodicamente enquanto
+ * `enabled === true`. Pensado para ser ativado quando o WebSocket está
+ * desconectado, dando ao usuário um fallback de "near-realtime".
+ *
+ * SSR-safe: no-op quando `window` não existe.
+ */
+declare function useFallbackPolling(options?: UseFallbackPollingOptions): void;
+
+export { type ConnectionStatus, ConnectionStatusBanner, type ConnectionStatusBannerProps, type ConnectionStatusValue, type EchoChannelLike, type EchoConfig, type EchoConnectorLike, type EchoEventListener, type EchoLike, type PresenceChannelLike, type PresenceMember, type UseFallbackPollingOptions, setupEcho, useConnectionStatus, useFallbackPolling };

package/dist/index.js

@@ -0,0 +1,205 @@
+import { Alert, AlertDescription } from '@arqel-dev/ui';
+import { useState, useRef, useEffect } from 'react';
+import { router } from '@inertiajs/react';
+import { jsx } from 'react/jsx-runtime';
+import Echo from 'laravel-echo';
+import Pusher from 'pusher-js';
+
+// src/ConnectionStatusBanner.tsx
+function readEcho() {
+  if (typeof window === "undefined") return null;
+  const w = window;
+  return w.Echo ?? null;
+}
+function readConnection(echo) {
+  const connection = echo?.connector?.pusher?.connection;
+  if (!connection || typeof connection.bind !== "function") return null;
+  return connection;
+}
+var POLL_INTERVAL_MS = 250;
+var POLL_TIMEOUT_MS = 5e3;
+function useConnectionStatus() {
+  const [value, setValue] = useState(() => {
+    if (typeof window === "undefined") {
+      return { status: "unavailable", lastConnectedAt: null, retryCount: 0 };
+    }
+    const echo = readEcho();
+    const connection = readConnection(echo);
+    const initialState = connection?.state ?? "connecting";
+    return {
+      status: initialState === "connected" ? "connected" : "connecting",
+      lastConnectedAt: initialState === "connected" ? Date.now() : null,
+      retryCount: 0
+    };
+  });
+  const valueRef = useRef(value);
+  valueRef.current = value;
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    let disposed = false;
+    let pollTimer = null;
+    let pollDeadline = null;
+    let connection = null;
+    const handlers = [];
+    const transition = (next) => {
+      setValue((prev) => {
+        const wasConnected = prev.status === "connected";
+        const stillNotConnected = next !== "connected";
+        const incrementRetry = wasConnected && stillNotConnected;
+        return {
+          status: next,
+          lastConnectedAt: next === "connected" ? Date.now() : prev.lastConnectedAt,
+          retryCount: incrementRetry ? prev.retryCount + 1 : prev.retryCount
+        };
+      });
+    };
+    const subscribe = () => {
+      const echo = readEcho();
+      const conn = readConnection(echo);
+      if (!conn) return false;
+      connection = conn;
+      const events = [
+        "connected",
+        "connecting",
+        "disconnected",
+        "failed",
+        "unavailable"
+      ];
+      for (const event of events) {
+        const cb = () => {
+          if (disposed) return;
+          transition(event);
+        };
+        conn.bind(event, cb);
+        handlers.push({ event, cb });
+      }
+      if (conn.state === "connected" && valueRef.current.status !== "connected") {
+        transition("connected");
+      }
+      return true;
+    };
+    if (!subscribe()) {
+      pollTimer = setInterval(() => {
+        if (subscribe() && pollTimer) {
+          clearInterval(pollTimer);
+          pollTimer = null;
+          if (pollDeadline) {
+            clearTimeout(pollDeadline);
+            pollDeadline = null;
+          }
+        }
+      }, POLL_INTERVAL_MS);
+      pollDeadline = setTimeout(() => {
+        if (pollTimer) {
+          clearInterval(pollTimer);
+          pollTimer = null;
+        }
+        if (!disposed && valueRef.current.status === "connecting") {
+          transition("unavailable");
+        }
+      }, POLL_TIMEOUT_MS);
+    }
+    return () => {
+      disposed = true;
+      if (pollTimer) clearInterval(pollTimer);
+      if (pollDeadline) clearTimeout(pollDeadline);
+      if (connection?.unbind) {
+        for (const { event, cb } of handlers) {
+          connection.unbind(event, cb);
+        }
+      }
+    };
+  }, []);
+  return value;
+}
+var DEFAULT_INTERVAL_MS = 3e4;
+function useFallbackPolling(options = {}) {
+  const { enabled = false, intervalMs = DEFAULT_INTERVAL_MS, only } = options;
+  const onlyKey = only ? only.join(",") : "";
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    if (!enabled) return;
+    const onlyList = onlyKey ? onlyKey.split(",") : [];
+    const interval = setInterval(() => {
+      const reloadOptions = {};
+      if (onlyList.length > 0) {
+        reloadOptions.only = onlyList;
+      }
+      router.reload(reloadOptions);
+    }, intervalMs);
+    return () => {
+      clearInterval(interval);
+    };
+  }, [enabled, intervalMs, onlyKey]);
+}
+var DEFAULT_MESSAGES = {
+  connected: "",
+  connecting: "Connecting...",
+  disconnected: "Connection lost. Reconnecting...",
+  failed: "Connection failed. Refresh page.",
+  unavailable: ""
+};
+var STATUS_VARIANT = {
+  connected: "default",
+  connecting: "default",
+  disconnected: "default",
+  failed: "destructive",
+  unavailable: "default"
+};
+var STATUS_TONE = {
+  connected: "border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300",
+  connecting: "border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300",
+  disconnected: "border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300",
+  failed: "",
+  unavailable: ""
+};
+function ConnectionStatusBanner(props) {
+  const { pollOnDisconnect, pollIntervalMs, pollOnly, renderBanner, className } = props;
+  const { status, retryCount } = useConnectionStatus();
+  const pollingOptions = {
+    enabled: pollOnDisconnect === true && status === "disconnected"
+  };
+  if (pollIntervalMs !== void 0) pollingOptions.intervalMs = pollIntervalMs;
+  if (pollOnly !== void 0) pollingOptions.only = pollOnly;
+  useFallbackPolling(pollingOptions);
+  if (status === "connected" || status === "unavailable") {
+    return null;
+  }
+  if (renderBanner) {
+    return renderBanner(status, retryCount);
+  }
+  return /* @__PURE__ */ jsx(
+    Alert,
+    {
+      variant: STATUS_VARIANT[status],
+      role: "status",
+      "aria-live": "polite",
+      "data-status": status,
+      "data-arqel-connection-banner": "",
+      className: [STATUS_TONE[status], className].filter(Boolean).join(" "),
+      children: /* @__PURE__ */ jsx(AlertDescription, { children: DEFAULT_MESSAGES[status] })
+    }
+  );
+}
+function setupEcho(config) {
+  if (typeof window === "undefined") {
+    console.warn("[arqel-dev/realtime] setupEcho called in SSR context \u2014 skipping.");
+    return;
+  }
+  const w = window;
+  if (w.Echo) {
+    console.warn("[arqel-dev/realtime] window.Echo already initialized \u2014 skipping setupEcho.");
+    return;
+  }
+  w.Pusher = Pusher;
+  const echoOptions = {
+    broadcaster: "reverb",
+    ...config
+  };
+  const instance = new Echo(echoOptions);
+  w.Echo = instance;
+}
+
+export { ConnectionStatusBanner, setupEcho, useConnectionStatus, useFallbackPolling };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/useConnectionStatus.ts","../src/useFallbackPolling.ts","../src/ConnectionStatusBanner.tsx","../src/setupEcho.ts"],"names":["useEffect"],"mappings":"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","file":"index.js","sourcesContent":["import { useEffect, useRef, useState } from 'react';\nimport type { EchoLike } from './types';\n\n/**\n * Estados possíveis da conexão WebSocket reportados pelo Pusher protocol\n * (Reverb fala o mesmo protocolo).\n *\n * - `connected`    — handshake OK, recebendo eventos.\n * - `connecting`   — tentando conectar (incluindo reconnect attempts).\n * - `disconnected` — perdeu conexão temporariamente; Pusher tentará reconectar.\n * - `failed`       — falhou definitivamente; navegador/transporte incompatível.\n * - `unavailable`  — `window.Echo` ausente (SSR ou pacote não bootstrapado).\n */\nexport type ConnectionStatus =\n  | 'connected'\n  | 'connecting'\n  | 'disconnected'\n  | 'failed'\n  | 'unavailable';\n\nexport interface ConnectionStatusValue {\n  status: ConnectionStatus;\n  /** Timestamp (ms) da última transição para `connected`. */\n  lastConnectedAt: number | null;\n  /** Quantas vezes a conexão saiu de `connected` desde o mount. */\n  retryCount: number;\n}\n\ninterface PusherConnectionLike {\n  bind: (event: string, callback: (data?: unknown) => void) => void;\n  unbind?: (event: string, callback?: (data?: unknown) => void) => void;\n  state?: string;\n}\n\ninterface WindowWithEcho {\n  Echo?: EchoLike;\n}\n\nfunction readEcho(): EchoLike | null {\n  if (typeof window === 'undefined') return null;\n  const w = window as unknown as WindowWithEcho;\n  return w.Echo ?? null;\n}\n\nfunction readConnection(echo: EchoLike | null): PusherConnectionLike | null {\n  // biome-ignore lint/suspicious/noExplicitAny: pusher-js connection é genuinamente untyped no shape público\n  const connection = (echo?.connector as any)?.pusher?.connection;\n  if (!connection || typeof connection.bind !== 'function') return null;\n  return connection as PusherConnectionLike;\n}\n\nconst POLL_INTERVAL_MS = 250;\nconst POLL_TIMEOUT_MS = 5000;\n\n/**\n * Hook React que expõe o status atual da conexão WebSocket.\n *\n * SSR-safe: sem `window` ou sem `window.Echo`, retorna `'unavailable'`\n * permanente. Quando `window.Echo` aparece tarde (boot async), o hook\n * faz polling curto (≤5s) para se inscrever assim que disponível.\n */\nexport function useConnectionStatus(): ConnectionStatusValue {\n  const [value, setValue] = useState<ConnectionStatusValue>(() => {\n    if (typeof window === 'undefined') {\n      return { status: 'unavailable', lastConnectedAt: null, retryCount: 0 };\n    }\n    const echo = readEcho();\n    const connection = readConnection(echo);\n    const initialState = connection?.state ?? 'connecting';\n    return {\n      status: initialState === 'connected' ? 'connected' : 'connecting',\n      lastConnectedAt: initialState === 'connected' ? Date.now() : null,\n      retryCount: 0,\n    };\n  });\n\n  const valueRef = useRef(value);\n  valueRef.current = value;\n\n  useEffect(() => {\n    if (typeof window === 'undefined') return;\n\n    let disposed = false;\n    let pollTimer: ReturnType<typeof setInterval> | null = null;\n    let pollDeadline: ReturnType<typeof setTimeout> | null = null;\n    let connection: PusherConnectionLike | null = null;\n\n    const handlers: Array<{ event: string; cb: (data?: unknown) => void }> = [];\n\n    const transition = (next: ConnectionStatus) => {\n      setValue((prev) => {\n        // Conta retry quando saímos de `connected` para qualquer coisa não-conectada.\n        const wasConnected = prev.status === 'connected';\n        const stillNotConnected = next !== 'connected';\n        const incrementRetry = wasConnected && stillNotConnected;\n        return {\n          status: next,\n          lastConnectedAt: next === 'connected' ? Date.now() : prev.lastConnectedAt,\n          retryCount: incrementRetry ? prev.retryCount + 1 : prev.retryCount,\n        };\n      });\n    };\n\n    const subscribe = () => {\n      const echo = readEcho();\n      const conn = readConnection(echo);\n      if (!conn) return false;\n\n      connection = conn;\n\n      const events: ConnectionStatus[] = [\n        'connected',\n        'connecting',\n        'disconnected',\n        'failed',\n        'unavailable',\n      ];\n\n      for (const event of events) {\n        const cb = () => {\n          if (disposed) return;\n          // `unavailable` do Pusher significa \"transporte indisponível\" — mas\n          // mantemos o nosso `'unavailable'` para \"Echo ausente\". Mapeamos o\n          // evento Pusher unavailable para o estado homônimo (mesma semântica\n          // de UX: nada a fazer).\n          transition(event);\n        };\n        conn.bind(event, cb);\n        handlers.push({ event, cb });\n      }\n\n      // Caso já estejamos conectados quando subscrevemos, normaliza o estado.\n      if (conn.state === 'connected' && valueRef.current.status !== 'connected') {\n        transition('connected');\n      }\n\n      return true;\n    };\n\n    if (!subscribe()) {\n      // Echo ainda não disponível — polling curto até aparecer.\n      pollTimer = setInterval(() => {\n        if (subscribe() && pollTimer) {\n          clearInterval(pollTimer);\n          pollTimer = null;\n          if (pollDeadline) {\n            clearTimeout(pollDeadline);\n            pollDeadline = null;\n          }\n        }\n      }, POLL_INTERVAL_MS);\n\n      pollDeadline = setTimeout(() => {\n        if (pollTimer) {\n          clearInterval(pollTimer);\n          pollTimer = null;\n        }\n        if (!disposed && valueRef.current.status === 'connecting') {\n          // Não chegamos a subscrever; degrada para `unavailable`.\n          transition('unavailable');\n        }\n      }, POLL_TIMEOUT_MS);\n    }\n\n    return () => {\n      disposed = true;\n      if (pollTimer) clearInterval(pollTimer);\n      if (pollDeadline) clearTimeout(pollDeadline);\n      if (connection?.unbind) {\n        for (const { event, cb } of handlers) {\n          connection.unbind(event, cb);\n        }\n      }\n    };\n  }, []);\n\n  return value;\n}\n","import { router } from '@inertiajs/react';\nimport { useEffect } from 'react';\n\nexport interface UseFallbackPollingOptions {\n  /** Quando `false` (default), o hook não faz nada. */\n  enabled?: boolean;\n  /** Intervalo entre `router.reload`s. Default 30s. */\n  intervalMs?: number;\n  /** Lista de props parciais para `router.reload({ only })`. */\n  only?: string[];\n}\n\nconst DEFAULT_INTERVAL_MS = 30_000;\n\n/**\n * Hook que dispara `router.reload({ only })` periodicamente enquanto\n * `enabled === true`. Pensado para ser ativado quando o WebSocket está\n * desconectado, dando ao usuário um fallback de \"near-realtime\".\n *\n * SSR-safe: no-op quando `window` não existe.\n */\nexport function useFallbackPolling(options: UseFallbackPollingOptions = {}): void {\n  const { enabled = false, intervalMs = DEFAULT_INTERVAL_MS, only } = options;\n  // Serializa `only` para estabilidade no array de dependências —\n  // arrays inline criam nova referência a cada render. Em vez de listar\n  // `only` (que causaria re-execução indevida), listamos apenas `onlyKey`\n  // e reconstruímos a lista a partir dele dentro do efeito.\n  const onlyKey = only ? only.join(',') : '';\n\n  useEffect(() => {\n    if (typeof window === 'undefined') return;\n    if (!enabled) return;\n\n    const onlyList = onlyKey ? onlyKey.split(',') : [];\n\n    const interval = setInterval(() => {\n      const reloadOptions: { only?: string[] } = {};\n      if (onlyList.length > 0) {\n        reloadOptions.only = onlyList;\n      }\n      router.reload(reloadOptions);\n    }, intervalMs);\n\n    return () => {\n      clearInterval(interval);\n    };\n  }, [enabled, intervalMs, onlyKey]);\n}\n","import { Alert, AlertDescription } from '@arqel-dev/ui';\nimport type { ReactNode } from 'react';\nimport { type ConnectionStatus, useConnectionStatus } from './useConnectionStatus';\nimport { useFallbackPolling } from './useFallbackPolling';\n\nexport interface ConnectionStatusBannerProps {\n  /**\n   * Quando `true` e o status é `'disconnected'`, ativa polling Inertia\n   * via `router.reload({ only: pollOnly })` enquanto durar o disconnect.\n   */\n  pollOnDisconnect?: boolean;\n  /** Intervalo do fallback polling (default 30s). */\n  pollIntervalMs?: number;\n  /** Props parciais a recarregar via Inertia. */\n  pollOnly?: string[];\n  /**\n   * Render customizado. Recebe o status atual e o número de retries desde\n   * o mount. Quando fornecido, substitui o banner default — mas o componente\n   * ainda retorna `null` para `connected` e `unavailable` antes de chamar\n   * `renderBanner`.\n   */\n  renderBanner?: (status: ConnectionStatus, retryCount: number) => ReactNode;\n  /** Classe CSS aplicada ao container default. */\n  className?: string;\n}\n\nconst DEFAULT_MESSAGES: Record<ConnectionStatus, string> = {\n  connected: '',\n  connecting: 'Connecting...',\n  disconnected: 'Connection lost. Reconnecting...',\n  failed: 'Connection failed. Refresh page.',\n  unavailable: '',\n};\n\ntype AlertVariant = 'default' | 'destructive';\n\nconst STATUS_VARIANT: Record<ConnectionStatus, AlertVariant> = {\n  connected: 'default',\n  connecting: 'default',\n  disconnected: 'default',\n  failed: 'destructive',\n  unavailable: 'default',\n};\n\n// Tailwind classes layered on top of the Alert variant to convey\n// success/warning intent without extending shadcn's variant set.\nconst STATUS_TONE: Record<ConnectionStatus, string> = {\n  connected: 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300',\n  connecting: 'border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300',\n  disconnected: 'border-amber-500/30 bg-amber-500/10 text-amber-700 dark:text-amber-300',\n  failed: '',\n  unavailable: '',\n};\n\n/**\n * Banner inline que mostra o estado da conexão WebSocket e (opcionalmente)\n * dispara fallback polling Inertia quando o canal cai.\n *\n * Render rules:\n * - `connected`   → null\n * - `unavailable` → null (Echo não configurado; ignora silenciosamente)\n * - outros        → `<Alert>` com variant mapeada por status\n *\n * O fallback polling só é ativado quando `pollOnDisconnect === true` e\n * `status === 'disconnected'`. Em `connecting` / `failed` não polleamos\n * (em `connecting` Pusher já está negociando; em `failed` polling não\n * resolve — usuário precisa refresh).\n */\nexport function ConnectionStatusBanner(props: ConnectionStatusBannerProps): ReactNode {\n  const { pollOnDisconnect, pollIntervalMs, pollOnly, renderBanner, className } = props;\n  const { status, retryCount } = useConnectionStatus();\n\n  const pollingOptions: {\n    enabled: boolean;\n    intervalMs?: number;\n    only?: string[];\n  } = {\n    enabled: pollOnDisconnect === true && status === 'disconnected',\n  };\n  if (pollIntervalMs !== undefined) pollingOptions.intervalMs = pollIntervalMs;\n  if (pollOnly !== undefined) pollingOptions.only = pollOnly;\n  useFallbackPolling(pollingOptions);\n\n  if (status === 'connected' || status === 'unavailable') {\n    return null;\n  }\n\n  if (renderBanner) {\n    return renderBanner(status, retryCount);\n  }\n\n  return (\n    <Alert\n      variant={STATUS_VARIANT[status]}\n      role=\"status\"\n      aria-live=\"polite\"\n      data-status={status}\n      data-arqel-connection-banner=\"\"\n      className={[STATUS_TONE[status], className].filter(Boolean).join(' ')}\n    >\n      <AlertDescription>{DEFAULT_MESSAGES[status]}</AlertDescription>\n    </Alert>\n  );\n}\n","import Echo from 'laravel-echo';\nimport Pusher from 'pusher-js';\nimport type { EchoConfig, EchoLike } from './types';\n\n/**\n * Bootstrapa Laravel Echo + Pusher no `window`, configurado para o broadcaster\n * Reverb (que fala o protocolo Pusher). Idempotente: chamadas subsequentes\n * com `window.Echo` já populado são silenciosamente ignoradas (warning).\n *\n * Em ambiente SSR (sem `window`), retorna sem efeito — útil para builds\n * Inertia que renderizam server-side.\n *\n * Uso típico em `resources/js/app.tsx`:\n *\n * ```ts\n * setupEcho({\n *   key: import.meta.env.VITE_REVERB_APP_KEY,\n *   wsHost: import.meta.env.VITE_REVERB_HOST,\n *   wsPort: import.meta.env.VITE_REVERB_PORT ?? 80,\n *   wssPort: import.meta.env.VITE_REVERB_PORT ?? 443,\n *   forceTLS: (import.meta.env.VITE_REVERB_SCHEME ?? 'https') === 'https',\n * });\n * ```\n */\nexport function setupEcho(config: EchoConfig): void {\n  if (typeof window === 'undefined') {\n    // SSR: nada a fazer. Não usamos console.error pois não é erro real.\n    console.warn('[arqel-dev/realtime] setupEcho called in SSR context — skipping.');\n    return;\n  }\n\n  const w = window as unknown as {\n    Echo?: EchoLike;\n    Pusher?: typeof Pusher;\n  };\n\n  if (w.Echo) {\n    console.warn('[arqel-dev/realtime] window.Echo already initialized — skipping setupEcho.');\n    return;\n  }\n\n  // pusher-js anexa-se ao `window.Pusher` para uso interno do laravel-echo.\n  w.Pusher = Pusher;\n\n  const echoOptions = {\n    broadcaster: 'reverb' as const,\n    ...config,\n  };\n\n  // O construtor do Echo aceita o objeto de opções diretamente; o tipo do\n  // pacote `laravel-echo` é overloaded e não casa exatamente com nosso\n  // `EchoConfig`, então fazemos cast seguro para o subset que documentamos.\n  // biome-ignore lint/suspicious/noExplicitAny: laravel-echo overloads não casam com nosso EchoConfig\n  const instance = new Echo(echoOptions as any);\n\n  w.Echo = instance as unknown as EchoLike;\n}\n"]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@arqel-dev/realtime",
+  "version": "0.8.0",
+  "description": "Laravel Echo + Reverb setup helper para Arqel — bootstrap WebSocket realtime pipeline.",
+  "license": "MIT",
+  "homepage": "https://arqel.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arqel-dev/arqel.git",
+    "directory": "packages-js/realtime"
+  },
+  "keywords": [
+    "arqel",
+    "laravel",
+    "inertia",
+    "react",
+    "realtime",
+    "echo",
+    "reverb",
+    "websocket"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "dependencies": {
+    "laravel-echo": "^2.0.0",
+    "pusher-js": "^8.4.0"
+  },
+  "peerDependencies": {
+    "@inertiajs/react": "^3.0.0",
+    "react": "^19.2.0",
+    "@arqel-dev/ui": "0.8.0"
+  },
+  "devDependencies": {
+    "@inertiajs/react": "^3.0.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.0.0",
+    "@arqel-dev/ui": "0.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check --diagnostic-level=error src tests",
+    "format": "biome format --write src tests",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}