@voyantjs/extras 0.19.0 → 0.21.0

package/dist/catalog-policy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Catalog plane field policy for `packages/extras`.
+ *
+ * Extras are booking add-ons (optional line items layered on a booked
+ * parent product) — **not independently sellable inventory**. Per
+ * architecture §3.3.1, extras are a partial-adoption vertical:
+ *
+ *   - **Adopt:** provenance shape (§5.1), booking snapshot graph (§5.3),
+ *     catalog event taxonomy for the cancellation/fulfillment lifecycle.
+ *   - **Skip:** search index projection (§5.4), editorial overlay store
+ *     (§5.2), embeddings / RAG (Phase 2). Extras are discovered through
+ *     the parent's surface, not via standalone catalog browse.
+ *
+ * Every field below has `reindex: "none"` because extras don't appear in
+ * the search index. Snapshot mode is `"on-book"` (or `"never"` for
+ * volatile fields) because refunds and audits need to know exactly what
+ * extra a customer added.
+ *
+ * Scope of this file:
+ *   - The `product_extras` table (extra catalog definitions).
+ *
+ * Out of scope:
+ *   - `option_extra_configs` — option-level overrides; promoted child.
+ *   - `booking_extras` — runtime line items on a booking; not catalog data.
+ */
+import { type FieldPolicyInput } from "@voyantjs/catalog/contract";
+declare const EXTRAS_FIELD_POLICY: FieldPolicyInput[];
+export declare const extrasCatalogPolicy: import("@voyantjs/catalog").FieldPolicy[];
+export { EXTRAS_FIELD_POLICY };
+//# sourceMappingURL=catalog-policy.d.ts.map

package/dist/catalog-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-policy.d.ts","sourceRoot":"","sources":["../src/catalog-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAErF,QAAA,MAAM,mBAAmB,EAAE,gBAAgB,EAwR1C,CAAA;AAED,eAAO,MAAM,mBAAmB,2CAAyC,CAAA;AAEzE,OAAO,EAAE,mBAAmB,EAAE,CAAA"}

package/dist/catalog-policy.js

@@ -0,0 +1,305 @@
+/**
+ * Catalog plane field policy for `packages/extras`.
+ *
+ * Extras are booking add-ons (optional line items layered on a booked
+ * parent product) — **not independently sellable inventory**. Per
+ * architecture §3.3.1, extras are a partial-adoption vertical:
+ *
+ *   - **Adopt:** provenance shape (§5.1), booking snapshot graph (§5.3),
+ *     catalog event taxonomy for the cancellation/fulfillment lifecycle.
+ *   - **Skip:** search index projection (§5.4), editorial overlay store
+ *     (§5.2), embeddings / RAG (Phase 2). Extras are discovered through
+ *     the parent's surface, not via standalone catalog browse.
+ *
+ * Every field below has `reindex: "none"` because extras don't appear in
+ * the search index. Snapshot mode is `"on-book"` (or `"never"` for
+ * volatile fields) because refunds and audits need to know exactly what
+ * extra a customer added.
+ *
+ * Scope of this file:
+ *   - The `product_extras` table (extra catalog definitions).
+ *
+ * Out of scope:
+ *   - `option_extra_configs` — option-level overrides; promoted child.
+ *   - `booking_extras` — runtime line items on a booking; not catalog data.
+ */
+import { defineFieldPolicy } from "@voyantjs/catalog/contract";
+const EXTRAS_FIELD_POLICY = [
+    // ── Source pointer / provenance ─────────────────────────────────────────
+    {
+        path: "source.kind",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "facet-affecting",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "source.ref",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "seller.operator_id",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "static",
+    },
+    // ── Identity / lifecycle ────────────────────────────────────────────────
+    {
+        path: "id",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "first-class-table",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "static",
+    },
+    {
+        path: "code",
+        class: "managed",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "createdAt",
+        class: "managed",
+        merge: "source-only",
+        drift: "none",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "static",
+    },
+    {
+        path: "updatedAt",
+        class: "managed",
+        merge: "source-only",
+        drift: "none",
+        reindex: "none",
+        snapshot: "never",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Cross-module reference (the parent product the extra attaches to) ──
+    {
+        path: "productId",
+        class: "managed",
+        merge: "source-only",
+        drift: "critical",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "supplierId",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Snapshot-relevant managed fields ────────────────────────────────────
+    // Extras' name/description aren't merchandised standalone — they're
+    // shown inside the parent product's add-on UI. Marked as managed for
+    // simplicity; if a future case requires marketing overrides on extras'
+    // names, this can be promoted to merchandisable.
+    {
+        path: "name",
+        class: "managed",
+        merge: "source-only",
+        drift: "medium",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "description",
+        class: "managed",
+        merge: "source-only",
+        drift: "low",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "blob-only",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    // ── Selection / pricing structure (snapshotted at book time) ───────────
+    {
+        path: "selectionType",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "pricingMode",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-quote-and-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "pricedPerPerson",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-quote-and-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "minQuantity",
+        class: "structural",
+        merge: "source-only",
+        drift: "medium",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "maxQuantity",
+        class: "structural",
+        merge: "source-only",
+        drift: "medium",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "defaultQuantity",
+        class: "structural",
+        merge: "source-only",
+        drift: "low",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff", "customer", "partner"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "active",
+        class: "structural",
+        merge: "source-only",
+        drift: "high",
+        reindex: "none",
+        snapshot: "on-book",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "none",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+    {
+        path: "sortOrder",
+        class: "structural",
+        merge: "source-only",
+        drift: "none",
+        reindex: "none",
+        snapshot: "never",
+        query: "indexed-column",
+        localized: false,
+        visibility: ["staff"],
+        editRole: "ops",
+        overrideFriction: "none",
+        sourceFreshness: "sync",
+    },
+];
+export const extrasCatalogPolicy = defineFieldPolicy(EXTRAS_FIELD_POLICY);
+export { EXTRAS_FIELD_POLICY };

package/dist/content-shape.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Extras content shape — the rich detail-page content shape returned
+ * by `getContent` for sourced extras (excursions, transfers, add-on
+ * services).
+ *
+ * The extras content aggregate is `{ extra, options[], media[],
+ * policies[] }` — one payload returned by a single `getContent`.
+ * Pricing stays out (volatile-live, flows through `liveResolve`).
+ *
+ * Extras are simpler than the other verticals because they're add-ons,
+ * not standalone products. There's no day-by-day itinerary, no
+ * room-type / cabin-category map, no ship spec — just an extra
+ * description, optional sub-options (e.g. "half-day vs full-day"),
+ * media, and the operational/cancellation policies.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.2, §3.5.4, §3.6.
+ */
+import { type ContentOverlay, type MergeOverlaysOptions } from "@voyantjs/catalog";
+import { z } from "zod";
+export declare const EXTRAS_CONTENT_SCHEMA_VERSION = "extras/v1";
+export declare const extraSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    selection_type: z.ZodOptional<z.ZodString>;
+    pricing_mode: z.ZodOptional<z.ZodString>;
+    priced_per_person: z.ZodOptional<z.ZodBoolean>;
+    category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    hero_image_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    highlights: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    supplier: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    duration_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    requirements_summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const extraOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    default_selected: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const extraMediaItemSchema: z.ZodObject<{
+    url: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        image: "image";
+        video: "video";
+        document: "document";
+    }>>;
+    caption: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    alt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export declare const extraPolicySchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        supplier_notes: "supplier_notes";
+        cancellation: "cancellation";
+        payment: "payment";
+        requirements: "requirements";
+    }>;
+    body: z.ZodString;
+    rules: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const extraContentSchema: z.ZodObject<{
+    extra: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        status: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        selection_type: z.ZodOptional<z.ZodString>;
+        pricing_mode: z.ZodOptional<z.ZodString>;
+        priced_per_person: z.ZodOptional<z.ZodBoolean>;
+        category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        hero_image_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        highlights: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        supplier: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        duration_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        requirements_summary: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>;
+    options: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        default_selected: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    media: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            image: "image";
+            video: "video";
+            document: "document";
+        }>>;
+        caption: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        alt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    policies: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            supplier_notes: "supplier_notes";
+            cancellation: "cancellation";
+            payment: "payment";
+            requirements: "requirements";
+        }>;
+        body: z.ZodString;
+        rules: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ExtraContent = z.infer<typeof extraContentSchema>;
+export type ExtraSummary = z.infer<typeof extraSummarySchema>;
+export type ExtraOption = z.infer<typeof extraOptionSchema>;
+export type ExtraMediaItem = z.infer<typeof extraMediaItemSchema>;
+export type ExtraPolicy = z.infer<typeof extraPolicySchema>;
+export declare function validateExtraContent(payload: unknown): {
+    valid: true;
+    content: ExtraContent;
+} | {
+    valid: false;
+    reason: string;
+};
+export declare function mergeOverlaysIntoExtraContent(payload: ExtraContent, overlays: ReadonlyArray<ContentOverlay>, options?: Pick<MergeOverlaysOptions, "onOverlayError">): ExtraContent;
+//# sourceMappingURL=content-shape.d.ts.map

package/dist/content-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-shape.d.ts","sourceRoot":"","sources":["../src/content-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EAE1B,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,eAAO,MAAM,6BAA6B,cAAc,CAAA;AAExD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;iBAgC7B,CAAA;AAEF,eAAO,MAAM,iBAAiB;;;;;iBAM5B,CAAA;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;iBAK/B,CAAA;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;iBAI5B,CAAA;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAK7B,CAAA;AAEF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAC7D,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAC7D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAC3D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AACjE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,GACf;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAU3E;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,EACvC,OAAO,GAAE,IAAI,CAAC,oBAAoB,EAAE,gBAAgB,CAAM,GACzD,YAAY,CASd"}

package/dist/content-shape.js

@@ -0,0 +1,98 @@
+/**
+ * Extras content shape — the rich detail-page content shape returned
+ * by `getContent` for sourced extras (excursions, transfers, add-on
+ * services).
+ *
+ * The extras content aggregate is `{ extra, options[], media[],
+ * policies[] }` — one payload returned by a single `getContent`.
+ * Pricing stays out (volatile-live, flows through `liveResolve`).
+ *
+ * Extras are simpler than the other verticals because they're add-ons,
+ * not standalone products. There's no day-by-day itinerary, no
+ * room-type / cabin-category map, no ship spec — just an extra
+ * description, optional sub-options (e.g. "half-day vs full-day"),
+ * media, and the operational/cancellation policies.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.2, §3.5.4, §3.6.
+ */
+import { mergeOverlaysIntoContent, } from "@voyantjs/catalog";
+import { z } from "zod";
+export const EXTRAS_CONTENT_SCHEMA_VERSION = "extras/v1";
+export const extraSummarySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    status: z.string().optional(),
+    description: z.string().nullable().optional(),
+    /**
+     * Selection type — mirrors the owned `extra_selection_type` enum:
+     * "optional" | "required" | "default_selected" | "unavailable".
+     * Sourced adapters set what they support; thin synthesis defaults to
+     * "optional".
+     */
+    selection_type: z.string().optional(),
+    /**
+     * Pricing mode — mirrors the owned `extra_pricing_mode` enum:
+     * "included" | "per_person" | "per_booking" | "quantity_based" |
+     * "on_request" | "free". Captures the structural pricing model the
+     * upstream advertises; actual prices come through `liveResolve`.
+     */
+    pricing_mode: z.string().optional(),
+    /** Hint — true when the extra is priced per traveler, not per booking. */
+    priced_per_person: z.boolean().optional(),
+    /** Service category (e.g. "transfer", "excursion", "insurance", "spa"). */
+    category: z.string().nullable().optional(),
+    /** Hero media URL. */
+    hero_image_url: z.string().nullable().optional(),
+    highlights: z.array(z.string()).optional(),
+    /** Free-form supplier hint surfaced to ops (not customer-facing). */
+    supplier: z.string().nullable().optional(),
+    /** Estimated duration in minutes for time-bound extras (excursions). */
+    duration_minutes: z.number().int().nonnegative().nullable().optional(),
+    /** Constraints / requirements summary surfaced on the booking flow. */
+    requirements_summary: z.string().nullable().optional(),
+});
+export const extraOptionSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable().optional(),
+    /** Whether this option auto-selects when the extra is selected. */
+    default_selected: z.boolean().optional(),
+});
+export const extraMediaItemSchema = z.object({
+    url: z.string(),
+    type: z.enum(["image", "video", "document"]).default("image"),
+    caption: z.string().nullable().optional(),
+    alt: z.string().nullable().optional(),
+});
+export const extraPolicySchema = z.object({
+    kind: z.enum(["cancellation", "payment", "supplier_notes", "requirements"]),
+    body: z.string(),
+    rules: z.unknown().optional(),
+});
+export const extraContentSchema = z.object({
+    extra: extraSummarySchema,
+    options: z.array(extraOptionSchema).default([]),
+    media: z.array(extraMediaItemSchema).default([]),
+    policies: z.array(extraPolicySchema).default([]),
+});
+export function validateExtraContent(payload) {
+    const result = extraContentSchema.safeParse(payload);
+    if (result.success) {
+        return { valid: true, content: result.data };
+    }
+    const issue = result.error.issues[0];
+    return {
+        valid: false,
+        reason: issue ? `${issue.path.join(".")}: ${issue.message}` : "validation failed",
+    };
+}
+export function mergeOverlaysIntoExtraContent(payload, overlays, options = {}) {
+    const merged = mergeOverlaysIntoContent(payload, overlays, {
+        validate(p) {
+            const r = validateExtraContent(p);
+            return r.valid ? { valid: true } : { valid: false, reason: r.reason };
+        },
+        onOverlayError: options.onOverlayError,
+    });
+    return extraContentSchema.parse(merged);
+}

package/dist/draft-shape.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Project an `ExtraContent` payload into a `BookingDraftShape`.
+ *
+ * Extras are booking add-ons (excursions, transfers, insurance) —
+ * they're never standalone bookable on their own; they always layer
+ * onto a parent product. So the descriptor here is **degenerate**:
+ *
+ *   - `showsConfigure: false` (no configure step — extras are picked
+ *     during the parent product's add-on step).
+ *   - `showsTravelers: false` (extras don't have their own pax flow).
+ *   - `showsPayment: false` (extras roll up into the parent's pricing).
+ *   - `addons.catalog`: the extra itself + its sub-options projected
+ *     as a small catalog. Useful for journey contexts that want to
+ *     render an add-on detail view (e.g. ops admin reviewing a
+ *     supplier's extras).
+ *
+ * In practice templates rarely call this directly — the parent
+ * product's `BookingDraftShape` aggregates extras via the journey's
+ * cross-product composer. This function is the building block.
+ */
+import { type BookingDraftShape } from "@voyantjs/catalog/booking-engine";
+import type { ExtraContent } from "./content-shape.js";
+export interface BuildExtraDraftShapeOptions {
+    locale?: string;
+    /**
+     * When true, returns the full descriptor surface (configure +
+     * travelers + payment all visible). Useful for tests or admin
+     * surfaces that render extras standalone. Defaults to false (the
+     * normal "extras-as-addon" mode).
+     */
+    standalone?: boolean;
+}
+export declare function buildExtraDraftShape(content: ExtraContent, options?: BuildExtraDraftShapeOptions): BookingDraftShape;
+//# sourceMappingURL=draft-shape.d.ts.map

package/dist/draft-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-shape.d.ts","sourceRoot":"","sources":["../src/draft-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EAMvB,MAAM,kCAAkC,CAAA;AAEzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAMtD,MAAM,WAAW,2BAA2B;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,2BAAgC,GACxC,iBAAiB,CAsCnB"}

package/dist/draft-shape.js

@@ -0,0 +1,69 @@
+/**
+ * Project an `ExtraContent` payload into a `BookingDraftShape`.
+ *
+ * Extras are booking add-ons (excursions, transfers, insurance) —
+ * they're never standalone bookable on their own; they always layer
+ * onto a parent product. So the descriptor here is **degenerate**:
+ *
+ *   - `showsConfigure: false` (no configure step — extras are picked
+ *     during the parent product's add-on step).
+ *   - `showsTravelers: false` (extras don't have their own pax flow).
+ *   - `showsPayment: false` (extras roll up into the parent's pricing).
+ *   - `addons.catalog`: the extra itself + its sub-options projected
+ *     as a small catalog. Useful for journey contexts that want to
+ *     render an add-on detail view (e.g. ops admin reviewing a
+ *     supplier's extras).
+ *
+ * In practice templates rarely call this directly — the parent
+ * product's `BookingDraftShape` aggregates extras via the journey's
+ * cross-product composer. This function is the building block.
+ */
+import { defaultBookingFields, defaultDraftShapeFlags, defaultTravelerFields, paxBandsAllowedTotalFrom, } from "@voyantjs/catalog/booking-engine";
+const DEGENERATE_PAX_BANDS = [
+    { code: "adult", label: "Adult", minCount: 0, maxCount: 8 },
+];
+export function buildExtraDraftShape(content, options = {}) {
+    const flags = defaultDraftShapeFlags();
+    const standalone = options.standalone ?? false;
+    // Project the extra + its options as add-on offers. The extra
+    // itself becomes the lead item; sub-options follow.
+    const items = [
+        {
+            id: content.extra.id,
+            name: content.extra.name,
+            description: content.extra.description ?? null,
+            kind: kindForExtraCategory(content.extra.category ?? null),
+            pricingMode: content.extra.pricing_mode ?? null,
+        },
+        ...content.options.map((opt) => ({
+            id: opt.id,
+            name: opt.name,
+            description: opt.description ?? null,
+            kind: "extras",
+            pricingMode: null,
+        })),
+    ];
+    return {
+        ...flags,
+        showsConfigure: standalone,
+        showsTravelers: standalone,
+        showsPayment: standalone,
+        showsAddons: true,
+        paxBands: DEGENERATE_PAX_BANDS,
+        paxBandsAllowedTotal: paxBandsAllowedTotalFrom(DEGENERATE_PAX_BANDS),
+        travelerFields: standalone ? defaultTravelerFields() : [],
+        bookingFields: standalone ? defaultBookingFields() : [],
+        addons: { catalog: items },
+        paymentIntents: standalone ? ["hold", "card"] : [],
+    };
+}
+function kindForExtraCategory(category) {
+    if (!category)
+        return "extras";
+    const lower = category.toLowerCase();
+    if (lower.includes("excursion") || lower.includes("tour"))
+        return "excursions";
+    if (lower.includes("insurance"))
+        return "insurance";
+    return "extras";
+}