@peektravel/app-utilities 0.8.2 → 0.9.1

package/dist/index.d.cts

@@ -1,3 +1,24 @@
+/**
+ * A platform's tiny map of **API endpoint key → relative path** (the "slug"
+ * inserted between the install's base API URL and the endpoint's own path).
+ *
+ * The base API URL is the install's app endpoint with no routing segment — the
+ * install webhook's `apiUrl` (with any slug stripped back off), or
+ * `baseUrl/appId` when built from the deprecated defaults. Each service class
+ * resolves *its own* slug through this lookup, so two services on the same
+ * platform can route through different slugs. Adding a new API — even one on a
+ * different slug than its siblings — is a single entry here.
+ *
+ * An empty-string path means the endpoint sits directly on the base with no
+ * slug (e.g. the legacy Peek v1 GraphQL gateway, which has no extendable slug).
+ */
+declare class ApiEndpoints<Key extends string = string> {
+    private readonly paths;
+    constructor(paths: Readonly<Record<Key, string>>);
+    /** The relative path (slug) for `endpoint`, appended to the base API URL. */
+    pathFor(endpoint: Key): string;
+}
+
 /**
  * Minimal structured logger interface the package can write diagnostics to.
  *
@@ -20,19 +41,13 @@ interface GraphQLBody<T> {
 }
 interface GraphQLClientOptions {
     /**
-     * The install's app endpoint URL (the install webhook's `apiUrl`). When set it
-     * is the **sole request URL** — every GraphQL call POSTs to it unmodified, and
-     * `baseUrl`/`appId`/`endpointPathPrefix`/`endpointName` are ignored for URL
-     * construction. Takes precedence over `baseUrl`.
+     * The install's **base API URL** (no trailing slash, no routing slug). Every
+     * GraphQL call POSTs to `baseApiUrl/<slug>`, where the slug comes from
+     * {@link endpoints} for the request's endpoint name.
      */
-    apiUrl?: string;
-    /**
-     * Base URL of the backoffice GraphQL gateway (no trailing slash). Used only
-     * when `apiUrl` is not set; the URL is `baseUrl/appId/[prefix/]endpointName`.
-     */
-    baseUrl?: string;
-    /** Peek app ID, used in the endpoint path (legacy `baseUrl` mode only). */
-    appId?: string;
+    baseApiUrl: string;
+    /** Maps an endpoint name to the relative slug appended to {@link baseApiUrl}. */
+    endpoints: ApiEndpoints;
     /** 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. */
@@ -43,11 +58,6 @@ 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;
@@ -1671,13 +1681,17 @@ interface BaseAccessServiceConfig {
     /** JWT issuer — the app name / app ID. */
     issuer: string;
     /**
-     * The install's **app endpoint URL** — persist the install webhook's `apiUrl`
-     * and pass it here. When set it is used **as given**: for Peek it is the sole
-     * request URL (every call POSTs to it); for CNG/ACME it is the base and the
-     * REST path is appended. No app-id/gateway segment is inserted, so `appId` is
-     * not required. This is the forward-looking way to target an install — prefer
-     * it over `baseUrl`/`appId`, which are deprecated (the hardcoded base-URL
-     * fallbacks will be removed and a URL will become required in a future release).
+     * The install's **base API URL** — persist the install webhook's `apiUrl` and
+     * pass it here. It is the app endpoint with no per-platform routing slug; each
+     * service class appends its own slug (e.g. `peek_backoffice_api-v1`, via that
+     * platform's endpoint lookup) when it makes a call, so different services can
+     * route through different slugs. If the URL you pass still carries this
+     * platform's slug it is stripped back off to recover the base; a URL carrying a
+     * *different* platform's slug makes the constructor throw. No app-id/gateway
+     * segment is inserted, so `appId` is not required. This is the forward-looking
+     * way to target an install — prefer it over `baseUrl`/`appId`, which are
+     * deprecated (the hardcoded base-URL fallbacks will be removed and a URL will
+     * become required in a future release).
      */
     apiUrl?: string;
     /**
@@ -2178,109 +2192,101 @@ declare class PeekAccessService {
      * authenticated transport. The instance is created lazily and reused.
      */
     getReviewService(): ReviewService;
-    /** All products (activities + add-ons). Delegates to {@link ProductService.getAllProducts}. */
+    /** 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(): Promise<Product[]>;
-    /** All activity products (excludes add-ons). Delegates to {@link ProductService.getAllActivities}. */
+    /** All activity products (excludes add-ons). @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link ProductService.getAllActivities}. */
     getAllActivities(): Promise<Product[]>;
-    /** All rental products. Delegates to {@link ProductService.getAllRentals}. */
+    /** All rental products. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link ProductService.getAllRentals}. */
     getAllRentals(): Promise<Product[]>;
-    /** All add-on products. Delegates to {@link ProductService.getAllAddons}. */
+    /** All add-on products. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link ProductService.getAllAddons}. */
     getAllAddons(): Promise<Product[]>;
-    /** An activity's custom questions. Delegates to {@link ProductService.getCustomQuestions}. */
+    /** An activity's custom questions. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link ProductService.getCustomQuestions}. */
     getCustomQuestions(productId: string): Promise<CustomQuestion[]>;
-    /** All active account users. Delegates to {@link AccountUserService.getAll}. */
+    /** All active account users. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link AccountUserService.getAll}. */
     getAllAccountUsers(): Promise<AccountUser[]>;
-    /** Account user by id, or null. Delegates to {@link AccountUserService.getById}. */
+    /** Account user by id, or null. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link AccountUserService.getById}. */
     getAccountUserById(userId: string): Promise<AccountUser | null>;
-    /** All resource pools. Delegates to {@link ResourcePoolService.getAll}. */
+    /** All resource pools. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link ResourcePoolService.getAll}. */
     getAllResourcePools(mode?: ResourcePoolMode): Promise<ResourcePool[]>;
-    /** Timeslots for an activity on a given date. Delegates to {@link TimeslotService.getForDay}. */
+    /** Timeslots for an activity on a given date. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link TimeslotService.getForDay}. */
     getTimeslotsForDay(productId: string, date: string, filter?: TimeslotFilter): Promise<Timeslot[]>;
-    /** Single timeslot by id. Delegates to {@link TimeslotService.getById}. */
+    /** Single timeslot by id. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link TimeslotService.getById}. */
     getTimeslotById(timeslotId: string): Promise<Timeslot | null>;
-    /** Set timeslot status. Delegates to {@link TimeslotService.setAvailability}. */
+    /** Set timeslot status. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link TimeslotService.setAvailability}. */
     setTimeslotAvailability(timeslotId: string, status: string): Promise<UpdateTimeslotResult>;
-    /** Set timeslot manifest notes. Delegates to {@link TimeslotService.setNotes}. */
+    /** Set timeslot manifest notes. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link TimeslotService.setNotes}. */
     setTimeslotNotes(timeslotId: string, manifestNotes: string): Promise<UpdateTimeslotResult>;
-    /** Assign or unassign guides on timeslots. Delegates to {@link TimeslotService.assignGuide}. */
+    /** Assign or unassign guides on timeslots. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link TimeslotService.assignGuide}. */
     assignTimeslotGuide(assignment: GuideAssignment): Promise<AssignGuideResult>;
-    /** All reseller channels. Delegates to {@link ResellerService.getAllChannels}. */
+    /** All reseller channels. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link ResellerService.getAllChannels}. */
     getAllChannels(agentsPerChannel?: number): Promise<Channel[]>;
-    /** All promo codes. Delegates to {@link PromoCodeService.getAll}. */
+    /** All promo codes. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link PromoCodeService.getAll}. */
     getAllPromoCodes(): Promise<PromoCode[]>;
-    /** Create a promo code. Delegates to {@link PromoCodeService.create}. */
+    /** Create a promo code. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link PromoCodeService.create}. */
     createPromoCode(input: CreatePromoCodeInput): Promise<CreatedPromoCode>;
-    /** Create a pricing engine. Delegates to {@link PricingService.createEngine}. */
+    /** Create a pricing engine. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link PricingService.createEngine}. */
     createPricingEngine(input: CreateEngineInput): Promise<CreatedPricingEngine>;
-    /** Update a pricing engine. Delegates to {@link PricingService.updateEngine}. */
+    /** Update a pricing engine. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link PricingService.updateEngine}. */
     updatePricingEngine(input: UpdateEngineInput): Promise<PricingEngine>;
-    /** Delete a pricing engine (idempotent). Delegates to {@link PricingService.deleteEngine}. */
+    /** Delete a pricing engine (idempotent). @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link PricingService.deleteEngine}. */
     deletePricingEngine(engineId: string): Promise<void>;
-    /** Upsert pricing overrides. Delegates to {@link PricingService.upsertOverrides}. */
+    /** Upsert pricing overrides. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link PricingService.upsertOverrides}. */
     upsertPricingOverrides(input: UpsertOverridesInput): Promise<UpsertOverridesResult>;
-    /** Clear pricing overrides for a set of activities. Delegates to {@link PricingService.clearOverrides}. */
+    /** Clear pricing overrides for a set of activities. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link PricingService.clearOverrides}. */
     clearPricingOverrides(input: ClearOverridesInput): Promise<UpsertOverridesResult>;
-    /** Today's daily note. Delegates to {@link DailyNoteService.getToday}. */
+    /** Today's daily note. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link DailyNoteService.getToday}. */
     getDailyNoteToday(): Promise<DailyNote | null>;
-    /** Update today's daily note. Delegates to {@link DailyNoteService.update}. */
+    /** Update today's daily note. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link DailyNoteService.update}. */
     updateDailyNote(note: string): Promise<DailyNote | null>;
-    /** Availability times for an activity. Delegates to {@link AvailabilityService.getAvailabilityTimes}. */
+    /** Availability times for an activity. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link AvailabilityService.getAvailabilityTimes}. */
     getAvailabilityTimes(query: AvailabilityTimesQuery): Promise<AvailabilityTime[]>;
-    /** All memberships. Delegates to {@link MembershipService.getAll}. */
+    /** All memberships. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link MembershipService.getAll}. */
     getAllMemberships(): Promise<Membership[]>;
-    /** Purchase a membership. Delegates to {@link MembershipService.purchase}. */
+    /** Purchase a membership. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link MembershipService.purchase}. */
     purchaseMembership(input: MembershipPurchaseInput): Promise<PurchasedMembership>;
-    /** Booking by id. Delegates to {@link BookingService.getById}. */
+    /** Booking by id. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.getById}. */
     getBookingById(bookingId: string, options?: BookingReadOptions): Promise<Booking | null>;
-    /** Bookings by time range. Delegates to {@link BookingService.searchByTimeRange}. */
+    /** Bookings by time range. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.searchByTimeRange}. */
     searchBookingsByTimeRange(input: BookingTimeRangeSearch): Promise<Booking[]>;
-    /** Bookings on a timeslot. Delegates to {@link BookingService.searchByTimeslot}. */
+    /** Bookings on a timeslot. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.searchByTimeslot}. */
     searchBookingsByTimeslot(timeslotId: string, options?: BookingReadOptions): Promise<Booking[]>;
-    /** Guests on a booking. Delegates to {@link BookingService.getGuests}. */
+    /** Guests on a booking. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.getGuests}. */
     getBookingGuests(bookingId: string): Promise<Guest[]>;
-    /** Payments on file for a booking. Delegates to {@link BookingService.getPaymentsOnFile}. */
+    /** Payments on file for a booking. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.getPaymentsOnFile}. */
     getBookingPaymentsOnFile(bookingId: string): Promise<BookingPaymentsOnFile | null>;
-    /** Append or overwrite operator notes. Delegates to {@link BookingService.appendNote}. */
+    /** Append or overwrite operator notes. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.appendNote}. */
     appendBookingNote(bookingId: string, note: string, mode?: NoteMode): Promise<Booking | null>;
-    /** Set booking check-in status. Delegates to {@link BookingService.setCheckinStatus}. */
+    /** Set booking check-in status. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.setCheckinStatus}. */
     setBookingCheckinStatus(bookingId: string, checkedIn: boolean): Promise<Booking | null>;
-    /** Cancel a booking. Delegates to {@link BookingService.cancel}. */
+    /** Cancel a booking. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.cancel}. */
     cancelBooking(bookingId: string, notes?: string): Promise<CancelBookingResult>;
-    /** Charge a booking. Delegates to {@link BookingService.makePayment}. */
+    /** Charge a booking. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.makePayment}. */
     makeBookingPayment(input: MakePaymentInput): Promise<MakePaymentResult>;
-    /** Refund a booking payment. Delegates to {@link BookingService.refund}. */
+    /** Refund a booking payment. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.refund}. */
     refundBooking(input: RefundInput): Promise<RefundResult>;
-    /** Create an invoice link. Delegates to {@link BookingService.createInvoiceLink}. */
+    /** Create an invoice link. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.createInvoiceLink}. */
     createBookingInvoiceLink(bookingId: string): Promise<InvoiceLinkResult>;
-    /** List add-ons on a booking. Delegates to {@link BookingService.listAddons}. */
+    /** List add-ons on a booking. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.listAddons}. */
     listBookingAddons(bookingId: string): Promise<BookingAddons>;
-    /** Add an add-on to a booking. Delegates to {@link BookingService.addAddon}. */
+    /** Add an add-on to a booking. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.addAddon}. */
     addBookingAddon(bookingId: string, input: AddAddonInput): Promise<BookingAddonsMutationResult>;
-    /** Remove an add-on from a booking. Delegates to {@link BookingService.removeAddon}. */
+    /** Remove an add-on from a booking. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.removeAddon}. */
     removeBookingAddon(bookingId: string, input: AddAddonInput): Promise<BookingAddonsMutationResult>;
-    /** Create a booking. Delegates to {@link BookingService.create}. */
+    /** Create a booking. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link BookingService.create}. */
     createBooking(input: CreateBookingInput): Promise<CreatedBooking>;
-    /** Reviews for an activity. Delegates to {@link ReviewService.getReviews}. */
+    /** Reviews for an activity. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link ReviewService.getReviews}. */
     getReviews(productId: string, reviewCount?: number, reviewOffset?: number): Promise<Review[]>;
 }
 
 interface RestClientOptions$1 {
     /**
-     * The install's app endpoint URL (the install webhook's `apiUrl`). When set it
-     * is the **base URL** and only the REST path is appended (`apiUrl/path`) —
-     * `baseUrl`/`appId`/`extendableSlug` are ignored. Takes precedence over
-     * `baseUrl`.
+     * The install's **base API URL** (no trailing slash, no routing slug). Each
+     * request builds `baseApiUrl/<slug>/<path>`, where the slug comes from
+     * {@link endpoints} for the request's endpoint key.
      */
-    apiUrl?: string;
-    /**
-     * Base URL of the backoffice gateway (no trailing slash). Used only when
-     * `apiUrl` is not set; the URL is `baseUrl/appId/extendableSlug/path`.
-     */
-    baseUrl?: string;
-    /** App ID, used in the endpoint path (legacy `baseUrl` mode only). */
-    appId?: string;
-    /** Fixed extendable slug inserted between `appId` and the REST path (legacy mode). */
-    extendableSlug?: string;
+    baseApiUrl: string;
+    /** Maps an endpoint key to the relative slug appended to {@link baseApiUrl}. */
+    endpoints: ApiEndpoints;
     /** Supplies a valid bearer token for each request. */
     getToken: () => string;
     /** Backoff delays (ms) applied on successive HTTP 429 responses. */
@@ -2303,7 +2309,7 @@ declare class RestClient$1 {
      * @throws {CngPermissionError} on HTTP 403 (app missing a permission)
      * @throws {CngApiError} on any other non-2xx response
      */
-    get<T>(path: string): Promise<T>;
+    get<T>(endpoint: string, path: string): Promise<T>;
     private endpoint;
     private buildHeaders;
 }
@@ -2390,7 +2396,7 @@ type CngAccessServiceConfig = BaseAccessServiceConfig;
  *   appId: process.env.PEEK_APP_ID!,
  * });
  *
- * const activities: Activity[] = await cng.getAllActivities();
+ * const activities: Activity[] = await cng.getProductService().getAllActivities();
  * ```
  *
  * @throws {Error} from the constructor when any required config field
@@ -2405,27 +2411,19 @@ declare class CngAccessService {
      * authenticated transport. The instance is created lazily and reused.
      */
     getProductService(): CngProductService;
-    /** All activities. Delegates to {@link CngProductService.getAllActivities}. */
+    /** All activities. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link CngProductService.getAllActivities}. */
     getAllActivities(): Promise<Activity[]>;
 }
 
 interface RestClientOptions {
     /**
-     * The install's app endpoint URL (the install webhook's `apiUrl`). When set it
-     * is the **base URL** and only the REST path is appended (`apiUrl/path`) —
-     * `baseUrl`/`appId`/`extendableSlug` are ignored. Takes precedence over
-     * `baseUrl`.
-     */
-    apiUrl?: string;
-    /**
-     * Base URL of the backoffice gateway (no trailing slash). Used only when
-     * `apiUrl` is not set; the URL is `baseUrl/appId/extendableSlug/path`.
+     * The install's **base API URL** (no trailing slash, no routing slug). Each
+     * request builds `baseApiUrl/<slug>/<path>`, where the slug comes from
+     * {@link endpoints} for the request's endpoint key.
      */
-    baseUrl?: string;
-    /** App ID, used in the endpoint path (legacy `baseUrl` mode only). */
-    appId?: string;
-    /** Fixed extendable slug inserted between `appId` and the REST path (legacy mode). */
-    extendableSlug?: string;
+    baseApiUrl: string;
+    /** Maps an endpoint key to the relative slug appended to {@link baseApiUrl}. */
+    endpoints: ApiEndpoints;
     /** Supplies a valid bearer token for each request. */
     getToken: () => string;
     /** Backoff delays (ms) applied on successive HTTP 429 responses. */
@@ -2447,7 +2445,7 @@ declare class RestClient {
      * @throws {RateLimitError} on HTTP 429 after retries are exhausted
      * @throws {AcmeApiError} on any other non-2xx response
      */
-    get<T>(path: string): Promise<T>;
+    get<T>(endpoint: string, path: string): Promise<T>;
     private endpoint;
     private buildHeaders;
 }
@@ -2525,7 +2523,7 @@ type AcmeAccessServiceConfig = BaseAccessServiceConfig;
  *   appId: process.env.PEEK_APP_ID!,
  * });
  *
- * const activities: AcmeActivity[] = await acme.getAllActivities();
+ * const activities: AcmeActivity[] = await acme.getProductService().getAllActivities();
  * ```
  *
  * @throws {Error} from the constructor when any required config field
@@ -2540,7 +2538,7 @@ declare class AcmeAccessService {
      * authenticated transport. The instance is created lazily and reused.
      */
     getProductService(): AcmeProductService;
-    /** All activities. Delegates to {@link AcmeProductService.getAllActivities}. */
+    /** All activities. @deprecated The access service exposes only its resource-service accessors; call the service directly instead. See {@link AcmeProductService.getAllActivities}. */
     getAllActivities(): Promise<AcmeActivity[]>;
 }
 
@@ -2565,7 +2563,12 @@ declare class AcmeAccessService {
 interface InstallAccessTarget {
     /** Which platform serves the install (the install webhook's `platform`). */
     platform: PeekPlatform | null;
-    /** The install's app endpoint URL (the install webhook's `apiUrl`), used as given. */
+    /**
+     * The install's base API URL (the install webhook's `apiUrl`). The chosen
+     * access service's service classes append their own backoffice slug when they
+     * call; a URL already carrying this platform's slug is stripped back to the
+     * base, and one carrying a different platform's slug throws.
+     */
     apiUrl: string;
     /** The install id (the install webhook's `installId`) — becomes the JWT subject. */
     installId: string;