@peektravel/app-utilities 0.1.6 → 0.2.3

package/dist/index.d.cts

@@ -23,8 +23,8 @@ 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. */
@@ -33,6 +33,11 @@ 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;
 }
 declare class GraphQLClient {
     private readonly options;
@@ -1179,15 +1184,28 @@ declare class PromoCodeService {
     create(input: CreatePromoCodeInput): Promise<CreatedPromoCode>;
 }
 
-/**
- * Authenticated root entry point to the Peek backoffice GraphQL gateway.
- *
- * Configure one instance per install with everything needed to authenticate and
- * reach the gateway. The access service owns the shared, authenticated
- * transport (it mints and caches tokens on demand) and hands out per-resource
- * service objects — e.g. {@link PeekAccessService.getProductService} — that
- * carry the resource-specific business logic.
- */
+/** User context embedded in a Peek auth token. */
+interface PeekAuthTokenUser {
+    /** User's email address. */
+    email: string;
+    /** User's Peek account ID */
+    id: string;
+    /** Whether the user has admin privileges. */
+    isAdmin: boolean;
+    /** User's locale (e.g. `"en"`). */
+    locale: string;
+    /** User's display name. */
+    name: string;
+}
+/** Claims returned by {@link PeekAccessService.verifyPeekAuthToken}. */
+interface PeekAuthTokenClaims {
+    /** Install ID — the JWT subject (`sub`). Peek-assigned UUID. */
+    installId: string;
+    /** App display version at time of issuance. */
+    displayVersion: string;
+    /** Authenticated user context. */
+    user: PeekAuthTokenUser;
+}
 
 /** Configuration for a {@link PeekAccessService} instance. */
 interface PeekAccessServiceConfig {
@@ -1199,9 +1217,16 @@ 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;
-    /** Override the gateway base URL. Default: Peek production gateway. */
+    /** API gateway key, sent as the `pk-api-key` header. Required in v1 mode; not used in v2. */
+    gatewayKey?: string;
+    /**
+     * 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;
@@ -1246,6 +1271,7 @@ interface PeekAccessServiceConfig {
 declare class PeekAccessService {
     private readonly client;
     private readonly productServiceOptions;
+    private readonly jwtSecret;
     private productService?;
     private accountUserService?;
     private resourcePoolService?;
@@ -1258,6 +1284,25 @@ declare class PeekAccessService {
     private bookingService?;
     private reviewService?;
     constructor(config: PeekAccessServiceConfig);
+    /**
+     * Verifies a Peek auth token issued by the app registry and returns the
+     * decoded claims.
+     *
+     * Validates the HMAC signature (using this service's `jwtSecret`), the token
+     * expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience. Throws
+     * from the `jsonwebtoken` library on any failure — callers should catch to
+     * distinguish error kinds:
+     *
+     * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or token
+     *   malformed
+     * - `TokenExpiredError` — past `exp`
+     * - `NotBeforeError` — before `nbf`
+     *
+     * @throws {JsonWebTokenError} signature invalid or token malformed
+     * @throws {TokenExpiredError} token has expired
+     * @throws {NotBeforeError} token not yet valid
+     */
+    verifyPeekAuthToken(token: string): PeekAuthTokenClaims;
     /**
      * Returns the {@link ProductService} for this install, bound to the shared
      * authenticated transport. The instance is created lazily and reused.
@@ -1429,4 +1474,4 @@ declare class PeekGraphQLError extends Error {
     constructor(graphqlErrors: unknown[], message?: string);
 }
 
-export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };
+export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, type PeekAuthTokenClaims, type PeekAuthTokenUser, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };

package/dist/index.d.ts

@@ -23,8 +23,8 @@ 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. */
@@ -33,6 +33,11 @@ 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;
 }
 declare class GraphQLClient {
     private readonly options;
@@ -1179,15 +1184,28 @@ declare class PromoCodeService {
     create(input: CreatePromoCodeInput): Promise<CreatedPromoCode>;
 }
 
-/**
- * Authenticated root entry point to the Peek backoffice GraphQL gateway.
- *
- * Configure one instance per install with everything needed to authenticate and
- * reach the gateway. The access service owns the shared, authenticated
- * transport (it mints and caches tokens on demand) and hands out per-resource
- * service objects — e.g. {@link PeekAccessService.getProductService} — that
- * carry the resource-specific business logic.
- */
+/** User context embedded in a Peek auth token. */
+interface PeekAuthTokenUser {
+    /** User's email address. */
+    email: string;
+    /** User's Peek account ID */
+    id: string;
+    /** Whether the user has admin privileges. */
+    isAdmin: boolean;
+    /** User's locale (e.g. `"en"`). */
+    locale: string;
+    /** User's display name. */
+    name: string;
+}
+/** Claims returned by {@link PeekAccessService.verifyPeekAuthToken}. */
+interface PeekAuthTokenClaims {
+    /** Install ID — the JWT subject (`sub`). Peek-assigned UUID. */
+    installId: string;
+    /** App display version at time of issuance. */
+    displayVersion: string;
+    /** Authenticated user context. */
+    user: PeekAuthTokenUser;
+}
 
 /** Configuration for a {@link PeekAccessService} instance. */
 interface PeekAccessServiceConfig {
@@ -1199,9 +1217,16 @@ 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;
-    /** Override the gateway base URL. Default: Peek production gateway. */
+    /** API gateway key, sent as the `pk-api-key` header. Required in v1 mode; not used in v2. */
+    gatewayKey?: string;
+    /**
+     * 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;
@@ -1246,6 +1271,7 @@ interface PeekAccessServiceConfig {
 declare class PeekAccessService {
     private readonly client;
     private readonly productServiceOptions;
+    private readonly jwtSecret;
     private productService?;
     private accountUserService?;
     private resourcePoolService?;
@@ -1258,6 +1284,25 @@ declare class PeekAccessService {
     private bookingService?;
     private reviewService?;
     constructor(config: PeekAccessServiceConfig);
+    /**
+     * Verifies a Peek auth token issued by the app registry and returns the
+     * decoded claims.
+     *
+     * Validates the HMAC signature (using this service's `jwtSecret`), the token
+     * expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience. Throws
+     * from the `jsonwebtoken` library on any failure — callers should catch to
+     * distinguish error kinds:
+     *
+     * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or token
+     *   malformed
+     * - `TokenExpiredError` — past `exp`
+     * - `NotBeforeError` — before `nbf`
+     *
+     * @throws {JsonWebTokenError} signature invalid or token malformed
+     * @throws {TokenExpiredError} token has expired
+     * @throws {NotBeforeError} token not yet valid
+     */
+    verifyPeekAuthToken(token: string): PeekAuthTokenClaims;
     /**
      * Returns the {@link ProductService} for this install, bound to the shared
      * authenticated transport. The instance is created lazily and reused.
@@ -1429,4 +1474,4 @@ declare class PeekGraphQLError extends Error {
     constructor(graphqlErrors: unknown[], message?: string);
 }
 
-export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };
+export { ADD_ON_PRODUCT_TYPE, type AccountUser, AccountUserService, type AccountUserServiceOptions, type AddAddonInput, AdminAccountRequiredError, type Agent, type AssignGuideResult, type AssignedActivity, type AssignedResource, type Availability, AvailabilityService, type AvailabilityTime, type AvailabilityTimesQuery, type Booking, type BookingAddon, type BookingAddonMoney, type BookingAddonOption, type BookingAddons, type BookingAddonsMutationResult, type BookingPaymentsOnFile, type BookingReadOptions, type BookingSearchBy, BookingService, type BookingServiceOptions, type BookingTimeRangeSearch, type CancelBookingResult, type Channel, type CreateBookingGuest, type CreateBookingInput, type CreateBookingTicket, type CreatePromoCodeInput, type CreatedBooking, type CreatedPromoCode, type CustomQuestionAnswer, type DailyNote, DailyNoteService, type Duration, type Guest, type GuestMetadata, type Guide, type GuideAssignment, type InvoiceLinkResult, type Logger, type MakePaymentInput, type MakePaymentResult, type Membership, type MembershipPurchaseInput, MembershipService, type NoteMode, type Payment, type PaymentSource, PeekAccessService, type PeekAccessServiceConfig, type PeekAuthTokenClaims, type PeekAuthTokenUser, PeekGraphQLError, type Price, type Product, ProductService, type ProductServiceOptions, type ProductTicket, type PromoCode, type PromoCodeFixedAmount, PromoCodeService, type PromoCodeServiceOptions, type PurchasedMembership, RateLimitError, type RefundInput, type RefundResult, ResellerService, type Resource, type ResourceOptionQuantity, type ResourcePool, type ResourcePoolAccountUser, type ResourcePoolAssignment, type ResourcePoolMode, ResourcePoolService, type Review, ReviewService, type Ticket, type Timeslot, type TimeslotFilter, TimeslotService, type UpdateTimeslotResult, type Waiver, noopLogger, parseBookingWebhook, parseWaiverWebhook };

package/dist/index.js

@@ -1,8 +1,11 @@
-import { randomUUID } from 'crypto';
 import * as jwt from 'jsonwebtoken';
+import { randomUUID } from 'crypto';
+
+// src/peek-access-service.ts
 
 // src/internal/gateway-endpoints.ts
 var SALES_ENDPOINT = "sales";
+var V2_EXTENDABLE_SLUG = "peek_backoffice_api-v1";
 
 // src/internal/account-users/account-user-converter.ts
 var ACTIVE_STATUS = "ACTIVE";
@@ -1819,14 +1822,19 @@ var GraphQLClient = class {
     throw new RateLimitError();
   }
   endpoint(endpointName) {
-    return `${this.options.baseUrl}/${this.options.appId}/${endpointName}`;
+    const { baseUrl, appId, endpointPathPrefix } = this.options;
+    const prefix = endpointPathPrefix ? `${endpointPathPrefix}/` : "";
+    return `${baseUrl}/${appId}/${prefix}${endpointName}`;
   }
   buildHeaders() {
-    return {
+    const headers = {
       "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;
   }
 };
 
@@ -2886,12 +2894,15 @@ 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 DEFAULT_TOKEN_TTL_SECONDS = 3600;
 var DEFAULT_TOKEN_REFRESH_LEEWAY_SECONDS = 60;
 var DEFAULT_RETRY_DELAYS_MS = [1e3, 2e3, 4e3];
+var PEEK_TOKEN_ISSUER = "app_registry_v2";
 var PeekAccessService = class {
   client;
   productServiceOptions;
+  jwtSecret;
   productService;
   accountUserService;
   resourcePoolService;
@@ -2904,11 +2915,13 @@ var PeekAccessService = class {
   bookingService;
   reviewService;
   constructor(config) {
+    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");
+    this.jwtSecret = config.jwtSecret;
     const logger = config.logger ?? noopLogger;
     const tokens = new TokenManager({
       secret: config.jwtSecret,
@@ -2917,19 +2930,56 @@ var PeekAccessService = class {
       ttlSeconds: config.tokenTtlSeconds ?? DEFAULT_TOKEN_TTL_SECONDS,
       leewaySeconds: 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
+      fetchFn: config.fetch ?? globalThis.fetch,
+      endpointPathPrefix: isV2 ? V2_EXTENDABLE_SLUG : void 0
     });
     this.productServiceOptions = {
       itemOptionsPageSize: config.itemOptionsPageSize
     };
   }
+  /**
+   * Verifies a Peek auth token issued by the app registry and returns the
+   * decoded claims.
+   *
+   * Validates the HMAC signature (using this service's `jwtSecret`), the token
+   * expiry, the `"app_registry_v2"` issuer, and the `"Joken"` audience. Throws
+   * from the `jsonwebtoken` library on any failure — callers should catch to
+   * distinguish error kinds:
+   *
+   * - `JsonWebTokenError` — signature invalid, wrong issuer/audience, or token
+   *   malformed
+   * - `TokenExpiredError` — past `exp`
+   * - `NotBeforeError` — before `nbf`
+   *
+   * @throws {JsonWebTokenError} signature invalid or token malformed
+   * @throws {TokenExpiredError} token has expired
+   * @throws {NotBeforeError} token not yet valid
+   */
+  verifyPeekAuthToken(token) {
+    const payload = jwt.verify(token, this.jwtSecret, {
+      issuer: PEEK_TOKEN_ISSUER
+    });
+    const { user: u } = payload;
+    return {
+      installId: payload.sub,
+      displayVersion: payload.display_version,
+      user: {
+        email: u.email,
+        id: u.id,
+        isAdmin: u.is_admin,
+        locale: u.locale,
+        name: u.name
+      }
+    };
+  }
   /**
    * Returns the {@link ProductService} for this install, bound to the shared
    * authenticated transport. The instance is created lazily and reused.