@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/navigation/view-title-resolution.d.ts

@@ -0,0 +1,32 @@
+import { NavigationViewLabelFamily } from '@wildo-ai/presets-components-models';
+import { NavigationContentType } from './navigation.schemas';
+export declare function buildCompositeViewLabelKey(translationRef: string): string;
+export declare function buildNavigationViewLabelKey(params: {
+    family: NavigationViewLabelFamily;
+    translationRef: string;
+}): string;
+export declare function buildApplicationViewTranslationRef(viewRef: string): string;
+export declare function buildResourceViewTranslationRef(resourceType: string, localRef: string): string;
+export declare function resolveCompositeViewTranslationRef(viewRef: string): string | undefined;
+export interface NavigationViewLabelTarget {
+    family: NavigationViewLabelFamily;
+    translationRef: string;
+}
+export declare function resolveNavigationViewLabelTarget(params: {
+    viewRef: string;
+    contentType: NavigationContentType;
+}): NavigationViewLabelTarget | undefined;
+/**
+ * Resolve the display title for a navigable view surface.
+ *
+ * Composite views have a first-class translation identity and must resolve
+ * through `composite_views.{translationRef}.title`. Other supported view
+ * families resolve through `views.{family}.{translationRef}.title`.
+ */
+export declare function resolveNavigationViewTitle(params: {
+    viewRef: string;
+    contentType: NavigationContentType;
+    tCompositeView: (translationRef: string, key: 'title') => string;
+    tView: (family: NavigationViewLabelFamily, translationRef: string, key: 'title') => string;
+}): string;
+//# sourceMappingURL=view-title-resolution.d.ts.map

package/dist/esm/core/navigation/view-title-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-title-resolution.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/view-title-resolution.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,yBAAyB,EAC1B,MAAM,qCAAqC,CAAC;AAU7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,wBAAgB,0BAA0B,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEzE;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,yBAAyB,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,MAAM,CAET;AAED,wBAAgB,kCAAkC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,wBAAgB,+BAA+B,CAC7C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER;AAED,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAiBpB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,yBAAyB,CAAC;IAClC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,gCAAgC,CAAC,MAAM,EAAE;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,qBAAqB,CAAC;CACpC,GAAG,yBAAyB,GAAG,SAAS,CAoDxC;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,qBAAqB,CAAC;IACnC,cAAc,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;IACjE,KAAK,EAAE,CACL,MAAM,EAAE,yBAAyB,EACjC,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,OAAO,KACT,MAAM,CAAC;CACb,GAAG,MAAM,CAmBT"}

package/dist/esm/core/navigation/view-title-resolution.js

@@ -0,0 +1,94 @@
+import { LabellingTypes, NavigationViewLabelFamily, } from '@wildo-ai/presets-components-models';
+import { buildApplicationCompositeViewTranslationRef, buildResourceCompositeViewTranslationRef, } from '../../core/config/composite-view.schemas.js';
+import { FrontendInsertedViewHostKind, FrontendInsertedViewKind, parseFrontendInsertedViewRef, } from '../../core/config/inserted-view.frontend.schemas.js';
+import { NavigationContentType } from './navigation.schemas.js';
+export function buildCompositeViewLabelKey(translationRef) {
+    return `${LabellingTypes.COMPOSITE_VIEWS}.${translationRef}`;
+}
+export function buildNavigationViewLabelKey(params) {
+    return `${LabellingTypes.VIEWS}.${params.family}.${params.translationRef}`;
+}
+export function buildApplicationViewTranslationRef(viewRef) {
+    return `app.${viewRef}`;
+}
+export function buildResourceViewTranslationRef(resourceType, localRef) {
+    return `resources.${resourceType}.${localRef}`;
+}
+export function resolveCompositeViewTranslationRef(viewRef) {
+    const insertedView = parseFrontendInsertedViewRef(viewRef);
+    if (!insertedView) {
+        return buildApplicationCompositeViewTranslationRef(viewRef);
+    }
+    if (insertedView.viewKind !== FrontendInsertedViewKind.COMPOSITE_VIEW) {
+        return undefined;
+    }
+    if (insertedView.hostKind === FrontendInsertedViewHostKind.RESOURCE) {
+        return buildResourceCompositeViewTranslationRef(insertedView.hostRef, insertedView.localRef);
+    }
+    return buildApplicationCompositeViewTranslationRef(insertedView.localRef);
+}
+export function resolveNavigationViewLabelTarget(params) {
+    const insertedView = parseFrontendInsertedViewRef(params.viewRef);
+    if (params.contentType === NavigationContentType.CHART_VIEW) {
+        if (insertedView?.viewKind === FrontendInsertedViewKind.CHART_VIEW) {
+            return {
+                family: NavigationViewLabelFamily.CHART,
+                translationRef: buildResourceViewTranslationRef(insertedView.hostRef, insertedView.localRef),
+            };
+        }
+        return {
+            family: NavigationViewLabelFamily.CHART,
+            translationRef: buildApplicationViewTranslationRef(params.viewRef),
+        };
+    }
+    if (params.contentType === NavigationContentType.EXECUTION_VIEW) {
+        if (insertedView?.viewKind === FrontendInsertedViewKind.EXECUTION_VIEW) {
+            return {
+                family: NavigationViewLabelFamily.EXECUTION,
+                translationRef: buildResourceViewTranslationRef(insertedView.hostRef, insertedView.localRef),
+            };
+        }
+        return {
+            family: NavigationViewLabelFamily.EXECUTION,
+            translationRef: buildApplicationViewTranslationRef(params.viewRef),
+        };
+    }
+    if (params.contentType === NavigationContentType.FULL_CUSTOM_VIEW) {
+        return {
+            family: NavigationViewLabelFamily.FULL_CUSTOM,
+            translationRef: buildApplicationViewTranslationRef(params.viewRef),
+        };
+    }
+    if (params.contentType === NavigationContentType.FLOWS_ACTORS_VIEW) {
+        return {
+            family: NavigationViewLabelFamily.FLOWS_ACTORS,
+            translationRef: buildApplicationViewTranslationRef(params.viewRef),
+        };
+    }
+    return undefined;
+}
+/**
+ * Resolve the display title for a navigable view surface.
+ *
+ * Composite views have a first-class translation identity and must resolve
+ * through `composite_views.{translationRef}.title`. Other supported view
+ * families resolve through `views.{family}.{translationRef}.title`.
+ */
+export function resolveNavigationViewTitle(params) {
+    if (params.contentType === NavigationContentType.COMPOSITE_VIEW) {
+        const translationRef = resolveCompositeViewTranslationRef(params.viewRef);
+        if (!translationRef) {
+            return '';
+        }
+        return params.tCompositeView(translationRef, 'title');
+    }
+    const viewTarget = resolveNavigationViewLabelTarget({
+        viewRef: params.viewRef,
+        contentType: params.contentType,
+    });
+    if (!viewTarget) {
+        return '';
+    }
+    return params.tView(viewTarget.family, viewTarget.translationRef, 'title');
+}
+//# sourceMappingURL=view-title-resolution.js.map

package/dist/esm/core/navigation/view-title-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-title-resolution.js","sourceRoot":"","sources":["../../../../../src/core/navigation/view-title-resolution.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  LabellingTypes,\n  NavigationViewLabelFamily,\n} from '@wildo-ai/presets-components-models';\nimport {\n  buildApplicationCompositeViewTranslationRef,\n  buildResourceCompositeViewTranslationRef,\n} from '~wildo-frontend-lib/core/config/composite-view.schemas';\nimport {\n  FrontendInsertedViewHostKind,\n  FrontendInsertedViewKind,\n  parseFrontendInsertedViewRef,\n} from '~wildo-frontend-lib/core/config/inserted-view.frontend.schemas';\nimport { NavigationContentType } from './navigation.schemas';\n\nexport function buildCompositeViewLabelKey(translationRef: string): string {\n  return `${LabellingTypes.COMPOSITE_VIEWS}.${translationRef}`;\n}\n\nexport function buildNavigationViewLabelKey(params: {\n  family: NavigationViewLabelFamily;\n  translationRef: string;\n}): string {\n  return `${LabellingTypes.VIEWS}.${params.family}.${params.translationRef}`;\n}\n\nexport function buildApplicationViewTranslationRef(viewRef: string): string {\n  return `app.${viewRef}`;\n}\n\nexport function buildResourceViewTranslationRef(\n  resourceType: string,\n  localRef: string,\n): string {\n  return `resources.${resourceType}.${localRef}`;\n}\n\nexport function resolveCompositeViewTranslationRef(\n  viewRef: string,\n): string | undefined {\n  const insertedView = parseFrontendInsertedViewRef(viewRef);\n  if (!insertedView) {\n    return buildApplicationCompositeViewTranslationRef(viewRef);\n  }\n  if (insertedView.viewKind !== FrontendInsertedViewKind.COMPOSITE_VIEW) {\n    return undefined;\n  }\n\n  if (insertedView.hostKind === FrontendInsertedViewHostKind.RESOURCE) {\n    return buildResourceCompositeViewTranslationRef(\n      insertedView.hostRef,\n      insertedView.localRef,\n    );\n  }\n\n  return buildApplicationCompositeViewTranslationRef(insertedView.localRef);\n}\n\nexport interface NavigationViewLabelTarget {\n  family: NavigationViewLabelFamily;\n  translationRef: string;\n}\n\nexport function resolveNavigationViewLabelTarget(params: {\n  viewRef: string;\n  contentType: NavigationContentType;\n}): NavigationViewLabelTarget | undefined {\n  const insertedView = parseFrontendInsertedViewRef(params.viewRef);\n\n  if (params.contentType === NavigationContentType.CHART_VIEW) {\n    if (insertedView?.viewKind === FrontendInsertedViewKind.CHART_VIEW) {\n      return {\n        family: NavigationViewLabelFamily.CHART,\n        translationRef: buildResourceViewTranslationRef(\n          insertedView.hostRef,\n          insertedView.localRef,\n        ),\n      };\n    }\n\n    return {\n      family: NavigationViewLabelFamily.CHART,\n      translationRef: buildApplicationViewTranslationRef(params.viewRef),\n    };\n  }\n\n  if (params.contentType === NavigationContentType.EXECUTION_VIEW) {\n    if (insertedView?.viewKind === FrontendInsertedViewKind.EXECUTION_VIEW) {\n      return {\n        family: NavigationViewLabelFamily.EXECUTION,\n        translationRef: buildResourceViewTranslationRef(\n          insertedView.hostRef,\n          insertedView.localRef,\n        ),\n      };\n    }\n\n    return {\n      family: NavigationViewLabelFamily.EXECUTION,\n      translationRef: buildApplicationViewTranslationRef(params.viewRef),\n    };\n  }\n\n  if (params.contentType === NavigationContentType.FULL_CUSTOM_VIEW) {\n    return {\n      family: NavigationViewLabelFamily.FULL_CUSTOM,\n      translationRef: buildApplicationViewTranslationRef(params.viewRef),\n    };\n  }\n\n  if (params.contentType === NavigationContentType.FLOWS_ACTORS_VIEW) {\n    return {\n      family: NavigationViewLabelFamily.FLOWS_ACTORS,\n      translationRef: buildApplicationViewTranslationRef(params.viewRef),\n    };\n  }\n\n  return undefined;\n}\n\n/**\n * Resolve the display title for a navigable view surface.\n *\n * Composite views have a first-class translation identity and must resolve\n * through `composite_views.{translationRef}.title`. Other supported view\n * families resolve through `views.{family}.{translationRef}.title`.\n */\nexport function resolveNavigationViewTitle(params: {\n  viewRef: string;\n  contentType: NavigationContentType;\n  tCompositeView: (translationRef: string, key: 'title') => string;\n  tView: (\n    family: NavigationViewLabelFamily,\n    translationRef: string,\n    key: 'title',\n  ) => string;\n}): string {\n  if (params.contentType === NavigationContentType.COMPOSITE_VIEW) {\n    const translationRef = resolveCompositeViewTranslationRef(params.viewRef);\n    if (!translationRef) {\n      return '';\n    }\n\n    return params.tCompositeView(translationRef, 'title');\n  }\n\n  const viewTarget = resolveNavigationViewLabelTarget({\n    viewRef: params.viewRef,\n    contentType: params.contentType,\n  });\n  if (!viewTarget) {\n    return '';\n  }\n\n  return params.tView(viewTarget.family, viewTarget.translationRef, 'title');\n}\n"]}

package/dist/esm/core/requests/api-readiness-checker.frontend.service.d.ts

@@ -9,17 +9,49 @@ export interface ReadinessCheckerConfig {
     /** Timeout for each health check request in ms (default: 5000) */
     requestTimeoutMs?: number;
 }
+/**
+ * Typed rejection produced when a BOUNDED {@link ApiReadinessChecker.waitForReady}
+ * gives up before the backend reports ready.
+ *
+ * This is the first-class "network unavailable" lane for foreground requests:
+ * before it existed, every request issued after a connection loss parked forever
+ * on the never-settling readiness promise (audit finding B2 — an FK dropdown
+ * spinner that never resolves). Callers and retry ladders classify it by `name`
+ * / `code` (or via {@link isApiNotReadyError}); it is a TRANSIENT condition —
+ * the backend may come back — never a validation or server failure.
+ *
+ * The background poll loop is NOT stopped by this rejection: it keeps polling
+ * `/health/ready` (that part is by design, see {@link ApiReadinessChecker}),
+ * so a later request finds the gate open again once the backend recovers.
+ */
+export declare class ApiNotReadyError extends Error {
+    readonly name = "ApiNotReadyError";
+    /** Stable machine-readable classifier for retry logic. */
+    readonly code = "API_NOT_READY";
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    constructor(baseUrl: string, timeoutMs: number);
+}
+/**
+ * Recognise an {@link ApiNotReadyError} across module instances (dual-package /
+ * multiple bundles), matching by the stable `name` rather than `instanceof`.
+ */
+export declare function isApiNotReadyError(error: unknown): error is ApiNotReadyError;
 /**
  * API Readiness Checker
  *
  * Checks if the target API is ready by polling /health/ready endpoint.
  * Uses exponential backoff: 2^attempts * baseDelay, capped at maxDelay.
- * Never stops - keeps retrying until API is ready.
+ * The background poll loop never stops — it keeps retrying until the API is
+ * ready. Individual waiters may bound their wait (`waitForReady(timeoutMs)`)
+ * and receive a typed {@link ApiNotReadyError} rejection without affecting
+ * the shared loop.
  *
  * @example
  * ```typescript
  * const checker = new ApiReadinessChecker('https://api.example.com');
- * await checker.waitForReady(); // Blocks until API is ready
+ * await checker.waitForReady();        // Blocks until API is ready (unbounded)
+ * await checker.waitForReady(10_000);  // Rejects with ApiNotReadyError after 10s
  * ```
  */
 export declare class ApiReadinessChecker {
@@ -29,10 +61,18 @@ export declare class ApiReadinessChecker {
     private logDebug;
     private isReady;
     private readinessPromise;
+    private isChecking;
     constructor(baseUrl: string, config?: ReadinessCheckerConfig);
     /**
-     * Calculate delay for given attempt using exponential backoff
-     * Formula: min(2^attempt * baseDelay, maxDelay)
+     * Calculate the poll delay for a given attempt using JITTERED exponential
+     * backoff: a random value in [0, min(maxDelay, 2^attempt · baseDelay)].
+     *
+     * The jitter is the cross-client de-herd lever for the readiness gate. Every
+     * client that was up when the backend went down starts polling /health/ready at
+     * the same moment and, with a deterministic curve, would hit the endpoint in
+     * lockstep — and then all flip "ready" and flood the backend on the same tick.
+     * Randomising the poll cadence spreads both the health-probe load and the
+     * subsequent recovery burst.
      */
     private calculateDelay;
     /**
@@ -41,11 +81,25 @@ export declare class ApiReadinessChecker {
      */
     private checkOnce;
     /**
-     * Wait until the API is ready (blocks until ready)
-     * Uses exponential backoff with warnings logged at each retry.
-     * Never stops - keeps retrying until API is ready.
+     * Wait until the API is ready.
+     *
+     * Without `timeoutMs`, blocks until the backend reports ready — the shared
+     * poll loop (`performReadinessCheck`) uses exponential backoff and never
+     * gives up. That unbounded form is appropriate for background consumers
+     * (e.g. connectivity banners) that WANT to ride the outage to its end.
+     *
+     * With `timeoutMs`, the wait is BOUNDED: if the backend is still not ready
+     * when the timeout elapses, the returned promise rejects with a typed
+     * {@link ApiNotReadyError} so the caller's error path runs (toast, inline
+     * error, retry ladder classification). Foreground request paths MUST use
+     * this form — an unbounded wait parks every user-visible request forever
+     * after a connection loss (audit B2). The timeout is per-caller: it never
+     * settles, cancels, or otherwise affects the SHARED `readinessPromise`,
+     * whose loop keeps polling in the background so a later call can succeed.
+     *
+     * @param timeoutMs - Optional bound in ms. Omit for the unbounded wait.
      */
-    waitForReady(): Promise<void>;
+    waitForReady(timeoutMs?: number): Promise<void>;
     /**
      * Perform the actual readiness check with retries
      */
@@ -59,7 +113,14 @@ export declare class ApiReadinessChecker {
      */
     getIsReady(): boolean;
     /**
-     * Reset the ready state (useful for reconnection scenarios)
+     * Reset the ready state (useful for reconnection scenarios).
+     *
+     * Only clears `readinessPromise` when no poll loop is currently running. If a
+     * `performReadinessCheck` is mid-flight, nulling the promise here would let the
+     * next `waitForReady()` spawn a SECOND concurrent poll loop on the same instance
+     * (both would hammer /health/ready). Instead the running loop is left in place —
+     * setting `isReady = false` keeps it polling until the backend recovers, which
+     * is exactly the re-arm behaviour `reset()` wants.
      */
     reset(): void;
     /**

package/dist/esm/core/requests/api-readiness-checker.frontend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-readiness-checker.frontend.service.d.ts","sourceRoot":"","sources":["../../../../src/core/requests/api-readiness-checker.frontend.service.ts"],"names":[],"mappings":"AAaA;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,QAAQ,CAA2C;IAC3D,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,gBAAgB,CAA8B;gBAE1C,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,sBAA2B;IAYhE;;;OAGG;IACH,OAAO,CAAC,cAAc;IAKtB;;;OAGG;YACW,SAAS;IAsBvB;;;;OAIG;IACU,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB1C;;OAEG;YACW,qBAAqB;IA8BnC;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACI,UAAU,IAAI,OAAO;IAI5B;;OAEG;IACI,KAAK,IAAI,IAAI;IAKpB;;OAEG;IACI,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAK5C;AAQD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,sBAAsB,GAC9B,mBAAmB,CAUrB"}
+{"version":3,"file":"api-readiness-checker.frontend.service.d.ts","sourceRoot":"","sources":["../../../../../src/core/requests/api-readiness-checker.frontend.service.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAsB;IAC5C,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAK/C;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAmC;IACjD,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,QAAQ,CAA2C;IAC3D,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,gBAAgB,CAA8B;IAItD,OAAO,CAAC,UAAU,CAAkB;gBAExB,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,sBAA2B;IAYhE;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IAItB;;;OAGG;YACW,SAAS;IAsBvB;;;;;;;;;;;;;;;;;;OAkBG;IACU,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwC5D;;OAEG;YACW,qBAAqB;IAgEnC;;OAEG;IACH,OAAO,CAAC,KAAK;IAIb;;OAEG;IACI,UAAU,IAAI,OAAO;IAI5B;;;;;;;;;OASG;IACI,KAAK,IAAI,IAAI;IAOpB;;OAEG;IACI,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAK5C;AAQD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,sBAAsB,GAC9B,mBAAmB,CAUrB"}

package/dist/esm/core/requests/api-readiness-checker.frontend.service.js

@@ -1,19 +1,58 @@
 import axios from 'axios';
 import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+import { fullJitterBackoffMs, recoveryOffsetMs } from './network-backoff.frontend.utils.js';
 const DEFAULT_BASE_DELAY_MS = 100;
 const DEFAULT_MAX_DELAY_MS = 10000;
 const DEFAULT_REQUEST_TIMEOUT_MS = 5000;
+/**
+ * Typed rejection produced when a BOUNDED {@link ApiReadinessChecker.waitForReady}
+ * gives up before the backend reports ready.
+ *
+ * This is the first-class "network unavailable" lane for foreground requests:
+ * before it existed, every request issued after a connection loss parked forever
+ * on the never-settling readiness promise (audit finding B2 — an FK dropdown
+ * spinner that never resolves). Callers and retry ladders classify it by `name`
+ * / `code` (or via {@link isApiNotReadyError}); it is a TRANSIENT condition —
+ * the backend may come back — never a validation or server failure.
+ *
+ * The background poll loop is NOT stopped by this rejection: it keeps polling
+ * `/health/ready` (that part is by design, see {@link ApiReadinessChecker}),
+ * so a later request finds the gate open again once the backend recovers.
+ */
+export class ApiNotReadyError extends Error {
+    name = 'ApiNotReadyError';
+    /** Stable machine-readable classifier for retry logic. */
+    code = 'API_NOT_READY';
+    baseUrl;
+    timeoutMs;
+    constructor(baseUrl, timeoutMs) {
+        super(`Backend API at ${baseUrl || '<unset baseUrl>'} did not become ready within ${timeoutMs}ms`);
+        this.baseUrl = baseUrl;
+        this.timeoutMs = timeoutMs;
+    }
+}
+/**
+ * Recognise an {@link ApiNotReadyError} across module instances (dual-package /
+ * multiple bundles), matching by the stable `name` rather than `instanceof`.
+ */
+export function isApiNotReadyError(error) {
+    return error instanceof Error && error.name === 'ApiNotReadyError';
+}
 /**
  * API Readiness Checker
  *
  * Checks if the target API is ready by polling /health/ready endpoint.
  * Uses exponential backoff: 2^attempts * baseDelay, capped at maxDelay.
- * Never stops - keeps retrying until API is ready.
+ * The background poll loop never stops — it keeps retrying until the API is
+ * ready. Individual waiters may bound their wait (`waitForReady(timeoutMs)`)
+ * and receive a typed {@link ApiNotReadyError} rejection without affecting
+ * the shared loop.
  *
  * @example
  * ```typescript
  * const checker = new ApiReadinessChecker('https://api.example.com');
- * await checker.waitForReady(); // Blocks until API is ready
+ * await checker.waitForReady();        // Blocks until API is ready (unbounded)
+ * await checker.waitForReady(10_000);  // Rejects with ApiNotReadyError after 10s
  * ```
  */
 export class ApiReadinessChecker {
@@ -23,6 +62,10 @@ export class ApiReadinessChecker {
     logDebug;
     isReady = false;
     readinessPromise = null;
+    // True while a `performReadinessCheck` loop is actively polling. Guards against
+    // `reset()` nulling `readinessPromise` mid-poll and letting a second concurrent
+    // loop spawn on the same instance (redundant /health/ready load).
+    isChecking = false;
     constructor(baseUrl, config = {}) {
         this.baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
         this.config = {
@@ -35,12 +78,18 @@ export class ApiReadinessChecker {
         this.logger.setDebugTypeLogging('ApiReadinessChecker', false);
     }
     /**
-     * Calculate delay for given attempt using exponential backoff
-     * Formula: min(2^attempt * baseDelay, maxDelay)
+     * Calculate the poll delay for a given attempt using JITTERED exponential
+     * backoff: a random value in [0, min(maxDelay, 2^attempt · baseDelay)].
+     *
+     * The jitter is the cross-client de-herd lever for the readiness gate. Every
+     * client that was up when the backend went down starts polling /health/ready at
+     * the same moment and, with a deterministic curve, would hit the endpoint in
+     * lockstep — and then all flip "ready" and flood the backend on the same tick.
+     * Randomising the poll cadence spreads both the health-probe load and the
+     * subsequent recovery burst.
      */
     calculateDelay(attempt) {
-        const delay = Math.pow(2, attempt) * this.config.baseDelayMs;
-        return Math.min(delay, this.config.maxDelayMs);
+        return fullJitterBackoffMs(attempt, this.config.baseDelayMs, this.config.maxDelayMs);
     }
     /**
      * Check readiness once
@@ -64,11 +113,25 @@ export class ApiReadinessChecker {
         }
     }
     /**
-     * Wait until the API is ready (blocks until ready)
-     * Uses exponential backoff with warnings logged at each retry.
-     * Never stops - keeps retrying until API is ready.
+     * Wait until the API is ready.
+     *
+     * Without `timeoutMs`, blocks until the backend reports ready — the shared
+     * poll loop (`performReadinessCheck`) uses exponential backoff and never
+     * gives up. That unbounded form is appropriate for background consumers
+     * (e.g. connectivity banners) that WANT to ride the outage to its end.
+     *
+     * With `timeoutMs`, the wait is BOUNDED: if the backend is still not ready
+     * when the timeout elapses, the returned promise rejects with a typed
+     * {@link ApiNotReadyError} so the caller's error path runs (toast, inline
+     * error, retry ladder classification). Foreground request paths MUST use
+     * this form — an unbounded wait parks every user-visible request forever
+     * after a connection loss (audit B2). The timeout is per-caller: it never
+     * settles, cancels, or otherwise affects the SHARED `readinessPromise`,
+     * whose loop keeps polling in the background so a later call can succeed.
+     *
+     * @param timeoutMs - Optional bound in ms. Omit for the unbounded wait.
      */
-    async waitForReady() {
+    async waitForReady(timeoutMs) {
         // If no baseUrl configured, skip readiness check
         if (!this.baseUrl) {
             this.logger.warn('API readiness check skipped: no baseUrl configured');
@@ -78,39 +141,93 @@ export class ApiReadinessChecker {
         if (this.isReady) {
             return;
         }
-        // If already waiting, return the existing promise
-        if (this.readinessPromise) {
-            return this.readinessPromise;
+        // Join (or start) the shared readiness poll. The shared promise only ever
+        // RESOLVES (the loop retries forever), so racing it below can never leave
+        // an unhandled rejection behind on the shared object.
+        if (!this.readinessPromise) {
+            this.readinessPromise = this.performReadinessCheck();
+        }
+        const readiness = this.readinessPromise;
+        if (timeoutMs === undefined) {
+            await readiness;
+            return;
+        }
+        let timer;
+        try {
+            await Promise.race([
+                readiness,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new ApiNotReadyError(this.baseUrl, timeoutMs)), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            // Always clear the per-caller timer so a resolved wait doesn't leave a
+            // stray timeout (and a pending ApiNotReadyError construction) behind.
+            if (timer !== undefined)
+                clearTimeout(timer);
         }
-        // Start the readiness check
-        this.readinessPromise = this.performReadinessCheck();
-        await this.readinessPromise;
     }
     /**
      * Perform the actual readiness check with retries
      */
     async performReadinessCheck() {
         let attempt = 0;
+        this.isChecking = true;
         this.logDebug('Starting API readiness check', { baseUrl: this.baseUrl });
-        while (!this.isReady) {
-            const ready = await this.checkOnce();
-            if (ready) {
-                this.isReady = true;
-                this.logDebug('API is ready', {
+        try {
+            while (!this.isReady) {
+                const ready = await this.checkOnce();
+                if (ready) {
+                    // Recovery de-sync: if the backend was actually unavailable for a while
+                    // (attempt > 0 = we had to retry), delay the "ready" flip by a per-client
+                    // random offset so every client that was blocked on the SAME outage
+                    // doesn't release its queued requests — and re-fire its WS reconnect — in
+                    // the same instant. The first-ever cold check (attempt 0 succeeds
+                    // immediately against a healthy backend) is NOT delayed, so page load and
+                    // normal navigation stay fast.
+                    if (attempt > 0) {
+                        const offset = recoveryOffsetMs();
+                        this.logDebug('API ready after outage — applying recovery de-sync offset', {
+                            baseUrl: this.baseUrl,
+                            offsetMs: offset,
+                        });
+                        await this.sleep(offset);
+                        // The backend may have died again DURING the (up to 2s) offset sleep.
+                        // Re-confirm before committing the sticky `isReady` flag — otherwise we
+                        // could flip the gate open against a down backend and fire the next
+                        // request blindly. If it's no longer healthy, keep polling.
+                        if (!(await this.checkOnce())) {
+                            const delay = this.calculateDelay(attempt);
+                            this.logger.warn(`API went unhealthy during recovery offset, retrying in ${delay}ms`, {
+                                baseUrl: this.baseUrl,
+                                attempt: attempt + 1,
+                            });
+                            await this.sleep(delay);
+                            attempt++;
+                            continue;
+                        }
+                    }
+                    this.isReady = true;
+                    this.logDebug('API is ready', {
+                        baseUrl: this.baseUrl,
+                        attempts: attempt + 1,
+                    });
+                    return;
+                }
+                // Not ready - log warning and retry
+                const delay = this.calculateDelay(attempt);
+                this.logger.warn(`API not ready, retrying in ${delay}ms`, {
                     baseUrl: this.baseUrl,
-                    attempts: attempt + 1,
+                    attempt: attempt + 1,
+                    nextDelayMs: delay,
                 });
-                return;
+                await this.sleep(delay);
+                attempt++;
             }
-            // Not ready - log warning and retry
-            const delay = this.calculateDelay(attempt);
-            this.logger.warn(`API not ready, retrying in ${delay}ms`, {
-                baseUrl: this.baseUrl,
-                attempt: attempt + 1,
-                nextDelayMs: delay,
-            });
-            await this.sleep(delay);
-            attempt++;
+        }
+        finally {
+            this.isChecking = false;
         }
     }
     /**
@@ -126,11 +243,20 @@ export class ApiReadinessChecker {
         return this.isReady;
     }
     /**
-     * Reset the ready state (useful for reconnection scenarios)
+     * Reset the ready state (useful for reconnection scenarios).
+     *
+     * Only clears `readinessPromise` when no poll loop is currently running. If a
+     * `performReadinessCheck` is mid-flight, nulling the promise here would let the
+     * next `waitForReady()` spawn a SECOND concurrent poll loop on the same instance
+     * (both would hammer /health/ready). Instead the running loop is left in place —
+     * setting `isReady = false` keeps it polling until the backend recovers, which
+     * is exactly the re-arm behaviour `reset()` wants.
      */
     reset() {
         this.isReady = false;
-        this.readinessPromise = null;
+        if (!this.isChecking) {
+            this.readinessPromise = null;
+        }
     }
     /**
      * Update the base URL (useful when environment changes)
@@ -158,4 +284,4 @@ export function getReadinessChecker(baseUrl, config) {
     }
     return checker;
 }
-//# sourceMappingURL=api-readiness-checker.frontend.service.js.map
+//# sourceMappingURL=api-readiness-checker.frontend.service.js.map

package/dist/esm/core/requests/api-readiness-checker.frontend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-readiness-checker.frontend.service.js","sourceRoot":"","sources":["../../../../src/core/requests/api-readiness-checker.frontend.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-readiness-checker.frontend.service.js","sourceRoot":"","sources":["../../../../../src/core/requests/api-readiness-checker.frontend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import axios from 'axios';\nimport { LoggerFrontendService } from '~wildo-frontend-lib/core/monitoring/logger.frontend.service';\nimport { fullJitterBackoffMs, recoveryOffsetMs } from './network-backoff.frontend.utils';\n\n/**\n * Readiness check response from /health/ready endpoint\n */\ninterface ReadinessResponse {\n  status: 'healthy' | 'unhealthy' | 'degraded';\n  timestamp: string;\n  uptime: number;\n  version: string;\n}\n\n/**\n * Configuration for the readiness checker\n */\nexport interface ReadinessCheckerConfig {\n  /** Base delay in ms for exponential backoff (default: 100) */\n  baseDelayMs?: number;\n  /** Maximum delay cap in ms (default: 10000 = 10s) */\n  maxDelayMs?: number;\n  /** Timeout for each health check request in ms (default: 5000) */\n  requestTimeoutMs?: number;\n}\n\nconst DEFAULT_BASE_DELAY_MS = 100;\nconst DEFAULT_MAX_DELAY_MS = 10000;\nconst DEFAULT_REQUEST_TIMEOUT_MS = 5000;\n\n/**\n * Typed rejection produced when a BOUNDED {@link ApiReadinessChecker.waitForReady}\n * gives up before the backend reports ready.\n *\n * This is the first-class \"network unavailable\" lane for foreground requests:\n * before it existed, every request issued after a connection loss parked forever\n * on the never-settling readiness promise (audit finding B2 — an FK dropdown\n * spinner that never resolves). Callers and retry ladders classify it by `name`\n * / `code` (or via {@link isApiNotReadyError}); it is a TRANSIENT condition —\n * the backend may come back — never a validation or server failure.\n *\n * The background poll loop is NOT stopped by this rejection: it keeps polling\n * `/health/ready` (that part is by design, see {@link ApiReadinessChecker}),\n * so a later request finds the gate open again once the backend recovers.\n */\nexport class ApiNotReadyError extends Error {\n  override readonly name = 'ApiNotReadyError';\n  /** Stable machine-readable classifier for retry logic. */\n  readonly code = 'API_NOT_READY';\n  readonly baseUrl: string;\n  readonly timeoutMs: number;\n\n  constructor(baseUrl: string, timeoutMs: number) {\n    super(`Backend API at ${baseUrl || '<unset baseUrl>'} did not become ready within ${timeoutMs}ms`);\n    this.baseUrl = baseUrl;\n    this.timeoutMs = timeoutMs;\n  }\n}\n\n/**\n * Recognise an {@link ApiNotReadyError} across module instances (dual-package /\n * multiple bundles), matching by the stable `name` rather than `instanceof`.\n */\nexport function isApiNotReadyError(error: unknown): error is ApiNotReadyError {\n  return error instanceof Error && error.name === 'ApiNotReadyError';\n}\n\n/**\n * API Readiness Checker\n *\n * Checks if the target API is ready by polling /health/ready endpoint.\n * Uses exponential backoff: 2^attempts * baseDelay, capped at maxDelay.\n * The background poll loop never stops — it keeps retrying until the API is\n * ready. Individual waiters may bound their wait (`waitForReady(timeoutMs)`)\n * and receive a typed {@link ApiNotReadyError} rejection without affecting\n * the shared loop.\n *\n * @example\n * ```typescript\n * const checker = new ApiReadinessChecker('https://api.example.com');\n * await checker.waitForReady();        // Blocks until API is ready (unbounded)\n * await checker.waitForReady(10_000);  // Rejects with ApiNotReadyError after 10s\n * ```\n */\nexport class ApiReadinessChecker {\n  private baseUrl: string;\n  private config: Required<ReadinessCheckerConfig>;\n  private logger: LoggerFrontendService;\n  private logDebug: (message: string, context?: any) => void;\n  private isReady: boolean = false;\n  private readinessPromise: Promise<void> | null = null;\n  // True while a `performReadinessCheck` loop is actively polling. Guards against\n  // `reset()` nulling `readinessPromise` mid-poll and letting a second concurrent\n  // loop spawn on the same instance (redundant /health/ready load).\n  private isChecking: boolean = false;\n\n  constructor(baseUrl: string, config: ReadinessCheckerConfig = {}) {\n    this.baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;\n    this.config = {\n      baseDelayMs: config.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,\n      maxDelayMs: config.maxDelayMs ?? DEFAULT_MAX_DELAY_MS,\n      requestTimeoutMs: config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,\n    };\n    this.logger = LoggerFrontendService.getLogger();\n    this.logDebug = this.logger.debugByType('ApiReadinessChecker');\n    this.logger.setDebugTypeLogging('ApiReadinessChecker', false);\n  }\n\n  /**\n   * Calculate the poll delay for a given attempt using JITTERED exponential\n   * backoff: a random value in [0, min(maxDelay, 2^attempt · baseDelay)].\n   *\n   * The jitter is the cross-client de-herd lever for the readiness gate. Every\n   * client that was up when the backend went down starts polling /health/ready at\n   * the same moment and, with a deterministic curve, would hit the endpoint in\n   * lockstep — and then all flip \"ready\" and flood the backend on the same tick.\n   * Randomising the poll cadence spreads both the health-probe load and the\n   * subsequent recovery burst.\n   */\n  private calculateDelay(attempt: number): number {\n    return fullJitterBackoffMs(attempt, this.config.baseDelayMs, this.config.maxDelayMs);\n  }\n\n  /**\n   * Check readiness once\n   * @returns true if API is ready, false otherwise\n   */\n  private async checkOnce(): Promise<boolean> {\n    try {\n      const response = await axios.get<ReadinessResponse>(\n        `${this.baseUrl}/health/ready`,\n        {\n          timeout: this.config.requestTimeoutMs,\n          // Don't throw on non-2xx status - we handle it ourselves\n          validateStatus: () => true,\n        }\n      );\n\n      if (response.status === 200 && response.data?.status === 'healthy') {\n        return true;\n      }\n\n      return false;\n    } catch (error) {\n      // Network error, timeout, etc.\n      return false;\n    }\n  }\n\n  /**\n   * Wait until the API is ready.\n   *\n   * Without `timeoutMs`, blocks until the backend reports ready — the shared\n   * poll loop (`performReadinessCheck`) uses exponential backoff and never\n   * gives up. That unbounded form is appropriate for background consumers\n   * (e.g. connectivity banners) that WANT to ride the outage to its end.\n   *\n   * With `timeoutMs`, the wait is BOUNDED: if the backend is still not ready\n   * when the timeout elapses, the returned promise rejects with a typed\n   * {@link ApiNotReadyError} so the caller's error path runs (toast, inline\n   * error, retry ladder classification). Foreground request paths MUST use\n   * this form — an unbounded wait parks every user-visible request forever\n   * after a connection loss (audit B2). The timeout is per-caller: it never\n   * settles, cancels, or otherwise affects the SHARED `readinessPromise`,\n   * whose loop keeps polling in the background so a later call can succeed.\n   *\n   * @param timeoutMs - Optional bound in ms. Omit for the unbounded wait.\n   */\n  public async waitForReady(timeoutMs?: number): Promise<void> {\n    // If no baseUrl configured, skip readiness check\n    if (!this.baseUrl) {\n      this.logger.warn('API readiness check skipped: no baseUrl configured');\n      return;\n    }\n\n    // If already ready, return immediately\n    if (this.isReady) {\n      return;\n    }\n\n    // Join (or start) the shared readiness poll. The shared promise only ever\n    // RESOLVES (the loop retries forever), so racing it below can never leave\n    // an unhandled rejection behind on the shared object.\n    if (!this.readinessPromise) {\n      this.readinessPromise = this.performReadinessCheck();\n    }\n    const readiness = this.readinessPromise;\n\n    if (timeoutMs === undefined) {\n      await readiness;\n      return;\n    }\n\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    try {\n      await Promise.race([\n        readiness,\n        new Promise<never>((_, reject) => {\n          timer = setTimeout(() => reject(new ApiNotReadyError(this.baseUrl, timeoutMs)), timeoutMs);\n        }),\n      ]);\n    } finally {\n      // Always clear the per-caller timer so a resolved wait doesn't leave a\n      // stray timeout (and a pending ApiNotReadyError construction) behind.\n      if (timer !== undefined) clearTimeout(timer);\n    }\n  }\n\n  /**\n   * Perform the actual readiness check with retries\n   */\n  private async performReadinessCheck(): Promise<void> {\n    let attempt = 0;\n\n    this.isChecking = true;\n    this.logDebug('Starting API readiness check', { baseUrl: this.baseUrl });\n\n    try {\n    while (!this.isReady) {\n      const ready = await this.checkOnce();\n\n      if (ready) {\n        // Recovery de-sync: if the backend was actually unavailable for a while\n        // (attempt > 0 = we had to retry), delay the \"ready\" flip by a per-client\n        // random offset so every client that was blocked on the SAME outage\n        // doesn't release its queued requests — and re-fire its WS reconnect — in\n        // the same instant. The first-ever cold check (attempt 0 succeeds\n        // immediately against a healthy backend) is NOT delayed, so page load and\n        // normal navigation stay fast.\n        if (attempt > 0) {\n          const offset = recoveryOffsetMs();\n          this.logDebug('API ready after outage — applying recovery de-sync offset', {\n            baseUrl: this.baseUrl,\n            offsetMs: offset,\n          });\n          await this.sleep(offset);\n          // The backend may have died again DURING the (up to 2s) offset sleep.\n          // Re-confirm before committing the sticky `isReady` flag — otherwise we\n          // could flip the gate open against a down backend and fire the next\n          // request blindly. If it's no longer healthy, keep polling.\n          if (!(await this.checkOnce())) {\n            const delay = this.calculateDelay(attempt);\n            this.logger.warn(`API went unhealthy during recovery offset, retrying in ${delay}ms`, {\n              baseUrl: this.baseUrl,\n              attempt: attempt + 1,\n            });\n            await this.sleep(delay);\n            attempt++;\n            continue;\n          }\n        }\n        this.isReady = true;\n        this.logDebug('API is ready', {\n          baseUrl: this.baseUrl,\n          attempts: attempt + 1,\n        });\n        return;\n      }\n\n      // Not ready - log warning and retry\n      const delay = this.calculateDelay(attempt);\n      this.logger.warn(`API not ready, retrying in ${delay}ms`, {\n        baseUrl: this.baseUrl,\n        attempt: attempt + 1,\n        nextDelayMs: delay,\n      });\n\n      await this.sleep(delay);\n      attempt++;\n    }\n    } finally {\n      this.isChecking = false;\n    }\n  }\n\n  /**\n   * Sleep for given duration\n   */\n  private sleep(ms: number): Promise<void> {\n    return new Promise(resolve => setTimeout(resolve, ms));\n  }\n\n  /**\n   * Check if API is currently marked as ready\n   */\n  public getIsReady(): boolean {\n    return this.isReady;\n  }\n\n  /**\n   * Reset the ready state (useful for reconnection scenarios).\n   *\n   * Only clears `readinessPromise` when no poll loop is currently running. If a\n   * `performReadinessCheck` is mid-flight, nulling the promise here would let the\n   * next `waitForReady()` spawn a SECOND concurrent poll loop on the same instance\n   * (both would hammer /health/ready). Instead the running loop is left in place —\n   * setting `isReady = false` keeps it polling until the backend recovers, which\n   * is exactly the re-arm behaviour `reset()` wants.\n   */\n  public reset(): void {\n    this.isReady = false;\n    if (!this.isChecking) {\n      this.readinessPromise = null;\n    }\n  }\n\n  /**\n   * Update the base URL (useful when environment changes)\n   */\n  public updateBaseUrl(baseUrl: string): void {\n    this.baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;\n    // Reset readiness when URL changes\n    this.reset();\n  }\n}\n\n/**\n * Singleton factory for API readiness checkers\n * Maintains one checker per base URL\n */\nconst readinessCheckers: Map<string, ApiReadinessChecker> = new Map();\n\n/**\n * Get or create an API readiness checker for the given base URL\n */\nexport function getReadinessChecker(\n  baseUrl: string,\n  config?: ReadinessCheckerConfig\n): ApiReadinessChecker {\n  const normalizedUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;\n  \n  let checker = readinessCheckers.get(normalizedUrl);\n  if (!checker) {\n    checker = new ApiReadinessChecker(normalizedUrl, config);\n    readinessCheckers.set(normalizedUrl, checker);\n  }\n  \n  return checker;\n}\n"]}