@godxjp/sdk 0.4.0 → 0.5.0

package/README.md

@@ -171,6 +171,27 @@ import {
 
 So nothing from the transport appears in this API — no Echo type, no Pusher connection state, no channel object. A consumer able to name the underlying client has already defeated the point.
 
+### Two transports
+
+```ts
+// The product's own Reverb, as before (a config without `driver`):
+configureRealtime({ key, host, port, scheme });
+
+// The platform's Centrifugo, on the socket the GoDX Dock already holds (godx-jp/id#2019):
+configureRealtime({
+  driver: "godx-dock",
+  channelPrefix: `private-svc.${clientId}.`,
+  authEndpoint: "/broadcasting/auth",
+});
+```
+
+With `godx-dock` the server publishes through php-sdk's `godx` broadcast driver, and this package
+listens through `window.GodxDock.realtime()`. The Dock lends only a narrow `subscribe` for
+`private-svc.*` channels, never its client. Channel and event names stay the product's own
+(`issue.7`, `.issue.changed`). The subscription token comes from `authEndpoint`, so your
+`routes/channels.php` still decides. A page with no Dock, no session or no Centrifugo reports
+`unavailable`, and your polling fallback takes over.
+
 ### Three words, not six
 
 ```ts

package/dist/realtime/index.d.ts

@@ -22,8 +22,9 @@
  * because a screen has the same job in all three.
  */
 type RealtimeStatus = "connecting" | "connected" | "unavailable";
-/** What the host must hand over to reach its own server. */
-type RealtimeConfig = {
+/** A product's own Reverb server — what every config meant before `driver` existed. */
+type ReverbRealtimeConfig = {
+    driver?: "reverb";
     /** The app key the server issued. */
     key: string;
     host: string;
@@ -31,6 +32,19 @@ type RealtimeConfig = {
     /** `https` turns on TLS and the `wss` transport. */
     scheme: "http" | "https";
 };
+/**
+ * The platform's Centrifugo, over the socket the GoDX Dock already holds (godx-jp/id#2019). The
+ * server side is php-sdk's `godx` broadcast driver.
+ */
+type DockRealtimeConfig = {
+    driver: "godx-dock";
+    /** `private-svc.{client_id}.` — where the platform relay puts every channel of this service. */
+    channelPrefix: string;
+    /** The product's own channel authorization endpoint, usually `/broadcasting/auth`. */
+    authEndpoint: string;
+};
+/** What the host must hand over to reach its realtime server. */
+type RealtimeConfig = ReverbRealtimeConfig | DockRealtimeConfig;
 /**
  * Map a transport's own vocabulary onto ours.
  *
@@ -39,44 +53,28 @@ type RealtimeConfig = {
  */
 declare function toRealtimeStatus(raw: string | null | undefined): RealtimeStatus;
 
-/**
- * The Echo/Pusher adapter — today's transport, and the only file in this
- * package that may import it.
- */
 /**
  * Wire the connection once, for the life of the tab.
  *
- * The host reads its own server's details wherever it keeps them (a meta tag,
- * an API call) and passes them in. The SDK does not guess: `import.meta.env`
- * belongs to whoever runs the bundler, and four products do not share one.
+ * The host reads its own server's details wherever it keeps them (a meta tag, an API call) and
+ * passes them in. A config without `driver` is the product's own Reverb, as before.
  */
 declare function configureRealtime(config: RealtimeConfig): void;
 /**
- * Whether `configureRealtime` ran.
- *
- * CONFIGURED IS NOT CONNECTED, and conflating them is a real bug this project
- * has already shipped once: a screen that reads "configured" as "live" keeps
- * its polling fallback switched off while the server is down, and freezes on
- * whatever it loaded with. Ask `useRealtimeStatus()` for liveness.
+ * Whether `configureRealtime` ran. CONFIGURED IS NOT CONNECTED: ask `useRealtimeStatus()` for
+ * liveness.
  */
 declare function isRealtimeConfigured(): boolean;
-/** Liveness, in this package's three words rather than the transport's six. */
+/** Liveness, in this package's three words rather than the transport's own. */
 declare function useRealtimeStatus(): RealtimeStatus;
 /**
- * Listen to one named event on one channel.
- *
- * `event` is the name the server broadcasts, leading dot and all — the
- * transport's convention for "this is our own event, not a framework one".
+ * Listen to one named event on one private channel. `event` is the name the server broadcasts,
+ * leading dot and all.
  */
 declare function useChannelEvent<T = unknown>(channel: string, event: string, handler: (payload: T) => void, deps?: unknown[]): void;
 /**
- * Listen to a user's notification channel.
- *
- * SEPARATE FROM `useChannelEvent` ON PURPOSE. Laravel broadcasts every
- * notification under one framework event name, so subscribing by a custom name
- * succeeds and then never fires — a failure that presents as "connected but
- * nothing happens". Naming the two cases apart is what stops the next person
- * reaching for the wrong one.
+ * Listen to a user's notification channel. SEPARATE FROM `useChannelEvent` ON PURPOSE: Laravel
+ * broadcasts every notification under one framework event name.
  */
 declare function useUserNotification<T = unknown>(channel: string, handler: (payload: T) => void): void;
 
@@ -113,4 +111,4 @@ declare function platformChannel(resource: string, resourceId: string): ChannelN
 declare function parseChannelName(name: string): ParsedChannelName;
 declare function tryParseChannelName(name: string): ParsedChannelName | null;
 
-export { type ChannelName, ChannelNameError, type ParsedChannelName, type RealtimeConfig, type RealtimeStatus, configureRealtime, isRealtimeConfigured, organizationChannel, parseChannelName, platformChannel, toRealtimeStatus, tryParseChannelName, useChannelEvent, useRealtimeStatus, useUserNotification };
+export { type ChannelName, ChannelNameError, type DockRealtimeConfig, type ParsedChannelName, type RealtimeConfig, type RealtimeStatus, type ReverbRealtimeConfig, configureRealtime, isRealtimeConfigured, organizationChannel, parseChannelName, platformChannel, toRealtimeStatus, tryParseChannelName, useChannelEvent, useRealtimeStatus, useUserNotification };

package/dist/realtime/index.js

@@ -1,6 +1,128 @@
+import { useSyncExternalStore, useRef, useEffect } from 'react';
 import { configureEcho, echoIsConfigured, useConnectionStatus, useEcho, useEchoNotification } from '@laravel/echo-react';
 
-// src/realtime/echo-adapter.ts
+// src/realtime/dock-adapter.ts
+var NOTIFICATION_EVENT = "Illuminate\\Notifications\\Events\\BroadcastNotificationCreated";
+var config = null;
+var dock = null;
+function configureDockRealtime(next) {
+  config = next;
+  dock = null;
+}
+function isDockRealtimeConfigured() {
+  return config !== null;
+}
+function dockRealtime() {
+  dock ??= new Promise((resolve) => {
+    const found = () => window.GodxDock ?? null;
+    if (found() !== null || document.readyState === "complete") {
+      resolve(found());
+    } else {
+      window.addEventListener("load", () => resolve(found()), { once: true });
+    }
+  }).then((global) => global?.realtime === void 0 ? null : global.realtime());
+  return dock;
+}
+function readCookie(name) {
+  const match = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
+  return match?.[1] === void 0 ? null : decodeURIComponent(match[1]);
+}
+async function subscriptionToken(channel) {
+  const active = config;
+  if (active === null) {
+    throw new Error("realtime is not configured");
+  }
+  const xsrf = readCookie("XSRF-TOKEN");
+  const response = await fetch(active.authEndpoint, {
+    method: "POST",
+    credentials: "same-origin",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      ...xsrf === null ? {} : { "X-XSRF-TOKEN": xsrf }
+    },
+    body: JSON.stringify({ channel_name: `private-${channel}` })
+  });
+  if (!response.ok) {
+    throw new Error(`channel authorization refused (${response.status})`);
+  }
+  const data = await response.json();
+  if (typeof data.token !== "string") {
+    throw new Error("channel authorization answered without a token");
+  }
+  return data.token;
+}
+function literal(event) {
+  return event.startsWith(".") ? event.slice(1) : event;
+}
+function useDockSubscription(channel, event, handler, deps) {
+  const latest = useRef(handler);
+  latest.current = handler;
+  useEffect(() => {
+    const active = config;
+    if (active === null) {
+      return;
+    }
+    let stop = null;
+    let cancelled = false;
+    const wanted = literal(event);
+    void dockRealtime().then((realtime) => {
+      if (realtime === null || cancelled) {
+        return;
+      }
+      stop = realtime.subscribe(`${active.channelPrefix}${channel}`, {
+        getToken: () => subscriptionToken(channel),
+        onPublication: (name, data) => {
+          if (name === wanted) {
+            latest.current(data);
+          }
+        }
+      });
+    });
+    return () => {
+      cancelled = true;
+      stop?.();
+    };
+  }, [channel, event, ...deps]);
+}
+function useDockChannelEvent(channel, event, handler, deps) {
+  useDockSubscription(channel, event, handler, deps);
+}
+function useDockUserNotification(channel, handler) {
+  useDockSubscription(channel, NOTIFICATION_EVENT, handler, []);
+}
+var status = "connecting";
+var statusListeners = /* @__PURE__ */ new Set();
+var watching = false;
+function watchStatus() {
+  if (watching || config === null) {
+    return;
+  }
+  watching = true;
+  void dockRealtime().then((realtime) => {
+    const set = (next) => {
+      status = next;
+      statusListeners.forEach((listener) => listener());
+    };
+    if (realtime === null) {
+      set("unavailable");
+      return;
+    }
+    set(realtime.status());
+    realtime.onStatus(set);
+  });
+}
+function useDockRealtimeStatus() {
+  return useSyncExternalStore(
+    (listener) => {
+      statusListeners.add(listener);
+      watchStatus();
+      return () => statusListeners.delete(listener);
+    },
+    () => status,
+    () => "connecting"
+  );
+}
 
 // src/realtime/types.ts
 function toRealtimeStatus(raw) {
@@ -14,30 +136,62 @@ function toRealtimeStatus(raw) {
 }
 
 // src/realtime/echo-adapter.ts
-function configureRealtime(config) {
+function configureEchoRealtime(config2) {
   configureEcho({
     broadcaster: "reverb",
-    key: config.key,
-    wsHost: config.host,
-    wsPort: config.port,
-    wssPort: config.port,
-    forceTLS: config.scheme === "https",
+    key: config2.key,
+    wsHost: config2.host,
+    wsPort: config2.port,
+    wssPort: config2.port,
+    forceTLS: config2.scheme === "https",
     enabledTransports: ["ws", "wss"]
   });
 }
-function isRealtimeConfigured() {
+function isEchoRealtimeConfigured() {
   return echoIsConfigured();
 }
-function useRealtimeStatus() {
+function useEchoRealtimeStatus() {
   return toRealtimeStatus(useConnectionStatus());
 }
-function useChannelEvent(channel, event, handler, deps = []) {
+function useEchoChannelEvent(channel, event, handler, deps = []) {
   useEcho(channel, event, handler, deps);
 }
-function useUserNotification(channel, handler) {
+function useEchoUserNotification(channel, handler) {
   useEchoNotification(channel, handler);
 }
 
+// src/realtime/select.ts
+var driver = "reverb";
+function configureRealtime(config2) {
+  if (config2.driver === "godx-dock") {
+    driver = "godx-dock";
+    configureDockRealtime(config2);
+    return;
+  }
+  driver = "reverb";
+  configureEchoRealtime(config2);
+}
+function isRealtimeConfigured() {
+  return driver === "godx-dock" ? isDockRealtimeConfigured() : isEchoRealtimeConfigured();
+}
+function useRealtimeStatus() {
+  return driver === "godx-dock" ? useDockRealtimeStatus() : useEchoRealtimeStatus();
+}
+function useChannelEvent(channel, event, handler, deps = []) {
+  if (driver === "godx-dock") {
+    useDockChannelEvent(channel, event, handler, deps);
+  } else {
+    useEchoChannelEvent(channel, event, handler, deps);
+  }
+}
+function useUserNotification(channel, handler) {
+  if (driver === "godx-dock") {
+    useDockUserNotification(channel, handler);
+  } else {
+    useEchoUserNotification(channel, handler);
+  }
+}
+
 // src/realtime/channel-name.ts
 var ChannelNameError = class extends Error {
   constructor(message) {

package/package.json

@@ -1,8 +1,16 @@
 {
     "name": "@godxjp/sdk",
-    "version": "0.4.0",
+    "version": "0.5.0",
     "description": "GoDX JavaScript SDK \u2014 shared frontend infrastructure for GoDX products.",
     "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/godx-jp/web-sdk.git"
+    },
+    "homepage": "https://github.com/godx-jp/web-sdk#readme",
+    "bugs": {
+        "url": "https://github.com/godx-jp/web-sdk/issues"
+    },
     "type": "module",
     "sideEffects": false,
     "files": [
@@ -36,10 +44,12 @@
         "@laravel/echo-react": "^2.5.0",
         "@types/node": "^22.10.2",
         "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
         "jsdom": "^25.0.1",
         "laravel-echo": "^2.5.0",
         "pusher-js": "^8.6.0",
         "react": "^19.3.0",
+        "react-dom": "^19.3.0",
         "tsup": "^8.5.1",
         "typescript": "^5.7.2",
         "vitest": "^2.1.8"