@emesoft_company/playwright-core 2.1.0

package/README.md

@@ -0,0 +1,62 @@
+# @emesoft_company/playwright-core
+
+Shared, production-grade Playwright automation core consumed by independent test project
+repositories. Provides fixtures, config loading, API client abstraction, auth helpers,
+generic UI base components, structured logging, retry/error handling, and optional Allure
+reporting integration.
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for how core and consuming projects
+interact, [`docs/EXTENDING.md`](docs/EXTENDING.md) for override patterns,
+[`docs/PUBLISHING.md`](docs/PUBLISHING.md) for versioning/publishing strategy, and
+[`docs/NEW_PROJECT.md`](docs/NEW_PROJECT.md) for scaffolding a new project that consumes core
+(`scripts/scaffold-e2e-project.sh` + `templates/e2e-project/`).
+
+## Install (consuming projects)
+
+No private registry yet — install directly from this repo, pinned to a tag:
+
+```bash
+pnpm add "@emesoft_company/playwright-core@github:emesoft/playwright-core#v2.1.0"
+```
+
+For local development across repos in the same workspace, a project can point at the local
+folder instead via a `file:` dependency (see `docs/PUBLISHING.md`).
+
+## Develop
+
+```bash
+pnpm install
+pnpm build       # tsup -> dist/ (ESM + CJS + .d.ts)
+pnpm test        # vitest unit tests for loader/retry/etc.
+pnpm typecheck
+```
+
+## Package layout
+
+| Subpath | Purpose |
+|---|---|
+| `@emesoft_company/playwright-core` | Barrel export of the full public API |
+| `@emesoft_company/playwright-core/config` | Multi-environment config loader + zod schema |
+| `@emesoft_company/playwright-core/fixtures` | Base Playwright fixtures (logger, apiClient, auth, retry) |
+| `@emesoft_company/playwright-core/api` | API client abstraction over `APIRequestContext` |
+| `@emesoft_company/playwright-core/auth` | Token provider / JWT auth helpers |
+| `@emesoft_company/playwright-core/ui` | Generic `BasePage` / `BaseComponent` (no selectors, no business logic) |
+| `@emesoft_company/playwright-core/logging` | Structured logger |
+| `@emesoft_company/playwright-core/errors` | `AppError` classes + `withRetry` helper |
+| `@emesoft_company/playwright-core/reporting` | Optional Allure reporter wiring |
+| `@emesoft_company/playwright-core/di` | Lightweight service container used by fixtures |
+| `@emesoft_company/playwright-core/utils` | `sleep`, `waitForCondition` (generic polling, outside UI locators), `deepMerge` |
+| `@emesoft_company/playwright-core/data` | Unique/random value generators (`uniqueId`, `uniqueEmail`, `isoDate`, …) |
+| `@emesoft_company/playwright-core/expect` | `expect` with `toHaveStatus` / `toMatchSchema` (also re-exported from `/fixtures`) |
+
+## What a project gets for free
+
+- **`defineE2EConfig()`** — the entire `playwright.config.ts` in three lines
+- **`TableComponent`** — cells by column name, whole-table `records()`, row filtering
+- **`BasePage` / `BaseComponent`** — safe click/fill/select/upload, scoped lookups, waits
+- **`ApiClient`** — bearer auth, retry on 5xx/429, zod-validated responses, assertable error statuses
+- **Auth** — one-time login (single or per role) with reusable storage state
+- **Diagnostics** — console/page errors and failed requests attached to the report automatically
+- **`cleanup`** — LIFO teardown for data a test created
+
+Upgrading from 1.x? See [`docs/MIGRATION-v2.md`](docs/MIGRATION-v2.md).

package/dist/api/index.cjs

@@ -0,0 +1,248 @@
+'use strict';
+
+// src/errors/app-error.ts
+var AppError = class extends Error {
+  code;
+  context;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = new.target.name;
+    this.code = options.code;
+    this.context = options.context;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ApiError = class extends AppError {
+  status;
+  method;
+  url;
+  constructor(message, options) {
+    super(message, options);
+    this.status = options.status;
+    this.method = options.method;
+    this.url = options.url;
+  }
+};
+
+// src/auth/token-provider.ts
+var NullTokenProvider = class {
+  async getToken() {
+    return "";
+  }
+  invalidate() {
+  }
+};
+
+// src/utils/sleep.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/errors/retry.ts
+function backoffDelay(attempt, minDelayMs, maxDelayMs, factor) {
+  const exponential = minDelayMs * factor ** (attempt - 1);
+  const jitter = Math.random() * minDelayMs;
+  return Math.min(exponential + jitter, maxDelayMs);
+}
+async function withRetry(fn, options = {}) {
+  const {
+    retries = 2,
+    minDelayMs = 200,
+    maxDelayMs = 5e3,
+    factor = 2,
+    retryOn = () => true,
+    onRetry,
+    onGiveUp
+  } = options;
+  const maxAttempts = retries + 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      const isLastAttempt = attempt >= maxAttempts;
+      if (isLastAttempt || !retryOn(error)) {
+        onGiveUp?.(error, attempt);
+        throw error;
+      }
+      onRetry?.(error, attempt);
+      await sleep(backoffDelay(attempt, minDelayMs, maxDelayMs, factor));
+    }
+  }
+  throw new Error("withRetry: unreachable state");
+}
+
+// src/api/interceptors.ts
+function isRetryableStatus(status) {
+  return status === 429 || status >= 500 && status <= 599;
+}
+
+// src/api/api-client.ts
+var TransientHttpError = class extends Error {
+  constructor(status) {
+    super(`Transient HTTP status ${status}`);
+    this.status = status;
+  }
+  status;
+};
+var ApiClient = class {
+  request;
+  baseUrl;
+  tokenProvider;
+  logger;
+  retryOptions;
+  defaultHeaders;
+  interceptors;
+  constructor(options) {
+    this.request = options.request;
+    this.baseUrl = options.baseUrl;
+    this.tokenProvider = options.tokenProvider ?? new NullTokenProvider();
+    this.logger = options.logger;
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.interceptors = options.interceptors ?? {};
+    this.retryOptions = { ...options.retry };
+  }
+  get(path, options) {
+    return this.requestBody("GET", path, options);
+  }
+  post(path, options) {
+    return this.requestBody("POST", path, options);
+  }
+  put(path, options) {
+    return this.requestBody("PUT", path, options);
+  }
+  patch(path, options) {
+    return this.requestBody("PATCH", path, options);
+  }
+  delete(path, options) {
+    return this.requestBody("DELETE", path, options);
+  }
+  /**
+   * Full response including status and headers. Retries transient statuses, then returns
+   * whatever came back — a 404 or 500 is a normal return value here, not an exception.
+   * Network/timeout failures still throw.
+   */
+  async send(method, path, options = {}) {
+    const url = this.resolveUrl(path, options.params);
+    let lastResponse;
+    try {
+      await withRetry(
+        async () => {
+          lastResponse = await this.fetchOnce(method, url, options);
+          if (isRetryableStatus(lastResponse.status) && !this.isExpectedStatus(lastResponse.status, options)) {
+            throw new TransientHttpError(lastResponse.status);
+          }
+        },
+        {
+          ...this.retryOptions,
+          retryOn: (error) => error instanceof TransientHttpError,
+          onRetry: (error, attempt) => this.logger?.warn({ method, url, attempt, err: error }, "retrying API request")
+        }
+      );
+    } catch (error) {
+      if (!(error instanceof TransientHttpError)) throw error;
+    }
+    if (!lastResponse) {
+      throw new AppError(`API request produced no response: ${method} ${url}`, {
+        code: "API_NO_RESPONSE",
+        context: { method, url }
+      });
+    }
+    return lastResponse;
+  }
+  async requestBody(method, path, options = {}) {
+    const response = await this.send(method, path, options);
+    if (!this.isExpectedStatus(response.status, options)) {
+      if (response.status === 401) this.tokenProvider.invalidate();
+      this.logger?.error(
+        { status: response.status, method, url: response.url, body: response.data },
+        "API request failed"
+      );
+      throw new ApiError(
+        `API request failed: ${method} ${response.url} -> ${response.status}` + (options.expectStatus === void 0 ? "" : ` (expected ${String(options.expectStatus)})`),
+        {
+          code: "API_REQUEST_FAILED",
+          status: response.status,
+          method,
+          url: response.url,
+          context: { body: response.data }
+        }
+      );
+    }
+    return response.data;
+  }
+  isExpectedStatus(status, options) {
+    if (options.expectStatus === void 0) return status >= 200 && status < 300;
+    const expected = Array.isArray(options.expectStatus) ? options.expectStatus : [options.expectStatus];
+    return expected.includes(status);
+  }
+  async fetchOnce(method, url, options) {
+    const headers = await this.buildHeaders(method, url, options);
+    const response = await this.request.fetch(url, {
+      method,
+      headers,
+      data: options.data,
+      form: options.form,
+      multipart: options.multipart,
+      timeout: options.timeoutMs
+    });
+    await this.interceptors.onResponse?.({ method, url, status: response.status() });
+    return {
+      status: response.status(),
+      ok: response.ok(),
+      headers: response.headers(),
+      data: await this.parseBody(response, options),
+      url,
+      method
+    };
+  }
+  resolveUrl(path, params) {
+    const base = this.baseUrl ? new URL(path, this.baseUrl).toString() : path;
+    if (!params) return base;
+    const url = new URL(base);
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  async buildHeaders(method, url, options) {
+    let headers = { ...this.defaultHeaders, ...options.headers };
+    if (!options.skipAuth) {
+      const token = await this.tokenProvider.getToken();
+      if (token) headers = { ...headers, Authorization: `Bearer ${token}` };
+    }
+    const overridden = await this.interceptors.onRequest?.({ method, url, headers });
+    return overridden ?? headers;
+  }
+  async parseBody(response, options) {
+    const raw = await this.readBody(response);
+    if (!options.schema) return raw;
+    const result = options.schema.safeParse(raw);
+    if (!result.success) {
+      throw new ApiError(`API response did not match the expected schema: ${response.url()}`, {
+        code: "API_SCHEMA_MISMATCH",
+        status: response.status(),
+        url: response.url(),
+        context: { issues: result.error.issues, body: raw }
+      });
+    }
+    return result.data;
+  }
+  async readBody(response) {
+    const contentType = response.headers()["content-type"] ?? "";
+    if (contentType.includes("application/json")) {
+      const text = await response.text();
+      if (text.trim() === "") return void 0;
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    }
+    return response.text();
+  }
+};
+
+exports.ApiClient = ApiClient;
+exports.isRetryableStatus = isRetryableStatus;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/api/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors/app-error.ts","../../src/auth/token-provider.ts","../../src/utils/sleep.ts","../../src/errors/retry.ts","../../src/api/interceptors.ts","../../src/api/api-client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["export interface AppErrorOptions {\n  code: string;\n  cause?: unknown;\n  context?: Record<string, unknown>;\n}\n\n/**\n * Base error class for the framework. Every error thrown by core carries a\n * machine-readable `code` and optional `context`, so callers can branch on\n * `error.code` instead of parsing messages.\n */\nexport class AppError extends Error {\n  readonly code: string;\n  readonly context?: Record<string, unknown>;\n\n  constructor(message: string, options: AppErrorOptions) {\n    super(message, { cause: options.cause });\n    this.name = new.target.name;\n    this.code = options.code;\n    this.context = options.context;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\nexport class ConfigValidationError extends AppError {\n  constructor(message: string, issues: unknown, context?: Record<string, unknown>) {\n    super(message, { code: \"CONFIG_VALIDATION_ERROR\", context: { issues, ...context } });\n  }\n}\n\nexport class ApiError extends AppError {\n  readonly status?: number;\n  readonly method?: string;\n  readonly url?: string;\n\n  constructor(\n    message: string,\n    options: AppErrorOptions & { status?: number; method?: string; url?: string },\n  ) {\n    super(message, options);\n    this.status = options.status;\n    this.method = options.method;\n    this.url = options.url;\n  }\n}\n\nexport class AuthError extends AppError {\n  constructor(message: string, options: Omit<AppErrorOptions, \"code\"> = {}) {\n    super(message, { code: \"AUTH_ERROR\", ...options });\n  }\n}\n\nexport class ConfigMissingError extends AppError {\n  constructor(name: string) {\n    super(`Required environment variable \"${name}\" is not set`, {\n      code: \"ENV_VAR_MISSING\",\n      context: { name },\n    });\n  }\n}\n","import { AuthError } from \"../errors/app-error.js\";\nimport type { Logger } from \"../logging/logger.js\";\nimport type { TokenProvider } from \"./types.js\";\n\n/** Token provider that always returns a fixed token. Useful for tests/local dev with a pre-issued token. */\nexport class StaticTokenProvider implements TokenProvider {\n  constructor(private readonly token: string) {}\n\n  async getToken(): Promise<string> {\n    return this.token;\n  }\n\n  invalidate(): void {\n    // no-op: nothing to invalidate for a static token\n  }\n}\n\n/** No-op provider for endpoints that don't require authentication. */\nexport class NullTokenProvider implements TokenProvider {\n  async getToken(): Promise<string> {\n    return \"\";\n  }\n\n  invalidate(): void {\n    // no-op\n  }\n}\n\nexport interface JwtTokenProviderOptions {\n  tokenUrl: string;\n  clientId?: string;\n  clientSecret?: string;\n  username?: string;\n  password?: string;\n  /** Seconds subtracted from the token's `expires_in` to refresh proactively. Default: 30. */\n  refreshSkewSeconds?: number;\n  logger?: Logger;\n  fetchImpl?: typeof fetch;\n}\n\ninterface CachedToken {\n  token: string;\n  expiresAt: number;\n}\n\n/**\n * JWT/OAuth2 token provider supporting client-credentials or password grants.\n * Caches the token in-memory and transparently refreshes it before expiry.\n */\nexport class JwtTokenProvider implements TokenProvider {\n  private cached?: CachedToken;\n  private inFlight?: Promise<string>;\n\n  constructor(private readonly options: JwtTokenProviderOptions) {}\n\n  async getToken(): Promise<string> {\n    if (this.cached && this.cached.expiresAt > Date.now()) {\n      return this.cached.token;\n    }\n    if (!this.inFlight) {\n      this.inFlight = this.fetchToken().finally(() => {\n        this.inFlight = undefined;\n      });\n    }\n    return this.inFlight;\n  }\n\n  invalidate(): void {\n    this.cached = undefined;\n  }\n\n  private async fetchToken(): Promise<string> {\n    const { tokenUrl, clientId, clientSecret, username, password, refreshSkewSeconds = 30, logger, fetchImpl = fetch } = this.options;\n\n    const body = new URLSearchParams();\n    if (username && password) {\n      body.set(\"grant_type\", \"password\");\n      body.set(\"username\", username);\n      body.set(\"password\", password);\n    } else {\n      body.set(\"grant_type\", \"client_credentials\");\n    }\n    if (clientId) body.set(\"client_id\", clientId);\n    if (clientSecret) body.set(\"client_secret\", clientSecret);\n\n    logger?.debug({ tokenUrl }, \"fetching auth token\");\n\n    let response: Response;\n    try {\n      response = await fetchImpl(tokenUrl, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n        body,\n      });\n    } catch (cause) {\n      throw new AuthError(`Failed to reach token endpoint ${tokenUrl}`, { cause });\n    }\n\n    if (!response.ok) {\n      const text = await response.text().catch(() => \"\");\n      throw new AuthError(`Token endpoint returned ${response.status}: ${text}`, {\n        context: { status: response.status, tokenUrl },\n      });\n    }\n\n    const data = (await response.json()) as { access_token?: string; expires_in?: number };\n    if (!data.access_token) {\n      throw new AuthError(\"Token endpoint response missing access_token\", { context: { tokenUrl } });\n    }\n\n    const expiresInSeconds = data.expires_in ?? 300;\n    this.cached = {\n      token: data.access_token,\n      expiresAt: Date.now() + Math.max(expiresInSeconds - refreshSkewSeconds, 0) * 1000,\n    };\n    return this.cached.token;\n  }\n}\n","export function sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n","import { sleep } from \"../utils/sleep.js\";\n\nexport interface RetryOptions {\n  /** Number of retry attempts after the initial try. Default: 2. */\n  retries?: number;\n  minDelayMs?: number;\n  maxDelayMs?: number;\n  /** Exponential backoff factor. Default: 2. */\n  factor?: number;\n  /** Return true to retry this error, false to fail fast. Default: retry everything. */\n  retryOn?: (error: unknown) => boolean;\n  /** Called before each retry (not before the first attempt). */\n  onRetry?: (error: unknown, attempt: number) => void;\n  /** Called once when giving up, with the total number of attempts made. */\n  onGiveUp?: (error: unknown, attempts: number) => void;\n}\n\nfunction backoffDelay(attempt: number, minDelayMs: number, maxDelayMs: number, factor: number): number {\n  const exponential = minDelayMs * factor ** (attempt - 1);\n  const jitter = Math.random() * minDelayMs;\n  return Math.min(exponential + jitter, maxDelayMs);\n}\n\n/**\n * Runs `fn` with exponential-backoff retry. Used for both flaky API calls and\n * flaky UI actions so the retry policy stays consistent across the framework.\n *\n * Always rethrows the ORIGINAL error — whether it failed fast (`retryOn` returned\n * false) or exhausted its retries. That's what makes `catch (e) { e instanceof ApiError }`\n * and `expect(...).rejects.toThrow(ApiError)` work in tests; wrapping the error in a\n * retry-specific type would hide the only thing the caller actually wants to assert on.\n * Use `onGiveUp` if you need the attempt count.\n */\nexport async function withRetry<T>(fn: () => Promise<T>, options: RetryOptions = {}): Promise<T> {\n  const {\n    retries = 2,\n    minDelayMs = 200,\n    maxDelayMs = 5_000,\n    factor = 2,\n    retryOn = () => true,\n    onRetry,\n    onGiveUp,\n  } = options;\n\n  const maxAttempts = retries + 1;\n\n  for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n    try {\n      return await fn();\n    } catch (error) {\n      const isLastAttempt = attempt >= maxAttempts;\n      if (isLastAttempt || !retryOn(error)) {\n        onGiveUp?.(error, attempt);\n        throw error;\n      }\n      onRetry?.(error, attempt);\n      await sleep(backoffDelay(attempt, minDelayMs, maxDelayMs, factor));\n    }\n  }\n\n  // Unreachable: the loop either returns or throws.\n  throw new Error(\"withRetry: unreachable state\");\n}\n","/** 429 (rate-limited) and any 5xx are considered transient and safe to retry. */\nexport function isRetryableStatus(status: number): boolean {\n  return status === 429 || (status >= 500 && status <= 599);\n}\n","import type { APIRequestContext, APIResponse } from \"@playwright/test\";\nimport { NullTokenProvider } from \"../auth/token-provider.js\";\nimport type { TokenProvider } from \"../auth/types.js\";\nimport { ApiError, AppError } from \"../errors/app-error.js\";\nimport { withRetry, type RetryOptions } from \"../errors/retry.js\";\nimport type { Logger } from \"../logging/logger.js\";\nimport { isRetryableStatus } from \"./interceptors.js\";\nimport type { ApiClientInterceptors, ApiRequestOptions, ApiResponse } from \"./types.js\";\n\nexport interface ApiClientOptions {\n  /** Playwright's `APIRequestContext` (from `request` fixture or `context.request`). */\n  request: APIRequestContext;\n  baseUrl?: string;\n  tokenProvider?: TokenProvider;\n  logger?: Logger;\n  retry?: Partial<RetryOptions>;\n  defaultHeaders?: Record<string, string>;\n  interceptors?: ApiClientInterceptors;\n}\n\n/** Internal signal used to drive retry backoff; never escapes `send()`. */\nclass TransientHttpError extends Error {\n  constructor(readonly status: number) {\n    super(`Transient HTTP status ${status}`);\n  }\n}\n\n/**\n * Thin, project-agnostic abstraction over Playwright's `APIRequestContext`:\n * base URL resolution, bearer-token injection, structured error mapping, and\n * retry-on-5xx/429. Projects extend this for domain-specific API clients\n * instead of calling `request.fetch` directly in tests.\n *\n * Two levels of API, on purpose:\n * - `get`/`post`/... return the body and THROW `ApiError` on an unexpected status — the right\n *   default for arranging test data, where a failed call should stop the test loudly.\n * - `send()` returns the full `ApiResponse` (status, headers, body) and never throws for an\n *   HTTP status — for tests that assert on error responses themselves.\n */\nexport class ApiClient {\n  private readonly request: APIRequestContext;\n  private readonly baseUrl?: string;\n  private readonly tokenProvider: TokenProvider;\n  private readonly logger?: Logger;\n  private readonly retryOptions: RetryOptions;\n  private readonly defaultHeaders: Record<string, string>;\n  private readonly interceptors: ApiClientInterceptors;\n\n  constructor(options: ApiClientOptions) {\n    this.request = options.request;\n    this.baseUrl = options.baseUrl;\n    this.tokenProvider = options.tokenProvider ?? new NullTokenProvider();\n    this.logger = options.logger;\n    this.defaultHeaders = options.defaultHeaders ?? {};\n    this.interceptors = options.interceptors ?? {};\n    this.retryOptions = { ...options.retry };\n  }\n\n  get<T = unknown>(path: string, options?: ApiRequestOptions<T>): Promise<T> {\n    return this.requestBody<T>(\"GET\", path, options);\n  }\n\n  post<T = unknown>(path: string, options?: ApiRequestOptions<T>): Promise<T> {\n    return this.requestBody<T>(\"POST\", path, options);\n  }\n\n  put<T = unknown>(path: string, options?: ApiRequestOptions<T>): Promise<T> {\n    return this.requestBody<T>(\"PUT\", path, options);\n  }\n\n  patch<T = unknown>(path: string, options?: ApiRequestOptions<T>): Promise<T> {\n    return this.requestBody<T>(\"PATCH\", path, options);\n  }\n\n  delete<T = unknown>(path: string, options?: ApiRequestOptions<T>): Promise<T> {\n    return this.requestBody<T>(\"DELETE\", path, options);\n  }\n\n  /**\n   * Full response including status and headers. Retries transient statuses, then returns\n   * whatever came back — a 404 or 500 is a normal return value here, not an exception.\n   * Network/timeout failures still throw.\n   */\n  async send<T = unknown>(\n    method: string,\n    path: string,\n    options: ApiRequestOptions<T> = {},\n  ): Promise<ApiResponse<T>> {\n    const url = this.resolveUrl(path, options.params);\n    let lastResponse: ApiResponse<T> | undefined;\n\n    try {\n      await withRetry(\n        async () => {\n          lastResponse = await this.fetchOnce<T>(method, url, options);\n          if (isRetryableStatus(lastResponse.status) && !this.isExpectedStatus(lastResponse.status, options)) {\n            throw new TransientHttpError(lastResponse.status);\n          }\n        },\n        {\n          ...this.retryOptions,\n          retryOn: (error) => error instanceof TransientHttpError,\n          onRetry: (error, attempt) =>\n            this.logger?.warn({ method, url, attempt, err: error }, \"retrying API request\"),\n        },\n      );\n    } catch (error) {\n      // A transient status that never recovered is still a response the caller may want to\n      // inspect; anything else (DNS, TLS, timeout) is a real failure and must propagate.\n      if (!(error instanceof TransientHttpError)) throw error;\n    }\n\n    if (!lastResponse) {\n      throw new AppError(`API request produced no response: ${method} ${url}`, {\n        code: \"API_NO_RESPONSE\",\n        context: { method, url },\n      });\n    }\n    return lastResponse;\n  }\n\n  private async requestBody<T>(\n    method: string,\n    path: string,\n    options: ApiRequestOptions<T> = {},\n  ): Promise<T> {\n    const response = await this.send<T>(method, path, options);\n\n    if (!this.isExpectedStatus(response.status, options)) {\n      if (response.status === 401) this.tokenProvider.invalidate();\n      this.logger?.error(\n        { status: response.status, method, url: response.url, body: response.data },\n        \"API request failed\",\n      );\n      throw new ApiError(\n        `API request failed: ${method} ${response.url} -> ${response.status}` +\n          (options.expectStatus === undefined ? \"\" : ` (expected ${String(options.expectStatus)})`),\n        {\n          code: \"API_REQUEST_FAILED\",\n          status: response.status,\n          method,\n          url: response.url,\n          context: { body: response.data },\n        },\n      );\n    }\n    return response.data;\n  }\n\n  private isExpectedStatus(status: number, options: ApiRequestOptions<unknown>): boolean {\n    if (options.expectStatus === undefined) return status >= 200 && status < 300;\n    const expected = Array.isArray(options.expectStatus) ? options.expectStatus : [options.expectStatus];\n    return expected.includes(status);\n  }\n\n  private async fetchOnce<T>(\n    method: string,\n    url: string,\n    options: ApiRequestOptions<T>,\n  ): Promise<ApiResponse<T>> {\n    const headers = await this.buildHeaders(method, url, options);\n    const response = await this.request.fetch(url, {\n      method,\n      headers,\n      data: options.data,\n      form: options.form,\n      multipart: options.multipart,\n      timeout: options.timeoutMs,\n    });\n    await this.interceptors.onResponse?.({ method, url, status: response.status() });\n\n    return {\n      status: response.status(),\n      ok: response.ok(),\n      headers: response.headers(),\n      data: await this.parseBody<T>(response, options),\n      url,\n      method,\n    };\n  }\n\n  private resolveUrl(path: string, params?: ApiRequestOptions<unknown>[\"params\"]): string {\n    const base = this.baseUrl ? new URL(path, this.baseUrl).toString() : path;\n    if (!params) return base;\n    const url = new URL(base);\n    for (const [key, value] of Object.entries(params)) {\n      if (value !== undefined) url.searchParams.set(key, String(value));\n    }\n    return url.toString();\n  }\n\n  private async buildHeaders(\n    method: string,\n    url: string,\n    options: ApiRequestOptions<unknown>,\n  ): Promise<Record<string, string>> {\n    let headers: Record<string, string> = { ...this.defaultHeaders, ...options.headers };\n    if (!options.skipAuth) {\n      const token = await this.tokenProvider.getToken();\n      if (token) headers = { ...headers, Authorization: `Bearer ${token}` };\n    }\n    const overridden = await this.interceptors.onRequest?.({ method, url, headers });\n    return overridden ?? headers;\n  }\n\n  private async parseBody<T>(response: APIResponse, options: ApiRequestOptions<T>): Promise<T> {\n    const raw = await this.readBody(response);\n\n    if (!options.schema) return raw as T;\n\n    const result = options.schema.safeParse(raw);\n    if (!result.success) {\n      throw new ApiError(`API response did not match the expected schema: ${response.url()}`, {\n        code: \"API_SCHEMA_MISMATCH\",\n        status: response.status(),\n        url: response.url(),\n        context: { issues: result.error.issues, body: raw },\n      });\n    }\n    return result.data;\n  }\n\n  private async readBody(response: APIResponse): Promise<unknown> {\n    const contentType = response.headers()[\"content-type\"] ?? \"\";\n    if (contentType.includes(\"application/json\")) {\n      // A JSON content-type with an empty body (some 204s) would otherwise throw on parse.\n      const text = await response.text();\n      if (text.trim() === \"\") return undefined;\n      try {\n        return JSON.parse(text);\n      } catch {\n        return text;\n      }\n    }\n    return response.text();\n  }\n}\n"]}

package/dist/api/index.d.cts

@@ -0,0 +1,12 @@
+export { A as ApiClient, a as ApiClientOptions } from '../api-client-CpXo_NOU.cjs';
+export { A as ApiClientInterceptors, a as ApiRequestOptions, b as ApiResponse, M as MultipartFile, R as RequestContext, c as ResponseContext } from '../types-hInbkPXf.cjs';
+import '@playwright/test';
+import '../types-CopwwpSW.cjs';
+import '../retry-XqnSC8YL.cjs';
+import 'pino';
+import 'zod';
+
+/** 429 (rate-limited) and any 5xx are considered transient and safe to retry. */
+declare function isRetryableStatus(status: number): boolean;
+
+export { isRetryableStatus };

package/dist/api/index.d.ts

@@ -0,0 +1,12 @@
+export { A as ApiClient, a as ApiClientOptions } from '../api-client-C_StjpPX.js';
+export { A as ApiClientInterceptors, a as ApiRequestOptions, b as ApiResponse, M as MultipartFile, R as RequestContext, c as ResponseContext } from '../types-hInbkPXf.js';
+import '@playwright/test';
+import '../types-CopwwpSW.js';
+import '../retry-XqnSC8YL.js';
+import 'pino';
+import 'zod';
+
+/** 429 (rate-limited) and any 5xx are considered transient and safe to retry. */
+declare function isRetryableStatus(status: number): boolean;
+
+export { isRetryableStatus };

package/dist/api/index.js

@@ -0,0 +1,245 @@
+// src/errors/app-error.ts
+var AppError = class extends Error {
+  code;
+  context;
+  constructor(message, options) {
+    super(message, { cause: options.cause });
+    this.name = new.target.name;
+    this.code = options.code;
+    this.context = options.context;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ApiError = class extends AppError {
+  status;
+  method;
+  url;
+  constructor(message, options) {
+    super(message, options);
+    this.status = options.status;
+    this.method = options.method;
+    this.url = options.url;
+  }
+};
+
+// src/auth/token-provider.ts
+var NullTokenProvider = class {
+  async getToken() {
+    return "";
+  }
+  invalidate() {
+  }
+};
+
+// src/utils/sleep.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/errors/retry.ts
+function backoffDelay(attempt, minDelayMs, maxDelayMs, factor) {
+  const exponential = minDelayMs * factor ** (attempt - 1);
+  const jitter = Math.random() * minDelayMs;
+  return Math.min(exponential + jitter, maxDelayMs);
+}
+async function withRetry(fn, options = {}) {
+  const {
+    retries = 2,
+    minDelayMs = 200,
+    maxDelayMs = 5e3,
+    factor = 2,
+    retryOn = () => true,
+    onRetry,
+    onGiveUp
+  } = options;
+  const maxAttempts = retries + 1;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      const isLastAttempt = attempt >= maxAttempts;
+      if (isLastAttempt || !retryOn(error)) {
+        onGiveUp?.(error, attempt);
+        throw error;
+      }
+      onRetry?.(error, attempt);
+      await sleep(backoffDelay(attempt, minDelayMs, maxDelayMs, factor));
+    }
+  }
+  throw new Error("withRetry: unreachable state");
+}
+
+// src/api/interceptors.ts
+function isRetryableStatus(status) {
+  return status === 429 || status >= 500 && status <= 599;
+}
+
+// src/api/api-client.ts
+var TransientHttpError = class extends Error {
+  constructor(status) {
+    super(`Transient HTTP status ${status}`);
+    this.status = status;
+  }
+  status;
+};
+var ApiClient = class {
+  request;
+  baseUrl;
+  tokenProvider;
+  logger;
+  retryOptions;
+  defaultHeaders;
+  interceptors;
+  constructor(options) {
+    this.request = options.request;
+    this.baseUrl = options.baseUrl;
+    this.tokenProvider = options.tokenProvider ?? new NullTokenProvider();
+    this.logger = options.logger;
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.interceptors = options.interceptors ?? {};
+    this.retryOptions = { ...options.retry };
+  }
+  get(path, options) {
+    return this.requestBody("GET", path, options);
+  }
+  post(path, options) {
+    return this.requestBody("POST", path, options);
+  }
+  put(path, options) {
+    return this.requestBody("PUT", path, options);
+  }
+  patch(path, options) {
+    return this.requestBody("PATCH", path, options);
+  }
+  delete(path, options) {
+    return this.requestBody("DELETE", path, options);
+  }
+  /**
+   * Full response including status and headers. Retries transient statuses, then returns
+   * whatever came back — a 404 or 500 is a normal return value here, not an exception.
+   * Network/timeout failures still throw.
+   */
+  async send(method, path, options = {}) {
+    const url = this.resolveUrl(path, options.params);
+    let lastResponse;
+    try {
+      await withRetry(
+        async () => {
+          lastResponse = await this.fetchOnce(method, url, options);
+          if (isRetryableStatus(lastResponse.status) && !this.isExpectedStatus(lastResponse.status, options)) {
+            throw new TransientHttpError(lastResponse.status);
+          }
+        },
+        {
+          ...this.retryOptions,
+          retryOn: (error) => error instanceof TransientHttpError,
+          onRetry: (error, attempt) => this.logger?.warn({ method, url, attempt, err: error }, "retrying API request")
+        }
+      );
+    } catch (error) {
+      if (!(error instanceof TransientHttpError)) throw error;
+    }
+    if (!lastResponse) {
+      throw new AppError(`API request produced no response: ${method} ${url}`, {
+        code: "API_NO_RESPONSE",
+        context: { method, url }
+      });
+    }
+    return lastResponse;
+  }
+  async requestBody(method, path, options = {}) {
+    const response = await this.send(method, path, options);
+    if (!this.isExpectedStatus(response.status, options)) {
+      if (response.status === 401) this.tokenProvider.invalidate();
+      this.logger?.error(
+        { status: response.status, method, url: response.url, body: response.data },
+        "API request failed"
+      );
+      throw new ApiError(
+        `API request failed: ${method} ${response.url} -> ${response.status}` + (options.expectStatus === void 0 ? "" : ` (expected ${String(options.expectStatus)})`),
+        {
+          code: "API_REQUEST_FAILED",
+          status: response.status,
+          method,
+          url: response.url,
+          context: { body: response.data }
+        }
+      );
+    }
+    return response.data;
+  }
+  isExpectedStatus(status, options) {
+    if (options.expectStatus === void 0) return status >= 200 && status < 300;
+    const expected = Array.isArray(options.expectStatus) ? options.expectStatus : [options.expectStatus];
+    return expected.includes(status);
+  }
+  async fetchOnce(method, url, options) {
+    const headers = await this.buildHeaders(method, url, options);
+    const response = await this.request.fetch(url, {
+      method,
+      headers,
+      data: options.data,
+      form: options.form,
+      multipart: options.multipart,
+      timeout: options.timeoutMs
+    });
+    await this.interceptors.onResponse?.({ method, url, status: response.status() });
+    return {
+      status: response.status(),
+      ok: response.ok(),
+      headers: response.headers(),
+      data: await this.parseBody(response, options),
+      url,
+      method
+    };
+  }
+  resolveUrl(path, params) {
+    const base = this.baseUrl ? new URL(path, this.baseUrl).toString() : path;
+    if (!params) return base;
+    const url = new URL(base);
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  async buildHeaders(method, url, options) {
+    let headers = { ...this.defaultHeaders, ...options.headers };
+    if (!options.skipAuth) {
+      const token = await this.tokenProvider.getToken();
+      if (token) headers = { ...headers, Authorization: `Bearer ${token}` };
+    }
+    const overridden = await this.interceptors.onRequest?.({ method, url, headers });
+    return overridden ?? headers;
+  }
+  async parseBody(response, options) {
+    const raw = await this.readBody(response);
+    if (!options.schema) return raw;
+    const result = options.schema.safeParse(raw);
+    if (!result.success) {
+      throw new ApiError(`API response did not match the expected schema: ${response.url()}`, {
+        code: "API_SCHEMA_MISMATCH",
+        status: response.status(),
+        url: response.url(),
+        context: { issues: result.error.issues, body: raw }
+      });
+    }
+    return result.data;
+  }
+  async readBody(response) {
+    const contentType = response.headers()["content-type"] ?? "";
+    if (contentType.includes("application/json")) {
+      const text = await response.text();
+      if (text.trim() === "") return void 0;
+      try {
+        return JSON.parse(text);
+      } catch {
+        return text;
+      }
+    }
+    return response.text();
+  }
+};
+
+export { ApiClient, isRetryableStatus };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map