@voyantjs/extras-contracts 0.90.0

package/README.md

@@ -0,0 +1,30 @@
+# @voyantjs/extras-contracts
+
+Pure extras content contracts for adapter implementers and external consumers
+that need to validate `extras/v1` rich content payloads without installing the
+full extras runtime package.
+
+Use this package for `EXTRAS_CONTENT_SCHEMA_VERSION`, `extraContentSchema`,
+`ExtraContent`, nested content types, and `validateExtraContent`. Use
+`@voyantjs/extras` when you also need Drizzle schema, routes, services, booking
+integration, catalog projection, or runtime content resolution (including the
+`mergeOverlaysIntoExtraContent` overlay composition).
+
+## Install
+
+```bash
+pnpm add @voyantjs/extras-contracts zod
+```
+
+## Usage
+
+```ts
+import {
+  EXTRAS_CONTENT_SCHEMA_VERSION,
+  extraContentSchema,
+  type ExtraContent,
+} from "@voyantjs/extras-contracts"
+```
+
+Existing `@voyantjs/extras/content-shape` imports remain available for
+applications that already depend on the full runtime package.

package/dist/content-shape.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ *
+ * This module is the pure content contract: schemas, types, version, and
+ * the validator. The `mergeOverlaysIntoExtraContent` overlay composition
+ * stays in the `@voyantjs/extras` runtime package.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.2, §3.5.4, §3.6.
+ */
+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<{
+        cancellation: "cancellation";
+        payment: "payment";
+        supplier_notes: "supplier_notes";
+        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<{
+            cancellation: "cancellation";
+            payment: "payment";
+            supplier_notes: "supplier_notes";
+            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;
+};
+//# 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;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,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"}

package/dist/content-shape.js

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ *
+ * This module is the pure content contract: schemas, types, version, and
+ * the validator. The `mergeOverlaysIntoExtraContent` overlay composition
+ * stays in the `@voyantjs/extras` runtime package.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.2, §3.5.4, §3.6.
+ */
+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",
+    };
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=content-shape.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content-shape.test.d.ts","sourceRoot":"","sources":["../src/content-shape.test.ts"],"names":[],"mappings":""}

package/dist/content-shape.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { EXTRAS_CONTENT_SCHEMA_VERSION, extraContentSchema, validateExtraContent, } from "./index.js";
+describe("@voyantjs/extras-contracts content shape", () => {
+    it("validates the extras/v1 rich content payload", () => {
+        const content = extraContentSchema.parse({
+            extra: { id: "prx_abc", name: "Airport Transfer", category: "transfer" },
+            options: [{ id: "opt_private", name: "Private Vehicle" }],
+            media: [{ url: "https://cdn.example.com/transfer.jpg" }],
+            policies: [{ kind: "cancellation", body: "Free up to 24h before." }],
+        });
+        expect(EXTRAS_CONTENT_SCHEMA_VERSION).toBe("extras/v1");
+        expect(validateExtraContent(content)).toMatchObject({ valid: true });
+        expect(content.options).toHaveLength(1);
+        expect(content.media[0]?.type).toBe("image");
+    });
+    it("defaults the options, media, and policies arrays to empty", () => {
+        const content = extraContentSchema.parse({
+            extra: { id: "prx_abc", name: "Spa Day Pass" },
+        });
+        expect(content.options).toEqual([]);
+        expect(content.media).toEqual([]);
+        expect(content.policies).toEqual([]);
+    });
+    it("rejects payloads missing the required extra summary", () => {
+        expect(validateExtraContent({ options: [] })).toMatchObject({ valid: false });
+        expect(validateExtraContent({ extra: { id: "x" } })).toMatchObject({ valid: false });
+    });
+    it("rejects unknown policy kinds and media types", () => {
+        expect(validateExtraContent({
+            extra: { id: "prx_abc", name: "Airport Transfer" },
+            policies: [{ kind: "loyalty", body: "x" }],
+        })).toMatchObject({ valid: false });
+        expect(validateExtraContent({
+            extra: { id: "prx_abc", name: "Airport Transfer" },
+            media: [{ url: "https://cdn.example.com/x.bin", type: "audio" }],
+        })).toMatchObject({ valid: false });
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./content-shape.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./content-shape.js";

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@voyantjs/extras-contracts",
+  "version": "0.90.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./content-shape": "./src/content-shape.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "pnpm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./content-shape": {
+        "types": "./dist/content-shape.d.ts",
+        "import": "./dist/content-shape.js",
+        "default": "./dist/content-shape.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@voyantjs/voyant-typescript-config": "workspace:*",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyantjs/voyant.git",
+    "directory": "packages/extras-contracts"
+  }
+}