@cobre-npm/library-response-catalog-node 0.6.0 → 0.7.0

package/dist/index.js

@@ -1,5 +1,981 @@
 'use strict';
 
+var axios = require('axios');
+var api = require('@opentelemetry/api');
+var libraryNodejsTelemetry = require('@cobre-npm/library-nodejs-telemetry');
+var cockatiel = require('cockatiel');
+var http = require('http');
+var https = require('https');
+var fs = require('fs');
+require('path');
+
+const NO_AUTH_HEADERS_SOURCE = {
+    async headers() {
+        return {};
+    },
+    confirm(_httpStatusCode) {
+        // no-op
+    },
+};
+const noAuthHeadersSource = () => NO_AUTH_HEADERS_SOURCE;
+
+const CONNECTION_MODES = {
+    INTERNAL_GATEWAY: 'INTERNAL_GATEWAY',
+    CLUSTER_DNS: 'CLUSTER_DNS',
+};
+
+const CREDENTIAL_ERROR_CODES$1 = new Set([401, 403, 491, 493]);
+/**
+ * Auth source for INTERNAL_GATEWAY. Caches headers from library-nodejs-common and
+ * invalidates the cache when `confirm` reports a credential rejection so the next
+ * retry (after confirm) fetches fresh credentials — same semantic as Java's
+ * APIGWKeysUseCase.confirmStatusCode.
+ */
+class InternalGatewayAuthHeadersSource {
+    options;
+    cachedHeaders = null;
+    inFlight = null;
+    invalidateOnNextHeaders = false;
+    constructor(options) {
+        this.options = options;
+    }
+    async headers() {
+        if (this.invalidateOnNextHeaders) {
+            this.cachedHeaders = null;
+            this.invalidateOnNextHeaders = false;
+        }
+        if (this.cachedHeaders !== null) {
+            return this.cachedHeaders;
+        }
+        // Concurrent cold calls share one fetch: the retry issues headers() per
+        // attempt, and a consumer resolving several errors at once would otherwise
+        // hit Secrets Manager once per caller.
+        this.inFlight ??= this.fetchAndCache();
+        return this.inFlight;
+    }
+    async fetchAndCache() {
+        try {
+            const headers = await this.options.fetchHeaders({
+                secretAdapterRegion: this.options.secretAdapterRegion,
+                apigwSecretName: this.options.secretName,
+                authManagerBaseURL: this.options.authManagerBaseURL,
+            });
+            // Forwarded as-is, like Java's adapter does with getKeysForAPICalls. An
+            // allowlist here silently dropped anything the credential source added,
+            // and a casing change (X-APIGW-AUTH vs x-apigw-auth) would have sent the
+            // request with no credentials at all rather than failing loudly.
+            this.cachedHeaders = { ...headers };
+            return this.cachedHeaders;
+        }
+        finally {
+            this.inFlight = null;
+        }
+    }
+    confirm(httpStatusCode) {
+        if (CREDENTIAL_ERROR_CODES$1.has(httpStatusCode)) {
+            this.invalidateOnNextHeaders = true;
+        }
+    }
+}
+
+/**
+ * Outbound port: resolve a supplier error against the response catalog.
+ * Consumers depend on this abstract class, never on a concrete adapter — the
+ * HTTP implementation ships in `createCatalogClient` / `createCatalogClientSync`.
+ *
+ * @example
+ * ```typescript
+ * class FakeCatalogPort extends CatalogPort {
+ *   async fetchResponse(context: SupplierErrorContext): Promise<Response> {
+ *     return {
+ *       supplier: null,
+ *       internal: null,
+ *       api: null,
+ *       resolvedLocale: 'en-US',
+ *       resolvedMessage: 'stubbed for a test',
+ *       fallbackApplied: false,
+ *     }
+ *   }
+ * }
+ * ```
+ */
+class CatalogPort {
+}
+
+const HTTP_SERVER_ERROR_THRESHOLD = 500;
+const CREDENTIAL_ERROR_CODES = new Set([401, 403, 491, 493]);
+/**
+ * Raised when a {@link CatalogPort} implementation fails to resolve a
+ * supplier error, whether due to an HTTP error response from the catalog or
+ * a network-level failure (timeout, DNS, connection reset).
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await catalogPort.fetchResponse(context)
+ * } catch (error) {
+ *   if (error instanceof CatalogClientError && error.isTransient()) {
+ *     // safe to retry or fall back locally
+ *   }
+ * }
+ * ```
+ */
+class CatalogClientError extends Error {
+    /**
+     * HTTP status code returned by the catalog, or `null` when the failure
+     * was a network-level error (no HTTP response was received).
+     */
+    httpStatusCode;
+    /**
+     * @param message - Human-readable description of the failure
+     * @param httpStatusCodeOrCause - HTTP status code from the catalog response,
+     *   or the underlying `Error` when the failure happened before a response
+     *   was received (network failure). Omit for failures with neither.
+     */
+    constructor(message, httpStatusCodeOrCause) {
+        if (httpStatusCodeOrCause instanceof Error) {
+            super(message, { cause: httpStatusCodeOrCause });
+            this.httpStatusCode = null;
+        }
+        else {
+            super(message);
+            this.httpStatusCode = httpStatusCodeOrCause ?? null;
+        }
+        this.name = 'CatalogClientError';
+    }
+    /**
+     * Whether this failure is likely temporary and safe to retry: a network
+     * failure (`httpStatusCode` is `null`) or a `5xx` response from the
+     * catalog.
+     */
+    isTransient() {
+        return this.httpStatusCode === null || this.httpStatusCode >= HTTP_SERVER_ERROR_THRESHOLD;
+    }
+    /**
+     * Whether this failure was caused by invalid or expired credentials:
+     * `401`, `403`, or the catalog's custom credential-error codes `491`/`493`.
+     */
+    isCredentialError() {
+        return this.httpStatusCode !== null && CREDENTIAL_ERROR_CODES.has(this.httpStatusCode);
+    }
+}
+
+/**
+ * Blank-string predicates shared by the domain and the adapters. A value counts
+ * as text only when it is present and holds at least one non-whitespace
+ * character, so `''`, `'   '`, `null` and `undefined` are all treated alike.
+ */
+/**
+ * Narrows a possibly-absent string to one that holds non-whitespace text.
+ *
+ * @param value - The value to check
+ * @returns `true` when the value is a string with non-whitespace content
+ *
+ * @example
+ * ```typescript
+ * hasText('  es-CO ') // true
+ * hasText('   ')      // false
+ * ```
+ */
+const hasText = (value) => value !== null && value !== undefined && value.trim().length > 0;
+/**
+ * Returns the trimmed value, or throws when it holds no text.
+ *
+ * @param value - The value to validate
+ * @param fieldName - Name used in the error message
+ * @returns The value with surrounding whitespace removed
+ * @throws Error when the value holds no non-whitespace character
+ *
+ * @example
+ * ```typescript
+ * requireText(' #UNKNOWN# ', 'token') // '#UNKNOWN#'
+ * requireText('  ', 'token')          // throws: token must not be blank
+ * ```
+ */
+const requireText = (value, fieldName) => {
+    if (!hasText(value)) {
+        throw new Error(`${fieldName} must not be blank`);
+    }
+    return value.trim();
+};
+
+const CATALOG_UNAVAILABLE_REASONS = {
+    NETWORK: 'network',
+    SERVER_ERROR: 'server_error',
+    CIRCUIT_OPEN: 'circuit_open',
+    INVALID_RESPONSE: 'invalid_response',
+};
+
+class CatalogUnavailableError extends CatalogClientError {
+    reason;
+    constructor(message, reason, httpStatusCodeOrCause) {
+        super(message, httpStatusCodeOrCause);
+        this.reason = reason;
+        this.name = 'CatalogUnavailableError';
+    }
+}
+
+/**
+ * Builds the degraded {@link Response} returned when the catalog is
+ * unavailable. `internal` and `api` are null because there is no catalog entry
+ * to populate them — see `docs/fallback.md`.
+ *
+ * @param context - The supplier error being resolved
+ * @param fallback - The locally resolved token
+ * @returns A response carrying the token as `resolvedMessage`
+ */
+const createFallbackResponse = (context, fallback) => ({
+    supplier: {
+        supplierId: context.supplier,
+        domain: context.domain,
+        supplierResponseStatusCode: context.code,
+    },
+    internal: null,
+    api: null,
+    resolvedLocale: fallback.resolvedLocale,
+    resolvedMessage: fallback.token,
+    fallbackApplied: true,
+});
+
+/**
+ * Walks an error and its `cause` chain looking for the first value the
+ * predicate accepts. Resilience policies wrap the original failure, so the
+ * catalog exception is usually nested rather than thrown directly.
+ *
+ * @param error - The error to inspect, along with its causes
+ * @param predicate - Type guard identifying the error being looked for
+ * @returns The first matching error, or `undefined` when none matches
+ *
+ * @example
+ * ```typescript
+ * const catalogError = findErrorInChain(
+ *   wrapped,
+ *   (candidate): candidate is CatalogClientError => candidate instanceof CatalogClientError,
+ * )
+ * ```
+ */
+const findErrorInChain = (error, predicate) => {
+    let current = error;
+    // Guards against a cause cycle, which would otherwise loop forever.
+    const seen = new Set();
+    while (current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        if (predicate(current)) {
+            return current;
+        }
+        if (current instanceof Error && current.cause !== undefined && current.cause !== current) {
+            current = current.cause;
+        }
+        else {
+            break;
+        }
+    }
+    return undefined;
+};
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_CIRCUIT_BREAKER_WAIT_DURATION_MS = 30_000;
+/** Failure-rate threshold (0–1). Matches Resilience4j's default 50%. */
+const CIRCUIT_BREAKER_FAILURE_RATE_THRESHOLD = 0.5;
+const RETRY_INITIAL_INTERVAL_MS = 100;
+const RETRY_BACKOFF_MULTIPLIER = 2;
+const SLIDING_WINDOW_SIZE = 20;
+const MINIMUM_NUMBER_OF_CALLS = 10;
+const findCatalogError = (error) => findErrorInChain(error, (candidate) => candidate instanceof CatalogClientError);
+const isRetryable = (error) => {
+    const catalogError = findCatalogError(error);
+    if (catalogError === undefined) {
+        return false;
+    }
+    // Java retries on isTransient() || isCredentialError(). CatalogUnavailableError
+    // is added explicitly because an unusable 2xx body carries that status, so it
+    // is not transient by status alone, yet Java retries it too.
+    return catalogError instanceof CatalogUnavailableError
+        || catalogError.isTransient()
+        || catalogError.isCredentialError();
+};
+/**
+ * A business response — a supplier code the catalog does not have, a rejected
+ * request — says nothing about the service's health, so the breaker ignores it
+ * rather than counting it either way.
+ */
+const isBusinessResponse = (error) => {
+    const catalogError = findCatalogError(error);
+    if (catalogError === undefined || catalogError instanceof CatalogUnavailableError) {
+        return false;
+    }
+    return !catalogError.isTransient();
+};
+const createResiliencePolicies = ({ maxAttempts = DEFAULT_MAX_ATTEMPTS, circuitBreakerOpenDurationMs = DEFAULT_CIRCUIT_BREAKER_WAIT_DURATION_MS, } = {}) => {
+    // Known divergence from Java: Resilience4j permits 3 trial calls in the
+    // half-open state, cockatiel permits exactly one, so recovery is decided on a
+    // single probe. Not configurable in cockatiel.
+    const breaker = cockatiel.circuitBreaker(cockatiel.handleWhen((error) => !isBusinessResponse(error)), {
+        halfOpenAfter: circuitBreakerOpenDurationMs,
+        breaker: new cockatiel.CountBreaker({
+            threshold: CIRCUIT_BREAKER_FAILURE_RATE_THRESHOLD,
+            size: SLIDING_WINDOW_SIZE,
+            minimumNumberOfCalls: MINIMUM_NUMBER_OF_CALLS,
+        }),
+    });
+    // cockatiel counts retries; Resilience4j counts total attempts including the
+    // first. Convert so maxAttempts means the same to consumers of this library
+    // as it does in library-response-catalog-java.
+    const maxRetries = Math.max(maxAttempts - 1, 0);
+    const retryPolicy = cockatiel.retry(cockatiel.handleWhen(isRetryable), {
+        maxAttempts: maxRetries,
+        backoff: new cockatiel.ExponentialBackoff({
+            initialDelay: RETRY_INITIAL_INTERVAL_MS,
+            exponent: RETRY_BACKOFF_MULTIPLIER,
+            maxDelay: RETRY_INITIAL_INTERVAL_MS * RETRY_BACKOFF_MULTIPLIER ** maxRetries,
+        }),
+    });
+    return { policy: cockatiel.wrap(retryPolicy, breaker) };
+};
+const isBrokenCircuitError = (error) => error instanceof cockatiel.BrokenCircuitError;
+
+const RESOLVE_PATH = '/v1/resolve';
+const RELATIVE_RESOLVE_PATH = RESOLVE_PATH.slice(1);
+const SPAN_NAME = 'adapter.response_catalog.fetch_response';
+const TRACER_NAME = '@cobre-npm/library-response-catalog-node';
+const METER_NAME$1 = '@cobre-npm/library-response-catalog-node';
+const HTTP_CLIENT_DURATION_METRIC = 'http.client.request.duration';
+class CatalogHttpAdapter extends CatalogPort {
+    axiosClient;
+    baseUrl;
+    authHeadersSource;
+    fallbackTokenResolver;
+    fallbackActivationRecorder;
+    resilience;
+    httpClientDuration = api.metrics
+        .getMeter(METER_NAME$1)
+        .createHistogram(HTTP_CLIENT_DURATION_METRIC, {
+        description: 'Duration of outbound Response Catalog HTTP calls',
+        unit: 'ms',
+    });
+    constructor(dependencies) {
+        super();
+        this.axiosClient = dependencies.axiosClient;
+        this.baseUrl = dependencies.baseUrl;
+        this.authHeadersSource = dependencies.authHeadersSource;
+        this.fallbackTokenResolver = dependencies.fallbackTokenResolver;
+        this.fallbackActivationRecorder = dependencies.fallbackActivationRecorder;
+        this.resilience = dependencies.resilience ?? createResiliencePolicies();
+    }
+    async fetchResponse(context) {
+        const tracer = api.trace.getTracer(TRACER_NAME);
+        return tracer.startActiveSpan(SPAN_NAME, { kind: api.SpanKind.CLIENT }, async (span) => {
+            try {
+                return await this.resilience.policy.execute(async () => this.callCatalog(context));
+            }
+            catch (error) {
+                const unavailable = findErrorInChain(error, (candidate) => candidate instanceof CatalogUnavailableError);
+                if (unavailable !== undefined) {
+                    return this.activateFallback(context, unavailable.reason);
+                }
+                if (isBrokenCircuitError(error)) {
+                    libraryNodejsTelemetry.log.error({
+                        message: 'Catalog service circuit breaker is open',
+                        content: error,
+                        attrs: this.contextAttributes(context),
+                    });
+                    return this.activateFallback(context, CATALOG_UNAVAILABLE_REASONS.CIRCUIT_OPEN);
+                }
+                const clientError = findErrorInChain(error, (candidate) => candidate instanceof CatalogClientError
+                    && !(candidate instanceof CatalogUnavailableError));
+                if (clientError !== undefined) {
+                    throw clientError;
+                }
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
+    }
+    async callCatalog(context) {
+        const startedAt = process.hrtime.bigint();
+        let statusCode;
+        try {
+            const url = this.buildUrl(context);
+            const headers = await this.authHeadersSource.headers();
+            const response = await this.axiosClient.get(url, { headers });
+            statusCode = response.status;
+            this.recordHttpDuration(startedAt, response.status);
+            // mapResponseError owns the confirm for error statuses, so the
+            // success path is the only other place that reports an outcome. Calling
+            // it here as well would double-fire on every 4xx/5xx, because
+            // validateStatus lets error responses through instead of throwing.
+            if (response.status >= 400) {
+                throw this.mapResponseError(context, response.status);
+            }
+            this.authHeadersSource.confirm(response.status);
+            return this.requireBody({
+                context,
+                response: response.data,
+                statusCode: response.status,
+                startedAt,
+            });
+        }
+        catch (error) {
+            // validateStatus accepts every status, so axios rejects only when no
+            // response arrived at all: a network failure, a timeout, or a body it
+            // could not read. Anything carrying a status took the branch above.
+            if (statusCode === undefined) {
+                this.recordHttpDuration(startedAt, 0);
+            }
+            // Covers CatalogUnavailableError too, which extends it.
+            if (error instanceof CatalogClientError) {
+                throw error;
+            }
+            if (axios.isAxiosError(error)) {
+                throw this.mapNetworkError(context, error);
+            }
+            throw this.mapUnexpectedError(context, error);
+        }
+    }
+    recordHttpDuration(startedAt, statusCode) {
+        const durationMillis = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+        this.httpClientDuration.record(durationMillis, {
+            'url.template': RESOLVE_PATH,
+            'http.response.status_code': statusCode,
+        });
+    }
+    requireBody({ context, response, statusCode, startedAt }) {
+        if (!this.isUsable(response)) {
+            const cause = new Error('response body is empty or missing required fields');
+            libraryNodejsTelemetry.log.error({
+                message: 'Catalog service returned an unusable response body',
+                content: cause,
+                attrs: this.contextAttributes(context),
+            });
+            throw new CatalogUnavailableError(`Catalog service returned an unusable response body for supplier ${context.supplier}`, CATALOG_UNAVAILABLE_REASONS.INVALID_RESPONSE, statusCode);
+        }
+        this.logSuccess(context, startedAt);
+        return response;
+    }
+    isUsable(response) {
+        return response != null
+            && response.supplier != null
+            && response.internal != null
+            && response.api != null
+            && hasText(response.resolvedLocale)
+            && hasText(response.resolvedMessage);
+    }
+    buildUrl(context) {
+        // RESOLVE_PATH is joined as a relative reference so a baseUrl carrying a
+        // path prefix (the usual shape behind the internal gateway) keeps it. An
+        // absolute '/v1/resolve' would replace the prefix instead of extending it.
+        const base = this.baseUrl.endsWith('/') ? this.baseUrl : `${this.baseUrl}/`;
+        const url = new URL(RELATIVE_RESOLVE_PATH, base);
+        url.searchParams.set('supplier', context.supplier);
+        url.searchParams.set('domain', context.domain);
+        url.searchParams.set('code', context.code);
+        if (context.locale !== null) {
+            url.searchParams.set('locale', context.locale);
+        }
+        // URLSearchParams serializes a space as '+', which is only equivalent to
+        // %20 for servers that apply form decoding. Java percent-encodes it, so
+        // match that and keep the query unambiguous.
+        url.search = url.searchParams.toString().replace(/\+/g, '%20');
+        return url.toString();
+    }
+    mapResponseError(context, statusCode) {
+        this.authHeadersSource.confirm(statusCode);
+        const exception = this.catalogErrorForStatus(context, statusCode);
+        const attrs = {
+            ...this.contextAttributes(context),
+            'response.status_code': String(statusCode),
+        };
+        if (exception.isTransient()) {
+            libraryNodejsTelemetry.log.error({
+                message: 'Catalog service returned an error response',
+                attrs,
+            });
+        }
+        else if (exception.isCredentialError()) {
+            libraryNodejsTelemetry.log.error({
+                message: 'Catalog service rejected the credentials',
+                attrs,
+            });
+        }
+        else {
+            libraryNodejsTelemetry.log.info({
+                message: 'Catalog service rejected the request as a client error',
+                attrs,
+            });
+        }
+        return exception;
+    }
+    catalogErrorForStatus(context, statusCode) {
+        const message = `Catalog service returned status ${statusCode} for supplier ${context.supplier}`;
+        if (statusCode >= 500) {
+            return new CatalogUnavailableError(message, CATALOG_UNAVAILABLE_REASONS.SERVER_ERROR, statusCode);
+        }
+        return new CatalogClientError(message, statusCode);
+    }
+    mapNetworkError(context, error) {
+        libraryNodejsTelemetry.log.error({
+            message: 'Catalog service could not be reached',
+            content: error,
+            attrs: this.contextAttributes(context),
+        });
+        return new CatalogUnavailableError(`Catalog service could not be reached for supplier ${context.supplier}`, CATALOG_UNAVAILABLE_REASONS.NETWORK, error);
+    }
+    mapUnexpectedError(context, error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        libraryNodejsTelemetry.log.error({
+            message: 'Unexpected error calling the catalog service',
+            content: cause,
+            attrs: this.contextAttributes(context),
+        });
+        return new CatalogClientError(`Unexpected error calling the catalog service for supplier ${context.supplier}`, cause);
+    }
+    activateFallback(context, reason) {
+        const fallback = this.fallbackTokenResolver.resolve(context);
+        this.fallbackActivationRecorder.record(context, fallback, reason);
+        return createFallbackResponse(context, fallback);
+    }
+    logSuccess(context, startedAt) {
+        const durationMillis = Number(process.hrtime.bigint() - startedAt) / 1_000_000;
+        libraryNodejsTelemetry.log.info({
+            message: 'Resolved response catalog entry',
+            attrs: {
+                ...this.contextAttributes(context),
+                'result.duration_ms': String(Math.round(durationMillis)),
+            },
+        });
+    }
+    contextAttributes(context) {
+        const attrs = {
+            'request.supplier': context.supplier,
+            'request.domain': context.domain,
+            'request.code': context.code,
+        };
+        if (context.locale !== null) {
+            attrs['request.locale'] = context.locale;
+        }
+        return attrs;
+    }
+}
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 2_000;
+const DEFAULT_READ_TIMEOUT_MS = 5_000;
+const createAxiosClient = ({ connectTimeoutMs, readTimeoutMs }) => axios.create({
+    timeout: readTimeoutMs,
+    validateStatus: () => true,
+    transitional: {
+        silentJSONParsing: false,
+    },
+    httpAgent: new http.Agent({ keepAlive: true, timeout: connectTimeoutMs }),
+    httpsAgent: new https.Agent({ keepAlive: true, timeout: connectTimeoutMs }),
+});
+
+const FALLBACK_MATCHES = {
+    EXACT: 'exact',
+    DEFAULT: 'default',
+};
+
+const toFallbackKey = (code, locale) => `${code}::${locale}`;
+
+/**
+ * Canonicalizes a locale tag, accepting both underscore and hyphen separators.
+ *
+ * @param locale - Locale tag such as `es_CO` or `es-co`
+ * @returns The canonical BCP 47 tag (`es-CO`)
+ * @throws Error when the tag is not a structurally valid locale
+ *
+ * @example
+ * ```typescript
+ * normalizeLocale('es_CO') // 'es-CO'
+ * ```
+ */
+const normalizeLocale = (locale) => {
+    const languageTag = locale.replace(/_/g, '-');
+    try {
+        // getCanonicalLocales returns exactly one tag for a single input and throws
+        // RangeError when the tag is not structurally valid, so joining the result
+        // yields the canonical form without an unreachable index fallback.
+        return Intl.getCanonicalLocales(languageTag).join('');
+    }
+    catch {
+        throw new Error(`Invalid locale: ${locale}`);
+    }
+};
+
+/**
+ * The locale the lookup runs under: the canonicalized context locale, or the
+ * map's default when it is absent or not a structurally valid tag.
+ */
+const effectiveLocale = (tokenMap, locale) => {
+    if (!hasText(locale)) {
+        return tokenMap.defaultLocale;
+    }
+    try {
+        return normalizeLocale(locale);
+    }
+    catch {
+        return tokenMap.defaultLocale;
+    }
+};
+/**
+ * Binds a validated token map to a resolver. The map is loaded once when the
+ * client is created, so resolution is a pure in-memory lookup.
+ *
+ * @param tokenMap - The validated map to look up in
+ * @returns A resolver over that map
+ */
+const createFallbackTokenResolver = (tokenMap) => ({
+    resolve: (context) => {
+        const locale = effectiveLocale(tokenMap, context.locale);
+        const token = tokenMap.tokens.get(toFallbackKey(context.code, locale));
+        return token === undefined
+            ? { token: tokenMap.defaultToken, resolvedLocale: locale, match: FALLBACK_MATCHES.DEFAULT }
+            : { token, resolvedLocale: locale, match: FALLBACK_MATCHES.EXACT };
+    },
+});
+
+var defaultLocale = "en-US";
+var defaultToken = "#UNKNOWN_ERROR#";
+var entries = [
+];
+var bundledFallbackTokens = {
+	defaultLocale: defaultLocale,
+	defaultToken: defaultToken,
+	entries: entries
+};
+
+const BUNDLE_PREFIX = 'bundle:';
+const FILE_PREFIX = 'file:';
+const TOKEN_PATTERN = /^#[A-Z0-9_]+#$/;
+const BUNDLED_RESOURCE_NAME = 'response-catalog-fallbacks.json';
+const FILE_PROPERTIES = ['defaultLocale', 'defaultToken', 'entries'];
+const ENTRY_PROPERTIES = ['code', 'locale', 'token'];
+const DEFAULT_FALLBACK_TOKENS_LOCATION = `${BUNDLE_PREFIX}${BUNDLED_RESOURCE_NAME}`;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Rejects properties the schema does not define, so a typo in a consumer's
+ * token file fails loudly instead of being silently ignored.
+ */
+const requireKnownProperties = (record, allowed, subject) => {
+    const unexpected = Object.keys(record).find((key) => !allowed.includes(key));
+    if (unexpected !== undefined) {
+        throw new Error(`${subject} contains unknown property '${unexpected}'`);
+    }
+};
+const requireString = (value, fieldName) => {
+    if (value !== null && value !== undefined && typeof value !== 'string') {
+        throw new Error(`${fieldName} must be a string, got: ${typeof value}`);
+    }
+    return requireText(value, fieldName);
+};
+const requireToken = (value, fieldName) => {
+    const token = requireString(value, fieldName);
+    if (!TOKEN_PATTERN.test(token)) {
+        throw new Error(`${fieldName} must match ${TOKEN_PATTERN.source}, got: ${token}`);
+    }
+    return token;
+};
+const requireValidLocale = (value, fieldName) => normalizeLocale(requireString(value, fieldName));
+const requireSupportedLocation = (location) => {
+    const value = requireText(location, 'fallbackTokensLocation');
+    if (!value.startsWith(BUNDLE_PREFIX) && !value.startsWith(FILE_PREFIX)) {
+        throw new Error(`fallbackTokensLocation must use ${BUNDLE_PREFIX} or ${FILE_PREFIX}, got: ${location}`);
+    }
+    return value;
+};
+/** Reads the raw document. Its shape is unverified until {@link toMap} runs. */
+const readFallbackFile = (location) => {
+    const supportedLocation = requireSupportedLocation(location);
+    if (supportedLocation.startsWith(BUNDLE_PREFIX)) {
+        const resourceName = supportedLocation.slice(BUNDLE_PREFIX.length);
+        if (resourceName !== BUNDLED_RESOURCE_NAME) {
+            throw new Error(`Only '${DEFAULT_FALLBACK_TOKENS_LOCATION}' is bundled with this package; `
+                + `use '${FILE_PREFIX}/absolute/path.json' for custom files. Got: ${supportedLocation}`);
+        }
+        return bundledFallbackTokens;
+    }
+    // Only file: can reach this point: requireSupportedLocation rejects anything
+    // else and the bundle: case returned above.
+    const filePath = supportedLocation.slice(FILE_PREFIX.length);
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`Fallback tokens resource not found: ${supportedLocation}`);
+    }
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+};
+const toEntryTokens = (entries) => {
+    if (!Array.isArray(entries)) {
+        throw new Error('Fallback tokens entries must be an array');
+    }
+    const tokens = new Map();
+    for (const entry of entries) {
+        if (entry === null || entry === undefined) {
+            throw new Error('Fallback tokens entries must not contain null');
+        }
+        if (!isRecord(entry)) {
+            throw new Error('Fallback tokens entries must contain JSON objects');
+        }
+        requireKnownProperties(entry, ENTRY_PROPERTIES, 'Fallback token entry');
+        const code = requireString(entry.code, 'code');
+        const locale = requireValidLocale(entry.locale, 'locale');
+        const key = toFallbackKey(code, locale);
+        if (tokens.has(key)) {
+            throw new Error(`Duplicate fallback token entry for code '${code}' and locale '${locale}'`);
+        }
+        tokens.set(key, requireToken(entry.token, 'token'));
+    }
+    return tokens;
+};
+/** Validates the unverified document and narrows it to a {@link FallbackTokenMap}. */
+const toMap = (file) => {
+    if (file === null || file === undefined) {
+        throw new Error('Fallback tokens file must not be empty');
+    }
+    if (!isRecord(file)) {
+        throw new Error(`Fallback tokens file must be a JSON object, got: ${typeof file}`);
+    }
+    requireKnownProperties(file, FILE_PROPERTIES, 'Fallback tokens file');
+    return {
+        defaultLocale: requireValidLocale(file.defaultLocale, 'defaultLocale'),
+        defaultToken: requireToken(file.defaultToken, 'defaultToken'),
+        tokens: toEntryTokens(file.entries ?? []),
+    };
+};
+const loadFallbackTokenMap = (location) => {
+    try {
+        return toMap(readFallbackFile(location));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error(`Fallback tokens file is not valid JSON: ${location}`, { cause: error });
+        }
+        throw error;
+    }
+};
+
+const METRIC_NAME = 'response_catalog.fallback.activations';
+const METRIC_UNIT = '{activation}';
+const LOG_MESSAGE = 'Response catalog local fallback activated';
+const METER_NAME = '@cobre-npm/library-response-catalog-node';
+const activationAttributes = (context, fallback, reason) => {
+    const attrs = {
+        'request.supplier': context.supplier,
+        'request.domain': context.domain,
+        'request.code': context.code,
+        'fallback.resolved_locale': fallback.resolvedLocale,
+        'fallback.token': fallback.token,
+        'fallback.match': fallback.match,
+        'failure.reason': reason,
+    };
+    if (context.locale !== null) {
+        attrs['request.locale'] = context.locale;
+    }
+    return attrs;
+};
+/**
+ * Records fallback activations as an OpenTelemetry counter plus a warning log.
+ * The counter is created once, when the recorder is built, and closed over.
+ *
+ * @returns A recorder wired to the process meter provider
+ */
+const createTelemetryFallbackActivationRecorder = () => {
+    const counter = api.metrics.getMeter(METER_NAME).createCounter(METRIC_NAME, {
+        description: 'Local fallback activations after response catalog technical unavailability',
+        unit: METRIC_UNIT,
+    });
+    return {
+        record: (context, fallback, reason) => {
+            libraryNodejsTelemetry.log.warning({
+                message: LOG_MESSAGE,
+                attrs: activationAttributes(context, fallback, reason),
+            });
+            counter.add(1, {
+                'failure.reason': reason,
+                'fallback.match': fallback.match,
+            });
+        },
+    };
+};
+
+/**
+ * Rejects a `baseUrl` that is not an absolute HTTP(S) URL, so a typo or a
+ * missing scheme fails when the client is created rather than surfacing later
+ * disguised as a network failure.
+ *
+ * Stricter than the Java library, which accepts any absolute URI: only `http:`
+ * and `https:` can reach the catalog over this adapter.
+ *
+ * @param baseUrl - The configured base URL
+ * @throws Error when the value is unparseable or uses another scheme
+ */
+const requireAbsoluteBaseUrl = (baseUrl) => {
+    let uri;
+    try {
+        uri = new URL(baseUrl);
+    }
+    catch (error) {
+        throw new Error(`baseUrl is not a valid URI: ${baseUrl}`, { cause: error });
+    }
+    if (uri.protocol !== 'http:' && uri.protocol !== 'https:') {
+        throw new Error('baseUrl must be an absolute URI with a scheme '
+            + `(e.g. http://... or https://...), got: ${baseUrl}`);
+    }
+};
+
+const buildCatalogClientSettings = (settings) => ({
+    baseUrl: settings.baseUrl,
+    connectTimeoutMs: settings.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS,
+    readTimeoutMs: settings.readTimeoutMs ?? DEFAULT_READ_TIMEOUT_MS,
+    maxAttempts: settings.maxAttempts && settings.maxAttempts > 0
+        ? settings.maxAttempts
+        : DEFAULT_MAX_ATTEMPTS,
+    fallbackTokensLocation: settings.fallbackTokensLocation?.trim()
+        ? settings.fallbackTokensLocation
+        : DEFAULT_FALLBACK_TOKENS_LOCATION,
+});
+const createCatalogHttpAdapter = (settings, authHeadersSource) => {
+    const resolvedSettings = buildCatalogClientSettings(settings);
+    requireAbsoluteBaseUrl(resolvedSettings.baseUrl);
+    let tokenMap;
+    try {
+        tokenMap = loadFallbackTokenMap(resolvedSettings.fallbackTokensLocation);
+    }
+    catch (error) {
+        throw new Error(`Failed to load response catalog fallback tokens from ${resolvedSettings.fallbackTokensLocation}`, { cause: error });
+    }
+    return new CatalogHttpAdapter({
+        axiosClient: createAxiosClient({
+            connectTimeoutMs: resolvedSettings.connectTimeoutMs,
+            readTimeoutMs: resolvedSettings.readTimeoutMs,
+        }),
+        baseUrl: resolvedSettings.baseUrl,
+        authHeadersSource,
+        fallbackTokenResolver: createFallbackTokenResolver(tokenMap),
+        fallbackActivationRecorder: createTelemetryFallbackActivationRecorder(),
+        resilience: createResiliencePolicies({ maxAttempts: resolvedSettings.maxAttempts }),
+    });
+};
+
+const requireSecretName = (options) => {
+    if (!hasText(options.secretName)) {
+        throw new Error('secretName must be configured when mode is INTERNAL_GATEWAY');
+    }
+    return options.secretName.trim();
+};
+const resolveAuthHeadersSource = async (options) => {
+    if (options.authHeadersSource !== undefined) {
+        return options.authHeadersSource;
+    }
+    const mode = options.mode ?? CONNECTION_MODES.CLUSTER_DNS;
+    if (mode === CONNECTION_MODES.CLUSTER_DNS) {
+        return noAuthHeadersSource();
+    }
+    return createInternalGatewayAuthHeadersSource({
+        secretName: requireSecretName(options),
+        authManagerDomainURL: options.authManagerDomainURL,
+        secretAdapterRegion: options.secretAdapterRegion,
+    });
+};
+const createInternalGatewayAuthHeadersSource = async (options) => {
+    let getInternalApiHeaders;
+    try {
+        // Deep import on purpose: library-nodejs-common@3.x declares `main: index.js`,
+        // a file it does not ship, so requiring the package root fails. dist/index.js
+        // is the real bundle and the only entry that resolves at runtime. Its types
+        // come from src/types/optional-peers.d.ts, so no assertion is needed here.
+        ({ getInternalApiHeaders } = await import('@cobre-npm/library-nodejs-common/dist/index.js'));
+    }
+    catch (error) {
+        throw new Error('mode is INTERNAL_GATEWAY but @cobre-npm/library-nodejs-common could not be loaded; '
+            + 'install it to use this mode. See the cause for the underlying resolution error.', { cause: error });
+    }
+    const secretAdapterRegion = options.secretAdapterRegion
+        ?? process.env.AWS_REGION
+        ?? 'us-east-1';
+    if (!hasText(options.authManagerDomainURL)) {
+        throw new Error('authManagerDomainURL must be configured when mode is INTERNAL_GATEWAY');
+    }
+    return new InternalGatewayAuthHeadersSource({
+        secretName: options.secretName,
+        authManagerBaseURL: options.authManagerDomainURL.trim(),
+        secretAdapterRegion,
+        fetchHeaders: getInternalApiHeaders,
+    });
+};
+const validateOptions = (options) => {
+    if (!hasText(options.baseUrl)) {
+        throw new Error('baseUrl must be configured');
+    }
+    try {
+        requireAbsoluteBaseUrl(options.baseUrl);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`baseUrl is malformed: ${reason}`, { cause: error });
+    }
+    const mode = options.mode ?? CONNECTION_MODES.CLUSTER_DNS;
+    if (mode === CONNECTION_MODES.INTERNAL_GATEWAY && !options.authHeadersSource) {
+        requireSecretName(options);
+    }
+};
+/**
+ * Preferred entry point. Resolves INTERNAL_GATEWAY credentials via
+ * `@cobre-npm/library-nodejs-common` when needed.
+ */
+const createCatalogClient = async (options) => {
+    validateOptions(options);
+    const authHeadersSource = await resolveAuthHeadersSource(options);
+    return createCatalogHttpAdapter({
+        baseUrl: options.baseUrl,
+        connectTimeoutMs: options.connectTimeoutMs,
+        readTimeoutMs: options.readTimeoutMs,
+        maxAttempts: options.maxAttempts,
+        fallbackTokensLocation: options.fallbackTokensLocation,
+    }, authHeadersSource);
+};
+/**
+ * Sync factory for CLUSTER_DNS or when you already have an `authHeadersSource`.
+ * Cannot auto-resolve INTERNAL_GATEWAY credentials — use `createCatalogClient` instead.
+ */
+const createCatalogClientSync = (options) => {
+    validateOptions(options);
+    const mode = options.mode ?? CONNECTION_MODES.CLUSTER_DNS;
+    if (mode === CONNECTION_MODES.INTERNAL_GATEWAY && !options.authHeadersSource) {
+        throw new Error('createCatalogClientSync cannot resolve INTERNAL_GATEWAY auth; pass authHeadersSource or use createCatalogClient');
+    }
+    const authHeadersSource = options.authHeadersSource ?? noAuthHeadersSource();
+    return createCatalogHttpAdapter({
+        baseUrl: options.baseUrl,
+        connectTimeoutMs: options.connectTimeoutMs,
+        readTimeoutMs: options.readTimeoutMs,
+        maxAttempts: options.maxAttempts,
+        fallbackTokensLocation: options.fallbackTokensLocation,
+    }, authHeadersSource);
+};
+
+/**
+ * Validates and builds a {@link SupplierErrorContext} from raw input.
+ *
+ * @param input - Supplier, domain, error code, and optional locale
+ * @returns A `SupplierErrorContext` with `locale` normalized to `null` when omitted
+ * @throws {Error} When `supplier`, `domain`, or `code` is `null`, `undefined`, or blank
+ * @example
+ * ```typescript
+ * const context = buildSupplierErrorContext({
+ *   supplier: 'nequi',
+ *   domain: 'wallets',
+ *   code: '58',
+ *   locale: 'es-CO',
+ * })
+ * ```
+ */
+const buildSupplierErrorContext = (input) => ({
+    supplier: requireText(input.supplier, 'supplier'),
+    domain: requireText(input.domain, 'domain'),
+    code: requireText(input.code, 'code'),
+    locale: hasText(input.locale) ? input.locale.trim() : null,
+});
+
 /**
  * @module @cobre-npm/library-response-catalog-node
  *
@@ -8,8 +984,6 @@
  * or `createCatalogClientSync`, then call `fetchResponse` with a
  * `SupplierErrorContext` from `buildSupplierErrorContext`.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.noAuthHeadersSource = exports.CONNECTION_MODES = exports.CatalogClientError = exports.buildSupplierErrorContext = exports.CatalogPort = exports.LIBRARY_VERSION = void 0;
 /**
  * Published package version. Matches `package.json`.
  *
@@ -21,16 +995,17 @@ exports.noAuthHeadersSource = exports.CONNECTION_MODES = exports.CatalogClientEr
  * ```
  *
  * @see {@link https://github.com/Cobre-Colombia/library-response-catalog-node/blob/trunk/CHANGELOG.md | CHANGELOG}
+ * @see {@link https://github.com/Cobre-Colombia/library-response-catalog-node/blob/trunk/docs/releases/01-scaffold.md | Scaffold notes}
  */
-exports.LIBRARY_VERSION = '0.3.0';
-var catalog_port_1 = require("./domain/ports/out/catalog-port");
-Object.defineProperty(exports, "CatalogPort", { enumerable: true, get: function () { return catalog_port_1.CatalogPort; } });
-var supplier_error_context_1 = require("./domain/core/models/supplier-error-context");
-Object.defineProperty(exports, "buildSupplierErrorContext", { enumerable: true, get: function () { return supplier_error_context_1.buildSupplierErrorContext; } });
-var catalog_client_error_1 = require("./domain/core/models/catalog-client-error");
-Object.defineProperty(exports, "CatalogClientError", { enumerable: true, get: function () { return catalog_client_error_1.CatalogClientError; } });
-var connection_mode_1 = require("./adapter/http/connection-mode");
-Object.defineProperty(exports, "CONNECTION_MODES", { enumerable: true, get: function () { return connection_mode_1.CONNECTION_MODES; } });
-var no_auth_headers_source_1 = require("./adapter/http/no-auth-headers-source");
-Object.defineProperty(exports, "noAuthHeadersSource", { enumerable: true, get: function () { return no_auth_headers_source_1.noAuthHeadersSource; } });
+const LIBRARY_VERSION = '0.3.0';
+
+exports.CONNECTION_MODES = CONNECTION_MODES;
+exports.CatalogClientError = CatalogClientError;
+exports.CatalogPort = CatalogPort;
+exports.DEFAULT_FALLBACK_TOKENS_LOCATION = DEFAULT_FALLBACK_TOKENS_LOCATION;
+exports.LIBRARY_VERSION = LIBRARY_VERSION;
+exports.buildSupplierErrorContext = buildSupplierErrorContext;
+exports.createCatalogClient = createCatalogClient;
+exports.createCatalogClientSync = createCatalogClientSync;
+exports.noAuthHeadersSource = noAuthHeadersSource;
 //# sourceMappingURL=index.js.map