@smess/networking 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,211 @@
+# Changelog
+
+All notable changes to `@smess/networking`. Versions follow [semver](https://semver.org).
+
+## 2.0.0 (2026-11-07)
+
+A rewrite: one typed client for core-services, built on `fetch`. Not compatible with 1.x.
+
+### Added
+
+- `createSmessClient` with a host map per core service, the tenant header (`clientId` → `X-Client-Id`),
+  per-request timeout combined with the caller's `AbortSignal`, app middleware and opt-in retries.
+- Endpoint contracts (`defineEndpoint`) with per-route auth mode (`none` / `optional` / `required`), so a
+  stale Bearer is never sent to core's anonymous firewalls.
+- Sessions: `webStorageSession`, `memorySession`, `staticSession`; refresh 30 s before expiry and once on
+  401, single-flight across concurrent requests; `onSessionExpired`.
+- `SmessApiError` with `kind`, `status`, `code`, `serverMessage`, `fields`, `retryAfter`, parsed from every
+  error format core-services emits.
+- Modules: `authentication`, `sso`, `campaign` (the smeup.email API), `smeup-file`, `danara`; optional
+  `rx` adapter.
+- Read-only smoke test against PROD Danara (`make smoke`), route table snapshot test.
+- Publishing from GitHub Actions with npm trusted publishing.
+
+### Fixed (compared with the hand-written app clients it replaces)
+
+- OTP and password-reset logins keep their refresh token: core returns it as `refreshToken` (camelCase),
+  which smeup.email read as `refresh_token`, so those sessions ended after one hour.
+- A caller's `AbortSignal` no longer disables the request timeout (Danara client).
+
+### Removed
+
+- The whole 1.x API (axios, rxjs services, Dexie cache, storefront services). Apps on 1.x keep working on
+  their pinned 1.x version; GPM migrates module by module.
+- Duplicate source tree `src/src`, the committed 1.0.18 tarball, Jest, per-version changelog files.
+
+## 1.x history
+
+Generated from the former per-version changelog files. `1.2.0` was published by mistake before `1.1.1`;
+do not use it.
+
+### 1.2.0
+
+- Update customer.service.ts
+- Update package
+
+### 1.1.5 (2026-01-14)
+
+- [Authentication] Update VerifyResetPassword
+
+### 1.1.4 (2026-01-14)
+
+- [Authentication] Update VerifyResetPassword
+
+### 1.1.3 (2026-01-14)
+
+- [Authentication] Update VerifyResetPassword
+
+### 1.1.2 (2025-11-24)
+
+- Update customer-product-remove
+
+### 1.1.1 (2025-11-23)
+
+- Update customer.service.ts
+- Update package
+
+### 1.1.0 (2025-11-20)
+
+- Update storefront.store.service.ts
+- Update storefront.store.service.ts
+
+### 1.0.30
+
+- Update storefront.store.service.ts
+- Update storefront.store.service.ts
+
+### 1.0.29 (2025-11-10)
+
+- [Fix] Bug
+
+### 1.0.28 (2025-11-10)
+
+- fix: remove customer product notes flow
+
+### 1.0.27 (2025-11-10)
+
+- feat(customer): add product category management
+
+### 1.0.26 (2025-11-09)
+
+- chore(build): clean publish artifacts
+
+### 1.0.25 (2025-11-09)
+
+- chore: export employee service
+- chore: expose helper and archive changelog
+- feat(auth): share auth reset helper
+
+### 1.0.24 (2025-11-09)
+
+- feat(employee): add service and tests
+- feat(customer): support cart and product operations
+
+### 1.0.23 (2025-10-24)
+
+- fix: Fix customer services
+
+### 1.0.22 (2025-10-24)
+
+- [StoreProduct] Fix bug
+
+### 1.0.21 (2025-10-20)
+
+- feat(dev-test): add Step 7.5 to use StoreCartService.batchItems\n\n- Call POST /store/cart/items/batch with dynamic create/update payloads\n- Log cart state after batch op and handle errors consistently
+- feat(cart): add batch items endpoint and tests\n\n- Add cart-batch-items target in StoreCartProvider (POST /store/cart/items/batch)\n- Define CartBatchItemsRequest payload type (create/update arrays)\n- Implement StoreCartService.batchItems(payload) with cart hash update\n- Add unit tests for success and error cases of batchItems
+
+### 1.0.20 (2025-10-16)
+
+- fix: update real-test.ts to use correct services and remove
+- fix: resolve errors in dev-test.ts
+- refactor: remove  from StoreService - stores are open access
+- refactor: remove redundant functions from StoreProductService
+
+### 1.0.19 (2025-10-15)
+
+- fix: standardize service return types and fix dev-test JSON parsing
+
+### 1.0.18 (2025-10-14)
+
+- fix(store-product): rename interfaces to avoid export conflicts
+
+### 1.0.17 (2025-10-14)
+
+- fix(dev-test): properly extract cart data from nested response structure
+- fix(store-cart): handle nested data structure in cart response
+- feat(dev-test): add comprehensive E2E store and cart flow test
+- feat(store-cart): add storeId support and X-Store-Id header
+- feat(store): add StoreProductService with product and store endpoints
+- Add StoreCartService with cart hash management
+
+### 1.0.16 (2025-09-23)
+
+- Simplify AuthService logic and add rememberMe test
+
+### 1.0.15 (2025-09-23)
+
+- Fix orde.service collection
+
+### 1.0.14 (2025-09-22)
+
+- Fix bear authentication
+
+### 1.0.13 (2025-09-22)
+
+- feat: add collection function to OrderService
+
+### 1.0.12 (2025-09-22)
+
+- fix release script
+
+### 1.0.11 (2025-09-22)
+
+- Fix types check
+- refactor: AuthService manages authToken internally
+
+### 1.0.10 (2025-08-02)
+
+- refactor: AuthService manages authToken internally
+- chore(release): generate changelog for v1.0.10
+- Update order services
+
+### 1.0.9 (2025-07-26)
+
+- Implement cache-first strategy for store
+- Implement cache-service
+
+### 1.0.8 (2025-07-26)
+
+- Export all services
+
+### 1.0.7 (2025-07-26)
+
+- Update build fixed
+- Revert "Update build for ES module"
+- Revert Update build for ES module
+- Revert "chore(release): generate changelog for v1.0.6"
+
+### 1.0.5 (2025-07-23)
+
+- Update build for ES module
+
+### 1.0.4 (2025-07-22)
+
+- Implement store service
+- Implement order service
+- Implement customer service
+- Fix bugs and improvement auth.services - make real test working
+- refactor!: move all services to services/, update docs and examples for @smess/networking, fix all tests and scripts for new structure
+
+### 1.0.3 (2025-07-22)
+
+- Fix bugs and improvement
+
+### 1.0.2 (2025-07-17)
+
+- Bump new version
+
+### 1.0.1 (2025-07-17)
+
+- Build Networking utilities and services for SMESS platform
+

package/README.md

@@ -1,147 +1,198 @@
-# SMESS Networking Package
+# @smess/networking
 
-## Features
+The standard client for the SMESS core-services API (`backend/smess-core-services`), for every SMESS
+JavaScript/TypeScript product: browser SPAs, Next.js (server and client components), Node scripts and
+React Native.
 
-- Per-instance configuration (no global config)
-- RxJS-based HTTP services
-- Extensible provider/service architecture
-- TypeScript-first
-- **Bundler-friendly** (Webpack, Vite, Rollup compatible)
+- Built on `fetch`, no runtime dependencies, ESM, typed.
+- One client per app: it knows core's hosts, the tenant header, the session and its refresh.
+- One module per core-services Microservice: `authentication`, `sso`, `campaign`, `smeup-file`, `danara`.
+- One error type, `SmessApiError`, for every error format core emits.
 
-## Installation
+Layers and the backend facts behind them: [docs/architecture.md](docs/architecture.md).
 
-```bash
+```sh
 npm install @smess/networking
 ```
 
-## Usage
-
-### 1. Define your config
-
-```typescript
-const configA = {
-  baseUrl: "https://api-a",
-  isProd: false,
-  clientId: "A",
-  apiKey: "keyA",
-};
-const configB = {
-  baseUrl: "https://api-b",
-  isProd: true,
-  clientId: "B",
-  apiKey: "keyB",
-};
-```
-
-### 2. Create providers/services with config
+## Quick start
 
-```typescript
-import { ProductService, UserService, AuthService } from "@smess/networking";
+### Browser app with a signed-in user (smeup.email)
 
-const productServiceA = new ProductService(configA);
-const productServiceB = new ProductService(configB);
-const userServiceA = new UserService(configA);
-const authServiceA = new AuthService(configA);
-```
+```ts
+import { createSmessClient, PRODUCTION_HOSTS, webStorageSession } from '@smess/networking';
+import { authentication, authenticationRefresh } from '@smess/networking/authentication';
+import { campaign } from '@smess/networking/campaign';
 
-### 3. Use services independently
+export const smess = createSmessClient({
+  hosts: PRODUCTION_HOSTS,
+  session: webStorageSession({ accessKey: 'app.token', refreshKey: 'app.refresh' }),
+  refresh: authenticationRefresh(),
+  onSessionExpired: () => router.navigate({ to: '/login' }),
+});
 
-```typescript
-// Using RxJS Observables
-productServiceA.fetchAllProducts().subscribe(...);
-productServiceB.createProduct({ name: 'X', price: 10 }).subscribe(...);
-userServiceA.fetchUserById(1).subscribe(...);
-authServiceA.login({ identifier: 'user', password: 'pass' }).subscribe(...);
+const auth = authentication(smess);
+await auth.otp.request({ identifier: email });
+await auth.otp.verify({ identifier: email, code }); // saves the session
 
-// Or convert to Promises for async/await
-const user = await userServiceA.fetchUserById(1).toPromise();
-const products = await productServiceA.fetchAllProducts().toPromise();
+const templates = await campaign(smess).email.templates.list(); // ApiList<Template>
 ```
 
-### 4. Example: Custom Provider
-
-```typescript
-import { BaseProvider, SmessService } from "@smess/networking";
-
-const config = {
-  baseUrl: "https://custom-api",
-  isProd: false,
-  clientId: "custom-client",
-  apiKey: "custom-key",
-};
-
-class ExampleProvider extends BaseProvider {
-  constructor(config, resourceId: string) {
-    super({
-      config,
-      path: `/resource/${resourceId}`,
-      method: "GET",
-      headers: { "Custom-Header": "value" },
-      getPath: () => `/resource/${resourceId}`,
-    });
-  }
-}
+### Tenant-scoped app, Next.js server component (Danara)
 
-const provider = new ExampleProvider(config, "123");
-const service = new SmessService(provider);
-service.request().subscribe((result) => {
-  // handle result
-});
-```
+```ts
+import { createSmessClient, staticSession } from '@smess/networking';
+import { danara } from '@smess/networking/danara';
 
-## Bundler Compatibility
+// Module scope: no session here, a server client is shared by every request.
+const base = createSmessClient({
+  hosts: { danara: 'https://api.danara.vn' },
+  clientId: process.env.NEXT_PUBLIC_CLIENT_ID, // X-Client-Id on every request
+  timeoutMs: 15_000,
+});
 
-This package is designed to work seamlessly with modern bundlers:
+// Per request: the visitor's token, read from the request cookie.
+const api = danara(base.with({ session: staticSession(await getServerAuthToken()) }));
+const { data, meta } = await api.listings.list({ page: 1, ward: 'son-tra' });
+const contracts = await api.leasing.contracts.get(uuid); // sends the Bearer
+```
 
-- **Webpack** ✅
-- **Vite** ✅
-- **Rollup** ✅
-- **Parcel** ✅
+## The client
+
+```ts
+createSmessClient({
+  hosts,              // required: base URL per service (PRODUCTION_HOSTS, or your environment)
+  clientId,           // tenant UUID → X-Client-Id on every request
+  session,            // SessionStore: webStorageSession() | memorySession() | staticSession(token) | your own
+  refresh,            // RefreshStrategy, e.g. authenticationRefresh()
+  onSessionExpired,   // called once when the session is cleared because it could not be renewed
+  timeoutMs,          // default 30 000; 0 disables
+  headers,            // on every request (e.g. Accept-Language)
+  fetchOptions,       // passed to fetch (cache, credentials, Next.js `next`)
+  middleware,         // app middleware (logging, metrics, test doubles)
+  retry,              // opt-in: { retries: 2 } retries GET on network errors, 429, 502, 503, 504
+  fetch,              // custom fetch
+});
+```
 
-The package uses **extensionless imports** in TypeScript source code, which bundlers handle automatically. No `.js` extensions needed in your imports!
+| Method | Purpose |
+|---|---|
+| `client.call(endpoint, input)` | Call a declared endpoint (what modules do). |
+| `client.request({ service, method, path, auth, … })` | Any route no module covers yet. `auth` is required. |
+| `client.with(overrides)` | Derived client (per-request session, other timeout). Shares the session store. |
+| `client.session.get/set/clear/claims()` | The current session and its JWT claims (unverified). |
+
+Every module function takes optional per-call options as its last argument:
+`{ signal, timeoutMs, headers, idempotencyKey, fetchOptions }`.
+
+### Auth modes
+
+Each endpoint declares how it uses the session, because core rejects any stale Bearer with 401, even
+on public routes:
+
+| `auth` | Behaviour |
+|---|---|
+| `none` | Never sends `Authorization` (login, refresh, OTP, SSO, public catalogs). |
+| `optional` | Sends the token when signed in. |
+| `required` | Fails with `unauthenticated` / `no_session` before the network when signed out. |
+
+### Sessions and refresh
+
+- The access token is refreshed 30 s before its `exp`, and once on a 401. Concurrent requests share
+  one refresh.
+- A refresh rejected with 4xx clears the session and calls `onSessionExpired({ reason: 'refresh_failed' })`.
+  A network or 5xx failure keeps the session.
+- A 401 that cannot be refreshed clears the session (`reason: 'unauthorized'`).
+- Server code: never share a writable store between requests. Use `staticSession(token)` per request.
+
+### Tenant (`clientId`)
+
+core-services rejects a JWT whose `client_id` differs from the `X-Client-Id` header, and a browser
+origin bound to a tenant must send that tenant. So a client either always sends the same tenant or
+never sends one. smeup.email sends none (the tenant comes from the JWT); Danara always sends its own.
+
+## Modules
+
+| Import | Backend module | Host key | Notes |
+|---|---|---|---|
+| `@smess/networking/authentication` | Authentication | `authentication` | password, OTP, refresh, reset, change password, logout |
+| `@smess/networking/sso` | Sso | `sso` | `start`, `completeLogin(location.hash)`, `parseSsoCallback`, `readSsoError` |
+| `@smess/networking/campaign` | Campaign (email) | `campaignApi` | the whole smeup.email API: sender, templates, campaigns, audiences, domains, addresses, short links, segments, automations, A/B tests, developers, SSO settings |
+| `@smess/networking/smeup-file` | SMEUpFile | `smeupFile` | base64 upload |
+| `@smess/networking/danara` | Danara | `danara` | identity, listings, sales, fit-out, leasing, owner portal, transit |
+| `@smess/networking/rx` | – | – | `fromSmess(signal => call)` → cancellable Observable (peer dep `rxjs`) |
+
+Each module also exports its endpoint table (`campaignEmailEndpoints`, `danaraEndpoints`, …) and its
+wire types.
+
+**Wire types are the server's.** Field names are exactly what core sends (mostly snake_case; Danara
+and a few others camelCase), so a type always matches DevTools. Single objects wrapped in `{"data": …}`
+are unwrapped; list envelopes are returned as sent because they carry the pagination
+(`ApiList<T>` = `{object: 'list', data, has_more, total_count}`, `PagedList<T>` = `{data, meta}`).
+Walk a cursor list with `paginate()`.
+
+## Errors
+
+Every call rejects with `SmessApiError`:
+
+```ts
+try {
+  await email.domains.create('example.com');
+} catch (error) {
+  if (isSmessApiError(error)) {
+    error.kind;          // 'validation' | 'unauthenticated' | 'forbidden' | 'not_found' | 'rate_limited' | …
+    error.status;        // HTTP status, 0 without a response
+    error.code;          // e.g. 'missing_client_id', 'email_already_registered', 'invalid_code'
+    error.serverMessage; // the server's text (may be an i18n key such as error.validation.not_blank)
+    error.fields;        // { field: 'first message' }
+    error.retryAfter;    // seconds, on 429
+  }
+}
+```
 
-### Example with Webpack/Vite
+The parser reads all of core's formats: Stripe-style `{error: {type, code, message, param}}`,
+`{errors: {field: [{message}]}}`, `{code, message}`, `{is_success: false, error_message}`,
+`{error: "text"}`, `violations`, plain text, and HTML pages (status only).
 
-```typescript
-// ✅ This works perfectly with bundlers
-import { UserService, ProductService } from "@smess/networking";
+## Routes not in a module yet
 
-const config = { baseUrl: "https://api.example.com", isProd: false };
-const userService = new UserService(config);
-const productService = new ProductService(config);
+```ts
+await client.request<MoveInCost>({
+  service: 'danara',
+  method: 'GET',
+  path: '/v1/listings/{uuid}/move-in-cost',
+  pathParams: { uuid },
+  auth: 'none',
+});
 ```
 
-## Available Services
-
-- `UserService` - User management operations
-- `ProductService` - Product CRUD operations
-- `AuthService` - Authentication (login, logout, password reset)
-- `CustomerService` - Customer registration and profile management
-- `OrderService` - Order management
-- `StoreService` - Store and product catalog operations
+Add the route to its module once it exists in core-services, with its type taken from the backend
+transformer or DTO, and a line in the route table snapshot (`test/__snapshots__`).
 
 ## Development
 
-```bash
-# Install dependencies
-npm install
-
-# Build the package
-npm run build
-
-# Run tests
-npm test
-
-# Clean build artifacts
-npm run clean
+```sh
+make install     # npm ci
+make check       # lint, typecheck, tests, build, publint
+make smoke       # read-only checks of the built package against PROD Danara (DANARA_CLIENT_ID=… make smoke)
 ```
 
----
+Try a local build in an app without publishing: `npm pack`, then in the app
+`npm install --no-save /path/to/smess-networking-2.x.y.tgz`.
+
+## Release
 
-## Private Package Usage
+Releases are published from GitHub Actions (`.github/workflows/release.yml`) when a `v*` tag is
+pushed, with npm trusted publishing (no token stored anywhere).
 
-See [SETUP.md](./SETUP.md) for instructions on using this package as a private dependency (GitHub repo, GitHub Packages, npm private registry) with the correct package name: `@smess/networking`.
+1. Add the version's section to `CHANGELOG.md` and commit.
+2. `make release VERSION=2.0.1` (bumps `package.json`, commits, tags `v2.0.1`, pushes).
+3. The workflow checks the tag against `package.json`, runs `npm run check`, publishes (pre-releases such
+   as `2.1.0-beta.1` go to the `next` dist-tag) and creates the GitHub release.
 
----
+One-time setup on npmjs.com: package `@smess/networking` → Settings → Trusted Publisher → GitHub
+Actions, owner `smeservicescloud`, repository `smess-networking`, workflow `release.yml`. The repository is
+private, so npm does not attach provenance.
 
-MIT License
+Version policy: semver. Breaking changes to a module's functions or wire types are major versions;
+new endpoints and modules are minor.

package/dist/core/body.d.ts

@@ -0,0 +1,10 @@
+export interface EncodedBody {
+    body: BodyInit | undefined;
+    /** Set only for JSON; FormData and friends let `fetch` pick the header (multipart boundary). */
+    contentType?: string;
+    /** False for one-shot streams, which cannot be sent again on a retry. */
+    replayable: boolean;
+}
+/** Plain values become JSON; platform body types (FormData, Blob, URLSearchParams, buffers, strings) pass through. */
+export declare function encodeBody(body: unknown): EncodedBody;
+//# sourceMappingURL=body.d.ts.map

package/dist/core/body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../../src/core/body.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC3B,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,UAAU,EAAE,OAAO,CAAC;CACrB;AAQD,sHAAsH;AACtH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CAcrD"}

package/dist/core/body.js

@@ -0,0 +1,22 @@
+const has = (name) => typeof globalThis[name] === 'function';
+function isInstance(value, name) {
+    return has(name) && value instanceof globalThis[name];
+}
+/** Plain values become JSON; platform body types (FormData, Blob, URLSearchParams, buffers, strings) pass through. */
+export function encodeBody(body) {
+    if (body === undefined || body === null)
+        return { body: undefined, replayable: true };
+    if (typeof body === 'string')
+        return { body, replayable: true };
+    if (isInstance(body, 'ReadableStream'))
+        return { body: body, replayable: false };
+    if (isInstance(body, 'FormData') ||
+        isInstance(body, 'URLSearchParams') ||
+        isInstance(body, 'Blob') ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body)) {
+        return { body: body, replayable: true };
+    }
+    return { body: JSON.stringify(body), contentType: 'application/json', replayable: true };
+}
+//# sourceMappingURL=body.js.map

package/dist/core/body.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.js","sourceRoot":"","sources":["../../src/core/body.ts"],"names":[],"mappings":"AAQA,MAAM,GAAG,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,OAAQ,UAAsC,CAAC,IAAI,CAAC,KAAK,UAAU,CAAC;AAE3G,SAAS,UAAU,CAAC,KAAc,EAAE,IAAY;IAC9C,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,YAAc,UAAsC,CAAC,IAAI,CAAuB,CAAC;AAC5G,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACtF,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAChE,IAAI,UAAU,CAAC,IAAI,EAAE,gBAAgB,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,IAAgB,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC7F,IACE,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC;QAC5B,UAAU,CAAC,IAAI,EAAE,iBAAiB,CAAC;QACnC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC;QACxB,IAAI,YAAY,WAAW;QAC3B,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,EACxB,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,IAAgB,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAC3F,CAAC"}

package/dist/core/client.d.ts

@@ -0,0 +1,74 @@
+import type { RefreshStrategy } from '../session/auth-middleware.js';
+import type { SmessJwtClaims } from '../session/jwt.js';
+import type { Session, SessionExpiredEvent, SessionStore } from '../session/types.js';
+import type { AnyEndpoint, CallArgs, CallOptions, EndpointResult } from './endpoint.js';
+import type { HostMap, ServiceKey } from './hosts.js';
+import type { Middleware } from './pipeline.js';
+import type { RetryOptions } from './retry.js';
+import type { AuthMode, FetchFunction, FetchOptions, HttpMethod, QueryParams, ResponseType } from './types.js';
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_REFRESH_SKEW_MS = 30000;
+export interface SmessClientConfig {
+    /** Base URL per service. Required: the client never guesses an environment. See `PRODUCTION_HOSTS`. */
+    hosts: HostMap;
+    /**
+     * The tenant (Authentication Client UUID), sent as `X-Client-Id` on every request when set.
+     * core-services rejects a JWT whose `client_id` differs from this header, so a client either always
+     * sends the same tenant or never sends one.
+     */
+    clientId?: string | undefined;
+    /** Where the signed-in session lives. Omit for anonymous clients (and on servers, use `staticSession` per request). */
+    session?: SessionStore | null | undefined;
+    /** How to renew the access token; e.g. `authenticationRefresh()`. Omit when the login flow has no refresh token. */
+    refresh?: RefreshStrategy | null | undefined;
+    /** Called once when the session is cleared because it could not be renewed. */
+    onSessionExpired?: ((event: SessionExpiredEvent) => void) | undefined;
+    /** Per-request timeout in ms. Default 30 000; 0 disables. */
+    timeoutMs?: number | undefined;
+    /** Headers on every request (e.g. `Accept-Language`). */
+    headers?: Readonly<Record<string, string>> | undefined;
+    /** Custom fetch (tests, instrumentation). Default: the global fetch, resolved per call. */
+    fetch?: FetchFunction | undefined;
+    /** Extra fetch options on every request (`cache`, `credentials`, Next.js `next`, ...). */
+    fetchOptions?: FetchOptions | undefined;
+    /** App middleware, outermost first; runs around retries and auth. */
+    middleware?: readonly Middleware[] | undefined;
+    /** Opt-in retries for idempotent requests. Default: none. */
+    retry?: RetryOptions | null | undefined;
+    /** Refresh this long before the access token's `exp`. Default 30 000 ms. */
+    refreshSkewMs?: number | undefined;
+}
+/** An ad-hoc request for routes no module covers yet. `auth` is required: decide per route. */
+export interface RawRequest extends CallOptions {
+    service?: ServiceKey;
+    /** Use instead of `service` for a URL outside the host map. */
+    baseUrl?: string;
+    method: HttpMethod;
+    /** Absolute path; `{name}` placeholders are filled from `pathParams`. */
+    path: string;
+    pathParams?: Readonly<Record<string, string | number>>;
+    auth: AuthMode;
+    query?: QueryParams;
+    body?: unknown;
+    requiresTenant?: boolean;
+    responseType?: ResponseType;
+}
+export interface SessionHandle {
+    get(): Promise<Session | null>;
+    set(session: Session): Promise<void>;
+    clear(): Promise<void>;
+    /** The current access token's claims (unverified), or null. */
+    claims(): Promise<SmessJwtClaims | null>;
+}
+export interface SmessClient {
+    readonly config: Readonly<SmessClientConfig>;
+    /** Calls a declared endpoint. */
+    call<E extends AnyEndpoint>(endpoint: E, ...args: CallArgs<E>): Promise<EndpointResult<E>>;
+    /** Calls any route. Prefer a module function when one exists. */
+    request<T = unknown>(request: RawRequest): Promise<T>;
+    /** A client with some settings replaced (headers are merged). Shares the session store unless replaced. */
+    with(overrides: Partial<SmessClientConfig>): SmessClient;
+    readonly session: SessionHandle;
+}
+export declare function createSmessClient(config: SmessClientConfig): SmessClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/core/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"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"}