@iqauth/sdk 2.6.4 → 2.8.1

package/README.md

@@ -8,7 +8,7 @@
 
 The canonical TypeScript SDK for **IQAuthService** — DispositionIQ's multi-tenant identity and authorization platform. One package covers the React client, the four major Node frameworks (Express, Fastify, Hono, Next.js), native mobile, and headless service automation.
 
-> **New in 2.0.3** — `SessionManager` gains `serverManagedSession: true` for confidential-client apps, and the cookie-managed `/refresh` helper no longer wipes cookies on transient failures. See [What's new in 2.0.3](#whats-new-in-203).
+> **New in 2.7.0** — `IQAuthError` now exposes a typed `code` taxonomy (`token_expired`, `jwks_unavailable`, `rate_limited`, …) plus `err.is(code)` / `IQAuthError.isIQAuthError(value)` helpers, and `tokens.verify<T>()` accepts a custom-claims generic so the returned object is fully typed. Both changes are purely additive — existing `catch (e: Error)` and untyped `verify()` callers keep compiling. See [What's new in 2.7.0](#whats-new-in-270).
 
 ---
 
@@ -17,6 +17,8 @@ The canonical TypeScript SDK for **IQAuthService** — DispositionIQ's multi-ten
 - [Install](#install)
 - [Five-line integration](#five-line-integration)
 - [Pick your environment](#pick-your-environment)
+- [What's new in 2.7.0](#whats-new-in-270)
+- [What's new in 2.6.5](#whats-new-in-265)
 - [What's new in 2.6.2](#whats-new-in-262)
 - [What's new in 2.6.1](#whats-new-in-261)
 - [What's new in 2.0.3](#whats-new-in-203)
@@ -174,6 +176,121 @@ The SDK is not "one auth model for every environment". The safe pattern depends
 
 ---
 
+## What's new in 2.7.0
+
+### 1. Typed `IQAuthError` taxonomy
+
+Every SDK-originated throw now carries a `code` from a fixed 10-value union,
+so callers can stop string-matching on `err.message` or guessing whether
+`err.code` is upper-snake or lowercase. Two helpers ship alongside it:
+`IQAuthError.isIQAuthError(value)` (instanceof-safe across realms) and
+`err.is(code)` (narrow-friendly).
+
+```ts
+import { IQAuthError, type IQAuthErrorCode } from "@iqauth/sdk";
+
+try {
+  const claims = await client.tokens.verify(token);
+} catch (err) {
+  if (IQAuthError.isIQAuthError(err)) {
+    if (err.is("token_expired"))      return refreshAndRetry();
+    if (err.is("jwks_fetch_failed"))  return retryAfterBackoff();
+    if (err.is("rate_limited"))       return showRateLimitToast();
+    if (err.is("network"))            return showOfflineBanner();
+    if (err.is("config_invalid"))     throw err; // boot-time misconfig
+  }
+  throw err;
+}
+```
+
+The full union:
+
+```ts
+type IQAuthErrorCode =
+  | "token_expired"
+  | "token_invalid"
+  | "jwks_unavailable"
+  | "jwks_fetch_failed"
+  | "rate_limited"
+  | "network"
+  | "config_invalid"
+  | "app_not_found"
+  | "permission_denied"
+  | "unknown";
+```
+
+**Back-compat:** the field is widened to `IQAuthErrorCode | (string & {})`,
+so server-rethrown codes (`TOKEN_REVOKED`, `SESSION_EXPIRED_INACTIVITY`, …)
+still flow through unchanged. The framework adapters (`/express`,
+`/fastify`, `/hono`) map both upper-snake and the new lowercase codes to
+`401`, so this rollout is invisible to existing app code. `IQAuthError`
+also gains a `cause` accessor (alias for the legacy `raw`).
+
+See [`docs/error-handling.md`](./docs/error-handling.md) for the full
+recipe book.
+
+### 2. `IQAuthClaims<T>` generic on `tokens.verify`
+
+`verify()` now accepts a custom-claims generic so your app's bespoke
+claims show up *typed* on the result — no index-signature widening, no
+`as any`:
+
+```ts
+interface MyClaims { plan: "free" | "pro"; orgId: string }
+
+const claims = await client.tokens.verify<MyClaims>(token);
+//    ^? IQAuthBaseClaims & MyClaims & JwtClaims
+
+if (claims.plan === "pro") doProThing(claims.orgId);
+console.log(claims.tenantId, claims.sub); // base claims still typed
+```
+
+`IQAuthBaseClaims` is exported separately for callers composing their own
+envelope. `JwtClaims` continues to be exported and remains the return
+type of `tokens.decode()` / `tokens.getClaims()` for back-compat. Calls
+to `verify()` without a generic argument behave exactly as before.
+
+---
+
+## What's new in 2.6.5
+
+### Server-managed userinfo (`mountUserinfo: true`)
+
+The framework adapters can now auto-mount `GET /api/iqauth/me` so
+server-managed integrators don't have to hand-roll a userinfo handler
+that calls `tokens.verify` and shapes a `data.user` / `data.claims`
+envelope.
+
+```ts
+app.use(iqAuth({
+  publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!,
+  secretKey:     process.env.IQAUTH_SECRET_KEY!,
+  mountUserinfo: true,
+  // Optional — shallow-merged over the claim-derived SessionUser defaults.
+  userinfoEnricher: async (claims, req) => ({
+    name: await loadDisplayName(claims.sub),
+  }),
+}));
+```
+
+Returns the documented `UserinfoResponse` envelope —
+`{ success: true, data: { user, claims, tenantId } }` — which is exactly
+the shape the browser SDK's `SessionManager.bootstrap()` already accepts
+(`data.user` is preferred; `claimsToSessionUser(data.claims)` is the
+fallback). The token is read from `Authorization: Bearer …` OR the
+`iqauth_at` cookie; verification reuses a per-issuer cached
+`TokensModule` so JWKS fetches are amortized.
+
+Two new framework-neutral exports for integrators who'd rather mount
+their own route but still emit the canonical envelope:
+`buildUserinfoResponse(claims, { enrich? })` and
+`handleUserinfo(config, { accessToken, req? })`. Re-exported from both
+`@iqauth/sdk` and `@iqauth/sdk/server`. See the
+[Server-managed userinfo](#server-managed-userinfo) section below for
+the full reference.
+
+---
+
 ## What's new in 2.6.2
 
 ### Card grows responsively on desktop (no more phone-sized form)
@@ -381,6 +498,7 @@ app.use("/admin",
 | `GET`  | `/api/iqauth/callback` | Receives the OIDC redirect, exchanges the code, sets `iqauth_at` + `iqauth_rt`, redirects to `return_to` |
 | `POST` | `/api/iqauth/refresh`  | Reads `iqauth_rt`, rotates, sets new cookies. Honors `clearCookiesOnRefreshFailure` |
 | `POST` | `/api/iqauth/signout`  | Revokes the refresh token upstream and clears both cookies |
+| `GET`  | `/api/iqauth/me`       | **Opt-in via `mountUserinfo: true`.** Verifies the access token and returns the documented userinfo envelope. See [Server-managed userinfo](#server-managed-userinfo) |
 
 All three set cookies with `HttpOnly; Secure; SameSite=lax; Path=/` by default. Override per-app:
 
@@ -398,6 +516,60 @@ iqAuth({
 
 ---
 
+### Server-managed userinfo
+
+When you're doing the cookie-managed pattern (browser SDK proxies through
+your own backend), your frontend needs *some* endpoint to learn "who am I"
+on first paint. Before 2.6.5 you had to hand-roll that handler — call
+`tokens.verify`, shape a `data.user` envelope, and remember to read the
+token from either `Authorization: Bearer …` OR the `iqauth_at` cookie.
+
+Opt into the auto-mounted route instead:
+
+```ts
+app.use(iqAuth({
+  publishableKey: process.env.IQAUTH_PUBLISHABLE_KEY!,
+  secretKey:     process.env.IQAUTH_SECRET_KEY!,
+  mountUserinfo: true,
+  // Optional — shallow-merged over the claim-derived SessionUser defaults.
+  userinfoEnricher: async (claims, req) => ({
+    name: await loadDisplayName(claims.sub),
+  }),
+}));
+```
+
+`GET /api/iqauth/me` returns the documented `UserinfoResponse` envelope:
+
+```jsonc
+{
+  "success": true,
+  "data": {
+    "user":     { "sub": "...", "email": "...", "name": "...", "tenantId": "...", "roles": [...], "entitlements": [...] },
+    "claims":   { /* full verified JWT payload */ },
+    "tenantId": "ten_..." // or null
+  }
+}
+```
+
+This is exactly the shape `SessionManager.bootstrap()` already accepts:
+`data.user` is preferred when present, `claimsToSessionUser(data.claims)`
+is the documented fallback. Same option works on Express, Fastify, Hono,
+and the Next.js handler. Token is verified with a per-issuer cached
+`TokensModule` so JWKS fetches are amortized across requests.
+
+Want to mount your own route but still emit the canonical envelope? Use
+the framework-neutral helpers:
+
+```ts
+import { buildUserinfoResponse, type UserinfoResponse } from "@iqauth/sdk/server";
+
+const envelope: UserinfoResponse = await buildUserinfoResponse(verifiedClaims, {
+  enrich: (c) => ({ name: lookupName(c.sub) }),
+});
+```
+
+---
+
 ## Token verification without a framework adapter
 
 If you're not using Express/Fastify/Hono/Next (custom Node server, AWS Lambda, Cloudflare Worker, etc.):

package/dist/browser-session.d.mts

@@ -1,7 +1,7 @@
-import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-DZAflmmq.mjs';
-import { I as IQAuthClient } from './client-kYlJFgPv.mjs';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.mjs';
-import './tokens-DCyzzn8L.mjs';
+import { I as IQAuthBrowserSessionClientConfig, S as SessionUser } from './types-Bn8O-OEd.mjs';
+import { I as IQAuthClient } from './client-D8L-PaWr.mjs';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.mjs';
+import './tokens-B06VtvUi.mjs';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);

package/dist/browser-session.d.ts

@@ -1,7 +1,7 @@
-import { c as IQAuthBrowserSessionClientConfig, d as SessionUser } from './types-DZAflmmq.js';
-import { I as IQAuthClient } from './client-BNQe3AgF.js';
-export { E as ErrorCodes, I as IQAuthError } from './errors-CDdl24MP.js';
-import './tokens-aHiGFr_E.js';
+import { I as IQAuthBrowserSessionClientConfig, S as SessionUser } from './types-Bn8O-OEd.js';
+import { I as IQAuthClient } from './client-DkPL0EPZ.js';
+export { E as ErrorCodes, I as IQAuthError } from './errors-Jl1Jtm-6.js';
+import './tokens-9F6ETrzk.js';
 
 declare class BrowserSessionIQAuthClient extends IQAuthClient {
     constructor(config: Omit<IQAuthBrowserSessionClientConfig, "environment">);