@winwinmbs/portal-api 1.0.0 → 2.0.0

package/README.md

@@ -1,29 +1,384 @@
-## @winwinmbs/portal-api
+# `@winwinmbs/portal-api` — Implementation Guide
 
-Business API client for WINWIN Portal. Decoupled from authentication — accepts a `getToken` callback from any auth source.
+Typed REST client for the WINWIN Portal API. Wraps every public endpoint
+(users, roles, permissions, workflows, files, todos, etc.) with type-safe
+methods. Uses axios under the hood; bearer-token + API-key injection are
+handled automatically.
 
-## Install
+> **For AI agents:** this package is **just an HTTP client**. It does not
+> manage auth state, refresh tokens, or persist anything. Pair it with
+> [`@winwinmbs/portal-auth`](https://www.npmjs.com/package/@winwinmbs/portal-auth) (browser) or
+> a service-to-service token (backend) for the auth side.
+
+---
+
+## 1. Install
 
 ```bash
+npm install @winwinmbs/portal-api
+# or
 pnpm add @winwinmbs/portal-api
 ```
 
-## Usage with @winwinmbs/portal-auth
+Peer requirement: `axios` (declared as dep — installed automatically).
+
+---
+
+## 2. The whole shape
+
+```ts
+import { PortalApiClient } from '@winwinmbs/portal-api';
+
+const portal = new PortalApiClient({
+  apiUrl: 'https://api.winwinmbs.com',
+  getToken: () => localStorage.getItem('access_token'),     // sync read
+  apiKey: 'app_xxx',                                        // optional
+  timeout: 30_000,                                          // optional, ms
+});
+
+// All API surfaces are properties on the client:
+const me = await portal.user.findById(userId);
+const orgs = await portal.organization.tree();
+const todos = await portal.todo.search({ /* ... */ });
+```
+
+---
+
+## 3. Available API namespaces
+
+Each namespace maps to a portal feature module. Consult the IDE's autocomplete
+for the full method list — types are exported from the package.
+
+| Namespace | Endpoint group | Common methods |
+|-----------|----------------|----------------|
+| `portal.user` | `/users/*` | `search`, `findById`, `create`, `update`, `delete`, `setRoles`, `setPositions` |
+| `portal.organization` | `/organizations/*` | `tree`, `findById`, `create`, `update`, `move`, `delete` |
+| `portal.role` | `/roles/*` | `search`, `findById`, `create`, `update`, `setPermissions` |
+| `portal.permission` | `/permissions/*` | `search`, `findById`, `create`, `update` |
+| `portal.permissionCategory` | `/permission-categories/*` | `search`, `tree`, `create` |
+| `portal.workflow` | `/workflows/*` | `search`, `findById`, `instances`, `tasks`, `approve`, `reject` |
+| `portal.todo` | `/todos/*` | `search`, `findById`, `create`, `update`, `complete` |
+| `portal.files` | `/files/*` | `upload`, `download`, `findById`, `delete` |
+| `portal.email` | `/emails/*` | `send`, `templates`, `history` |
+| `portal.otp` | `/otp/*` | `request`, `verify` |
+| `portal.line` | `/line/*` | `link`, `unlink`, `notify` |
+| `portal.webhook` | `/webhooks/*` | `search`, `findById`, `create`, `delete` |
+| `portal.systemConfig` | `/system-configs/*` | `getCategory`, `getByKey`, `update` |
+| `portal.eventLog` | `/event-logs/*` | `search`, `findById` |
+| `portal.health` | `/health` | `check` |
+
+Every method returns the underlying portal response shape (typed via
+`@win-portal/shared` DTOs). Most search/list endpoints return
+`ApiPaginatedResponse<T>`; single-resource endpoints return `ApiResponse<T>`.
+
+---
+
+## 4. Configuration reference
+
+```ts
+interface PortalApiConfig {
+  /** Portal API base URL (no trailing slash) */
+  apiUrl: string;
+
+  /**
+   * Sync getter for the current access token. Called on every request.
+   * Return null when there's no session — requests will go out without
+   * Authorization, and the portal will respond 401 if auth is required.
+   */
+  getToken: () => string | null;
+
+  /**
+   * Optional app-scoped API key. Required for /v1/auth/* endpoints and any
+   * other route that gates access via x-api-key. Sent as 'X-API-Key' header.
+   */
+  apiKey?: string;
+
+  /** Per-request timeout in ms. Default 30_000. */
+  timeout?: number;
+}
+```
+
+`getToken` is **synchronous on purpose**. Most consumers cache the current
+access token in memory or `localStorage` and read it cheaply. If you only
+have an async source, do the refresh out-of-band (e.g. on app boot or via
+`portal-auth.getAccessToken()`) and write the result somewhere sync-readable.
+
+---
 
-```typescript
+## 5. Quickstart — browser app paired with `portal-auth`
+
+```ts
 import { AuthClient } from '@winwinmbs/portal-auth';
 import { PortalApiClient } from '@winwinmbs/portal-api';
 
-const auth = new AuthClient({ apiUrl, mode: 'sso', portalUrl, appId });
-const api = new PortalApiClient({
+// 1) Auth side — manages tokens, refresh, storage
+const auth = new AuthClient({
+  apiUrl: 'https://api.winwinmbs.com',
+  mode: 'sso',
+  portalUrl: 'https://portal.winwinmbs.com',
+  appId: 'your-app-id',
+});
+await auth.start();
+
+// 2) API client — reads the token written by auth
+let cachedToken: string | null = null;
+auth.on('token_refreshed', ({ token }) => { cachedToken = token; });
+auth.on('authenticated', () => { auth.getAccessToken().then(t => cachedToken = t); });
+
+const portal = new PortalApiClient({
+  apiUrl: 'https://api.winwinmbs.com',
+  getToken: () => cachedToken,
+});
+
+// 3) Use it
+const users = await portal.user.search({ limit: 20 });
+```
+
+Or (simpler, but does an async read every request):
+
+```ts
+const portal = new PortalApiClient({
   apiUrl,
-  getToken: () => auth.getAccessToken(),
+  // axios wrapper is sync, so we can't await here. Pre-cache and let auth
+  // events keep the local token current.
+  getToken: () => auth['token'] ?? null,    // 👈 if you want to read internal cache
+});
+```
+
+The recommended pattern is the event-listener one above — it keeps the
+`getToken` callback predictably synchronous.
+
+---
+
+## 6. Quickstart — backend service-to-service
+
+```ts
+import { PortalApiClient } from '@winwinmbs/portal-api';
+
+// Backend has its own long-lived API key + can mint its own service token
+// (or proxy the user's token through). Simplest: read both from env.
+const portal = new PortalApiClient({
+  apiUrl: process.env.PORTAL_API_URL!,
+  apiKey: process.env.PORTAL_API_KEY!,
+  getToken: () => process.env.PORTAL_SERVICE_TOKEN ?? null,
 });
 
-await api.files.upload(/* ... */);
-await api.workflow.list();
+// Hit any read endpoint:
+const apps = await portal.organization.tree();
+```
+
+For per-request user-scoped calls (e.g. an Express handler forwarding the
+caller's token), close over the request:
+
+```ts
+app.get('/me/orgs', async (req, res) => {
+  const portal = new PortalApiClient({
+    apiUrl: process.env.PORTAL_API_URL!,
+    apiKey: process.env.PORTAL_API_KEY!,
+    getToken: () => req.token ?? null,    // populated by portal-auth-server
+  });
+  const orgs = await portal.organization.tree();
+  res.json(orgs);
+});
 ```
 
-## Available API modules
+The `PortalApiClient` is cheap to construct — instantiating per-request is
+fine. Or hoist + close over a mutable token holder if you prefer.
+
+---
+
+## 7. Common scenarios
+
+### 7.1 Search with pagination
+
+```ts
+const page = await portal.user.search({
+  page: 1,
+  limit: 20,
+  filter: { status: ['active'] },
+  sort: [{ field: 'created_at', order: 'DESC' }],
+});
+
+// Returned shape (ApiPaginatedResponse<UserResponseDto>):
+//   { success, data: User[], pagination: { page, limit, total, total_pages } }
+```
+
+### 7.2 File upload
+
+```ts
+const formData = new FormData();
+formData.append('file', file);
+const result = await portal.files.upload(formData, { category: 'avatar' });
+// result.data.id is the file_id you can store on user.avatar_file_id
+```
+
+(Browser `FormData` for browser; Node consumers use `FormData` from
+`undici` or `form-data`.)
+
+### 7.3 Workflow approval
+
+```ts
+const tasks = await portal.workflow.tasks({ assignee_user_id: meUserId });
+const myPending = tasks.data.filter(t => t.status === 'pending');
+
+await portal.workflow.approve(taskId, {
+  comment: 'LGTM',
+  metadata: { /* per-workflow custom data */ },
+});
+```
+
+### 7.4 Composing typed responses
+
+The DTOs are exported by `@win-portal/shared` (the portal's source of truth).
+This client re-uses those types directly:
+
+```ts
+import type { UserResponseDto } from '@win-portal/shared/user';
+
+async function findUser(id: string): Promise<UserResponseDto | null> {
+  try {
+    const res = await portal.user.findById(id);
+    return res.data;
+  } catch (err) {
+    if (axios.isAxiosError(err) && err.response?.status === 404) return null;
+    throw err;
+  }
+}
+```
+
+---
+
+## 8. Error handling
+
+The client lets axios errors propagate. Patterns:
+
+```ts
+import axios from 'axios';
+
+try {
+  await portal.user.findById(id);
+} catch (err) {
+  if (axios.isAxiosError(err)) {
+    const status = err.response?.status;
+    const body = err.response?.data;        // ApiResponse-style error envelope
+    if (status === 401) /* token expired or invalid */;
+    if (status === 403) /* forbidden — wrong app or missing permission */;
+    if (status === 404) /* not found */;
+    if (status === 429) /* rate limited; body.retry_after_ms tells you when */;
+    throw err;
+  }
+  throw err;
+}
+```
+
+The portal's error envelope (post-2026-05-05) is:
+
+```json
+{
+  "success": false,
+  "error": {
+    "code": "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "VALIDATION_ERROR" | ...,
+    "message": "<localized human message>",
+    "details": { ... },
+    "timestamp": "2026-05-05T...",
+    "path": "/users/abc",
+    "method": "GET",
+    "statusCode": 401,
+    "requestId": "req_..."
+  }
+}
+```
+
+`requestId` is searchable in the portal's audit log — pass it to portal
+support when reporting issues.
+
+---
+
+## 9. Don'ts
+
+- ❌ **Don't manage tokens inside this client.** It's a transport, not an
+  auth library. Refresh, storage, and lifecycle live in `portal-auth`.
+- ❌ **Don't decode `getToken`'s return value to check expiry.** Just return
+  it. If the portal says 401, deal with it then.
+- ❌ **Don't omit `apiKey` for `/v1/auth/*` calls.** That whole surface
+  requires it; you'll get 401 with `MISSING_API_KEY`.
+- ❌ **Don't share one `PortalApiClient` across users on a backend.** It
+  closes over `getToken`, so per-request construction (or a mutable holder)
+  is the correct pattern.
+- ❌ **Don't write your own retry logic on top of this.** The portal's rate
+  limiter returns 429 with `retry_after_ms`; respect that. Generic
+  exponential backoff against any 5xx is reasonable, but skip 4xx (it won't
+  recover by retrying).
+
+---
+
+## 10. Cross-package integration
+
+| Combine with | Why |
+|--------------|-----|
+| [`@winwinmbs/portal-auth`](https://www.npmjs.com/package/@winwinmbs/portal-auth) | Browser auth — feeds `getToken` from the SDK's storage |
+| [`@winwinmbs/portal-auth-react`](https://www.npmjs.com/package/@winwinmbs/portal-auth-react) | React app structure — `useSession().getAccessToken` for token reads (note: that's async, see §5) |
+| [`@winwinmbs/portal-auth-server`](https://www.npmjs.com/package/@winwinmbs/portal-auth-server) | Backend that validates AND forwards the user's token via this client |
+
+Two-package combo (browser):
+
+```
+React component
+  └─ useApi() {
+       const { getAccessToken } = useSession();
+       return useMemo(() => new PortalApiClient({
+         apiUrl,
+         getToken: () => /* sync mirror of getAccessToken result */,
+       }), [...]);
+     }
+```
+
+The trick: React renders synchronously, but `getAccessToken` is async
+(because it may refresh). Either:
+
+1. Maintain a sync mirror updated by the `'token_refreshed'` event
+   (recommended — illustrated in §5).
+2. Or wrap your fetch helpers in `async (path, init) => { const t = await
+   getAccessToken(); return fetch(...) }` and skip `PortalApiClient` for
+   that one call site.
+
+---
+
+## 11. Where to look in source
+
+| File | Contents |
+|------|----------|
+| `src/portal-api-client.ts` | The `PortalApiClient` class, axios setup, interceptors |
+| `src/api/user.api.ts` | User CRUD + role/position management |
+| `src/api/organization.api.ts` | Org tree CRUD + move |
+| `src/api/role.api.ts` | Role CRUD + permission attachment |
+| `src/api/permission.api.ts` | Permission CRUD |
+| `src/api/workflow.api.ts` | Workflow definition + instance + task |
+| `src/api/files.api.ts` | File upload/download |
+| `src/api/email.api.ts` | Email send + templates |
+| `src/api/otp.api.ts` | OTP request/verify |
+| `src/api/todo.api.ts` | Todo CRUD |
+| `src/api/system-config.api.ts` | System config read/write (admin-scoped) |
+| `src/api/health.api.ts` | Health check |
+| `src/api/event-log.api.ts` | Audit log search |
+| `src/api/line.api.ts` | LINE link/unlink/notify |
+| `src/api/webhook.api.ts` | Webhook subscriptions |
+| `src/api/permission-category.api.ts` | Permission grouping tree |
+| `src/types/` | Re-exported DTO types from `@win-portal/shared` |
+| `src/portal-api-client.spec.ts` | Reference for instantiation + interceptor behaviour |
+
+---
+
+## 12. Reference: API surface contract
+
+This client tracks the portal's HTTP API. Every method here corresponds to a
+NestJS controller route in `apps/api/src/modules/features/<domain>/`. If the
+portal adds an endpoint, it must be added here too — but the portal team
+keeps the two in sync via a shared DTO package, so renames or signature
+changes break compilation immediately rather than at runtime.
+
+For a list of capabilities (high-level inventory of what the portal can do),
+see [`docs/PORTAL_CAPABILITIES.md`](https://github.com/MBS-Business-Solutions/win-portal/blob/main/docs/PORTAL_CAPABILITIES.md).
 
-email, eventLog, files, health, line, organization, otp, permission, permissionCategory, role, systemConfig, todo, user, webhook, workflow
+For low-level type definitions, browse `packages/shared/src/dto/` — the
+client re-exports those types unchanged.

package/dist/_tsup-dts-rollup.d.mts

@@ -305,6 +305,72 @@ export { ClearAllDataResponse }
 export { ClearAllDataResponse as ClearAllDataResponse_alias_1 }
 export { ClearAllDataResponse as ClearAllDataResponse_alias_2 }
 
+/**
+ * Machine-to-machine (M2M) token provider — OAuth 2.0 `client_credentials` grant.
+ *
+ * For SERVER-side / service-to-service use only. The client secret is a
+ * confidential credential and must never run in a browser.
+ *
+ * Obtain a client_id / client_secret from the portal
+ * (Settings → Developer → Machine-to-Machine), then:
+ *
+ * ```ts
+ * const tokens = new ClientCredentialsTokenProvider({
+ *   apiUrl: 'https://portal.example.com',
+ *   clientId: 'app_...',
+ *   clientSecret: 'secret_...',
+ *   scope: 'applications:read',          // optional down-scope
+ * });
+ *
+ * const api = new PortalApiClient({
+ *   apiUrl: 'https://portal.example.com',
+ *   getToken: () => tokens.getAccessToken(), // async getToken is supported
+ * });
+ * ```
+ *
+ * The provider caches the access token and refreshes it shortly before expiry
+ * (`expires_in`), de-duplicating concurrent refreshes.
+ */
+declare interface ClientCredentialsConfig {
+    /** Portal API base URL, e.g. `https://portal.example.com`. */
+    apiUrl: string;
+    /** M2M client id (`app_...`). */
+    clientId: string;
+    /** M2M client secret (`secret_...`) — confidential, server-side only. */
+    clientSecret: string;
+    /** Optional space-separated scope to down-scope the token (RFC 6749 §3.3). */
+    scope?: string;
+    /** Refresh this many seconds before expiry (default 60). */
+    refreshSkewSeconds?: number;
+    /** Override the token endpoint (default `${apiUrl}/oauth/token`). */
+    tokenEndpoint?: string;
+    /** Custom fetch implementation (defaults to global `fetch`). */
+    fetchFn?: typeof fetch;
+}
+export { ClientCredentialsConfig }
+export { ClientCredentialsConfig as ClientCredentialsConfig_alias_1 }
+
+declare class ClientCredentialsTokenProvider {
+    private readonly config;
+    private token;
+    private expiresAtMs;
+    private inflight;
+    constructor(config: ClientCredentialsConfig);
+    /**
+     * Returns a valid access token, fetching or refreshing as needed. Safe to call
+     * on every request — cached until shortly before expiry. Concurrent calls
+     * share a single in-flight request.
+     */
+    getAccessToken(): Promise<string>;
+    /** Last cached token without triggering a fetch (may be stale or null). */
+    getCachedToken(): string | null;
+    /** Forget the cached token so the next `getAccessToken()` fetches a fresh one. */
+    reset(): void;
+    private fetchToken;
+}
+export { ClientCredentialsTokenProvider }
+export { ClientCredentialsTokenProvider as ClientCredentialsTokenProvider_alias_1 }
+
 /**
  * Create Event Log Request DTO
  *
@@ -2128,7 +2194,13 @@ export { PortalApiClient as PortalApiClient_alias_1 }
 
 declare interface PortalApiConfig {
     apiUrl: string;
-    getToken: () => string | null;
+    /**
+     * Bearer token source. May be sync or async — pass a
+     * `ClientCredentialsTokenProvider.getAccessToken` for service-to-server (M2M)
+     * auth, or any function returning the current user token. Optional when
+     * authenticating purely via `apiKey`.
+     */
+    getToken?: () => string | null | Promise<string | null>;
     apiKey?: string;
     timeout?: number;
 }

package/dist/_tsup-dts-rollup.d.ts

@@ -305,6 +305,72 @@ export { ClearAllDataResponse }
 export { ClearAllDataResponse as ClearAllDataResponse_alias_1 }
 export { ClearAllDataResponse as ClearAllDataResponse_alias_2 }
 
+/**
+ * Machine-to-machine (M2M) token provider — OAuth 2.0 `client_credentials` grant.
+ *
+ * For SERVER-side / service-to-service use only. The client secret is a
+ * confidential credential and must never run in a browser.
+ *
+ * Obtain a client_id / client_secret from the portal
+ * (Settings → Developer → Machine-to-Machine), then:
+ *
+ * ```ts
+ * const tokens = new ClientCredentialsTokenProvider({
+ *   apiUrl: 'https://portal.example.com',
+ *   clientId: 'app_...',
+ *   clientSecret: 'secret_...',
+ *   scope: 'applications:read',          // optional down-scope
+ * });
+ *
+ * const api = new PortalApiClient({
+ *   apiUrl: 'https://portal.example.com',
+ *   getToken: () => tokens.getAccessToken(), // async getToken is supported
+ * });
+ * ```
+ *
+ * The provider caches the access token and refreshes it shortly before expiry
+ * (`expires_in`), de-duplicating concurrent refreshes.
+ */
+declare interface ClientCredentialsConfig {
+    /** Portal API base URL, e.g. `https://portal.example.com`. */
+    apiUrl: string;
+    /** M2M client id (`app_...`). */
+    clientId: string;
+    /** M2M client secret (`secret_...`) — confidential, server-side only. */
+    clientSecret: string;
+    /** Optional space-separated scope to down-scope the token (RFC 6749 §3.3). */
+    scope?: string;
+    /** Refresh this many seconds before expiry (default 60). */
+    refreshSkewSeconds?: number;
+    /** Override the token endpoint (default `${apiUrl}/oauth/token`). */
+    tokenEndpoint?: string;
+    /** Custom fetch implementation (defaults to global `fetch`). */
+    fetchFn?: typeof fetch;
+}
+export { ClientCredentialsConfig }
+export { ClientCredentialsConfig as ClientCredentialsConfig_alias_1 }
+
+declare class ClientCredentialsTokenProvider {
+    private readonly config;
+    private token;
+    private expiresAtMs;
+    private inflight;
+    constructor(config: ClientCredentialsConfig);
+    /**
+     * Returns a valid access token, fetching or refreshing as needed. Safe to call
+     * on every request — cached until shortly before expiry. Concurrent calls
+     * share a single in-flight request.
+     */
+    getAccessToken(): Promise<string>;
+    /** Last cached token without triggering a fetch (may be stale or null). */
+    getCachedToken(): string | null;
+    /** Forget the cached token so the next `getAccessToken()` fetches a fresh one. */
+    reset(): void;
+    private fetchToken;
+}
+export { ClientCredentialsTokenProvider }
+export { ClientCredentialsTokenProvider as ClientCredentialsTokenProvider_alias_1 }
+
 /**
  * Create Event Log Request DTO
  *
@@ -2128,7 +2194,13 @@ export { PortalApiClient as PortalApiClient_alias_1 }
 
 declare interface PortalApiConfig {
     apiUrl: string;
-    getToken: () => string | null;
+    /**
+     * Bearer token source. May be sync or async — pass a
+     * `ClientCredentialsTokenProvider.getAccessToken` for service-to-server (M2M)
+     * auth, or any function returning the current user token. Optional when
+     * authenticating purely via `apiKey`.
+     */
+    getToken?: () => string | null | Promise<string | null>;
     apiKey?: string;
     timeout?: number;
 }

package/dist/index.d.mts

@@ -1,5 +1,7 @@
 export { PortalApiClient } from './_tsup-dts-rollup.mjs';
 export { PortalApiConfig } from './_tsup-dts-rollup.mjs';
+export { ClientCredentialsTokenProvider_alias_1 as ClientCredentialsTokenProvider } from './_tsup-dts-rollup.mjs';
+export { ClientCredentialsConfig_alias_1 as ClientCredentialsConfig } from './_tsup-dts-rollup.mjs';
 export { HealthAPI } from './_tsup-dts-rollup.mjs';
 export { SystemConfigAPI } from './_tsup-dts-rollup.mjs';
 export { FilesAPI } from './_tsup-dts-rollup.mjs';

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { PortalApiClient } from './_tsup-dts-rollup.js';
 export { PortalApiConfig } from './_tsup-dts-rollup.js';
+export { ClientCredentialsTokenProvider_alias_1 as ClientCredentialsTokenProvider } from './_tsup-dts-rollup.js';
+export { ClientCredentialsConfig_alias_1 as ClientCredentialsConfig } from './_tsup-dts-rollup.js';
 export { HealthAPI } from './_tsup-dts-rollup.js';
 export { SystemConfigAPI } from './_tsup-dts-rollup.js';
 export { FilesAPI } from './_tsup-dts-rollup.js';

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ActorType: () => ActorType,
+  ClientCredentialsTokenProvider: () => ClientCredentialsTokenProvider,
   EmailAPI: () => EmailAPI,
   EventCategory: () => EventCategory,
   EventLogApi: () => EventLogApi,
@@ -2011,8 +2012,8 @@ var PortalApiClient = class {
       timeout: config.timeout ?? 3e4,
       withCredentials: true
     });
-    this.axios.interceptors.request.use((cfg) => {
-      const token = config.getToken();
+    this.axios.interceptors.request.use(async (cfg) => {
+      const token = config.getToken ? await config.getToken() : null;
       if (token) cfg.headers.Authorization = `Bearer ${token}`;
       if (config.apiKey) cfg.headers["X-API-Key"] = config.apiKey;
       return cfg;
@@ -2050,6 +2051,78 @@ var PortalApiClient = class {
   }
 };
 
+// src/client-credentials.ts
+var ClientCredentialsTokenProvider = class {
+  constructor(config) {
+    this.config = config;
+    this.token = null;
+    this.expiresAtMs = 0;
+    this.inflight = null;
+    if (!config.clientId || !config.clientSecret) {
+      throw new Error("ClientCredentialsTokenProvider requires clientId and clientSecret");
+    }
+  }
+  /**
+   * Returns a valid access token, fetching or refreshing as needed. Safe to call
+   * on every request — cached until shortly before expiry. Concurrent calls
+   * share a single in-flight request.
+   */
+  async getAccessToken() {
+    const skewMs = (this.config.refreshSkewSeconds ?? 60) * 1e3;
+    if (this.token && Date.now() < this.expiresAtMs - skewMs) {
+      return this.token;
+    }
+    if (!this.inflight) {
+      this.inflight = this.fetchToken().finally(() => {
+        this.inflight = null;
+      });
+    }
+    return this.inflight;
+  }
+  /** Last cached token without triggering a fetch (may be stale or null). */
+  getCachedToken() {
+    return this.token;
+  }
+  /** Forget the cached token so the next `getAccessToken()` fetches a fresh one. */
+  reset() {
+    this.token = null;
+    this.expiresAtMs = 0;
+  }
+  async fetchToken() {
+    const fetchFn = this.config.fetchFn ?? globalThis.fetch;
+    if (typeof fetchFn !== "function") {
+      throw new Error("No fetch implementation available \u2014 pass config.fetchFn");
+    }
+    const endpoint = this.config.tokenEndpoint ?? `${this.config.apiUrl.replace(/\/$/, "")}/oauth/token`;
+    const body = {
+      grant_type: "client_credentials",
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret
+    };
+    if (this.config.scope) body.scope = this.config.scope;
+    const res = await fetchFn(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      let detail = "";
+      try {
+        detail = JSON.stringify(await res.json());
+      } catch {
+      }
+      throw new Error(`client_credentials token request failed (HTTP ${res.status}) ${detail}`.trim());
+    }
+    const data = await res.json();
+    if (!data.access_token) {
+      throw new Error("client_credentials response did not include an access_token");
+    }
+    this.token = data.access_token;
+    this.expiresAtMs = Date.now() + (data.expires_in ?? 3600) * 1e3;
+    return this.token;
+  }
+};
+
 // ../../shared/src/enums/common.enums.ts
 var OrganizationType = /* @__PURE__ */ ((OrganizationType2) => {
   OrganizationType2["GROUP"] = "group";
@@ -2118,6 +2191,7 @@ var TodoPriority = /* @__PURE__ */ ((TodoPriority2) => {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ActorType,
+  ClientCredentialsTokenProvider,
   EmailAPI,
   EventCategory,
   EventLogApi,