@peektravel/app-utilities 0.9.5 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -2011,6 +2011,15 @@ interface BaseAccessServiceConfig {
2011
2011
  * way to target an install — prefer it over `baseUrl`/`appId`, which are
2012
2012
  * deprecated (the hardcoded base-URL fallbacks will be removed and a URL will
2013
2013
  * become required in a future release).
2014
+ *
2015
+ * For Peek `mode: "v2"` this field is **required** (the constructor throws
2016
+ * without it). If you do not yet have a webhook `apiUrl` — e.g. an install that
2017
+ * predates webhook `apiUrl` delivery, which you don't want to uninstall /
2018
+ * reinstall just to obtain one — build one by appending your **app slug** to
2019
+ * the registry prefix and pass that here:
2020
+ * `https://apps.peek.com/installations-api/<app-slug>` (the trailing app-slug
2021
+ * segment is required — the prefix alone is not a valid URL). Treat that as a
2022
+ * transitional bridge and prefer the `apiUrl` the install webhook delivers.
2014
2023
  */
2015
2024
  apiUrl?: string;
2016
2025
  /**
@@ -2409,15 +2418,35 @@ interface InstallWebhookClaims {
2409
2418
  * Peek-specific extras below.
2410
2419
  */
2411
2420
  interface PeekAccessServiceConfig extends BaseAccessServiceConfig {
2412
- /** API gateway key, sent as the `pk-api-key` header. Required in v1 mode; not used in v2. */
2413
- gatewayKey?: string;
2414
2421
  /**
2415
- * Gateway mode. `"v2"` routes through the app-registry installations API
2416
- * (`baseUrl/appId/peek_backoffice_api-v1/endpointName`) and defaults to the
2417
- * app-registry sandbox base URL. `"v1"` (default) uses the standard backoffice
2418
- * GraphQL gateway.
2422
+ * API gateway key, sent as the `pk-api-key` header. Required in `"v1"` mode
2423
+ * (unless an `apiUrl` is supplied); not used in `"v2"`.
2419
2424
  */
2420
- mode?: "v2";
2425
+ gatewayKey?: string;
2426
+ /**
2427
+ * Which connection generation to use. **Required — choose explicitly.**
2428
+ *
2429
+ * This field used to be optional, and omitting it meant `"v1"`. It is now
2430
+ * mandatory so that updating the package forces a deliberate choice instead of
2431
+ * silently keeping the old behaviour. If your install used the previous
2432
+ * default, the fastest no-behaviour-change update is to pass `mode: "v1"`.
2433
+ *
2434
+ * - `"v2"` — **use this going forward.** Routes through the app-registry
2435
+ * installations API. It **requires** the install's **`apiUrl`**: the
2436
+ * per-install base URL delivered on the install webhook (`api.url`), which you
2437
+ * persist and pass as `apiUrl`. The constructor throws if it is missing —
2438
+ * there is no silent default. If you do not have a webhook `apiUrl` yet, build
2439
+ * one by appending your **app slug** to the registry prefix and pass that
2440
+ * yourself — `https://apps.peek.com/installations-api/<app-slug>` (same shape
2441
+ * as the webhook's `api.url`; the trailing app-slug segment is required, the
2442
+ * prefix alone is not a valid URL). Treat it as a transitional bridge and
2443
+ * prefer the webhook URL. No `gatewayKey` is needed (the registry
2444
+ * authenticates on the JWT alone).
2445
+ * - `"v1"` — **deprecated; will be removed.** The legacy backoffice GraphQL
2446
+ * gateway; requires `gatewayKey`. Retained only so existing installs can
2447
+ * update with no immediate behaviour change. Migrate to `"v2"`.
2448
+ */
2449
+ mode: "v1" | "v2";
2421
2450
  /** Page size for cursor-paginated item options. Default: 50. */
2422
2451
  itemOptionsPageSize?: number;
2423
2452
  }
@@ -2433,20 +2462,28 @@ interface PeekAccessServiceConfig extends BaseAccessServiceConfig {
2433
2462
  * ```ts
2434
2463
  * import { PeekAccessService, type Product } from "@peektravel/app-utilities";
2435
2464
  *
2465
+ * // "v2" (recommended) — registry connection, targeted by the install
2466
+ * // webhook's apiUrl; no gatewayKey needed:
2436
2467
  * const peek = new PeekAccessService({
2437
2468
  * installId: "install-123", // JWT subject
2438
2469
  * jwtSecret: process.env.PEEK_INTERNAL_SECRET!, // signs the JWT
2439
2470
  * issuer: process.env.APP_NAME!, // JWT issuer
2440
- * appId: process.env.PEEK_APP_ID!, // gateway path segment
2441
- * gatewayKey: process.env.PEEK_GATEWAY_KEY!, // pk-api-key header
2471
+ * mode: "v2", // connection generation (required)
2472
+ * apiUrl: install.apiUrl, // persisted from the install webhook
2442
2473
  * });
2443
2474
  *
2475
+ * // "v1" (deprecated) — legacy gateway; the fastest update for installs that
2476
+ * // relied on the old default:
2477
+ * // new PeekAccessService({ installId, jwtSecret, issuer, appId, gatewayKey, mode: "v1" })
2478
+ *
2444
2479
  * const products: Product[] = await peek.getProductService().getAllProducts();
2445
2480
  * const booking = await peek.getBookingService().getById("b_abc123");
2446
2481
  * ```
2447
2482
  *
2448
- * @throws {Error} from the constructor when any required config field
2449
- * (`installId`, `jwtSecret`, `issuer`, `appId`, `gatewayKey`) is empty.
2483
+ * @throws {Error} from the constructor when `mode` is missing or not `"v1"`/
2484
+ * `"v2"`; when `"v2"` is selected without an `apiUrl`; or when any required
2485
+ * config field is empty (`installId`, `jwtSecret`, `issuer`, and — in `"v1"`
2486
+ * mode without an `apiUrl` — `appId` and `gatewayKey`).
2450
2487
  */
2451
2488
  declare class PeekAccessService {
2452
2489
  private readonly client;
package/dist/index.d.ts CHANGED
@@ -2011,6 +2011,15 @@ interface BaseAccessServiceConfig {
2011
2011
  * way to target an install — prefer it over `baseUrl`/`appId`, which are
2012
2012
  * deprecated (the hardcoded base-URL fallbacks will be removed and a URL will
2013
2013
  * become required in a future release).
2014
+ *
2015
+ * For Peek `mode: "v2"` this field is **required** (the constructor throws
2016
+ * without it). If you do not yet have a webhook `apiUrl` — e.g. an install that
2017
+ * predates webhook `apiUrl` delivery, which you don't want to uninstall /
2018
+ * reinstall just to obtain one — build one by appending your **app slug** to
2019
+ * the registry prefix and pass that here:
2020
+ * `https://apps.peek.com/installations-api/<app-slug>` (the trailing app-slug
2021
+ * segment is required — the prefix alone is not a valid URL). Treat that as a
2022
+ * transitional bridge and prefer the `apiUrl` the install webhook delivers.
2014
2023
  */
2015
2024
  apiUrl?: string;
2016
2025
  /**
@@ -2409,15 +2418,35 @@ interface InstallWebhookClaims {
2409
2418
  * Peek-specific extras below.
2410
2419
  */
2411
2420
  interface PeekAccessServiceConfig extends BaseAccessServiceConfig {
2412
- /** API gateway key, sent as the `pk-api-key` header. Required in v1 mode; not used in v2. */
2413
- gatewayKey?: string;
2414
2421
  /**
2415
- * Gateway mode. `"v2"` routes through the app-registry installations API
2416
- * (`baseUrl/appId/peek_backoffice_api-v1/endpointName`) and defaults to the
2417
- * app-registry sandbox base URL. `"v1"` (default) uses the standard backoffice
2418
- * GraphQL gateway.
2422
+ * API gateway key, sent as the `pk-api-key` header. Required in `"v1"` mode
2423
+ * (unless an `apiUrl` is supplied); not used in `"v2"`.
2419
2424
  */
2420
- mode?: "v2";
2425
+ gatewayKey?: string;
2426
+ /**
2427
+ * Which connection generation to use. **Required — choose explicitly.**
2428
+ *
2429
+ * This field used to be optional, and omitting it meant `"v1"`. It is now
2430
+ * mandatory so that updating the package forces a deliberate choice instead of
2431
+ * silently keeping the old behaviour. If your install used the previous
2432
+ * default, the fastest no-behaviour-change update is to pass `mode: "v1"`.
2433
+ *
2434
+ * - `"v2"` — **use this going forward.** Routes through the app-registry
2435
+ * installations API. It **requires** the install's **`apiUrl`**: the
2436
+ * per-install base URL delivered on the install webhook (`api.url`), which you
2437
+ * persist and pass as `apiUrl`. The constructor throws if it is missing —
2438
+ * there is no silent default. If you do not have a webhook `apiUrl` yet, build
2439
+ * one by appending your **app slug** to the registry prefix and pass that
2440
+ * yourself — `https://apps.peek.com/installations-api/<app-slug>` (same shape
2441
+ * as the webhook's `api.url`; the trailing app-slug segment is required, the
2442
+ * prefix alone is not a valid URL). Treat it as a transitional bridge and
2443
+ * prefer the webhook URL. No `gatewayKey` is needed (the registry
2444
+ * authenticates on the JWT alone).
2445
+ * - `"v1"` — **deprecated; will be removed.** The legacy backoffice GraphQL
2446
+ * gateway; requires `gatewayKey`. Retained only so existing installs can
2447
+ * update with no immediate behaviour change. Migrate to `"v2"`.
2448
+ */
2449
+ mode: "v1" | "v2";
2421
2450
  /** Page size for cursor-paginated item options. Default: 50. */
2422
2451
  itemOptionsPageSize?: number;
2423
2452
  }
@@ -2433,20 +2462,28 @@ interface PeekAccessServiceConfig extends BaseAccessServiceConfig {
2433
2462
  * ```ts
2434
2463
  * import { PeekAccessService, type Product } from "@peektravel/app-utilities";
2435
2464
  *
2465
+ * // "v2" (recommended) — registry connection, targeted by the install
2466
+ * // webhook's apiUrl; no gatewayKey needed:
2436
2467
  * const peek = new PeekAccessService({
2437
2468
  * installId: "install-123", // JWT subject
2438
2469
  * jwtSecret: process.env.PEEK_INTERNAL_SECRET!, // signs the JWT
2439
2470
  * issuer: process.env.APP_NAME!, // JWT issuer
2440
- * appId: process.env.PEEK_APP_ID!, // gateway path segment
2441
- * gatewayKey: process.env.PEEK_GATEWAY_KEY!, // pk-api-key header
2471
+ * mode: "v2", // connection generation (required)
2472
+ * apiUrl: install.apiUrl, // persisted from the install webhook
2442
2473
  * });
2443
2474
  *
2475
+ * // "v1" (deprecated) — legacy gateway; the fastest update for installs that
2476
+ * // relied on the old default:
2477
+ * // new PeekAccessService({ installId, jwtSecret, issuer, appId, gatewayKey, mode: "v1" })
2478
+ *
2444
2479
  * const products: Product[] = await peek.getProductService().getAllProducts();
2445
2480
  * const booking = await peek.getBookingService().getById("b_abc123");
2446
2481
  * ```
2447
2482
  *
2448
- * @throws {Error} from the constructor when any required config field
2449
- * (`installId`, `jwtSecret`, `issuer`, `appId`, `gatewayKey`) is empty.
2483
+ * @throws {Error} from the constructor when `mode` is missing or not `"v1"`/
2484
+ * `"v2"`; when `"v2"` is selected without an `apiUrl`; or when any required
2485
+ * config field is empty (`installId`, `jwtSecret`, `issuer`, and — in `"v1"`
2486
+ * mode without an `apiUrl` — `appId` and `gatewayKey`).
2450
2487
  */
2451
2488
  declare class PeekAccessService {
2452
2489
  private readonly client;
package/dist/index.js CHANGED
@@ -2769,7 +2769,7 @@ async function requestWithRetry(http, url, init, label, onResponse) {
2769
2769
  // src/internal/sdk-headers.ts
2770
2770
  var SDK_HEADER_NAME = "x-peek-sdk";
2771
2771
  var SDK_PLATFORM = "js";
2772
- var SDK_VERSION = "0.9.5";
2772
+ var SDK_VERSION = "1.0.0";
2773
2773
  var SDK_HEADER_VALUE = `${SDK_PLATFORM}-${SDK_VERSION}`;
2774
2774
 
2775
2775
  // src/internal/peek/graphql-client.ts
@@ -4412,7 +4412,9 @@ var noopLogger = {
4412
4412
 
4413
4413
  // src/peek-access-service.ts
4414
4414
  var DEFAULT_BASE_URL = "https://apps.peekapis.com/backoffice-gql";
4415
- var DEFAULT_V2_BASE_URL = "https://app-registry.peeklabs.com/installations-api";
4415
+ var V2_FALLBACK_URL_PREFIX = "https://apps.peek.com/installations-api";
4416
+ var ERROR_MODE_REQUIRED = `PeekAccessService: "mode" is required and must be "v1" or "v2". Existing installs used the previous default of "v1" \u2014 pass mode: "v1" for the fastest update. Note: "v1" is deprecated and will be removed; migrate to "v2" and pass the install webhook's apiUrl.`;
4417
+ var ERROR_V2_API_URL_REQUIRED = `PeekAccessService: mode "v2" requires an "apiUrl" \u2014 the per-install URL delivered on the install webhook (api.url) and persisted per install. If you do not have one yet, append your app slug to the registry prefix and pass that, e.g. "${V2_FALLBACK_URL_PREFIX}/<app-slug>" (the trailing app-slug segment is required \u2014 the prefix alone is not a valid apiUrl).`;
4416
4418
  var PeekAccessService = class {
4417
4419
  client;
4418
4420
  productServiceOptions;
@@ -4434,19 +4436,24 @@ var PeekAccessService = class {
4434
4436
  customQuestionService;
4435
4437
  constructor(config) {
4436
4438
  const hasApiUrl = !!config.apiUrl;
4439
+ if (config.mode !== "v1" && config.mode !== "v2") {
4440
+ throw new Error(ERROR_MODE_REQUIRED);
4441
+ }
4437
4442
  const isV2 = config.mode === "v2";
4438
4443
  requireNonEmpty(config.installId, "installId", "PeekAccessService");
4439
4444
  requireNonEmpty(config.jwtSecret, "jwtSecret", "PeekAccessService");
4440
4445
  requireNonEmpty(config.issuer, "issuer", "PeekAccessService");
4441
- if (!hasApiUrl) requireNonEmpty(config.appId ?? "", "appId", "PeekAccessService");
4442
- if (!hasApiUrl && !isV2) requireNonEmpty(config.gatewayKey ?? "", "gatewayKey", "PeekAccessService");
4446
+ if (isV2 && !hasApiUrl) throw new Error(ERROR_V2_API_URL_REQUIRED);
4447
+ if (!isV2 && !hasApiUrl) {
4448
+ requireNonEmpty(config.appId ?? "", "appId", "PeekAccessService");
4449
+ requireNonEmpty(config.gatewayKey ?? "", "gatewayKey", "PeekAccessService");
4450
+ }
4443
4451
  this.jwtSecret = config.jwtSecret;
4444
4452
  this.issuer = config.issuer;
4445
4453
  const logger = config.logger ?? noopLogger;
4446
4454
  const tokens = createTokenManager(config);
4447
- const useRegistrySlug = hasApiUrl || isV2;
4448
- const defaultBaseUrl = isV2 ? DEFAULT_V2_BASE_URL : DEFAULT_BASE_URL;
4449
- const baseApiUrl = hasApiUrl ? resolveBaseApiUrl(config.apiUrl, V2_EXTENDABLE_SLUG, "PeekAccessService") : `${config.baseUrl ?? defaultBaseUrl}/${config.appId}`;
4455
+ const useRegistrySlug = hasApiUrl;
4456
+ const baseApiUrl = hasApiUrl ? resolveBaseApiUrl(config.apiUrl, V2_EXTENDABLE_SLUG, "PeekAccessService") : `${config.baseUrl ?? DEFAULT_BASE_URL}/${config.appId}`;
4450
4457
  this.client = new GraphQLClient({
4451
4458
  baseApiUrl,
4452
4459
  endpoints: peekApiEndpoints(useRegistrySlug),
@@ -5111,7 +5118,12 @@ var AcmeAccessService = class {
5111
5118
 
5112
5119
  // src/access-service-factory.ts
5113
5120
  function createAccessServiceForInstall(install, config) {
5114
- const shared = { ...config, installId: install.installId, apiUrl: install.apiUrl };
5121
+ const shared = {
5122
+ ...config,
5123
+ installId: install.installId,
5124
+ apiUrl: install.apiUrl,
5125
+ mode: "v2"
5126
+ };
5115
5127
  switch (install.platform) {
5116
5128
  case "peek":
5117
5129
  return new PeekAccessService(shared);