@peektravel/app-utilities 0.2.2 → 0.2.3

package/dist/index.d.cts

@@ -1184,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 {
@@ -1258,6 +1271,7 @@ interface PeekAccessServiceConfig {
 declare class PeekAccessService {
     private readonly client;
     private readonly productServiceOptions;
+    private readonly jwtSecret;
     private productService?;
     private accountUserService?;
     private resourcePoolService?;
@@ -1270,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.
@@ -1441,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

@@ -1184,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 {
@@ -1258,6 +1271,7 @@ interface PeekAccessServiceConfig {
 declare class PeekAccessService {
     private readonly client;
     private readonly productServiceOptions;
+    private readonly jwtSecret;
     private productService?;
     private accountUserService?;
     private resourcePoolService?;
@@ -1270,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.
@@ -1441,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,5 +1,7 @@
-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";
@@ -2896,9 +2898,11 @@ 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;
@@ -2917,6 +2921,7 @@ var PeekAccessService = class {
     requireNonEmpty(config.issuer, "issuer");
     requireNonEmpty(config.appId, "appId");
     if (!isV2) requireNonEmpty(config.gatewayKey ?? "", "gatewayKey");
+    this.jwtSecret = config.jwtSecret;
     const logger = config.logger ?? noopLogger;
     const tokens = new TokenManager({
       secret: config.jwtSecret,
@@ -2940,6 +2945,41 @@ var PeekAccessService = class {
       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.