@godxjp/sdk 0.1.0 → 0.3.0

package/README.md

@@ -8,43 +8,141 @@ Published for use by GoDX applications. The source repository is private; this p
 
 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 |
+| Entry        | Contents                                                           | Cadence                     |
+| ------------ | ------------------------------------------------------------------ | --------------------------- |
+| `.`          | 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.
+## Scope — what belongs here, and what does not
+
+Entries are decided by **who owns the contract**, not by what happens to be duplicated in two products. Duplication is a symptom; a contract that two sides must agree on is the criterion.
+
+The question for any candidate: **is it a shared integration contract owned by the platform, with more than one real consumer, no product-specific workflow, and explicit safety, recovery and compatibility semantics?**
+
+### In scope
+
+| Area                             | What the package carries                                                                                              | Why it qualifies                                                                                                                                                                                                              |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| HTTP transport for Laravel hosts | `createClient`, `ApiError`, query encoding, CSRF header, upload progress                                              | Every Laravel + React product needs the identical transport. Two of them had thirty-five raw `fetch()` call sites each hand-rolling headers and error handling                                                                |
+| Realtime seam                    | Configuration, connection status, channel and notification listeners                                                  | The transport underneath is expected to change; the seam is what keeps that change to one adapter                                                                                                                             |
+| Channel names                    | Branded `ChannelName`, parser, org- and platform-scoped forms                                                         | Two-sided contract with the PHP SDK. Both sides must produce and read the identical string                                                                                                                                    |
+| Identity snapshot for the UI     | The `/me` shape as a **branded snapshot type** carrying `authoritative: false`, reachable only through one parse gate | The same hook was copied between two products and has already drifted into incompatible role shapes. The PHP side already marks the equivalent call "display snapshot only"; the type is where that has to become unavoidable |
+
+### Out of scope
+
+| Area                                                                                                                         | Why not                                                                                                                                                                                                                               |
+| ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Anything that stores platform identity** — organization, branch, brand or user rows written into a consumer's own database | The identity a request carries is request-scoped. A stored copy is a second source of truth that goes stale silently, and consumer paths depending on a stored organization id are a known defect class, not a pattern to standardise |
+| **Business-domain state**, including a projection table that can be rebuilt from events                                      | A projection still carries product semantics, schema and lifecycle. Rebuildable is not the same as contract-owned                                                                                                                     |
+| **Product workflow** — what a notification means, which query to invalidate, what a screen does when an event arrives        | The package delivers the event; the product decides what it means. A mapping from event to query key belongs to the application                                                                                                       |
+| **Generic React utilities** that happen to be identical in two products                                                      | Byte-identical duplication is not a contract. Utilities with no platform meaning stay in the products or in the design system                                                                                                         |
+| **Design-system concerns** — components, styling, tokens                                                                     | `@godxjp/ui` owns those. The core of this package must run in a service with no DOM                                                                                                                                                   |
+
+### Rules that follow from the split
+
+- **The core has no DOM, no React, no CSS and no framework.** `./realtime` and any future `./react` entry declare their peers as optional, so a headless service can install the package and use the HTTP client alone.
+- **A DTO published here is a snapshot for the interface, never authorization evidence.** The server re-checks authority on every request regardless of what the client believes.
+- **Two-sided contracts are proven by a shared fixture set**, run through both implementations and compared line by line. Two suites passing separately does not show that two sides agree.
+
+## `.` — platform contracts
+
+```ts
+import {
+  mayShow,
+  parseUiPermissionSnapshot,
+  tryParseUiPermissionSnapshot,
+  type UiPermissionSnapshot,
+} from "@godxjp/sdk";
+```
+
+The `/me` response is a **display snapshot**, not authorization evidence. `parseUiPermissionSnapshot` is the only way to obtain a `UiPermissionSnapshot`; the branded type cannot be forged with `as`. The parser always sets `authoritative: false`, even if the wire payload claims otherwise — a hostile or broken server cannot upgrade what the UI believes into something the type treats as authoritative.
+
+Wire shape: `user` (`id` as number, `name`, `email`), `permissions` (string array, may be empty), `roles` (string array — not `{ slug }` objects). Unknown top-level fields are ignored so the contract can grow without breaking older clients.
+
+Use `mayShow(snapshot, permission)` only to decide whether a surface may appear in the UI; the server re-checks authority on every request. There are no `can` / `authorize` helpers on this entry — naming that implies client-side authorization is deliberately absent.
+
+Legacy Inertia page props with `roles: [{ slug }]` are normalized at the product boundary via `src/identity/inertia-adapter.ts` (not re-exported from `.`).
 
 ## `./laravel`
 
 ```ts
-import { createClient, ApiError } from '@godxjp/sdk/laravel';
+import { createClient, ApiError } from "@godxjp/sdk/laravel";
 
 export const apiClient = createClient({
-    baseUrl: '/api/app/v1',
-    signInUrl: (returnTo) => `/login?return=${encodeURIComponent(returnTo)}`,
+  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' });
+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.
 
+### Other ways to authenticate
+
+Every option below is optional; left out, the client behaves exactly as described above.
+
+```ts
+export const apiClient = createClient({
+  baseUrl: "https://api.example.com/v1",
+  // Read before every request — and again before a retry — so a token
+  // refreshed a moment ago is the one that goes out. Wins over the defaults.
+  headers: async () => ({ Authorization: `Bearer ${await tokens.access()}` }),
+  // `fetch` credentials mode, `same-origin` by default. `include` also sets
+  // `withCredentials` on an upload that goes out over XHR.
+  credentials: "include",
+  // 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(),
+});
+```
+
+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`.
+
+### Downloading a file
+
+```ts
+const { blob, headers, status } = await apiClient.download("/exports", {
+  method: "POST", // "GET" unless given
+  body: { ids: [1, 2] },
+  query: { format: "csv" },
+});
+const disposition = headers.get("Content-Disposition");
+```
+
+Same headers, XSRF header, retry and errors as every other method: a 4xx, a 419 or an unreachable server is still an `ApiError`.
+
+### Error messages
+
+`ApiError.message` is the server's `message` when it sent a non-empty one. Otherwise it comes from `messages`, or is empty — the client has no language of its own, and never uses `statusText`, which HTTP/2 does not send.
+
+```ts
+createClient({
+  baseUrl: "/api",
+  messages: (status) => (status === 419 ? t("session.expired") : undefined),
+});
+```
+
+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`.
+
 ## `./realtime`
 
 ```ts
 import {
-    configureRealtime,
-    isRealtimeConfigured,
-    useChannelEvent,
-    useRealtimeStatus,
-    useUserNotification,
-} from '@godxjp/sdk/realtime';
+  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.
@@ -54,7 +152,7 @@ So nothing from the transport appears in this API — no Echo type, no Pusher co
 ### Three words, not six
 
 ```ts
-type RealtimeStatus = 'connecting' | 'connected' | 'unavailable';
+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.
@@ -69,6 +167,15 @@ An unrecognised state maps to `unavailable`, never `connected`. Guessing toward
 
 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.
 
+### Channel names (PHP contract)
+
+Realtime channels use a fixed shape so the JS client and the PHP broadcaster never disagree on a string:
+
+- Organization scope: `org.{orgId}.{resource}.{resourceId}` — `orgId` and `resourceId` are `[A-Za-z0-9_-]+`; `resource` is lowercase `[a-z][a-z0-9-]*` (e.g. `issue`, `test-run`).
+- Platform scope: `platform.{resource}.{resourceId}` — same `resource` / `resourceId` rules; no fake org prefix for cross-tenant traffic.
+
+Build with `organizationChannel` / `platformChannel`, parse with `parseChannelName` or `tryParseChannelName`. The `ChannelName` brand is for compile-time safety only — it does not stop a client from subscribing to arbitrary strings. The server must always enforce user → organization → resource → authorization.
+
 ## Peer dependencies
 
 `./realtime` needs `@laravel/echo-react` and `react`. Both are optional peers: an application using only `./laravel` installs neither.

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Display-only permission snapshot from `/me` — not evidence the server will honor.
+ *
+ * Types here catch programmer mistakes only; a client can still send arbitrary
+ * requests. The server must re-check authority on every call regardless of what
+ * the UI believes.
+ */
+/** Only values produced by the parse gate carry this brand; `as` is not validation. */
+type UiPermissionSnapshot = {
+    readonly authoritative: false;
+    readonly user: {
+        readonly id: number;
+        readonly name: string;
+        readonly email: string;
+    };
+    readonly permissions: readonly string[];
+    readonly roles: readonly string[];
+} & {
+    readonly __brand: "UiPermissionSnapshot";
+};
+declare class UiPermissionSnapshotError extends Error {
+    constructor(message: string);
+}
+declare function parseUiPermissionSnapshot(raw: unknown): UiPermissionSnapshot;
+declare function tryParseUiPermissionSnapshot(raw: unknown): UiPermissionSnapshot | null;
+/**
+ * Whether the UI may show a surface gated by `permission`. This reads the
+ * display snapshot only; the server re-checks authority on every request.
+ */
+declare function mayShow(snapshot: UiPermissionSnapshot, permission: string): boolean;
+
+export { type UiPermissionSnapshot, UiPermissionSnapshotError, mayShow, parseUiPermissionSnapshot, tryParseUiPermissionSnapshot };

package/dist/index.js

@@ -0,0 +1,86 @@
+// src/identity/me.ts
+var UiPermissionSnapshotError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UiPermissionSnapshotError";
+  }
+};
+function brandUiPermissionSnapshot(snapshot) {
+  return snapshot;
+}
+function assertPlainObject(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new UiPermissionSnapshotError("snapshot must be a plain object");
+  }
+  return raw;
+}
+function assertUser(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new UiPermissionSnapshotError("user must be an object");
+  }
+  const record = raw;
+  const { id, name, email } = record;
+  if (typeof id !== "number" || !Number.isFinite(id)) {
+    throw new UiPermissionSnapshotError("user.id must be a finite number");
+  }
+  if (typeof name !== "string") {
+    throw new UiPermissionSnapshotError("user.name must be a string");
+  }
+  if (typeof email !== "string") {
+    throw new UiPermissionSnapshotError("user.email must be a string");
+  }
+  return { id, name, email };
+}
+function assertStringArray(field, raw) {
+  if (!Array.isArray(raw)) {
+    throw new UiPermissionSnapshotError(`${field} must be an array`);
+  }
+  const result = [];
+  for (let index = 0; index < raw.length; index += 1) {
+    const item = raw[index];
+    if (typeof item !== "string") {
+      throw new UiPermissionSnapshotError(
+        `${field}[${index}] must be a string`
+      );
+    }
+    result.push(item);
+  }
+  return result;
+}
+function parseUiPermissionSnapshot(raw) {
+  const record = assertPlainObject(raw);
+  if (!("user" in record)) {
+    throw new UiPermissionSnapshotError("user is required");
+  }
+  const user = assertUser(record.user);
+  if (!("permissions" in record)) {
+    throw new UiPermissionSnapshotError("permissions is required");
+  }
+  const permissions = assertStringArray("permissions", record.permissions);
+  if (!("roles" in record)) {
+    throw new UiPermissionSnapshotError("roles is required");
+  }
+  const roles = assertStringArray("roles", record.roles);
+  const authoritative = false;
+  return brandUiPermissionSnapshot({
+    authoritative,
+    user,
+    permissions,
+    roles
+  });
+}
+function tryParseUiPermissionSnapshot(raw) {
+  try {
+    return parseUiPermissionSnapshot(raw);
+  } catch (error) {
+    if (error instanceof UiPermissionSnapshotError) {
+      return null;
+    }
+    throw error;
+  }
+}
+function mayShow(snapshot, permission) {
+  return snapshot.permissions.includes(permission);
+}
+
+export { UiPermissionSnapshotError, mayShow, parseUiPermissionSnapshot, tryParseUiPermissionSnapshot };

package/dist/laravel/index.d.ts

@@ -45,6 +45,18 @@ type WriteOptions = RequestOptions & {
      */
     onUploadProgress?: (percent: number) => void;
 };
+type DownloadOptions = RequestOptions & {
+    /** `GET` unless given. A `POST` carries the XSRF header like any write. */
+    method?: "GET" | "POST";
+    body?: Body;
+    query?: ApiQuery;
+};
+/** A binary response, with the headers a screen reads the file name from. */
+type DownloadResult = {
+    blob: Blob;
+    headers: Headers;
+    status: number;
+};
 type ClientConfig = {
     /** Prefixed to every path, e.g. `/api/app/v1`. */
     baseUrl: string;
@@ -53,6 +65,31 @@ type ClientConfig = {
      * Omitted for a public API whose visitor has nowhere to sign in.
      */
     signInUrl?: (returnTo: string) => string;
+    /**
+     * Extra headers, read again before EVERY request (and before a retry), so a
+     * bearer token refreshed a moment ago is the one that goes out. Applied
+     * after the defaults, so a header named here wins.
+     */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /**
+     * `fetch` credentials mode; `same-origin` unless given. `include` is what a
+     * cross-origin API behind a cookie needs, and also turns on
+     * `withCredentials` for an upload that goes out over XHR.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * 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.
+     */
+    onUnauthorized?: () => Promise<boolean>;
+    /**
+     * The message for an `ApiError` whose response carried none — the client
+     * has no language of its own. Unset, or answering `undefined`, leaves
+     * `message` empty; status `0` then keeps its built-in text.
+     */
+    messages?: (status: number) => string | undefined;
 };
 type ApiClient = {
     get: <T>(path: string, options?: GetOptions) => Promise<T>;
@@ -60,8 +97,17 @@ type ApiClient = {
     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>;
+    /**
+     * The response as a `Blob` plus its headers, through the same error
+     * handling as every other method: a failure is still an `ApiError`.
+     */
+    download: (path: string, options?: DownloadOptions) => Promise<DownloadResult>;
 };
-/** `FormData` goes out as multipart untouched; anything else is JSON-encoded. */
+/**
+ * `FormData` goes out as multipart untouched; anything else is JSON-encoded.
+ * Either way the payload can be sent twice, which is what makes the retry
+ * after `onUnauthorized` safe — a stream body is never produced.
+ */
 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;
@@ -69,4 +115,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 GetOptions, type WriteOptions, createClient, flattenErrors, queryString };
+export { type ApiClient, ApiError, type ApiQuery, type ClientConfig, type DownloadOptions, type DownloadResult, type GetOptions, type WriteOptions, createClient, flattenErrors, queryString };

package/dist/laravel/index.js

@@ -12,7 +12,6 @@ var ApiError = class extends Error {
 };
 
 // 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) {
@@ -75,35 +74,33 @@ function redirectToSignIn(signInUrl) {
 }
 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 fetch(url, init);
   }
   return new Promise((resolve, reject) => {
     const xhr = new XMLHttpRequest();
     const abort = () => xhr.abort();
     xhr.open(init.method, url);
+    xhr.withCredentials = init.credentials === "include";
     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)
-        );
+        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
-      });
+      const empty = xhr.responseText === "" || [204, 205, 304].includes(xhr.status);
+      try {
+        resolve(
+          new Response(empty ? null : xhr.responseText, {
+            status: xhr.status
+          })
+        );
+      } catch (error) {
+        reject(error);
+      }
     };
     xhr.onerror = () => reject(new TypeError("Network request failed"));
     xhr.onabort = () => reject(new DOMException("The request was aborted.", "AbortError"));
@@ -115,7 +112,20 @@ function send(url, init, onUploadProgress) {
     xhr.send(init.body ?? null);
   });
 }
-async function request(config, method, path, body, { signal, query, onUploadProgress }) {
+function unreachable(config) {
+  return new ApiError(0, config.messages?.(0) ?? UNREACHABLE);
+}
+async function read(response, as, config, signal) {
+  try {
+    return await response[as]();
+  } catch (error) {
+    if (signal?.aborted) {
+      throw error;
+    }
+    throw unreachable(config);
+  }
+}
+async function exchange({ config, unauthorized }, method, path, body, { signal, query, onUploadProgress }, retried = false) {
   const headers = {
     Accept: "application/json",
     "X-Requested-With": "XMLHttpRequest"
@@ -131,51 +141,93 @@ async function request(config, method, path, body, { signal, query, onUploadProg
     headers["Content-Type"] = "application/json";
     payload = JSON.stringify(body);
   }
+  Object.assign(headers, await config.headers?.());
   let response;
   try {
     response = await send(
       `${config.baseUrl}${path}${queryString(query)}`,
-      { method, headers, body: payload, signal },
+      {
+        method,
+        headers,
+        body: payload,
+        signal,
+        credentials: config.credentials ?? "same-origin"
+      },
       onUploadProgress
     );
   } catch (error) {
     if (signal?.aborted) {
       throw error;
     }
-    throw new ApiError(0, UNREACHABLE);
+    throw unreachable(config);
   }
-  if (response.status === 204) {
-    return void 0;
+  if (response.status >= 200 && response.status < 300) {
+    return response;
   }
+  if (response.status === 401 && !retried && config.onUnauthorized !== void 0 && await unauthorized()) {
+    return exchange(
+      { config, unauthorized },
+      method,
+      path,
+      body,
+      { signal, query, onUploadProgress },
+      true
+    );
+  }
+  const text = await read(response, "text", config, signal);
   let json = void 0;
   try {
-    json = response.text === "" ? void 0 : JSON.parse(response.text);
+    json = text === "" ? void 0 : JSON.parse(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,
+    typeof bag.message === "string" && bag.message !== "" ? bag.message : config.messages?.(response.status) ?? "",
     flattenErrors(bag.errors)
   );
 }
+async function request(client, method, path, body, options) {
+  const response = await exchange(client, method, path, body, options);
+  if (response.status === 204) {
+    return void 0;
+  }
+  const text = await read(response, "text", client.config, options.signal);
+  try {
+    return text === "" ? void 0 : JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
 function createClient(config) {
+  let refreshing;
+  const client = {
+    config,
+    unauthorized: () => refreshing ??= (config.onUnauthorized?.() ?? Promise.resolve(false)).finally(() => {
+      refreshing = void 0;
+    })
+  };
   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),
+    get: (path, options = {}) => request(client, "GET", path, void 0, options),
+    post: (path, body, options = {}) => request(client, "POST", path, body, options),
+    put: (path, body, options = {}) => request(client, "PUT", path, body, options),
+    patch: (path, body, options = {}) => request(client, "PATCH", path, body, options),
     /** `query` for what identifies the targets (`?ids[]=1&ids[]=2`). */
-    delete: (path, options = {}) => request(config, "DELETE", path, void 0, options)
+    delete: (path, options = {}) => request(client, "DELETE", path, void 0, options),
+    download: async (path, { method = "GET", body, query, signal } = {}) => {
+      const response = await exchange(client, method, path, body, {
+        query,
+        signal
+      });
+      return {
+        blob: await read(response, "blob", config, signal),
+        headers: response.headers,
+        status: response.status
+      };
+    }
   };
 }
 

package/dist/realtime/index.d.ts

@@ -21,7 +21,7 @@
  * 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';
+type RealtimeStatus = "connecting" | "connected" | "unavailable";
 /** What the host must hand over to reach its own server. */
 type RealtimeConfig = {
     /** The app key the server issued. */
@@ -29,7 +29,7 @@ type RealtimeConfig = {
     host: string;
     port: number;
     /** `https` turns on TLS and the `wss` transport. */
-    scheme: 'http' | 'https';
+    scheme: "http" | "https";
 };
 /**
  * Map a transport's own vocabulary onto ours.
@@ -80,4 +80,37 @@ declare function useChannelEvent<T = unknown>(channel: string, event: string, ha
  */
 declare function useUserNotification<T = unknown>(channel: string, handler: (payload: T) => void): void;
 
-export { type RealtimeConfig, type RealtimeStatus, configureRealtime, isRealtimeConfigured, toRealtimeStatus, useChannelEvent, useRealtimeStatus, useUserNotification };
+/**
+ * Canonical realtime channel names shared with the PHP broadcaster.
+ *
+ * Types here catch programmer mistakes only — a client can still subscribe to
+ * any string it likes. The server must always map user → organization →
+ * resource → authorization before trusting a channel name.
+ */
+/** Only values produced by the factories or parser carry this brand; `as` is not validation. */
+type ChannelName = string & {
+    readonly __brand: "ChannelName";
+};
+type ParsedChannelName = {
+    scope: "org";
+    orgId: string;
+    resource: string;
+    resourceId: string;
+    name: ChannelName;
+} | {
+    scope: "platform";
+    resource: string;
+    resourceId: string;
+    name: ChannelName;
+};
+declare class ChannelNameError extends Error {
+    constructor(message: string);
+}
+/** Organization-scoped channel: org.{orgId}.{resource}.{resourceId} */
+declare function organizationChannel(orgId: string, resource: string, resourceId: string): ChannelName;
+/** Platform-wide channel: platform.{resource}.{resourceId} */
+declare function platformChannel(resource: string, resourceId: string): ChannelName;
+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 };

package/dist/realtime/index.js

@@ -38,4 +38,92 @@ function useUserNotification(channel, handler) {
   useEchoNotification(channel, handler);
 }
 
-export { configureRealtime, isRealtimeConfigured, toRealtimeStatus, useChannelEvent, useRealtimeStatus, useUserNotification };
+// src/realtime/channel-name.ts
+var ChannelNameError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChannelNameError";
+  }
+};
+var ORG_ID = /^[A-Za-z0-9_-]+$/;
+var RESOURCE = /^[a-z][a-z0-9-]*$/;
+var RESOURCE_ID = /^[A-Za-z0-9_-]+$/;
+function brandChannelName(value) {
+  return value;
+}
+function assertOrgId(orgId) {
+  if (orgId === void 0 || !ORG_ID.test(orgId)) {
+    throw new ChannelNameError(`invalid organization id: ${orgId ?? ""}`);
+  }
+  return orgId;
+}
+function assertResource(resource) {
+  if (resource === void 0 || !RESOURCE.test(resource)) {
+    throw new ChannelNameError(`invalid resource: ${resource ?? ""}`);
+  }
+  return resource;
+}
+function assertResourceId(resourceId) {
+  if (resourceId === void 0 || !RESOURCE_ID.test(resourceId)) {
+    throw new ChannelNameError(`invalid resource id: ${resourceId ?? ""}`);
+  }
+  return resourceId;
+}
+function organizationChannel(orgId, resource, resourceId) {
+  const safeOrgId = assertOrgId(orgId);
+  const safeResource = assertResource(resource);
+  const safeResourceId = assertResourceId(resourceId);
+  return brandChannelName(`org.${safeOrgId}.${safeResource}.${safeResourceId}`);
+}
+function platformChannel(resource, resourceId) {
+  const safeResource = assertResource(resource);
+  const safeResourceId = assertResourceId(resourceId);
+  return brandChannelName(`platform.${safeResource}.${safeResourceId}`);
+}
+function parseChannelName(name) {
+  if (name === "") {
+    throw new ChannelNameError("channel name is empty");
+  }
+  const parts = name.split(".");
+  if (parts[0] === "org") {
+    if (parts.length !== 4) {
+      throw new ChannelNameError(`invalid org channel shape: ${name}`);
+    }
+    const orgId = assertOrgId(parts[1]);
+    const resource = assertResource(parts[2]);
+    const resourceId = assertResourceId(parts[3]);
+    return {
+      scope: "org",
+      orgId,
+      resource,
+      resourceId,
+      name: brandChannelName(name)
+    };
+  }
+  if (parts[0] === "platform") {
+    if (parts.length !== 3) {
+      throw new ChannelNameError(`invalid platform channel shape: ${name}`);
+    }
+    const resource = assertResource(parts[1]);
+    const resourceId = assertResourceId(parts[2]);
+    return {
+      scope: "platform",
+      resource,
+      resourceId,
+      name: brandChannelName(name)
+    };
+  }
+  throw new ChannelNameError(`unknown channel scope: ${name}`);
+}
+function tryParseChannelName(name) {
+  try {
+    return parseChannelName(name);
+  } catch (error) {
+    if (error instanceof ChannelNameError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export { ChannelNameError, configureRealtime, isRealtimeConfigured, organizationChannel, parseChannelName, platformChannel, toRealtimeStatus, tryParseChannelName, useChannelEvent, useRealtimeStatus, useUserNotification };

package/fixtures/me.v1.json

@@ -0,0 +1,9 @@
+{
+    "user": {
+        "id": 42,
+        "name": "Ada Lovelace",
+        "email": "ada@godx.jp"
+    },
+    "permissions": ["issues.view", "issues.create"],
+    "roles": ["member", "editor"]
+}

package/package.json

@@ -1,16 +1,21 @@
 {
     "name": "@godxjp/sdk",
-    "version": "0.1.0",
-    "description": "GoDX JavaScript SDK — shared frontend infrastructure for GoDX products.",
+    "version": "0.3.0",
+    "description": "GoDX JavaScript SDK \u2014 shared frontend infrastructure for GoDX products.",
     "license": "Apache-2.0",
     "type": "module",
     "sideEffects": false,
     "files": [
         "dist",
+        "fixtures",
         "LICENSE",
         "README.md"
     ],
     "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
         "./laravel": {
             "types": "./dist/laravel/index.d.ts",
             "import": "./dist/laravel/index.js"
@@ -19,12 +24,13 @@
         "./realtime": {
             "types": "./dist/realtime/index.d.ts",
             "import": "./dist/realtime/index.js"
-        }
+        },
+        "./fixtures/me.v1.json": "./fixtures/me.v1.json"
     },
     "scripts": {
         "build": "tsup",
         "types:check": "tsc --noEmit",
-        "test": "vitest run"
+        "test": "vitest run --typecheck"
     },
     "devDependencies": {
         "@laravel/echo-react": "^2.5.0",