feat: add ACME backoffice accessor (#20)

Clone the CNG REST accessor for the ACME backoffice. Same shared auth,
transport, retry loop, and tooling — differs only in routing, endpoint,
and response shape:

- extendable slug acme_backoffice_api@v1 (note @v1 separator)
- endpoint v2/b2b/event/templates/names?pageSize=-1&page=1
- { list: [...] } envelope; converter filters to published templates
  and maps colorCategory.backgroundColor -> color
- tickets always empty; exposes id/name/color only

Public surface: AcmeAccessService (+config), AcmeProductService,
AcmeActivity/AcmeActivityTicket, AcmeApiError.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: coladarci

docs/internal/ARCHITECTURE.md

@@ -11,12 +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.
+The package also ships **sibling accessors for other backoffices** —
+`CngAccessService` and `AcmeAccessService` (both REST, not GraphQL). They reuse
+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` /
+`acme_backoffice_api@v1` vs `peek_backoffice_api-v1`). See "CNG accessor" and
+"ACME accessor" below.
 
 ## Layers
 
@@ -234,7 +235,9 @@ Recurring patterns inside services:
 The barrel re-exports only the public contract: `PeekAccessService` + its config,
 each resource service class (and the options/result types callers need), all
 data-model **types** (including `PeekAuthTokenClaims` and `PeekAuthTokenUser`),
-the `Logger` interface + `noopLogger`, and the three typed error classes. Query strings and raw response interfaces are deliberately kept
+the `Logger` interface + `noopLogger`, and the typed error classes
+(`AdminAccountRequiredError`, `RateLimitError`, `PeekGraphQLError`,
+`CngApiError`, `AcmeApiError`). Query strings and raw response interfaces are deliberately kept
 internal — including the booking-webhook registration query
 (`BOOKING_WEBHOOK_GQL_QUERY` stays internal, documented via `docs/webhooks.md`).
 The webhook-related public exports are the two parsers `parseBookingWebhook` and
@@ -287,6 +290,40 @@ plumbing rather than forking the package.
 > `cng/products/product-queries.ts`, `product-converter.ts`, and
 > `models/cng/product.ts`.
 
+### 5c. ACME accessor (REST)
+`src/acme-access-service.ts`, `src/internal/acme/`, `src/models/acme/product.ts`
+
+A third, brand-parallel accessor for the **ACME** backoffice, built by cloning
+the CNG accessor. Same auth/transport/tooling reuse as CNG (§5b) — only the
+routing, endpoint, and response shape differ:
+
+- **`AcmeAccessService`** — identical to `CngAccessService`: validates the same
+  four config fields (`installId`, `jwtSecret`, `issuer`, `appId`; no
+  `gatewayKey`), builds the shared `TokenManager` + a `RestClient`, defaults to
+  the app-registry base URL, and exposes `getProductService()` +
+  `getAllActivities()`.
+- **`RestClient`** (`src/internal/acme/rest-client.ts`) — the CNG REST client
+  cloned with `extendableSlug = acme_backoffice_api@v1` (note the `@v1`
+  separator, unlike CNG's `-v1`), logging `"Making ACME request"` and throwing
+  `AcmeApiError` on non-2xx.
+- **Products triad** (`src/internal/acme/products/`) — `product-queries.ts`
+  (raw `TemplateNode`/`TemplatesResponse` for the `{ list: [...] }` envelope,
+  plus the `PUBLISHED_REVIEW_STATE` constant, internal), `product-converter.ts`
+  (pure `fromTemplateNodes` → `AcmeActivity`, **filtering to published
+  templates only** and mapping `colorCategory.backgroundColor` → `color`),
+  `product-service.ts` (`AcmeProductService.getAllActivities()`, tolerating a
+  `{ list: [...] }` envelope or a bare array). Endpoint segments live in
+  `src/internal/acme/endpoints.ts` — the template-names path
+  `v2/b2b/event/templates/names?pageSize=-1&page=1`.
+- **Model** `src/models/acme/product.ts` — `AcmeActivity`/`AcmeActivityTicket`,
+  mirroring the CNG `Activity` shape. ACME exposes no tickets today, so
+  `tickets` is always empty; only `id`/`name`/`color` are populated.
+- **Public exports:** `AcmeAccessService` + `AcmeAccessServiceConfig`,
+  `AcmeProductService`, the `AcmeActivity`/`AcmeActivityTicket` types, and
+  `AcmeApiError` (added to the errors export). Distinct type names avoid the
+  collision with CNG's `Activity`. REST paths and raw response interfaces stay
+  internal.
+
 ### 6. UI components — the `./ui` subpath
 `src/ui/`
 

package.json

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

src/acme-access-service.ts

@@ -0,0 +1,95 @@
+/**
+ * Authenticated root entry point to the ACME backoffice REST gateway.
+ *
+ * The ACME sibling of {@link PeekAccessService} / {@link CngAccessService}.
+ * Configure one instance per install; it owns the shared, authenticated
+ * transport (minting/caching tokens on demand) and hands out the
+ * {@link AcmeProductService}.
+ *
+ * Auth and transport mirror the CNG 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 (`acme_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 { ACME_EXTENDABLE_SLUG } from "./internal/acme/endpoints.js";
+import { AcmeProductService } from "./internal/acme/products/product-service.js";
+import { RestClient } from "./internal/acme/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 an {@link AcmeAccessService} instance. ACME adds no fields
+ * beyond {@link BaseAccessServiceConfig} — it authenticates on the app JWT
+ * alone (no `pk-api-key`, so no `gatewayKey`).
+ */
+export type AcmeAccessServiceConfig = BaseAccessServiceConfig;
+
+/**
+ * Authenticated root entry point to the ACME backoffice REST gateway.
+ *
+ * @example
+ * ```ts
+ * import { AcmeAccessService, type AcmeActivity } from "@peektravel/app-utilities";
+ *
+ * const acme = new AcmeAccessService({
+ *   installId: "install-123",
+ *   jwtSecret: process.env.PEEK_APP_SECRET!,
+ *   issuer: process.env.PEEK_APP_ID!,
+ *   appId: process.env.PEEK_APP_ID!,
+ * });
+ *
+ * const activities: AcmeActivity[] = await acme.getAllActivities();
+ * ```
+ *
+ * @throws {Error} from the constructor when any required config field
+ * (`installId`, `jwtSecret`, `issuer`, `appId`) is empty.
+ */
+export class AcmeAccessService {
+  private readonly client: RestClient;
+  private productService?: AcmeProductService;
+
+  constructor(config: AcmeAccessServiceConfig) {
+    requireNonEmpty(config.installId, "installId", "AcmeAccessService");
+    requireNonEmpty(config.jwtSecret, "jwtSecret", "AcmeAccessService");
+    requireNonEmpty(config.issuer, "issuer", "AcmeAccessService");
+    requireNonEmpty(config.appId, "appId", "AcmeAccessService");
+
+    const logger = config.logger ?? noopLogger;
+    const tokens = createTokenManager(config);
+
+    this.client = new RestClient({
+      baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+      appId: config.appId,
+      extendableSlug: ACME_EXTENDABLE_SLUG,
+      getToken: () => tokens.getToken(),
+      retryDelaysMs: config.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
+      logger,
+      fetchFn: config.fetch ?? globalThis.fetch,
+    });
+  }
+
+  /**
+   * Returns the {@link AcmeProductService} for this install, bound to the shared
+   * authenticated transport. The instance is created lazily and reused.
+   */
+  getProductService(): AcmeProductService {
+    if (!this.productService) {
+      this.productService = new AcmeProductService(this.client);
+    }
+    return this.productService;
+  }
+
+  /** All activities. Delegates to {@link AcmeProductService.getAllActivities}. */
+  getAllActivities() {
+    return this.getProductService().getAllActivities();
+  }
+}

src/errors.ts

@@ -3,8 +3,9 @@
  * 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.
+ * `AdminAccountRequiredError` and `RateLimitError` are shared by all gateways.
+ * `PeekGraphQLError` is Peek-only; `CngApiError` is CNG-only; `AcmeApiError` is
+ * ACME-only.
  */
 
 /**
@@ -69,3 +70,24 @@ export class CngApiError extends Error {
     this.body = body;
   }
 }
+
+/**
+ * Thrown when the ACME 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 AcmeApiError.statusCode}, and the raw response body
+ * (parsed JSON when possible, otherwise the raw text) on
+ * {@link AcmeApiError.body}.
+ */
+export class AcmeApiError 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 ?? `ACME request failed with HTTP ${statusCode}`);
+    this.name = "AcmeApiError";
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}

src/index.ts

@@ -14,6 +14,12 @@ export type { CngAccessServiceConfig } from "./cng-access-service.js";
 export { CngProductService } from "./internal/cng/products/product-service.js";
 export type { Activity, ActivityTicket } from "./models/cng/product.js";
 
+// ─── ACME (REST) — sibling accessor sharing this package's auth/transport/UI ─
+export { AcmeAccessService } from "./acme-access-service.js";
+export type { AcmeAccessServiceConfig } from "./acme-access-service.js";
+export { AcmeProductService } from "./internal/acme/products/product-service.js";
+export type { AcmeActivity, AcmeActivityTicket } from "./models/acme/product.js";
+
 export { ProductService } from "./internal/peek/products/product-service.js";
 export type { ProductServiceOptions } from "./internal/peek/products/product-service.js";
 
@@ -131,6 +137,7 @@ export { noopLogger } from "./logger.js";
 export type { Logger } from "./logger.js";
 
 export {
+  AcmeApiError,
   AdminAccountRequiredError,
   CngApiError,
   PeekGraphQLError,

src/internal/acme/endpoints.ts

@@ -0,0 +1,15 @@
+/**
+ * Path segments for the ACME backoffice REST gateway. Shared across the ACME
+ * resources so each value lives in exactly one place. (The CNG gateway segments
+ * live separately in `../cng/endpoints.ts`.)
+ */
+
+/**
+ * Fixed extendable slug inserted between `appId` and the REST path. This is the
+ * only routing difference from the other gateways (CNG uses
+ * `cng_backoffice_api-v1`; note ACME's `@v1` separator).
+ */
+export const ACME_EXTENDABLE_SLUG = "acme_backoffice_api@v1";
+
+/** REST path (relative to the extendable) for the event-template names list. */
+export const TEMPLATES_PATH = "v2/b2b/event/templates/names?pageSize=-1&page=1";

src/internal/acme/products/product-converter.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure functions that map raw ACME template nodes into the clean
+ * {@link AcmeActivity} model. No I/O — straightforward, testable
+ * transformations.
+ *
+ * Only `"published"` templates are surfaced; ACME does not expose tickets, so
+ * every activity carries an empty `tickets` list.
+ */
+import { ACME_ACTIVITY_TYPE, type AcmeActivity } from "../../../models/acme/product.js";
+import { PUBLISHED_REVIEW_STATE, type TemplateNode } from "./product-queries.js";
+
+/**
+ * Converts a list of raw template nodes into {@link AcmeActivity}s, keeping only
+ * published templates.
+ */
+export function fromTemplateNodes(nodes: TemplateNode[]): AcmeActivity[] {
+  return nodes
+    .filter((node) => node.reviewState === PUBLISHED_REVIEW_STATE)
+    .map(fromTemplateNode);
+}
+
+/** Converts a single raw template node into an {@link AcmeActivity}. */
+function fromTemplateNode(node: TemplateNode): AcmeActivity {
+  return {
+    productId: node.id || "",
+    name: node.name || "",
+    type: node.type || ACME_ACTIVITY_TYPE,
+    color: node.colorCategory?.backgroundColor || "#d1d1d1",
+    tickets: [],
+  };
+}

src/internal/acme/products/product-queries.ts

@@ -0,0 +1,39 @@
+/**
+ * Raw ACME REST response shapes for event templates. Internal implementation
+ * detail of the package — deliberately not re-exported from the public entry
+ * point.
+ *
+ * The `v2/b2b/event/templates/names` endpoint returns a `{ list: [...] }`
+ * envelope. Each node carries a `reviewState`; only `"published"` templates are
+ * surfaced as activities (see the converter).
+ */
+
+/** The published review state — the only templates surfaced as activities. */
+export const PUBLISHED_REVIEW_STATE = "published";
+
+/** A single template node as returned by the templates/names endpoint. */
+export interface TemplateNode {
+  /** Stable template id. */
+  id: string;
+  /** Display name. */
+  name: string;
+  /** Template type (e.g. `"standard"`). */
+  type?: string;
+  /** Admission type (e.g. `"standard"`). */
+  admissionType?: string;
+  /** Publication state; only `"published"` templates are surfaced. */
+  reviewState?: string;
+  /** Display color pair, if set. */
+  colorCategory?: {
+    backgroundColor?: string | null;
+    textColor?: string | null;
+  } | null;
+}
+
+/**
+ * The templates list payload. Tolerates either a top-level `list` array or a
+ * bare array response.
+ */
+export interface TemplatesResponse {
+  list?: TemplateNode[];
+}

src/internal/acme/products/product-service.ts

@@ -0,0 +1,35 @@
+/**
+ * Product-related operations against the ACME gateway.
+ *
+ * Obtain an instance via {@link AcmeAccessService.getProductService} rather than
+ * constructing it directly — the access service wires in the authenticated,
+ * shared transport. This class is where ACME product-specific business logic
+ * lives. Named `AcmeProductService` to disambiguate from the Peek
+ * `ProductService` and the CNG `CngProductService` in the same package.
+ */
+import { TEMPLATES_PATH } from "../endpoints.js";
+import type { RestClient } from "../rest-client.js";
+import type { AcmeActivity } from "../../../models/acme/product.js";
+import { fromTemplateNodes } from "./product-converter.js";
+import type { TemplatesResponse } from "./product-queries.js";
+
+export class AcmeProductService {
+  constructor(private readonly client: RestClient) {}
+
+  /**
+   * Returns every published event template as a single flat list of activities.
+   *
+   * @example
+   * ```ts
+   * const activities = await acme.getProductService().getAllActivities();
+   * ```
+   */
+  async getAllActivities(): Promise<AcmeActivity[]> {
+    const body = await this.client.get<TemplatesResponse | TemplatesResponse["list"]>(
+      TEMPLATES_PATH,
+    );
+    // Tolerate either a { list: [...] } envelope or a bare array.
+    const nodes = Array.isArray(body) ? body : (body?.list ?? []);
+    return fromTemplateNodes(nodes ?? []);
+  }
+}