library-response-catalog-node

Node.js SDK that resolves a supplier-reported error against Cobre's response catalog. Call createCatalogClient, then fetchResponse, and let this library own HTTP, retries, the circuit breaker, and (unlike the Java sibling) a local technical fallback.

Outcomes

| What happened | What you get | |---|---| | Catalog returned a usable body | Response with api and internal populated | | Catalog down / 5xx / empty or unusable body / open circuit | Degraded Response — frontend token in resolvedMessage, fallbackApplied=true, api/internal = null | | Catalog returned HTTP 4xx, or credentials stayed rejected | CatalogClientError — do not retry | | Options missing or malformed | Error while creating the client |

Intentional divergence from Java

library-response-catalog-java throws CatalogClientError on technical unavailability. This Node library returns a local fallback token instead, so Node services can keep rendering a stable frontend message when the catalog is down.

| Flag / shape | Meaning | |---|---| | Remote fallbackApplied=true with api/internal populated | Catalog substituted a locale/entry server-side | | Local degraded: fallbackApplied=true and api === null | SDK technical fallback — render resolvedMessage as a frontend token |

const response = await catalog.fetchResponse(context)
if (response.fallbackApplied && response.api === null) {
  return renderToken(response.resolvedMessage) // e.g. #UNKNOWN_ERROR#
}
return handleCatalogResponse(response)

Quickstart

1. Dependency

pnpm add @cobre-npm/library-response-catalog-node

Requires pnpm 10.27.0 (packageManager in package.json). Same-cluster (CLUSTER_DNS, the default) needs nothing else. Cross-cluster (INTERNAL_GATEWAY) also needs @cobre-npm/library-nodejs-common.

2. Create the client

import {
  buildSupplierErrorContext,
  createCatalogClientSync,
  CONNECTION_MODES,
} from '@cobre-npm/library-response-catalog-node'

const catalog = createCatalogClientSync({
  baseUrl: 'http://response-catalog-util.util-prod.svc.cluster.local',
  mode: CONNECTION_MODES.CLUSTER_DNS,
})

const response = await catalog.fetchResponse(
  buildSupplierErrorContext({
    supplier: 'nequi',
    domain: 'wallets',
    code: '58',
    locale: 'es-CO',
  }),
)

For INTERNAL_GATEWAY, use the async factory (loads API Gateway credentials):

import { createCatalogClient, CONNECTION_MODES } from '@cobre-npm/library-response-catalog-node'

const catalog = await createCatalogClient({
  baseUrl: 'https://api-int.prod.co',
  mode: CONNECTION_MODES.INTERNAL_GATEWAY,
  secretName: 'response-catalog/credentials',
  authManagerDomainURL: 'https://auth-manager.example.com',
})

Which connection mode?

| Situation | Mode | Extra dependency | |---|---|---| | Catalog is in the same Kubernetes cluster | CLUSTER_DNS (default) | none | | Catalog is reached via api-int.<env>.co | INTERNAL_GATEWAY | @cobre-npm/library-nodejs-common + secretName + authManagerDomainURL |

Public API

| Type | Role | |---|---| | CatalogPort | Only method you call: fetchResponse | | buildSupplierErrorContext | Request: supplier, domain, code required; locale optional | | Response, SupplierInfo, InternalInfo, ApiInfo | Response payload | | CatalogClientError | HTTP 4xx or persistent credential rejection | | createCatalogClient / createCatalogClientSync | Wiring | | CONNECTION_MODES | CLUSTER_DNS or INTERNAL_GATEWAY | | LIBRARY_VERSION | Package version string |

Do not construct CatalogHttpAdapter from consumer code.

A scaffold snippet for LIBRARY_VERSION lives in examples/library-version.ts. A domain-only snippet (no HTTP adapter) lives in examples/domain-context.ts.

Guides

| Guide | Contents | |---|---| | Direct HTTP | Modes, options, /v1/resolve | | Error handling | What to catch vs local fallback | | Testing | Mock CatalogPort | | Observability | Span, logs, metrics | | HTTP client | Factory options, resilience, Java divergences | | Fallback behavior | When fallback applies and the token map | | Architecture | Package layout and Java divergence | | Stack layering | Stacked-PR layers and the same-cluster vs INTERNAL_GATEWAY split | | Docs index | Per-layer release notes | | Examples | Runnable snippets | | Changelog | Version history | | Contributing | Stack and tooling |

Build

pnpm lint
pnpm test
pnpm run build
pnpm run docs # generates TypeDoc HTML into docs/api/ (gitignored)