@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/README.md +38 -3
- package/dist/index.cjs +20 -8
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +48 -11
- package/dist/index.d.ts +48 -11
- package/dist/index.js +20 -8
- package/dist/index.js.map +1 -1
- package/docs/webhooks.md +6 -0
- package/llms.txt +14 -2
- package/package.json +1 -1
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
|
-
*
|
|
2416
|
-
* (`
|
|
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
|
-
|
|
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
|
-
*
|
|
2441
|
-
*
|
|
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
|
|
2449
|
-
*
|
|
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
|
-
*
|
|
2416
|
-
* (`
|
|
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
|
-
|
|
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
|
-
*
|
|
2441
|
-
*
|
|
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
|
|
2449
|
-
*
|
|
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.
|
|
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
|
|
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)
|
|
4442
|
-
if (!
|
|
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
|
|
4448
|
-
const
|
|
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 = {
|
|
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);
|