@awsmbiz/inbis-api-client 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @awsmbiz/inbis-api-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed browser calls for Inbis apps: an [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/)
+client for the app's own routes, with types generated from the app's `/openapi.json`, and
+Better Auth's client with the admin plugin for auth admin endpoints. Both reject failed calls
+with the same `ApiError`, and the package includes TanStack Query helpers.
+
+| Export | Contents |
+|---|---|
+| `createApiClient<paths>(options?)` | `openapi-fetch` client (`GET`, `POST`, `PATCH`, …) typed by the generated `paths`. Sends cookies (`credentials: "include"`). A failed call **rejects** with an `ApiError`, so `data` is always set when a call resolves. Options: `baseUrl` (default: the page's origin), `headers`, `fetch`. |
+| `createAuthAdminClient(options?)` | The auth admin client: Better Auth's admin plugin plus the platform's admin routes (see [The auth admin client](#the-auth-admin-client)). Failures reject with an `ApiError`. |
+| `ApiError`, `isApiError(value)` | The one error type (see below). `isApiError` also recognises an `ApiError` from another copy of the package. |
+| `API_ERROR_CODES` | Codes callers commonly branch on: `NETWORK_ERROR`, `STEP_UP_REQUIRED`, `TWO_FACTOR_REQUIRED`, `SESSION_NOT_FRESH`, `SESSION_EXPIRED`, `ADMIN_LOCKOUT`, `SETTINGS_VERSION_CONFLICT`, `VALIDATION_FAILED`, `RATE_LIMITED`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `INTERNAL_ERROR`, `REQUEST_FAILED`. Any other server code (`LAST_ADMIN`, `INVITATION_NOT_PENDING`, …) is passed through unchanged. |
+| `apiQueryOptions(api, path, init?)`, `apiQueryKey(path, params?)`, `invalidateApi(queryClient, ...paths)` | TanStack Query helpers for app routes. |
+| `authAdminKeys`, `authAdminQueries(auth)` | Query keys and query options for auth admin data. |
+| `invalidateQueries(queryClient, ...keys)` | Invalidates each key prefix. |
+| Types | App routes: `ApiClient`, `ApiClientOptions`, `ApiQueryOptions`, `QueryInvalidator`. Errors: `ApiErrorOptions`, `AccessRequirement`. Auth admin client: `AuthAdminClient`, `AuthAdminClientOptions`, `BetterAuthAdminClient`, `AdminRoutesClient`, `ListUsersQuery`; users: `AdminUsersQuery`, `AdminUsersPage`, `AdminUserSummary`, `AdminUserDetail`, `AdminUserSignInMethod`, `UserActionsAdminClient`, `CreateUserInput`, `CreatedUser`; invitations: `InvitationsAdminClient`, `Invitation`, `InvitationStatus`, `ListInvitationsQuery`; dashboard and activity: `AuthAdminStats`, `AuditEvent`, `AuditEventsQuery`; roles: `RoleAdminClient`, `AdminPermission`, `AdminRole`, `AdminRoleInput`, `AdminUserRole`; settings: `AuthSettingsAdminClient`, `AuthProvidersAdminClient`, `AuthSettingsView`, `AuthSettingsSnapshot`, `RuntimeAuthSettings`, `AuthSettingsPatch`, `AuthProviderStatus`, `RegistrationMode`, `AuthMethodName`, `BreachedPasswordCheck`, `RateLimitRule`, `RateLimitKey` |
+
+## The auth admin client
+
+`createAuthAdminClient({ baseURL?, basePath?, adminPath?, fetch? })` returns one object for every
+auth administration call. `baseURL` defaults to the page's origin; `basePath` (default
+`/api/auth`) must match the server's auth routes; `adminPath` (default `/api/admin`) is where the
+app mounts the admin routes below. Every member rejects with an `ApiError`, revives dates, and is
+for administrators only (the server applies the admin policy; changes that matter also need a
+recent sign-in, `SESSION_NOT_FRESH`).
+
+| Member | Calls | Server side |
+|---|---|---|
+| `admin` | Better Auth's admin plugin, typed by Better Auth: `listUsers`, `getUser`, `createUser`, `setRole`, `banUser`, `unbanUser`, `listUserSessions`, `revokeUserSessions`, `removeUser`, … Resolves to the response data | `mountAuth` (`@awsmbiz/inbis-auth/hono`) |
+| `userActions` | `create({ name, email \| phoneNumber, password?, role? })` (by email or phone number) → `{ user }`; `revokeSession({ userId, sessionId })` (by session ID: listings never carry tokens) | `mountAuth` |
+| `invitations` | `create({ email \| phoneNumber, role? })`, `list({ limit?, cursor?, status? })` (`status`: `pending`, `accepted`, `expired` or `revoked`), `resend({ invitationId })`, `revoke({ invitationId })` | `mountAuth` |
+| `users` | `list({ search?, role?, banned?, twoFactor?, emailVerified?, sort?, direction?, limit?, offset? })`: the user directory with every filter at once; `get(userId)`: one user with sign-in methods and 2FA status; `resetTwoFactor(userId)` → `{ sessionsRevoked }`: removes a lost authenticator and backup codes and revokes their sessions (never the caller's own account) | `mountAuthUsers` (`@awsmbiz/inbis-auth/hono`) |
+| `stats()` | The dashboard counts | `mountAuthStats` (`@awsmbiz/inbis-auth/hono`) |
+| `auditEvents` | `list({ action?, actor?, subject?, from?, to?, limit?, cursor? })`: the audit timeline, newest first | `mountAuditTimeline` (`@awsmbiz/inbis-audit/hono`) |
+| `permissions`, `roles`, `userRoles` | `permissions.list()`; `roles.list()`, `get(roleId)`, `create({ name, description?, permissions, inherits? })`, `update(roleId, changes)`, `delete(roleId)`; `userRoles.list(userId)`, `assign(userId, roleId)`, `unassign(userId, roleId)` (idempotent; both return the user's roles). Refusals (`ROLE_NAME_TAKEN`, `SYSTEM_ROLE_IMMUTABLE`, `ROLE_INHERITED`, …) carry the envelope's `details` | `mountRoleAdmin` (`@awsmbiz/inbis-access-control/hono`) |
+| `settings`, `providers` | `settings.get()`, `settings.update({ version, settings })` (a JSON merge patch; `null` removes an override); `providers.status()`: each method and provider configured / enabled | `mountAuthSettings` (`@awsmbiz/inbis-auth/hono`) |
+
+`@awsmbiz/inbis-admin-ui`'s screens take this client; its README shows which screen needs which member.
+
+**The admin route types are hand-written mirrors, not generated.** The platform's admin app
+routes (`/api/admin/*` from `mountAuthStats`, `mountAuthUsers`, `mountAuthSettings`,
+`mountAuditTimeline`, `mountRoleAdmin`) are plain Hono routes mounted by the platform packages,
+not `@awsmbiz/inbis-api` OpenAPI routes, so they are not in the app's `/openapi.json` and there is
+nothing to generate from (a known gap; see `docs/auth-capability-matrix.md`). The types here
+(`AuthAdminStats`, `AdminRole`, `AuditEvent`, …) mirror the server's documented responses by
+hand. This package's tests check each call against a fake server written to those responses, and
+the playground's browser suite runs the admin screens against the real routes; a server change
+needs the matching change here. Better Auth's own admin endpoints (`admin`) are typed by
+Better Auth.
+
+## Generating the app's types
+
+The types come from the app's OpenAPI document, which `@awsmbiz/inbis-api` serves at `/openapi.json`.
+Generate them with [`openapi-typescript`](https://openapi-ts.dev/) as a dev dependency of the
+app, and commit the output:
+
+```jsonc
+// app package.json
+"scripts": {
+  "generate:api-types": "openapi-typescript http://localhost:8787/openapi.json -o web/api-types.ts"
+},
+"devDependencies": { "openapi-typescript": "7.13.0" }
+```
+
+Run it while the Worker is up (`pnpm dev`), or point it at a saved copy of the document. Run it
+again whenever a route changes; `tsc` then reports every call that no longer matches. This
+package's own tests generate their fixture types the same way (`pnpm generate:fixture-types`
+from `test/fixture-app.ts`), and a test fails when the committed fixture types fall out of date.
+
+```ts
+import { createApiClient } from "@awsmbiz/inbis-api-client";
+import type { paths } from "./api-types";
+
+export const api = createApiClient<paths>();
+
+const { data: note } = await api.GET("/v1/notes/{id}", { params: { path: { id } } });
+await api.PATCH("/v1/notes/{id}", { params: { path: { id } }, body: { title, version } });
+```
+
+## Errors
+
+Every failed call rejects with an `ApiError`, read from either error shape:
+
+- app routes (`@awsmbiz/inbis-api`): `{ error: { code, message, requestId, details? } }`;
+- auth routes (Better Auth, `@awsmbiz/inbis-auth`): `{ code, message, details? }`.
+
+| Field | Meaning |
+|---|---|
+| `status` | HTTP status, `0` when no response arrived |
+| `code` | Stable server code. Without one, the code comes from the status (`RATE_LIMITED` for 429, `INTERNAL_ERROR` for 5xx, …, else `REQUEST_FAILED`). `NETWORK_ERROR` when the server could not be reached; the original error is kept as `cause`. |
+| `message` | Safe to show |
+| `requestId` | The server's request ID (app routes), else `null` |
+| `details` | Caller-safe extras: `allowedMethods`, validation `issues`, `lockedOutAdmins` and `paths` (`ADMIN_LOCKOUT`), … |
+| `requirement` | For `TWO_FACTOR_REQUIRED` / `STEP_UP_REQUIRED`: `{ kind: "two-factor" }` or `{ kind: "step-up", allowedMethods }`, the same shape as `accessRequirementOf` in `@awsmbiz/inbis-auth/client`. `null` otherwise. |
+| `isVersionConflict` | A stale-version conflict: `409` with a `…VERSION_CONFLICT` code, such as `SETTINGS_VERSION_CONFLICT`. Reload, then let the user reapply their change. |
+| `isNetworkError` | `code === "NETWORK_ERROR"` |
+
+```ts
+try {
+  await auth.admin.banUser({ userId, banReason });
+} catch (error) {
+  if (isApiError(error) && error.requirement) return promptStepUp(error.requirement);
+  throw error;
+}
+```
+
+## TanStack Query
+
+The helpers return plain `{ queryKey, queryFn }` objects. Pass them to `useQuery`, `query`
+or `prefetchQuery`. `queryFn` passes TanStack's abort `signal` on to the request. Invalidation
+accepts any `QueryClient`.
+
+**Key conventions**
+
+- App routes: `["api", path]`, or `["api", path, params]` when the call has `params`, e.g.
+  `["api", "/v1/notes/{id}", { path: { id: "n1" } }]`. `invalidateApi(queryClient, "/v1/notes")`
+  refreshes every query of that path, whatever its params. `invalidateApi(queryClient)` with no
+  path refreshes every app-route query.
+- Auth admin (`authAdminKeys`): `["auth-admin", "users", "list", query]`,
+  `["auth-admin", "users", "detail", userId]`, `["auth-admin", "users", "detail", userId, "sessions"]`,
+  `["auth-admin", "users", "directory", query]` (`users.list`), `["auth-admin", "users", "detail", userId, "profile"]` (`users.get`),
+  `["auth-admin", "invitations", "list", query]`, `["auth-admin", "stats"]`,
+  `["auth-admin", "audit-events", "list", query]`, `["auth-admin", "settings"]`,
+  `["auth-admin", "providers", "status"]`, `["auth-admin", "permissions"]`, `["auth-admin", "roles", "list"]`,
+  `["auth-admin", "roles", "detail", roleId]`, `["auth-admin", "users", "detail", userId, "roles"]` (`userRoles.list`).
+  After a role change or an assignment (user counts), invalidate `authAdminKeys.roles()`. After any change to a user (role, ban, sessions,
+  delete), invalidate `authAdminKeys.users()`. After an invitation change, invalidate
+  `authAdminKeys.invitations()`. `authAdminKeys.all` covers everything.
+
+```ts
+const auth = createAuthAdminClient();
+const queries = authAdminQueries(auth);
+
+const users = useQuery(queries.userList({ limit: 20, offset: 0, searchValue }));
+const note = useQuery(apiQueryOptions(api, "/v1/notes/{id}", { params: { path: { id } } }));
+
+const ban = useMutation({
+  mutationFn: (userId: string) => auth.admin.banUser({ userId }),
+  onSuccess: () => invalidateQueries(queryClient, authAdminKeys.users()),
+});
+```
+
+## Tests
+
+`test/` runs in Node (a browser package; no Workers APIs). The tests check typed calls, error
+parsing and network failures against a fake server. The app side is a real `@awsmbiz/inbis-api` app
+(`test/fixture-app.ts`), so errors use the platform's own envelope. The auth side is a stand-in
+for the auth routes (`test/fake-auth-server.ts`). Compile-time checks (`@ts-expect-error`,
+`expectTypeOf`) run in `pnpm typecheck`.
+
+Dependencies: `openapi-fetch` 0.17.0, `openapi-typescript-helpers` 0.1.0, `better-auth` 1.7.14
+(browser client only).