@godxjp/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,78 @@
+# @godxjp/sdk
+
+Shared frontend infrastructure for GoDX products.
+
+Published for use by GoDX applications. The source repository is private; this package is the distribution.
+
+## Two layers, two owners
+
+Entries are split by **who owns the contract**, not by what happens to be duplicated. Duplication alone is not a reason to share code; a contract that two sides must agree on is.
+
+| Entry | Contents | Cadence |
+| --- | --- | --- |
+| `.` — not yet published | Platform contracts: permission DTO, tenant-scoped channel names | Binds every product at once |
+| `./laravel` | House conventions for Laravel + React: HTTP client, `ApiError` | Moves faster |
+| `./realtime` | Realtime seam: configuration, connection status, channel listeners | Moves faster |
+
+`.` is deliberately **absent from `exports`** until the contracts it would carry are agreed. An empty entry published for the sake of symmetry is the thing to avoid.
+
+## `./laravel`
+
+```ts
+import { createClient, ApiError } from '@godxjp/sdk/laravel';
+
+export const apiClient = createClient({
+    baseUrl: '/api/app/v1',
+    signInUrl: (returnTo) => `/login?return=${encodeURIComponent(returnTo)}`,
+});
+
+// A public API whose visitor has nowhere to sign in: omit `signInUrl`,
+// and a 401 is simply reported.
+export const publicApiClient = createClient({ baseUrl: '/api' });
+```
+
+Authentication is the session cookie, so a write sends the `XSRF-TOKEN` cookie back as the `X-XSRF-TOKEN` header, exactly as Laravel expects. Also handled: `key[]=a&key[]=b` for array query values and `1`/`0` for booleans, `204` resolving to `undefined`, `419` as an expired session, an unreachable server as `status: 0`, and upload progress over `XMLHttpRequest` because `fetch` cannot report it.
+
+A cancellation stays an `AbortError` and is never converted to an `ApiError` — TanStack Query tells a cancelled query from a failed one by exactly that.
+
+## `./realtime`
+
+```ts
+import {
+    configureRealtime,
+    isRealtimeConfigured,
+    useChannelEvent,
+    useRealtimeStatus,
+    useUserNotification,
+} from '@godxjp/sdk/realtime';
+```
+
+**Why the seam exists:** the transport underneath is expected to change. Putting the seam in first makes a later move one adapter in one package, rather than every listening component in every product.
+
+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.
+
+### Three words, not six
+
+```ts
+type RealtimeStatus = 'connecting' | 'connected' | 'unavailable';
+```
+
+`connecting` is the first state of **every** page load and says nothing yet — a screen must not start polling here, or every visit doubles its requests for the first second. `unavailable` means the client actually tried and is not live; that is the only state a fallback may fire on. The transport's `failed`, `unavailable` and `disconnected` all land there, because a screen has the same job in all three.
+
+An unrecognised state maps to `unavailable`, never `connected`. Guessing toward live would switch a polling fallback **off** and freeze the screen — the exact failure the fallback exists to prevent.
+
+### Configured is not connected
+
+`isRealtimeConfigured()` answers only "did `configureRealtime` run", and stays true for the life of the tab. Ask `useRealtimeStatus()` when you need to know whether anything is actually arriving. Reading the former as the latter leaves a screen frozen on whatever it loaded with while the server is down.
+
+### `useUserNotification` is separate 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.
+
+## Peer dependencies
+
+`./realtime` needs `@laravel/echo-react` and `react`. Both are optional peers: an application using only `./laravel` installs neither.
+
+## Licence
+
+Apache-2.0.

package/dist/laravel/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A request to a Laravel JSON API that did not succeed.
+ *
+ * Lives apart from `api-client.ts` (which re-exports it) so a query layer can
+ * recognise a failure — server-side field errors, the retry policy — without
+ * importing the module that issues requests.
+ *
+ * `status` is 0 when the server was never reached. It is also the field
+ * `@godxjp/ui/query`'s `classifyQueryError` reads, so `DataState` picks the
+ * right recovery (sign in, no access, retry) with no adapter.
+ */
+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 one place a consumer calls `fetch` (or, for an upload that reports
+ * progress, `XMLHttpRequest`).
+ *
+ * Authentication is the `web` session cookie, so a write carries the
+ * `XSRF-TOKEN` cookie back as `X-XSRF-TOKEN`, exactly as Laravel expects.
+ *
+ * THE PACKAGE DOES NOT KNOW WHERE SIGNING IN LIVES. The host passes
+ * `signInUrl`; a client without one simply reports the 401. That is the only
+ * difference from the implementation this was lifted from (godx-task), where
+ * the sign-in route was imported directly and a boolean chose whether to use
+ * it — which tied the client to one app's route file.
+ */
+type QueryValue = string | number | boolean | null | undefined;
+type ApiQuery = Record<string, QueryValue | QueryValue[]>;
+type RequestOptions = {
+    signal?: AbortSignal;
+};
+type GetOptions = RequestOptions & {
+    query?: ApiQuery;
+};
+type WriteOptions = RequestOptions & {
+    /**
+     * Upload progress, 0–100. `fetch` cannot report it, so a request that asks
+     * for progress goes out over `XMLHttpRequest` instead — same headers, same
+     * answers, same errors.
+     */
+    onUploadProgress?: (percent: number) => void;
+};
+type ClientConfig = {
+    /** Prefixed to every path, e.g. `/api/app/v1`. */
+    baseUrl: string;
+    /**
+     * Where to send the browser on a 401, given the path to come back to.
+     * Omitted for a public API whose visitor has nowhere to sign in.
+     */
+    signInUrl?: (returnTo: string) => string;
+};
+type ApiClient = {
+    get: <T>(path: string, options?: GetOptions) => Promise<T>;
+    post: <T>(path: string, body?: Body, options?: WriteOptions) => Promise<T>;
+    put: <T>(path: string, body?: Body, options?: WriteOptions) => Promise<T>;
+    patch: <T>(path: string, body?: Body, options?: WriteOptions) => Promise<T>;
+    delete: <T>(path: string, options?: GetOptions) => Promise<T>;
+};
+/** `FormData` goes out as multipart untouched; anything else is JSON-encoded. */
+type Body = FormData | object;
+/** Laravel reads `key[]=a&key[]=b` as an array and '1'/'0' as booleans. */
+declare function queryString(query: ApiQuery | undefined): string;
+/** First message per key — the one a field shows (`$errors->first()`). */
+declare function flattenErrors(errors: unknown): Record<string, string>;
+declare function createClient(config: ClientConfig): ApiClient;
+
+export { type ApiClient, ApiError, type ApiQuery, type ClientConfig, type GetOptions, type WriteOptions, createClient, flattenErrors, queryString };

package/dist/laravel/index.js

@@ -0,0 +1,182 @@
+// src/laravel/api-error.ts
+var ApiError = class extends Error {
+  status;
+  /** Laravel's `{errors: {field: string[]}}`, first message per key; `{}` when absent. */
+  errors;
+  constructor(status, message, errors = {}) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.errors = errors;
+  }
+};
+
+// src/laravel/api-client.ts
+var SESSION_EXPIRED = "Your session has expired. Reload the page and try again.";
+var UNREACHABLE = "Could not reach the server. Check your connection and try again.";
+var redirectingToSignIn = false;
+function readCookie(name) {
+  const prefix = `${name}=`;
+  const entry = document.cookie.split("; ").find((cookie) => cookie.startsWith(prefix));
+  return entry === void 0 ? void 0 : decodeURIComponent(entry.slice(prefix.length));
+}
+function queryString(query) {
+  if (query === void 0) {
+    return "";
+  }
+  const params = new URLSearchParams();
+  const encode = (value) => {
+    if (value === null || value === void 0) {
+      return void 0;
+    }
+    if (typeof value === "boolean") {
+      return value ? "1" : "0";
+    }
+    return String(value);
+  };
+  for (const [key, value] of Object.entries(query)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        const encoded2 = encode(item);
+        if (encoded2 !== void 0) {
+          params.append(`${key}[]`, encoded2);
+        }
+      }
+      continue;
+    }
+    const encoded = encode(value);
+    if (encoded !== void 0) {
+      params.append(key, encoded);
+    }
+  }
+  const text = params.toString();
+  return text === "" ? "" : `?${text}`;
+}
+function flattenErrors(errors) {
+  if (errors === null || typeof errors !== "object") {
+    return {};
+  }
+  const flat = {};
+  for (const [key, messages] of Object.entries(errors)) {
+    const first = Array.isArray(messages) ? messages[0] : messages;
+    if (typeof first === "string") {
+      flat[key] = first;
+    }
+  }
+  return flat;
+}
+function redirectToSignIn(signInUrl) {
+  if (redirectingToSignIn) {
+    return;
+  }
+  redirectingToSignIn = true;
+  const { pathname, search } = window.location;
+  window.location.assign(signInUrl(`${pathname}${search}`));
+}
+function send(url, init, onUploadProgress) {
+  if (onUploadProgress === void 0) {
+    return fetch(url, { ...init, credentials: "same-origin" }).then(
+      async (response) => ({
+        status: response.status,
+        statusText: response.statusText,
+        text: await response.text()
+      })
+    );
+  }
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const abort = () => xhr.abort();
+    xhr.open(init.method, url);
+    for (const [name, value] of Object.entries(init.headers)) {
+      xhr.setRequestHeader(name, value);
+    }
+    xhr.upload.onprogress = (event) => {
+      if (event.lengthComputable && event.total > 0) {
+        onUploadProgress(
+          Math.round(event.loaded / event.total * 100)
+        );
+      }
+    };
+    xhr.onload = () => {
+      init.signal?.removeEventListener("abort", abort);
+      resolve({
+        status: xhr.status,
+        statusText: xhr.statusText,
+        text: xhr.responseText
+      });
+    };
+    xhr.onerror = () => reject(new TypeError("Network request failed"));
+    xhr.onabort = () => reject(new DOMException("The request was aborted.", "AbortError"));
+    if (init.signal?.aborted) {
+      reject(new DOMException("The request was aborted.", "AbortError"));
+      return;
+    }
+    init.signal?.addEventListener("abort", abort, { once: true });
+    xhr.send(init.body ?? null);
+  });
+}
+async function request(config, method, path, body, { signal, query, onUploadProgress }) {
+  const headers = {
+    Accept: "application/json",
+    "X-Requested-With": "XMLHttpRequest"
+  };
+  const xsrfToken = readCookie("XSRF-TOKEN");
+  if (xsrfToken !== void 0) {
+    headers["X-XSRF-TOKEN"] = xsrfToken;
+  }
+  let payload;
+  if (body instanceof FormData) {
+    payload = body;
+  } else if (body !== void 0) {
+    headers["Content-Type"] = "application/json";
+    payload = JSON.stringify(body);
+  }
+  let response;
+  try {
+    response = await send(
+      `${config.baseUrl}${path}${queryString(query)}`,
+      { method, headers, body: payload, signal },
+      onUploadProgress
+    );
+  } catch (error) {
+    if (signal?.aborted) {
+      throw error;
+    }
+    throw new ApiError(0, UNREACHABLE);
+  }
+  if (response.status === 204) {
+    return void 0;
+  }
+  let json = void 0;
+  try {
+    json = response.text === "" ? void 0 : JSON.parse(response.text);
+  } catch {
+  }
+  if (response.status >= 200 && response.status < 300) {
+    return json;
+  }
+  const bag = json ?? {};
+  if (response.status === 401 && config.signInUrl !== void 0) {
+    redirectToSignIn(config.signInUrl);
+  }
+  if (response.status === 419) {
+    throw new ApiError(419, SESSION_EXPIRED);
+  }
+  throw new ApiError(
+    response.status,
+    typeof bag.message === "string" && bag.message !== "" ? bag.message : response.statusText,
+    flattenErrors(bag.errors)
+  );
+}
+function createClient(config) {
+  return {
+    get: (path, options = {}) => request(config, "GET", path, void 0, options),
+    post: (path, body, options = {}) => request(config, "POST", path, body, options),
+    put: (path, body, options = {}) => request(config, "PUT", path, body, options),
+    patch: (path, body, options = {}) => request(config, "PATCH", path, body, options),
+    /** `query` for what identifies the targets (`?ids[]=1&ids[]=2`). */
+    delete: (path, options = {}) => request(config, "DELETE", path, void 0, options)
+  };
+}
+
+export { ApiError, createClient, flattenErrors, queryString };

package/dist/realtime/index.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The realtime seam.
+ *
+ * WHY THIS EXISTS AT ALL: the transport under it is expected to change. The
+ * decision on file (`godx-task:debate/realtime-reverb-vs-centrifugo`) keeps
+ * Reverb for now and puts this seam in first, so a later move to another
+ * server is one adapter in one package rather than six files in each of four
+ * products.
+ *
+ * SO NOTHING FROM THE TRANSPORT MAY APPEAR HERE. No Echo type, no Pusher
+ * connection state, no channel object. A consumer that can name `pusher-js`
+ * has already defeated the point.
+ */
+/**
+ * What the connection can tell a screen, in three words rather than Pusher's
+ * six.
+ *
+ * `connecting` is the first state of every page load and says NOTHING yet — a
+ * screen must not fall back to polling on it. `unavailable` means the client
+ * actually tried and is not live, which is the only state a fallback may fire
+ * on. Pusher's `failed`, `unavailable` and `disconnected` all land there,
+ * 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 = {
+    /** The app key the server issued. */
+    key: string;
+    host: string;
+    port: number;
+    /** `https` turns on TLS and the `wss` transport. */
+    scheme: 'http' | 'https';
+};
+/**
+ * Map a transport's own vocabulary onto ours.
+ *
+ * Exported because it is the ONE piece of this module with behaviour worth
+ * pinning, and a hook is an awkward place to pin it from.
+ */
+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.
+ */
+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.
+ */
+declare function isRealtimeConfigured(): boolean;
+/** Liveness, in this package's three words rather than the transport's six. */
+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".
+ */
+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.
+ */
+declare function useUserNotification<T = unknown>(channel: string, handler: (payload: T) => void): void;
+
+export { type RealtimeConfig, type RealtimeStatus, configureRealtime, isRealtimeConfigured, toRealtimeStatus, useChannelEvent, useRealtimeStatus, useUserNotification };

package/dist/realtime/index.js

@@ -0,0 +1,41 @@
+import { configureEcho, echoIsConfigured, useConnectionStatus, useEcho, useEchoNotification } from '@laravel/echo-react';
+
+// src/realtime/echo-adapter.ts
+
+// src/realtime/types.ts
+function toRealtimeStatus(raw) {
+  if (raw === "connected") {
+    return "connected";
+  }
+  if (raw === "connecting" || raw === "initialized" || raw == null) {
+    return "connecting";
+  }
+  return "unavailable";
+}
+
+// src/realtime/echo-adapter.ts
+function configureRealtime(config) {
+  configureEcho({
+    broadcaster: "reverb",
+    key: config.key,
+    wsHost: config.host,
+    wsPort: config.port,
+    wssPort: config.port,
+    forceTLS: config.scheme === "https",
+    enabledTransports: ["ws", "wss"]
+  });
+}
+function isRealtimeConfigured() {
+  return echoIsConfigured();
+}
+function useRealtimeStatus() {
+  return toRealtimeStatus(useConnectionStatus());
+}
+function useChannelEvent(channel, event, handler, deps = []) {
+  useEcho(channel, event, handler, deps);
+}
+function useUserNotification(channel, handler) {
+  useEchoNotification(channel, handler);
+}
+
+export { configureRealtime, isRealtimeConfigured, toRealtimeStatus, useChannelEvent, useRealtimeStatus, useUserNotification };

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@godxjp/sdk",
+    "version": "0.1.0",
+    "description": "GoDX JavaScript SDK — shared frontend infrastructure for GoDX products.",
+    "license": "Apache-2.0",
+    "type": "module",
+    "sideEffects": false,
+    "files": [
+        "dist",
+        "LICENSE",
+        "README.md"
+    ],
+    "exports": {
+        "./laravel": {
+            "types": "./dist/laravel/index.d.ts",
+            "import": "./dist/laravel/index.js"
+        },
+        "./package.json": "./package.json",
+        "./realtime": {
+            "types": "./dist/realtime/index.d.ts",
+            "import": "./dist/realtime/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsup",
+        "types:check": "tsc --noEmit",
+        "test": "vitest run"
+    },
+    "devDependencies": {
+        "@laravel/echo-react": "^2.5.0",
+        "@types/node": "^22.10.2",
+        "@types/react": "^19.3.0",
+        "jsdom": "^25.0.1",
+        "laravel-echo": "^2.5.0",
+        "pusher-js": "^8.6.0",
+        "react": "^19.3.0",
+        "tsup": "^8.5.1",
+        "typescript": "^5.7.2",
+        "vitest": "^2.1.8"
+    },
+    "peerDependencies": {
+        "@laravel/echo-react": "^2.5.0",
+        "react": "^19.3.0"
+    },
+    "peerDependenciesMeta": {
+        "@laravel/echo-react": {
+            "optional": true
+        },
+        "react": {
+            "optional": true
+        }
+    }
+}