@suiteop/storefront 0.5.0 → 0.6.0

package/dist/content.d.cts

@@ -1,7 +1,7 @@
-import { R as RequestOptions, P as Page, s as StorefrontImage, o as StorefrontContentRef, j as StorefrontClient } from './client-2KyVv-2l.cjs';
-export { m as StorefrontContentItem } from './client-2KyVv-2l.cjs';
+import { R as RequestOptions, P as Page, s as StorefrontImage, o as StorefrontContentRef, j as StorefrontClient } from './client-CX8K7JNt.cjs';
+export { m as StorefrontContentItem } from './client-CX8K7JNt.cjs';
 import { z } from 'zod';
-import './availability-Dh0yLSkj.cjs';
+import './availability.d-Cla9GuGc.cjs';
 
 declare const contentLocalizedSchema: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
 type ContentLocalized = z.infer<typeof contentLocalizedSchema>;
@@ -10,8 +10,8 @@ declare const contentModelSchema: z.ZodObject<{
     types: z.ZodArray<z.ZodObject<{
         key: z.ZodString;
         kind: z.ZodEnum<{
-            fields: "fields";
             collection: "collection";
+            fields: "fields";
             section: "section";
         }>;
         label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
@@ -30,17 +30,17 @@ declare const contentModelSchema: z.ZodObject<{
         fields: z.ZodArray<z.ZodObject<{
             key: z.ZodString;
             type: z.ZodEnum<{
-                number: "number";
                 boolean: "boolean";
-                rich_text: "rich_text";
-                link: "link";
-                text: "text";
                 date: "date";
-                image: "image";
                 gallery: "gallery";
+                image: "image";
+                link: "link";
+                number: "number";
                 option: "option";
                 reference: "reference";
                 references: "references";
+                rich_text: "rich_text";
+                text: "text";
             }>;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             help: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
@@ -64,20 +64,27 @@ declare const contentModelSchema: z.ZodObject<{
 type ContentModel = z.infer<typeof contentModelSchema>;
 type ContentModelInput = z.input<typeof contentModelSchema>;
 
+/** A label in one language, or one per language (`{ en: 'Blog', fr: 'Blog' }`). */
 type Localized = ContentLocalized;
 interface FieldBase {
     label: Localized;
+    /** A hint under the field in the dashboard. */
     help?: Localized;
+    /** The property manager must fill it in before saving. */
     required?: boolean;
 }
 interface TextOptions extends FieldBase {
+    /** Written once and AI-translated to the site's other languages. Default true. */
     translatable?: boolean;
     maxLength?: number;
 }
 interface ListOptions extends FieldBase {
+    /** Most photos (gallery) or items (references). */
     max?: number;
 }
+/** What a reference points at: a listing, a building, an area, or an item of a collection. */
 type ReferenceTarget = 'listing' | 'building' | 'area' | `collection:${string}`;
+/** An option of an `option` field: its value, or a value with a label. */
 type OptionChoice<V extends string = string> = V | {
     value: V;
     label: Localized;
@@ -122,25 +129,39 @@ type ContentFieldDefinition = TextField | RichTextField | ImageField | GalleryFi
 interface TypeBase {
     label: Localized;
     description?: Localized;
+    /** Keyed by field key: lower-case letters, digits and `_`, starting with a letter. */
     fields: Record<string, ContentFieldDefinition>;
 }
+/** Many items: a blog, press mentions, perks. */
 interface CollectionDefinition extends TypeBase {
     kind: 'collection';
+    /** The key of the `text` field that titles an item. */
     titleField: string;
+    /** Each item gets a web address (slug). */
     routable?: boolean;
+    /** Items start as drafts and are published explicitly. */
     drafts?: boolean;
+    /** `manual` (the property manager's drag order, the default) or `newest` (by publish date). */
     order?: 'manual' | 'newest';
 }
+/** One item: a home-page banner. */
 interface SectionDefinition extends TypeBase {
     kind: 'section';
 }
+/** Extra fields every building or every area carries. */
 interface FieldsDefinition extends TypeBase {
     kind: 'fields';
     attachesTo: 'building' | 'area';
 }
 type ContentTypeDefinition = CollectionDefinition | SectionDefinition | FieldsDefinition;
+/** Keyed by type key: what the site's code reads it by (`blog`, `home_hero`). */
 type ContentDefinition = Record<string, ContentTypeDefinition>;
+/**
+ * Declare the site's content model. Returns the object unchanged; its exact type is what
+ * `createContentReader` reads values as.
+ */
 declare function defineContent<const T extends ContentDefinition>(definition: T): T;
+/** Field builders. Each returns its options with the field's `type`. */
 declare const field: {
     text: <const O extends TextOptions>(o: O) => O & {
         type: "text";
@@ -183,6 +204,7 @@ declare const field: {
         type: "references";
     };
 };
+/** A link value. `url` is `https://…` or a path on the site (`/stays`). */
 interface ContentLink {
     url: string;
     label?: string;
@@ -190,6 +212,10 @@ interface ContentLink {
 type OptionValue<C> = C extends string ? C : C extends {
     value: infer V;
 } ? V : never;
+/**
+ * What a field reads as. Every single value can be null — not filled in yet, or no longer fitting
+ * the field after the site's code changed it — and lists are empty instead.
+ */
 type FieldValue<F> = F extends {
     type: 'text' | 'rich_text' | 'date';
 } ? string | null : F extends {
@@ -210,11 +236,13 @@ type FieldValue<F> = F extends {
 } ? StorefrontContentRef | null : F extends {
     type: 'references';
 } ? StorefrontContentRef[] : unknown;
+/** The values of one item of type `T`, by field key. */
 type FieldsOf<T> = T extends {
     fields: infer F;
 } ? {
     -readonly [K in keyof F]: FieldValue<F[K]>;
 } : never;
+/** One published item of type `K`. */
 interface ItemOf<D, K extends keyof D> {
     id: string;
     slug: string | null;
@@ -231,8 +259,18 @@ type KeysOfKind<D, Kind> = {
 type CollectionKeys<D> = KeysOfKind<D, 'collection'>;
 type SectionKeys<D> = KeysOfKind<D, 'section'>;
 type FieldsKeys<D> = KeysOfKind<D, 'fields'>;
+/** The declaration as the Storefront API stores it (`{ version: 1, types: [...] }`). */
 declare function toContentModel(definition: ContentDefinition): ContentModelInput;
+/**
+ * {@link toContentModel}, checked against the rules the API applies (keys, a collection's title
+ * field, reference targets…). Throws an error naming each problem's path.
+ */
 declare function parseContentModel(definition: ContentDefinition): ContentModel;
+/**
+ * Stored values as the declared fields read them: each one checked against its field's type, a
+ * missing or mistyped one as null (or `[]` for a list), undeclared keys dropped. A published site
+ * never breaks on a value its code no longer expects.
+ */
 declare function readFields<T extends ContentTypeDefinition>(type: T, values: Record<string, unknown> | null | undefined): FieldsOf<T>;
 interface ContentReader<D extends ContentDefinition> {
     collection<K extends CollectionKeys<D>>(key: K): {
@@ -240,15 +278,21 @@ interface ContentReader<D extends ContentDefinition> {
             limit?: number;
             offset?: number;
         }, opts?: RequestOptions): Promise<Page<ItemOf<D, K>>>;
+        /** By slug or id; null when nothing published answers to it. */
         get(slugOrId: string, opts?: RequestOptions): Promise<ItemOf<D, K> | null>;
     };
     section<K extends SectionKeys<D>>(key: K): {
         get(opts?: RequestOptions): Promise<ItemOf<D, K>>;
     };
+    /**
+     * The custom fields of type `key` on a building or an area the client returned
+     * (`client.buildings.get(id)`), typed; all empty when the record carries none.
+     */
     fieldsOf<K extends FieldsKeys<D>>(key: K, record: {
         fields?: Record<string, Record<string, unknown>> | null;
     }): FieldsOf<D[K]>;
 }
+/** Typed reads of the content `definition` declares, through `client`. */
 declare function createContentReader<D extends ContentDefinition>(client: StorefrontClient, definition: D): ContentReader<D>;
 
 export { type BooleanField, type CollectionDefinition, type CollectionKeys, type ContentDefinition, type ContentFieldDefinition, type ContentLink, type ContentReader, type ContentTypeDefinition, type DateField, type FieldValue, type FieldsDefinition, type FieldsKeys, type FieldsOf, type GalleryField, type ImageField, type ItemOf, type LinkField, type Localized, type NumberField, type OptionChoice, type OptionField, type ReferenceField, type ReferenceTarget, type ReferencesField, type RichTextField, type SectionDefinition, type SectionKeys, StorefrontContentRef, StorefrontImage, type TextField, contentModelSchema, createContentReader, defineContent, field, parseContentModel, readFields, toContentModel };

package/dist/content.d.ts

@@ -1,7 +1,7 @@
-import { R as RequestOptions, P as Page, s as StorefrontImage, o as StorefrontContentRef, j as StorefrontClient } from './client-C9Igm7O-.js';
-export { m as StorefrontContentItem } from './client-C9Igm7O-.js';
+import { R as RequestOptions, P as Page, s as StorefrontImage, o as StorefrontContentRef, j as StorefrontClient } from './client-s-lEwqzc.js';
+export { m as StorefrontContentItem } from './client-s-lEwqzc.js';
 import { z } from 'zod';
-import './availability-Dh0yLSkj.js';
+import './availability.d-Cla9GuGc.js';
 
 declare const contentLocalizedSchema: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
 type ContentLocalized = z.infer<typeof contentLocalizedSchema>;
@@ -10,8 +10,8 @@ declare const contentModelSchema: z.ZodObject<{
     types: z.ZodArray<z.ZodObject<{
         key: z.ZodString;
         kind: z.ZodEnum<{
-            fields: "fields";
             collection: "collection";
+            fields: "fields";
             section: "section";
         }>;
         label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
@@ -30,17 +30,17 @@ declare const contentModelSchema: z.ZodObject<{
         fields: z.ZodArray<z.ZodObject<{
             key: z.ZodString;
             type: z.ZodEnum<{
-                number: "number";
                 boolean: "boolean";
-                rich_text: "rich_text";
-                link: "link";
-                text: "text";
                 date: "date";
-                image: "image";
                 gallery: "gallery";
+                image: "image";
+                link: "link";
+                number: "number";
                 option: "option";
                 reference: "reference";
                 references: "references";
+                rich_text: "rich_text";
+                text: "text";
             }>;
             label: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
             help: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
@@ -64,20 +64,27 @@ declare const contentModelSchema: z.ZodObject<{
 type ContentModel = z.infer<typeof contentModelSchema>;
 type ContentModelInput = z.input<typeof contentModelSchema>;
 
+/** A label in one language, or one per language (`{ en: 'Blog', fr: 'Blog' }`). */
 type Localized = ContentLocalized;
 interface FieldBase {
     label: Localized;
+    /** A hint under the field in the dashboard. */
     help?: Localized;
+    /** The property manager must fill it in before saving. */
     required?: boolean;
 }
 interface TextOptions extends FieldBase {
+    /** Written once and AI-translated to the site's other languages. Default true. */
     translatable?: boolean;
     maxLength?: number;
 }
 interface ListOptions extends FieldBase {
+    /** Most photos (gallery) or items (references). */
     max?: number;
 }
+/** What a reference points at: a listing, a building, an area, or an item of a collection. */
 type ReferenceTarget = 'listing' | 'building' | 'area' | `collection:${string}`;
+/** An option of an `option` field: its value, or a value with a label. */
 type OptionChoice<V extends string = string> = V | {
     value: V;
     label: Localized;
@@ -122,25 +129,39 @@ type ContentFieldDefinition = TextField | RichTextField | ImageField | GalleryFi
 interface TypeBase {
     label: Localized;
     description?: Localized;
+    /** Keyed by field key: lower-case letters, digits and `_`, starting with a letter. */
     fields: Record<string, ContentFieldDefinition>;
 }
+/** Many items: a blog, press mentions, perks. */
 interface CollectionDefinition extends TypeBase {
     kind: 'collection';
+    /** The key of the `text` field that titles an item. */
     titleField: string;
+    /** Each item gets a web address (slug). */
     routable?: boolean;
+    /** Items start as drafts and are published explicitly. */
     drafts?: boolean;
+    /** `manual` (the property manager's drag order, the default) or `newest` (by publish date). */
     order?: 'manual' | 'newest';
 }
+/** One item: a home-page banner. */
 interface SectionDefinition extends TypeBase {
     kind: 'section';
 }
+/** Extra fields every building or every area carries. */
 interface FieldsDefinition extends TypeBase {
     kind: 'fields';
     attachesTo: 'building' | 'area';
 }
 type ContentTypeDefinition = CollectionDefinition | SectionDefinition | FieldsDefinition;
+/** Keyed by type key: what the site's code reads it by (`blog`, `home_hero`). */
 type ContentDefinition = Record<string, ContentTypeDefinition>;
+/**
+ * Declare the site's content model. Returns the object unchanged; its exact type is what
+ * `createContentReader` reads values as.
+ */
 declare function defineContent<const T extends ContentDefinition>(definition: T): T;
+/** Field builders. Each returns its options with the field's `type`. */
 declare const field: {
     text: <const O extends TextOptions>(o: O) => O & {
         type: "text";
@@ -183,6 +204,7 @@ declare const field: {
         type: "references";
     };
 };
+/** A link value. `url` is `https://…` or a path on the site (`/stays`). */
 interface ContentLink {
     url: string;
     label?: string;
@@ -190,6 +212,10 @@ interface ContentLink {
 type OptionValue<C> = C extends string ? C : C extends {
     value: infer V;
 } ? V : never;
+/**
+ * What a field reads as. Every single value can be null — not filled in yet, or no longer fitting
+ * the field after the site's code changed it — and lists are empty instead.
+ */
 type FieldValue<F> = F extends {
     type: 'text' | 'rich_text' | 'date';
 } ? string | null : F extends {
@@ -210,11 +236,13 @@ type FieldValue<F> = F extends {
 } ? StorefrontContentRef | null : F extends {
     type: 'references';
 } ? StorefrontContentRef[] : unknown;
+/** The values of one item of type `T`, by field key. */
 type FieldsOf<T> = T extends {
     fields: infer F;
 } ? {
     -readonly [K in keyof F]: FieldValue<F[K]>;
 } : never;
+/** One published item of type `K`. */
 interface ItemOf<D, K extends keyof D> {
     id: string;
     slug: string | null;
@@ -231,8 +259,18 @@ type KeysOfKind<D, Kind> = {
 type CollectionKeys<D> = KeysOfKind<D, 'collection'>;
 type SectionKeys<D> = KeysOfKind<D, 'section'>;
 type FieldsKeys<D> = KeysOfKind<D, 'fields'>;
+/** The declaration as the Storefront API stores it (`{ version: 1, types: [...] }`). */
 declare function toContentModel(definition: ContentDefinition): ContentModelInput;
+/**
+ * {@link toContentModel}, checked against the rules the API applies (keys, a collection's title
+ * field, reference targets…). Throws an error naming each problem's path.
+ */
 declare function parseContentModel(definition: ContentDefinition): ContentModel;
+/**
+ * Stored values as the declared fields read them: each one checked against its field's type, a
+ * missing or mistyped one as null (or `[]` for a list), undeclared keys dropped. A published site
+ * never breaks on a value its code no longer expects.
+ */
 declare function readFields<T extends ContentTypeDefinition>(type: T, values: Record<string, unknown> | null | undefined): FieldsOf<T>;
 interface ContentReader<D extends ContentDefinition> {
     collection<K extends CollectionKeys<D>>(key: K): {
@@ -240,15 +278,21 @@ interface ContentReader<D extends ContentDefinition> {
             limit?: number;
             offset?: number;
         }, opts?: RequestOptions): Promise<Page<ItemOf<D, K>>>;
+        /** By slug or id; null when nothing published answers to it. */
         get(slugOrId: string, opts?: RequestOptions): Promise<ItemOf<D, K> | null>;
     };
     section<K extends SectionKeys<D>>(key: K): {
         get(opts?: RequestOptions): Promise<ItemOf<D, K>>;
     };
+    /**
+     * The custom fields of type `key` on a building or an area the client returned
+     * (`client.buildings.get(id)`), typed; all empty when the record carries none.
+     */
     fieldsOf<K extends FieldsKeys<D>>(key: K, record: {
         fields?: Record<string, Record<string, unknown>> | null;
     }): FieldsOf<D[K]>;
 }
+/** Typed reads of the content `definition` declares, through `client`. */
 declare function createContentReader<D extends ContentDefinition>(client: StorefrontClient, definition: D): ContentReader<D>;
 
 export { type BooleanField, type CollectionDefinition, type CollectionKeys, type ContentDefinition, type ContentFieldDefinition, type ContentLink, type ContentReader, type ContentTypeDefinition, type DateField, type FieldValue, type FieldsDefinition, type FieldsKeys, type FieldsOf, type GalleryField, type ImageField, type ItemOf, type LinkField, type Localized, type NumberField, type OptionChoice, type OptionField, type ReferenceField, type ReferenceTarget, type ReferencesField, type RichTextField, type SectionDefinition, type SectionKeys, StorefrontContentRef, StorefrontImage, type TextField, contentModelSchema, createContentReader, defineContent, field, parseContentModel, readFields, toContentModel };

package/dist/content.js

@@ -1,4 +1,4 @@
-export { contentModelSchema, createContentReader, defineContent, field, parseContentModel, readFields, toContentModel } from './chunk-IUNIQSFB.js';
-import './chunk-5TUJX6GY.js';
+export { contentModelSchema, createContentReader, defineContent, field, parseContentModel, readFields, toContentModel } from './chunk-3B6ZYRYF.js';
+import './chunk-XOCFEVP4.js';
 import './chunk-W5K7IDYN.js';
 import './chunk-IBCBDAGY.js';

package/dist/{errors-DpImb0Uf.d.cts → errors-Oax7djdp.d.ts}

@@ -1,100 +1,131 @@
-import { B as BookingResult, z as StorefrontQuote } from './client-2KyVv-2l.cjs';
+import { B as BookingResult, z as StorefrontQuote } from './client-s-lEwqzc.js';
 import { z } from 'zod';
 
 declare const storefrontClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    name: z.ZodLiteral<"page_view">;
     eventId: z.ZodUUID;
     ts: z.ZodNumber;
     path: z.ZodString;
     referrerHost: z.ZodNullable<z.ZodString>;
+    name: z.ZodLiteral<"page_view">;
 }, z.core.$strip>, z.ZodObject<{
+    eventId: z.ZodUUID;
+    ts: z.ZodNumber;
+    path: z.ZodString;
+    referrerHost: z.ZodNullable<z.ZodString>;
     name: z.ZodLiteral<"view_search_results">;
     checkIn: z.ZodOptional<z.ZodISODate>;
     checkOut: z.ZodOptional<z.ZodISODate>;
     guests: z.ZodOptional<z.ZodNumber>;
     locationId: z.ZodOptional<z.ZodUUID>;
+}, z.core.$strip>, z.ZodObject<{
     eventId: z.ZodUUID;
     ts: z.ZodNumber;
     path: z.ZodString;
     referrerHost: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
     name: z.ZodLiteral<"view_item_list">;
     listName: z.ZodString;
     itemCount: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
     eventId: z.ZodUUID;
     ts: z.ZodNumber;
     path: z.ZodString;
     referrerHost: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
     name: z.ZodLiteral<"view_item">;
     listingId: z.ZodUUID;
+}, z.core.$strip>, z.ZodObject<{
     eventId: z.ZodUUID;
     ts: z.ZodNumber;
     path: z.ZodString;
     referrerHost: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
     name: z.ZodLiteral<"view_quote">;
     listingId: z.ZodUUID;
     valueMinor: z.ZodNumber;
     currency: z.ZodString;
     nights: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
     eventId: z.ZodUUID;
     ts: z.ZodNumber;
     path: z.ZodString;
     referrerHost: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
     name: z.ZodLiteral<"begin_checkout">;
     checkoutSessionId: z.ZodUUID;
+}, z.core.$strip>, z.ZodObject<{
     eventId: z.ZodUUID;
     ts: z.ZodNumber;
     path: z.ZodString;
     referrerHost: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
     name: z.ZodLiteral<"add_payment_info">;
     checkoutSessionId: z.ZodUUID;
+}, z.core.$strip>, z.ZodObject<{
     eventId: z.ZodUUID;
     ts: z.ZodNumber;
     path: z.ZodString;
     referrerHost: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
     name: z.ZodLiteral<"generate_lead">;
     formId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
     eventId: z.ZodUUID;
     ts: z.ZodNumber;
     path: z.ZodString;
     referrerHost: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>, z.ZodObject<{
     name: z.ZodLiteral<"sign_up">;
     method: z.ZodLiteral<"newsletter">;
-    eventId: z.ZodUUID;
-    ts: z.ZodNumber;
-    path: z.ZodString;
-    referrerHost: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>], "name">;
 type StorefrontClientEvent = z.infer<typeof storefrontClientEventSchema>;
 
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * An event as a page tracks it: the SDK fills `eventId`, `ts`, `path` and `referrerHost`.
+ * `purchase` is not among them — revenue is written by the server when a booking confirms.
+ */
 type TrackEvent = DistributiveOmit<StorefrontClientEvent, 'eventId' | 'ts' | 'path' | 'referrerHost'>;
+/** Called once per analytics instance, on the first failed send. */
 type AnalyticsReporter = (err: unknown) => void;
 interface AnalyticsOptions {
+    /** The site's publishable key — sent as `?key=` (`navigator.sendBeacon` cannot set headers). */
     publishableKey: string;
     report?: AnalyticsReporter;
 }
 interface StorefrontAnalytics {
     track(event: TrackEvent): void;
+    /** A `page_view` of the current location. */
     pageView(): void;
+    /** Send what is queued now; `beacon` for a page that is going away. */
     flush(opts?: {
         beacon?: boolean;
     }): void;
     dispose(): void;
 }
+/**
+ * The Meta Pixel `Purchase` for a confirmed booking, under ads consent only, with the booking
+ * request id as `eventID` — the same `event_id` the server's Conversions API purchase carries, so
+ * Meta keeps one. `value` / `currency` are sent when the caller has the amount (minor units,
+ * ×100). Never sent to gtag: GA4 and Google Ads get purchase from the server only.
+ */
 declare function trackPurchasePixel(booking: Pick<BookingResult, 'bookingRequestId'> & {
     totalMinor?: number | null;
     currency?: string | null;
 }): void;
+/**
+ * Storefront analytics: batches GA4-aligned events in memory and posts them to the
+ * storefront edge every 2 s, at 10 events, and on `pagehide` (`navigator.sendBeacon`, else
+ * `fetch` with `keepalive`). Sent regardless of consent: the edge stores labels only — no IP, no
+ * user agent, no identifier — and nothing here reads or writes a cookie or web storage. Each
+ * event is also mirrored to the site's client tags (`gtag` / `fbq`) when the consent allows.
+ * A 404 means the site is not behind the SuiteOp edge: the instance goes quiet.
+ */
 declare function createAnalytics(opts: AnalyticsOptions): StorefrontAnalytics;
+/**
+ * The document's one analytics instance for a publishable key. It outlives any component — an
+ * Astro island unmounted by a view transition keeps its queue — and flushes on `pagehide`.
+ */
 declare function analyticsFor(publishableKey: string): StorefrontAnalytics;
 
+/**
+ * Every `error.code` the Storefront API answers, the codes the SuiteOp storefront edge answers,
+ * and the SDK's own.
+ * `StorefrontError.code` stays `string`, so a code a newer API adds degrades, never throws.
+ */
 declare const STOREFRONT_ERROR_CODES: readonly ["wrong_region", "origin_not_allowed", "origin_required", "site_archived", "not_bookable", "quote_invalid", "quote_expired", "price_changed", "currency_unsupported", "payment_declined", "session_expired", "rate_limited", "contact_not_configured", "payment_account_unavailable", "idempotency_key_required", "idempotency_key_reused", "payment_mode_unsupported", "payment_not_authorized", "payment_method_required", "site_not_published", "preview_read_only", "bookings_closed", "extras_invalid", "UNAUTHORIZED", "VALIDATION_ERROR", "NOT_FOUND", "site_not_found", "upstream_timeout", "timeout", "network", "invalid_response", "internal_error", "checkout_unavailable"];
 type StorefrontErrorCode = (typeof STOREFRONT_ERROR_CODES)[number];
 type StorefrontRegion = 'us' | 'eu' | 'apac';
@@ -107,27 +138,36 @@ interface StorefrontErrorInit {
     details?: Record<string, unknown>;
     cause?: unknown;
 }
+/** Any failure the client reports: an API refusal, a malformed answer, a timeout, the network. */
 declare class StorefrontError extends Error {
     name: string;
+    /** HTTP status; 0 when no response arrived (timeout, network). */
     readonly status: number;
     readonly type: string;
+    /** `StorefrontErrorCode` for every code this version knows; any string for newer ones. */
     readonly code: StorefrontErrorCode | (string & {});
     readonly requestId: string | null;
     readonly details: Record<string, unknown>;
     constructor(init: StorefrontErrorInit);
 }
+/**
+ * `price_changed` (409). At checkout-session creation `quote` is the fresh quote to show the
+ * guest; at confirm it is null and `requiresNewSession` is true — start a new checkout.
+ */
 declare class PriceChangedError extends StorefrontError {
     name: string;
     readonly quote: StorefrontQuote | null;
     readonly requiresNewSession: boolean;
     constructor(init: StorefrontErrorInit);
 }
+/** `wrong_region` (421): the key belongs to another region. `baseUrl` is null when the API could not name it. */
 declare class WrongRegionError extends StorefrontError {
     name: string;
     readonly region: StorefrontRegion | null;
     readonly baseUrl: string | null;
     constructor(init: StorefrontErrorInit);
 }
+/** `rate_limited` (429). `scope` names the budget: this key, this visitor's IP, or the PMS account. */
 declare class RateLimitedError extends StorefrontError {
     name: string;
     readonly retryAfterSec: number | null;
@@ -144,6 +184,7 @@ declare class StorefrontNetworkError extends StorefrontError {
     name: string;
     constructor(cause: unknown);
 }
+/** A mistake in how the SDK is set up (bad key, bad base URL, hook outside its provider). */
 declare class StorefrontConfigError extends Error {
     name: string;
 }