@godxjp/sdk 0.1.0 → 0.2.0

package/README.md

@@ -8,27 +8,75 @@ 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.
@@ -39,12 +87,12 @@ A cancellation stays an `AbortError` and is never converted to an `ApiError` —
 
 ```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 +102,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 +117,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.js

@@ -92,9 +92,7 @@ function send(url, init, onUploadProgress) {
     }
     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 = () => {

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.2.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",