Merge pull request #8 from peek-travel/feature/v2

feat: support v2 registry api calls

Author: coladarci

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: ['**']
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test (with coverage gate)
+        run: npm run test:coverage

docs/internal/ARCHITECTURE.md

@@ -49,9 +49,15 @@ call typed methods like `peek.getProductService().getAllProducts()`.
     guide resolution).
   - `BookingService` receives the product service (for add-on → parent-item
     resolution).
-- Optional config: `baseUrl`, `tokenTtlSeconds` (3600), `tokenRefreshLeewaySeconds`
+- Optional config: `mode` (`"v2"` — see below), `baseUrl`, `tokenTtlSeconds` (3600), `tokenRefreshLeewaySeconds`
   (60), `retryDelaysMs` (`[1000, 2000, 4000]`), `logger` (no-op default),
   `fetch` (global default), `itemOptionsPageSize` (50).
+- **v2 mode** (`mode: "v2"`): routes requests through the app-registry
+  installations API. The endpoint URL becomes
+  `baseUrl/appId/peek_backoffice_api-v1/endpointName` and the default `baseUrl`
+  switches to `https://app-registry.peeklabs.com/installations-api`.
+  A custom `baseUrl` still overrides the default in v2 mode. All other
+  behaviour (JWT auth, headers, retries, resource services) is unchanged.
 
 ### 2. `TokenManager` — auth
 `src/internal/token-manager.ts`
@@ -65,8 +71,11 @@ call typed methods like `peek.getProductService().getAllProducts()`.
 
 The only place that touches the network. Responsibilities:
 
-- Builds the endpoint URL as `${baseUrl}/${appId}/${endpointName}`. Today every
-  operation routes through the single `sales` endpoint (`gateway-endpoints.ts`).
+- Builds the endpoint URL as `${baseUrl}/${appId}/${endpointName}`, or
+  `${baseUrl}/${appId}/${endpointPathPrefix}/${endpointName}` when an
+  `endpointPathPrefix` is set (v2 mode inserts `peek_backoffice_api-v1`). Today
+  every operation routes through the single `sales` endpoint
+  (`gateway-endpoints.ts`).
 - Sets headers: `X-Peek-Auth: Bearer <jwt>`, `pk-api-key: <gatewayKey>`,
   `Content-Type: application/json`.
 - Collapses query whitespace (`\s+` → single space) before sending.

src/internal/gateway-endpoints.ts

@@ -4,3 +4,6 @@
  * so the value lives in exactly one place.
  */
 export const SALES_ENDPOINT = "sales";
+
+/** Fixed path segment inserted between `appId` and the endpoint name in v2 mode. */
+export const V2_EXTENDABLE_SLUG = "peek_backoffice_api-v1";

src/internal/graphql-client.ts

@@ -24,8 +24,8 @@ export interface GraphQLClientOptions {
   baseUrl: string;
   /** Peek app ID, used in the endpoint path. */
   appId: string;
-  /** API gateway key sent as the `pk-api-key` header. */
-  gatewayKey: string;
+  /** API gateway key sent as the `pk-api-key` header. Omitted from headers when absent (v2 mode). */
+  gatewayKey?: string;
   /** Supplies a valid bearer token for each request. */
   getToken: () => string;
   /** Backoff delays (ms) applied on successive HTTP 429 responses. */
@@ -34,6 +34,11 @@ export interface GraphQLClientOptions {
   logger: Logger;
   /** `fetch` implementation to use. */
   fetchFn: typeof fetch;
+  /**
+   * Optional fixed path segment inserted between `appId` and the endpoint name.
+   * Used in v2 mode: `baseUrl/appId/endpointPathPrefix/endpointName`.
+   */
+  endpointPathPrefix?: string;
 }
 
 const sleep = (ms: number): Promise<void> =>
@@ -106,14 +111,19 @@ export class GraphQLClient {
   }
 
   private endpoint(endpointName: string): string {
-    return `${this.options.baseUrl}/${this.options.appId}/${endpointName}`;
+    const { baseUrl, appId, endpointPathPrefix } = this.options;
+    const prefix = endpointPathPrefix ? `${endpointPathPrefix}/` : "";
+    return `${baseUrl}/${appId}/${prefix}${endpointName}`;
   }
 
   private buildHeaders(): Record<string, string> {
-    return {
+    const headers: Record<string, string> = {
       "X-Peek-Auth": `Bearer ${this.options.getToken()}`,
-      "pk-api-key": this.options.gatewayKey,
       "Content-Type": "application/json",
     };
+    if (this.options.gatewayKey) {
+      headers["pk-api-key"] = this.options.gatewayKey;
+    }
+    return headers;
   }
 }

src/peek-access-service.ts

@@ -22,11 +22,15 @@ import {
   type ProductServiceOptions,
 } from "./internal/products/product-service.js";
 import { PromoCodeService } from "./internal/promo-codes/promo-code-service.js";
+import { V2_EXTENDABLE_SLUG } from "./internal/gateway-endpoints.js";
 import { TokenManager } from "./internal/token-manager.js";
 import { noopLogger, type Logger } from "./logger.js";
 
-/** Default backoffice GraphQL gateway base URL. */
+/** Default backoffice GraphQL gateway base URL (v1). */
 const DEFAULT_BASE_URL = "https://apps.peekapis.com/backoffice-gql";
+/** Default gateway base URL when operating in v2 mode. */
+const DEFAULT_V2_BASE_URL =
+  "https://app-registry.peeklabs.com/installations-api";
 /** Default JWT lifetime (1 hour). */
 const DEFAULT_TOKEN_TTL_SECONDS = 3600;
 /** Default leeway before expiry at which a cached token is re-minted. */
@@ -44,10 +48,17 @@ export interface PeekAccessServiceConfig {
   issuer: string;
   /** Peek app ID, used in the gateway endpoint path. */
   appId: string;
-  /** API gateway key, sent as the `pk-api-key` header. */
-  gatewayKey: string;
+  /** API gateway key, sent as the `pk-api-key` header. Required in v1 mode; not used in v2. */
+  gatewayKey?: string;
 
-  /** Override the gateway base URL. Default: Peek production gateway. */
+  /**
+   * Gateway mode. `"v2"` routes through the app-registry installations API
+   * (`baseUrl/appId/peek_backoffice_api-v1/endpointName`) and defaults to the
+   * app-registry sandbox base URL. `"v1"` (default) uses the standard backoffice
+   * GraphQL gateway.
+   */
+  mode?: "v2";
+  /** Override the gateway base URL. Default: Peek production gateway (v1) or app-registry sandbox (v2). */
   baseUrl?: string;
   /** JWT lifetime in seconds. Default: 3600. */
   tokenTtlSeconds?: number;
@@ -106,11 +117,12 @@ export class PeekAccessService {
   private reviewService?: ReviewService;
 
   constructor(config: PeekAccessServiceConfig) {
+    const isV2 = config.mode === "v2";
     requireNonEmpty(config.installId, "installId");
     requireNonEmpty(config.jwtSecret, "jwtSecret");
     requireNonEmpty(config.issuer, "issuer");
     requireNonEmpty(config.appId, "appId");
-    requireNonEmpty(config.gatewayKey, "gatewayKey");
+    if (!isV2) requireNonEmpty(config.gatewayKey ?? "", "gatewayKey");
 
     const logger = config.logger ?? noopLogger;
     const tokens = new TokenManager({
@@ -119,17 +131,20 @@ export class PeekAccessService {
       installId: config.installId,
       ttlSeconds: config.tokenTtlSeconds ?? DEFAULT_TOKEN_TTL_SECONDS,
       leewaySeconds:
-        config.tokenRefreshLeewaySeconds ?? DEFAULT_TOKEN_REFRESH_LEEWAY_SECONDS,
+        config.tokenRefreshLeewaySeconds ??
+        DEFAULT_TOKEN_REFRESH_LEEWAY_SECONDS,
     });
 
+    const defaultBaseUrl = isV2 ? DEFAULT_V2_BASE_URL : DEFAULT_BASE_URL;
     this.client = new GraphQLClient({
-      baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+      baseUrl: config.baseUrl ?? defaultBaseUrl,
       appId: config.appId,
       gatewayKey: config.gatewayKey,
       getToken: () => tokens.getToken(),
       retryDelaysMs: config.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS,
       logger,
       fetchFn: config.fetch ?? globalThis.fetch,
+      endpointPathPrefix: isV2 ? V2_EXTENDABLE_SLUG : undefined,
     });
 
     this.productServiceOptions = {