@peektravel/app-utilities 0.9.4 → 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

@@ -2496,6 +2496,123 @@ function buildCancellation(items, addonOptionId, quantity) {
   return { bookingQuotes, canceledCount };
 }
 
+// src/internal/peek/custom-questions/custom-question-converter.ts
+function fromQuestionConfigurations(configs) {
+  return configs.map(
+    (config) => fromQuestionNode(config.question, config.order, config.isRequired)
+  );
+}
+function fromQuestionNodes(questions) {
+  return questions.map((question) => fromQuestionNode(question));
+}
+function fromQuestionNode(question, order, isRequired) {
+  return {
+    id: question.id,
+    order: order ?? 0,
+    isRequired: isRequired ?? false,
+    questionText: question.text,
+    hintText: question.hint ?? null,
+    questionType: question.questionType,
+    internalLabel: question.internalLabel ?? null,
+    perGuest: question.perGuest ?? false,
+    defaultValue: question.answerDefaultValue ?? null,
+    options: (question.options ?? []).map(fromQuestionOption)
+  };
+}
+function fromQuestionOption(option) {
+  return {
+    id: option.id,
+    order: option.order,
+    value: option.text
+  };
+}
+
+// src/internal/peek/custom-questions/custom-question-queries.ts
+var ALL_CUSTOM_QUESTIONS_QUERY = `
+  query Sales {
+    questions {
+      id
+      questionType
+      text
+      answerDefaultValue
+      hint
+      internalLabel
+      perGuest
+      ... on ChoiceQuestion {
+        options {
+          id
+          text
+          order
+        }
+      }
+    }
+  }
+`;
+var CUSTOM_QUESTIONS_QUERY = `
+  query Sales($id: ID!) {
+    activity(id: $id) {
+      id
+      name
+      questionActivityConfigurations {
+        isRequired
+        order
+        question {
+          id
+          questionType
+          text
+          answerDefaultValue
+          hint
+          internalLabel
+          perGuest
+          ... on ChoiceQuestion {
+            options {
+              id
+              text
+              order
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+// src/internal/peek/custom-questions/custom-question-service.ts
+var CustomQuestionService = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Returns every custom question defined on the account, across all
+   * activities. Choice-style questions (`SELECT_ONE`, `LOCATION`, …) carry their
+   * selectable {@link CustomQuestion.options}; free-text/checkbox questions
+   * return an empty option list.
+   *
+   * These are account-wide question **definitions**, not customer answers — no
+   * PII is involved, so the result is unaffected by `fullCustomerAccess`. Unlike
+   * {@link ProductService.getCustomQuestions}, the catalog carries no
+   * per-activity configuration, so {@link CustomQuestion.order} is `0` and
+   * {@link CustomQuestion.isRequired} is `false` on every entry.
+   *
+   * @returns Every custom question on the account, or an empty list when none
+   *   are defined.
+   *
+   * @example
+   * ```ts
+   * const questions = await peek.getCustomQuestionService().getAll();
+   * ```
+   */
+  async getAll() {
+    const body = await this.client.request(
+      SALES_ENDPOINT,
+      ALL_CUSTOM_QUESTIONS_QUERY,
+      {}
+    );
+    return fromQuestionNodes(body.data?.questions ?? []);
+  }
+};
+
 // src/internal/peek/daily-notes/daily-note-converter.ts
 function toDailyNote(response) {
   const union = response?.dailyNote;
@@ -2674,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.4";
+var SDK_VERSION = "1.0.0";
 var SDK_HEADER_VALUE = `${SDK_PLATFORM}-${SDK_VERSION}`;
 
 // src/internal/peek/graphql-client.ts
@@ -3700,33 +3817,6 @@ function fromItemOptionNodes(nodes) {
   return Array.from(grouped.values());
 }
 
-// src/internal/peek/products/custom-question-converter.ts
-function fromQuestionConfigurations(configs) {
-  return configs.map(fromQuestionConfiguration);
-}
-function fromQuestionConfiguration(config) {
-  const question = config.question;
-  return {
-    id: question.id,
-    order: config.order ?? 0,
-    isRequired: config.isRequired ?? false,
-    questionText: question.text,
-    hintText: question.hint ?? null,
-    questionType: question.questionType,
-    internalLabel: question.internalLabel ?? null,
-    perGuest: question.perGuest ?? false,
-    defaultValue: question.answerDefaultValue ?? null,
-    options: (question.options ?? []).map(fromQuestionOption)
-  };
-}
-function fromQuestionOption(option) {
-  return {
-    id: option.id,
-    order: option.order,
-    value: option.text
-  };
-}
-
 // src/internal/peek/products/product-queries.ts
 var PRODUCTS_QUERY = `
   query Sales {
@@ -3785,36 +3875,6 @@ var ITEM_OPTIONS_QUERY = `
   }
 `;
 
-// src/internal/peek/products/custom-question-queries.ts
-var CUSTOM_QUESTIONS_QUERY = `
-  query Sales($id: ID!) {
-    activity(id: $id) {
-      id
-      name
-      questionActivityConfigurations {
-        isRequired
-        order
-        question {
-          id
-          questionType
-          text
-          answerDefaultValue
-          hint
-          internalLabel
-          perGuest
-          ... on ChoiceQuestion {
-            options {
-              id
-              text
-              order
-            }
-          }
-        }
-      }
-    }
-  }
-`;
-
 // src/internal/peek/products/product-service.ts
 var ERROR_PRODUCT_ID_REQUIRED2 = "A non-empty product id is required.";
 var DEFAULT_ITEM_OPTIONS_PAGE_SIZE = 50;
@@ -4374,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;
@@ -4393,21 +4455,27 @@ var PeekAccessService = class {
   membershipService;
   bookingServices = /* @__PURE__ */ new Map();
   reviewService;
+  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),
@@ -4593,6 +4661,16 @@ var PeekAccessService = class {
     }
     return this.reviewService;
   }
+  /**
+   * Returns the {@link CustomQuestionService} for this install, bound to the
+   * shared authenticated transport. The instance is created lazily and reused.
+   */
+  getCustomQuestionService() {
+    if (!this.customQuestionService) {
+      this.customQuestionService = new CustomQuestionService(this.client);
+    }
+    return this.customQuestionService;
+  }
   // ─── Product short-forms ─────────────────────────────────────────────────
   /** All products (activities + add-ons). @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link ProductService.getAllProducts}. */
   getAllProducts() {
@@ -5062,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);
@@ -5242,6 +5325,7 @@ exports.CngAccessService = CngAccessService;
 exports.CngApiError = CngApiError;
 exports.CngPermissionError = CngPermissionError;
 exports.CngProductService = CngProductService;
+exports.CustomQuestionService = CustomQuestionService;
 exports.DailyNoteService = DailyNoteService;
 exports.INSTALL_STATUSES = INSTALL_STATUSES;
 exports.MembershipService = MembershipService;