@godxjp/sdk 0.3.0 → 0.5.0

package/README.md

@@ -99,11 +99,20 @@ export const apiClient = createClient({
   // On a 401, before `signInUrl`: resolve `true` and the request is sent once
   // more; resolve `false` and the 401 takes its usual course. Never more than
   // one retry per request, and 401s that arrive together share one call.
-  onUnauthorized: () => tokens.refresh(),
+  // `ctx` is the request that was answered 401 — method, URL and the headers
+  // it was sent with — so a login that failed is not mistaken for an expired
+  // token.
+  onUnauthorized: ({ headers }) =>
+    headers.Authorization === undefined
+      ? Promise.resolve(false)
+      : tokens.refresh(),
+  // A request that never reached the server: `ApiError` with status 0 by
+  // default ("wrap"); "throw" rethrows fetch's own `TypeError`.
+  networkErrors: "throw",
 });
 ```
 
-A request body is always JSON text or `FormData`, never a stream, so it can be sent a second time. A request cancelled while the token was refreshed stays an `AbortError`.
+A request body is always JSON text or `FormData`, never a stream, so it can be sent a second time. A request cancelled while the token was refreshed stays an `AbortError`, whatever `networkErrors` says.
 
 ### Downloading a file
 
@@ -129,10 +138,23 @@ createClient({
 });
 ```
 
+Everything else the server sent is on `ApiError.body` — the parsed JSON, or `undefined` when there was none, it was not JSON, or the server was never reached. Read an `error` code, a `message` that is not a string, or every message per field from there:
+
+```ts
+if (error instanceof ApiError) {
+  const { error: code, errors } = (error.body ?? {}) as {
+    error?: string;
+    errors?: Record<string, string[]>;
+  };
+}
+```
+
 An unreachable server (`status: 0`) keeps its built-in text, `Could not reach the server. Check your connection and try again.`, unless `messages(0)` answers one.
 
 **Changed in 0.3.0.** Before, a 419 always carried `Your session has expired. Reload the page and try again.` and a response without a message fell back to `statusText`. Both are now the server's message or empty. To keep the old 419 text, pass `messages: (status) => status === 419 ? "Your session has expired. Reload the page and try again." : undefined`.
 
+**Changed in 0.4.0.** Additions only; a client configured for 0.3.0 sends and throws exactly what it did. `ApiError` gains `body` (also on a `download()` failure). `onUnauthorized` now receives the request that was answered 401 (`{ method, url, headers }`); a function that takes no argument still works. `networkErrors: "throw"` rethrows `fetch`'s own error instead of `ApiError(0)` — including a response body that breaks off mid-way.
+
 ## `./realtime`
 
 ```ts
@@ -149,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/laravel/index.d.ts

@@ -13,7 +13,14 @@ declare class ApiError extends Error {
     readonly status: number;
     /** Laravel's `{errors: {field: string[]}}`, first message per key; `{}` when absent. */
     readonly errors: Record<string, string>;
-    constructor(status: number, message: string, errors?: Record<string, string>);
+    /**
+     * The error response's body, parsed as JSON — everything `message` and
+     * `errors` leave out: an `error` code, a `message` that is not a string,
+     * every message per field. `undefined` when there was no body, it was not
+     * JSON, or the server was never reached.
+     */
+    readonly body: unknown;
+    constructor(status: number, message: string, errors?: Record<string, string>, body?: unknown);
 }
 
 /**
@@ -57,6 +64,14 @@ type DownloadResult = {
     headers: Headers;
     status: number;
 };
+/** The request a 401 answered, as `onUnauthorized` receives it. */
+type UnauthorizedContext = {
+    method: string;
+    /** The full URL, `baseUrl` and query string included. */
+    url: string;
+    /** Exactly the headers the request was sent with. */
+    headers: Record<string, string>;
+};
 type ClientConfig = {
     /** Prefixed to every path, e.g. `/api/app/v1`. */
     baseUrl: string;
@@ -81,9 +96,22 @@ type ClientConfig = {
      * Called on a 401 before `signInUrl`. Resolve `true` (a token was refreshed,
      * say) and the request is sent once more, headers read afresh; resolve
      * `false` and the 401 takes its usual course. A request is retried at most
-     * once, and 401s that arrive together share one call.
+     * once, and 401s that arrive together share one call — made with the
+     * context of the request that started it.
+     *
+     * `ctx` describes the request that was answered 401, with the headers it
+     * was actually sent with — so a host can refresh only when that request
+     * carried a token.
+     */
+    onUnauthorized?: (ctx: UnauthorizedContext) => Promise<boolean>;
+    /**
+     * What a request that never reached the server throws. `wrap` (the
+     * default) turns it into `ApiError` with status `0`; `throw` rethrows what
+     * `fetch` threw (a `TypeError`), for a host that tells a network failure
+     * from an HTTP one by exactly that. A cancelled request is an `AbortError`
+     * either way.
      */
-    onUnauthorized?: () => Promise<boolean>;
+    networkErrors?: "wrap" | "throw";
     /**
      * The message for an `ApiError` whose response carried none — the client
      * has no language of its own. Unset, or answering `undefined`, leaves
@@ -115,4 +143,4 @@ declare function queryString(query: ApiQuery | undefined): string;
 declare function flattenErrors(errors: unknown): Record<string, string>;
 declare function createClient(config: ClientConfig): ApiClient;
 
-export { type ApiClient, ApiError, type ApiQuery, type ClientConfig, type DownloadOptions, type DownloadResult, type GetOptions, type WriteOptions, createClient, flattenErrors, queryString };
+export { type ApiClient, ApiError, type ApiQuery, type ClientConfig, type DownloadOptions, type DownloadResult, type GetOptions, type UnauthorizedContext, type WriteOptions, createClient, flattenErrors, queryString };

package/dist/laravel/index.js

@@ -3,11 +3,19 @@ var ApiError = class extends Error {
   status;
   /** Laravel's `{errors: {field: string[]}}`, first message per key; `{}` when absent. */
   errors;
-  constructor(status, message, errors = {}) {
+  /**
+   * The error response's body, parsed as JSON — everything `message` and
+   * `errors` leave out: an `error` code, a `message` that is not a string,
+   * every message per field. `undefined` when there was no body, it was not
+   * JSON, or the server was never reached.
+   */
+  body;
+  constructor(status, message, errors = {}, body) {
     super(message);
     this.name = "ApiError";
     this.status = status;
     this.errors = errors;
+    this.body = body;
   }
 };
 
@@ -112,7 +120,10 @@ function send(url, init, onUploadProgress) {
     xhr.send(init.body ?? null);
   });
 }
-function unreachable(config) {
+function unreachable(config, error) {
+  if (config.networkErrors === "throw") {
+    return error;
+  }
   return new ApiError(0, config.messages?.(0) ?? UNREACHABLE);
 }
 async function read(response, as, config, signal) {
@@ -122,7 +133,7 @@ async function read(response, as, config, signal) {
     if (signal?.aborted) {
       throw error;
     }
-    throw unreachable(config);
+    throw unreachable(config, error);
   }
 }
 async function exchange({ config, unauthorized }, method, path, body, { signal, query, onUploadProgress }, retried = false) {
@@ -142,10 +153,11 @@ async function exchange({ config, unauthorized }, method, path, body, { signal,
     payload = JSON.stringify(body);
   }
   Object.assign(headers, await config.headers?.());
+  const url = `${config.baseUrl}${path}${queryString(query)}`;
   let response;
   try {
     response = await send(
-      `${config.baseUrl}${path}${queryString(query)}`,
+      url,
       {
         method,
         headers,
@@ -159,12 +171,12 @@ async function exchange({ config, unauthorized }, method, path, body, { signal,
     if (signal?.aborted) {
       throw error;
     }
-    throw unreachable(config);
+    throw unreachable(config, error);
   }
   if (response.status >= 200 && response.status < 300) {
     return response;
   }
-  if (response.status === 401 && !retried && config.onUnauthorized !== void 0 && await unauthorized()) {
+  if (response.status === 401 && !retried && config.onUnauthorized !== void 0 && await unauthorized({ method, url, headers: { ...headers } })) {
     return exchange(
       { config, unauthorized },
       method,
@@ -187,7 +199,8 @@ async function exchange({ config, unauthorized }, method, path, body, { signal,
   throw new ApiError(
     response.status,
     typeof bag.message === "string" && bag.message !== "" ? bag.message : config.messages?.(response.status) ?? "",
-    flattenErrors(bag.errors)
+    flattenErrors(bag.errors),
+    json
   );
 }
 async function request(client, method, path, body, options) {
@@ -206,7 +219,7 @@ function createClient(config) {
   let refreshing;
   const client = {
     config,
-    unauthorized: () => refreshing ??= (config.onUnauthorized?.() ?? Promise.resolve(false)).finally(() => {
+    unauthorized: (ctx) => refreshing ??= (config.onUnauthorized?.(ctx) ?? Promise.resolve(false)).finally(() => {
       refreshing = void 0;
     })
   };

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.3.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"