Merge pull request #18 from peek-travel/feat/cng-accessor

feat: add CNG REST accessor alongside Peek, share transport/auth/config

Author: coladarci

docs/internal/ARCHITECTURE.md

@@ -11,6 +11,13 @@ call typed methods like `peek.getProductService().getAllProducts()` or directly
 via the top-level short-forms like `peek.getAllProducts()` and
 `peek.getAllActivities()`.
 
+The package also ships a **sibling accessor for the CNG backoffice**,
+`CngAccessService` (REST, not GraphQL). It reuses this package's auth
+(`TokenManager`), retry/backoff loop, `Logger`, base error types, tooling, and
+the Odyssey UI — differing only in transport (REST vs GraphQL) and gateway
+routing (`cng_backoffice_api-v1` vs `peek_backoffice_api-v1`). See
+"CNG accessor" below.
+
 ## Layers
 
 ```
@@ -76,9 +83,14 @@ via the top-level short-forms like `peek.getAllProducts()` and
 - Caches the token and re-mints it once it is within `leewaySeconds` of expiry.
 
 ### 3. `GraphQLClient` — transport
-`src/internal/graphql-client.ts`
+`src/internal/peek/graphql-client.ts`
 
-The only place that touches the network. Responsibilities:
+The place that touches the network for Peek. The retry/backoff loop and 418/429
+mapping are **shared** with the CNG transport in
+`src/internal/http-transport.ts` (`requestWithRetry`): both clients build their
+own `url`/`init`, log their own "Making … request" line, and pass a per-response
+callback that handles the transport-specific success/error parsing.
+Responsibilities:
 
 - Builds the endpoint URL as `${baseUrl}/${appId}/${endpointName}`, or
   `${baseUrl}/${appId}/${endpointPathPrefix}/${endpointName}` when an
@@ -98,7 +110,11 @@ The only place that touches the network. Responsibilities:
   - other non-2xx → generic `Error` with the status.
 
 ### 4. Per-resource services
-`src/internal/<resource>/`
+`src/internal/peek/<resource>/`
+
+Every Peek resource lives under `src/internal/peek/` (mirrored by the CNG
+resources under `src/internal/cng/` — see §5b); the shared plumbing
+(`token-manager.ts`, `http-transport.ts`) stays at `src/internal/`.
 
 Each resource follows the same **three-file triad**:
 
@@ -110,15 +126,16 @@ Each resource follows the same **three-file triad**:
 
 Resources: `products`, `account-users`, `resource-pools`, `timeslots`,
 `resellers`, `promo-codes`, `daily-notes`, `availability`, `memberships`,
-`bookings`, `reviews`. Clean data shapes live in `src/models/`.
+`bookings`, `reviews`. Clean data shapes are split by brand: Peek models in
+`src/models/peek/`, CNG models in `src/models/cng/`.
 
 `ProductService` exposes three top-level product filters in addition to the combined `getAllProducts()`:
 - `getAllActivities()` — fetches only the `activities` connection (one request, no add-on pagination).
 - `getAllAddons()` — fetches only the `itemOptions` connection, paginated.
 
 `waivers` is a **webhook-only resource**: it has no GraphQL reads (so no
-queries/service/converter triad), just `src/internal/waivers/waiver-webhook.ts`
-and the `src/models/waiver.ts` model. See the webhook notes below.
+queries/service/converter triad), just `src/internal/peek/waivers/waiver-webhook.ts`
+and the `src/models/peek/waiver.ts` model. See the webhook notes below.
 
 A resource may split into more than one triad when it carries a distinct
 sub-domain. `bookings` does: alongside `booking-queries`/`booking-converter`,
@@ -223,6 +240,53 @@ internal — including the booking-webhook registration query
 The webhook-related public exports are the two parsers `parseBookingWebhook` and
 `parseWaiverWebhook` (plus the `Waiver` model type; see the webhook notes above).
 
+### 5b. CNG accessor (REST)
+`src/cng-access-service.ts`, `src/internal/cng/`, `src/models/cng/product.ts`
+
+A second, brand-parallel accessor for the **CNG** backoffice — REST, not
+GraphQL. Deliberately low-churn: it sits alongside the Peek code and shares the
+plumbing rather than forking the package.
+
+- **`CngAccessService`** — validates four config fields (`installId`,
+  `jwtSecret`, `issuer`, `appId`; **no `gatewayKey`** — the CNG gateway needs no
+  `pk-api-key`). Builds the shared `TokenManager` and a `RestClient`, defaults
+  the base URL to the app-registry installations API, and exposes
+  `getProductService()` + the short-form `getAllActivities()`.
+- **`RestClient`** (`src/internal/cng/rest-client.ts`) — the REST sibling of
+  `GraphQLClient`. Builds `${baseUrl}/${appId}/${extendableSlug}/${path}` with
+  `extendableSlug = cng_backoffice_api-v1`, GETs it with `X-Peek-Auth: Bearer`
+  (no `pk-api-key`, no `{query,variables}` body), and runs through the shared
+  `requestWithRetry` loop. Parses the body as JSON, falling back to raw text
+  when unparseable; non-2xx (other than 418/429) → `CngApiError` (status + body).
+- **Products triad** (`src/internal/cng/products/`) — same shape as every Peek
+  resource: `product-queries.ts` (raw REST `ProductNode`/`ProductsResponse`
+  interfaces, internal), `product-converter.ts` (pure `fromProductNodes` →
+  `Activity`), `product-service.ts` (`CngProductService.getAllActivities()`,
+  tolerating a `{ products: [...] }` envelope or a bare array). Endpoint segments
+  live in `src/internal/cng/endpoints.ts`.
+- **Model** `src/models/cng/product.ts` — `Activity`/`ActivityTicket`, mirroring
+  the Peek `Product` shape so both brands read uniformly.
+- **Shared, not duplicated:** the config contract (`BaseAccessServiceConfig` +
+  the `createTokenManager`/`requireNonEmpty` helpers and shared TTL/leeway/retry
+  defaults, all in `src/access-service-config.ts`), `TokenManager`,
+  `Logger`/`noopLogger`, the `AdminAccountRequiredError`/`RateLimitError` base
+  errors, the `requestWithRetry` transport core, the build/test tooling, and the
+  Odyssey UI. Each accessor's config just extends the base: `PeekAccessServiceConfig`
+  adds `gatewayKey`/`mode`/`itemOptionsPageSize`; `CngAccessServiceConfig` adds
+  nothing. So the only real per-accessor difference is the transport built and the
+  services exposed.
+- **Public exports:** `CngAccessService` + `CngAccessServiceConfig`,
+  `CngProductService`, the `Activity`/`ActivityTicket` types, and `CngApiError`
+  (added to the errors export). REST paths and raw response interfaces stay
+  internal.
+
+> ⚠️ **Guessed response shape.** The real `commerce-config/products` payload is
+> not yet confirmed. `ProductNode`, the converter mapping, and the `Activity`
+> field set are best-guess placeholders (snake_case REST fields, defensive
+> defaults). Confirm against a live sample and adjust — touch only
+> `cng/products/product-queries.ts`, `product-converter.ts`, and
+> `models/cng/product.ts`.
+
 ### 6. UI components — the `./ui` subpath
 `src/ui/`
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peektravel/app-utilities",
-  "version": "0.2.10",
+  "version": "0.3.0",
   "description": "GraphQL JS mapping utilities extracted from the Peek Pro Autopilot connector.",
   "license": "MIT",
   "repository": {

src/access-service-config.ts

@@ -0,0 +1,72 @@
+/**
+ * Config shared by every access service in this package (Peek, CNG, …).
+ *
+ * Each gateway's access service extends {@link BaseAccessServiceConfig} with its
+ * own extras (e.g. Peek adds `gatewayKey`/`mode`), so the only real difference
+ * between accessors is the transport they build and the services they expose.
+ * The shared defaults and the token-manager builder live here too, so that
+ * plumbing is written once.
+ */
+import { TokenManager } from "./internal/token-manager.js";
+import type { Logger } from "./logger.js";
+
+/** Fields common to every access service's config. */
+export interface BaseAccessServiceConfig {
+  /** Install ID. Becomes the JWT subject. */
+  installId: string;
+  /** HMAC secret used to sign the JWT. */
+  jwtSecret: string;
+  /** JWT issuer — the app name / app ID. */
+  issuer: string;
+  /** App ID, used in the gateway endpoint path. */
+  appId: string;
+
+  /** Override the gateway base URL. Default: per-service. */
+  baseUrl?: string;
+  /** JWT lifetime in seconds. Default: 3600. */
+  tokenTtlSeconds?: number;
+  /** Re-mint the cached token this many seconds before expiry. Default: 60. */
+  tokenRefreshLeewaySeconds?: number;
+  /** Backoff delays (ms) for HTTP 429 retries. Default: [1000, 2000, 4000]. */
+  retryDelaysMs?: number[];
+  /** Optional logger. Default: no-op (silent). */
+  logger?: Logger;
+  /** Custom `fetch` implementation. Default: the global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+/** Default JWT lifetime (1 hour). */
+export const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+/** Default leeway before expiry at which a cached token is re-minted. */
+export const DEFAULT_TOKEN_REFRESH_LEEWAY_SECONDS = 60;
+/** Default HTTP 429 retry backoff. */
+export const DEFAULT_RETRY_DELAYS_MS = [1000, 2000, 4000];
+
+/**
+ * Throws when a required config field is empty, prefixing the message with the
+ * concrete service name (e.g. `PeekAccessService: "installId" is required`).
+ */
+export function requireNonEmpty(
+  value: string,
+  name: string,
+  serviceName: string,
+): void {
+  if (!value) {
+    throw new Error(`${serviceName}: "${name}" is required`);
+  }
+}
+
+/**
+ * Builds the shared {@link TokenManager} from the common config fields, applying
+ * the shared TTL/leeway defaults. Used by every access service.
+ */
+export function createTokenManager(config: BaseAccessServiceConfig): TokenManager {
+  return new TokenManager({
+    secret: config.jwtSecret,
+    issuer: config.issuer,
+    installId: config.installId,
+    ttlSeconds: config.tokenTtlSeconds ?? DEFAULT_TOKEN_TTL_SECONDS,
+    leewaySeconds:
+      config.tokenRefreshLeewaySeconds ?? DEFAULT_TOKEN_REFRESH_LEEWAY_SECONDS,
+  });
+}

src/cng-access-service.ts

@@ -0,0 +1,94 @@
+/**
+ * Authenticated root entry point to the CNG backoffice REST gateway.
+ *
+ * The CNG sibling of {@link PeekAccessService}. Configure one instance per
+ * install; it owns the shared, authenticated transport (minting/caching tokens
+ * on demand) and hands out the {@link CngProductService}.
+ *
+ * Auth and transport mirror the Peek access service: the same app JWT
+ * (`X-Peek-Auth: Bearer`) minted from the Peek app credentials via the shared
+ * {@link TokenManager}, routed through the app-registry installations API. The
+ * only differences are the extendable slug (`cng_backoffice_api-v1`), REST
+ * rather than GraphQL, and no `pk-api-key` header.
+ */
+import {
+  createTokenManager,
+  requireNonEmpty,
+  DEFAULT_RETRY_DELAYS_MS,
+  type BaseAccessServiceConfig,
+} from "./access-service-config.js";
+import { CNG_EXTENDABLE_SLUG } from "./internal/cng/endpoints.js";
+import { CngProductService } from "./internal/cng/products/product-service.js";
+import { RestClient } from "./internal/cng/rest-client.js";
+import { noopLogger } from "./logger.js";
+
+/** Default gateway base URL — the app-registry installations API. */
+const DEFAULT_BASE_URL = "https://app-registry.peeklabs.com/installations-api";
+
+/**
+ * Configuration for a {@link CngAccessService} instance. CNG adds no fields
+ * beyond {@link BaseAccessServiceConfig} — it authenticates on the app JWT
+ * alone (no `pk-api-key`, so no `gatewayKey`).
+ */
+export type CngAccessServiceConfig = BaseAccessServiceConfig;
+
+/**
+ * Authenticated root entry point to the CNG backoffice REST gateway.
+ *
+ * @example
+ * ```ts
+ * import { CngAccessService, type Activity } from "@peektravel/app-utilities";
+ *
+ * const cng = new CngAccessService({
+ *   installId: "install-123",
+ *   jwtSecret: process.env.PEEK_APP_SECRET!,
+ *   issuer: process.env.PEEK_APP_ID!,
+ *   appId: process.env.PEEK_APP_ID!,
+ * });
+ *
+ * const activities: Activity[] = await cng.getAllActivities();
+ * ```
+ *
+ * @throws {Error} from the constructor when any required config field
+ * (`installId`, `jwtSecret`, `issuer`, `appId`) is empty.
+ */
+export class CngAccessService {
+  private readonly client: RestClient;
+  private productService?: CngProductService;
+
+  constructor(config: CngAccessServiceConfig) {
+    requireNonEmpty(config.installId, "installId", "CngAccessService");
+    requireNonEmpty(config.jwtSecret, "jwtSecret", "CngAccessService");
+    requireNonEmpty(config.issuer, "issuer", "CngAccessService");
+    requireNonEmpty(config.appId, "appId", "CngAccessService");
+
+    const logger = config.logger ?? noopLogger;
+    const tokens = createTokenManager(config);
+
+    this.client = new RestClient({
+      baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+      appId: config.appId,
+      extendableSlug: CNG_EXTENDABLE_SLUG,
+      getToken: () => tokens.getToken(),
+      retryDelaysMs: config.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
+      logger,
+      fetchFn: config.fetch ?? globalThis.fetch,
+    });
+  }
+
+  /**
+   * Returns the {@link CngProductService} for this install, bound to the shared
+   * authenticated transport. The instance is created lazily and reused.
+   */
+  getProductService(): CngProductService {
+    if (!this.productService) {
+      this.productService = new CngProductService(this.client);
+    }
+    return this.productService;
+  }
+
+  /** All activities. Delegates to {@link CngProductService.getAllActivities}. */
+  getAllActivities() {
+    return this.getProductService().getAllActivities();
+  }
+}

src/errors.ts

@@ -1,7 +1,10 @@
 /**
  * Typed errors thrown by the package. Each mirrors a failure mode of the Peek
- * GraphQL gateway so callers can branch on the error type rather than parsing
- * messages.
+ * GraphQL gateway (or the CNG REST gateway) so callers can branch on the error
+ * type rather than parsing messages.
+ *
+ * `AdminAccountRequiredError` and `RateLimitError` are shared by both gateways.
+ * `PeekGraphQLError` is Peek-only; `CngApiError` is CNG-only.
  */
 
 /**
@@ -46,3 +49,23 @@ export class PeekGraphQLError extends Error {
     this.graphqlErrors = graphqlErrors;
   }
 }
+
+/**
+ * Thrown when the CNG REST gateway returns a non-2xx response that is not one
+ * of the specifically-handled statuses (418/429). The offending status is
+ * preserved on {@link CngApiError.statusCode}, and the raw response body (parsed
+ * JSON when possible, otherwise the raw text) on {@link CngApiError.body}.
+ */
+export class CngApiError extends Error {
+  /** The HTTP status that triggered this error. */
+  public readonly statusCode: number;
+  /** The raw response body (parsed JSON when possible, otherwise text). */
+  public readonly body: unknown;
+
+  constructor(statusCode: number, body: unknown, message?: string) {
+    super(message ?? `CNG request failed with HTTP ${statusCode}`);
+    this.name = "CngApiError";
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}