@peektravel/app-utilities 0.9.5 → 1.0.0

package/README.md

@@ -34,8 +34,8 @@ const peek = new PeekAccessService({
   installId: 'install-123', // JWT subject
   jwtSecret: process.env.PEEK_INTERNAL_SECRET!, // signs the JWT
   issuer: process.env.APP_NAME!, // JWT issuer
-  appId: process.env.PEEK_APP_ID!, // gateway path segment
-  gatewayKey: process.env.PEEK_GATEWAY_KEY!, // pk-api-key header
+  mode: 'v2', // connection generation — required (see below)
+  apiUrl: install.apiUrl, // per-install base URL from the install webhook (persisted)
 });
 
 const products: Product[] = await peek.getProductService().getAllProducts();
@@ -44,6 +44,41 @@ const products: Product[] = await peek.getProductService().getAllProducts();
 The access service is the authenticated root; each `get<Resource>Service()`
 returns a (memoized) service that owns that resource's calls.
 
+### Connection mode (`v1` / `v2`) — **required**
+
+`mode` is a **mandatory** config field — you must choose a connection generation
+explicitly. (It used to be optional, defaulting to `v1`; it is now required so
+that updating the package forces a deliberate choice instead of silently keeping
+the old behaviour.)
+
+- **`mode: 'v2'`** — **use this going forward.** The app-registry connection. It
+  **requires** the install's `apiUrl` — the per-install base URL delivered on the
+  install webhook (`api.url`); the constructor throws without it. Persist that URL
+  per install (see [Webhooks](#webhooks)) and pass it as `apiUrl`; no `gatewayKey`
+  is needed. If you don't yet have a webhook `apiUrl` (e.g. an older install you
+  don't want to uninstall/reinstall just to get one), build one by appending your
+  **app slug** to the registry prefix and pass that as the `apiUrl` yourself —
+  `https://apps.peek.com/installations-api/<app-slug>` (same shape as the
+  webhook's `api.url`; the trailing app-slug segment is required — the prefix
+  alone is not a valid URL). Treat it as a transitional bridge and move to the
+  webhook URL.
+- **`mode: 'v1'`** — **deprecated; will be removed.** The legacy gateway; needs
+  `appId` + `gatewayKey`. If your install relied on the previous default, the
+  fastest no-behaviour-change update is to pass `mode: 'v1'` — then plan the
+  migration to `v2`.
+
+```ts
+// Legacy v1 (deprecated) — fastest update for an install that used the old default:
+const peek = new PeekAccessService({
+  installId: 'install-123',
+  jwtSecret: process.env.PEEK_INTERNAL_SECRET!,
+  issuer: process.env.APP_NAME!,
+  appId: process.env.PEEK_APP_ID!, // gateway path segment
+  gatewayKey: process.env.PEEK_GATEWAY_KEY!, // pk-api-key header
+  mode: 'v1',
+});
+```
+
 `getAllProducts()` returns a single flat list of activities **and** add-ons
 (add-ons tagged with `ADD_ON_PRODUCT_TYPE`), gathering all cursor-paginated
 add-on pages for you.
@@ -102,7 +137,7 @@ With `fullCustomerAccess` **off** (the default):
 
 ```ts
 const peek = new PeekAccessService({
-  installId, jwtSecret, issuer, appId, gatewayKey,
+  installId, jwtSecret, issuer, mode: 'v2', apiUrl,
   accessOptions: { fullCustomerAccess: true }, // opt into PII + payment operations
 });
 ```

package/dist/index.cjs

@@ -2791,7 +2791,7 @@ async function requestWithRetry(http, url, init, label, onResponse) {
 // src/internal/sdk-headers.ts
 var SDK_HEADER_NAME = "x-peek-sdk";
 var SDK_PLATFORM = "js";
-var SDK_VERSION = "0.9.5";
+var SDK_VERSION = "1.0.0";
 var SDK_HEADER_VALUE = `${SDK_PLATFORM}-${SDK_VERSION}`;
 
 // src/internal/peek/graphql-client.ts
@@ -4434,7 +4434,9 @@ var noopLogger = {
 
 // src/peek-access-service.ts
 var DEFAULT_BASE_URL = "https://apps.peekapis.com/backoffice-gql";
-var DEFAULT_V2_BASE_URL = "https://app-registry.peeklabs.com/installations-api";
+var V2_FALLBACK_URL_PREFIX = "https://apps.peek.com/installations-api";
+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.`;
+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).`;
 var PeekAccessService = class {
   client;
   productServiceOptions;
@@ -4456,19 +4458,24 @@ var PeekAccessService = class {
   customQuestionService;
   constructor(config) {
     const hasApiUrl = !!config.apiUrl;
+    if (config.mode !== "v1" && config.mode !== "v2") {
+      throw new Error(ERROR_MODE_REQUIRED);
+    }
     const isV2 = config.mode === "v2";
     requireNonEmpty(config.installId, "installId", "PeekAccessService");
     requireNonEmpty(config.jwtSecret, "jwtSecret", "PeekAccessService");
     requireNonEmpty(config.issuer, "issuer", "PeekAccessService");
-    if (!hasApiUrl) requireNonEmpty(config.appId ?? "", "appId", "PeekAccessService");
-    if (!hasApiUrl && !isV2) requireNonEmpty(config.gatewayKey ?? "", "gatewayKey", "PeekAccessService");
+    if (isV2 && !hasApiUrl) throw new Error(ERROR_V2_API_URL_REQUIRED);
+    if (!isV2 && !hasApiUrl) {
+      requireNonEmpty(config.appId ?? "", "appId", "PeekAccessService");
+      requireNonEmpty(config.gatewayKey ?? "", "gatewayKey", "PeekAccessService");
+    }
     this.jwtSecret = config.jwtSecret;
     this.issuer = config.issuer;
     const logger = config.logger ?? noopLogger;
     const tokens = createTokenManager(config);
-    const useRegistrySlug = hasApiUrl || isV2;
-    const defaultBaseUrl = isV2 ? DEFAULT_V2_BASE_URL : DEFAULT_BASE_URL;
-    const baseApiUrl = hasApiUrl ? resolveBaseApiUrl(config.apiUrl, V2_EXTENDABLE_SLUG, "PeekAccessService") : `${config.baseUrl ?? defaultBaseUrl}/${config.appId}`;
+    const useRegistrySlug = hasApiUrl;
+    const baseApiUrl = hasApiUrl ? resolveBaseApiUrl(config.apiUrl, V2_EXTENDABLE_SLUG, "PeekAccessService") : `${config.baseUrl ?? DEFAULT_BASE_URL}/${config.appId}`;
     this.client = new GraphQLClient({
       baseApiUrl,
       endpoints: peekApiEndpoints(useRegistrySlug),
@@ -5133,7 +5140,12 @@ var AcmeAccessService = class {
 
 // src/access-service-factory.ts
 function createAccessServiceForInstall(install, config) {
-  const shared = { ...config, installId: install.installId, apiUrl: install.apiUrl };
+  const shared = {
+    ...config,
+    installId: install.installId,
+    apiUrl: install.apiUrl,
+    mode: "v2"
+  };
   switch (install.platform) {
     case "peek":
       return new PeekAccessService(shared);