@voyantjs/charters-contracts 0.90.0

package/README.md

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

package/dist/content-shape.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Charters content shape — the rich detail-page content shape returned
+ * by `getContent` for sourced charter products.
+ *
+ * The charters content aggregate is `{ charter, yacht, voyages[],
+ * suites[], schedule_days[], policies[] }` — one payload returned by a
+ * single `getContent`. Pricing stays out (volatile-live, flows through
+ * `liveResolve`). Voyages here carry departure dates and structural
+ * info; their fares come through `liveResolve`.
+ *
+ * Charters' MYBA-style products often include APA (Advance
+ * Provisioning Allowance) terms in the policy block — captured under
+ * `policies[].kind: "supplier_notes"` or a structured rule shape. The
+ * synthesizer flattens what the projection knows.
+ *
+ * This module is the pure content contract: schemas, types, version, and
+ * the validator. The `mergeOverlaysIntoCharterContent` overlay
+ * composition stays in the `@voyantjs/charters` runtime package.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.2, §3.5.4, §3.6.
+ */
+import { z } from "zod";
+export declare const CHARTERS_CONTENT_SCHEMA_VERSION = "charters/v1";
+export declare const charterSummarySchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    charter_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    hero_image_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    highlights: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    cruising_area: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    base_port: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    duration_nights: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare const charterYachtSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    length_meters: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    beam_meters: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    capacity_guests: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    capacity_crew: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cabins: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    year_built: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    builder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    amenities: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    images: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+}, z.core.$strip>;
+export declare const charterVoyageSchema: z.ZodObject<{
+    id: z.ZodString;
+    source_ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    departure_date: z.ZodString;
+    return_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    duration_nights: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    embarkation_port: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    disembarkation_port: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    per_suite_bookable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const charterSuiteSchema: z.ZodObject<{
+    id: z.ZodString;
+    code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    capacity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    has_balcony: z.ZodOptional<z.ZodBoolean>;
+    size_sqm: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare const charterScheduleDaySchema: z.ZodObject<{
+    day_number: z.ZodNumber;
+    date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    port_or_anchorage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    is_at_sea: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+export declare const charterPolicySchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        cancellation: "cancellation";
+        payment: "payment";
+        supplier_notes: "supplier_notes";
+        requirements: "requirements";
+        apa: "apa";
+    }>;
+    body: z.ZodString;
+    rules: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const charterContentSchema: z.ZodObject<{
+    charter: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        status: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        charter_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        hero_image_url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        highlights: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        cruising_area: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        base_port: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        duration_nights: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>;
+    yacht: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        length_meters: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        beam_meters: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        capacity_guests: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        capacity_crew: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        cabins: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        year_built: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        builder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        flag: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        amenities: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+        images: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>>>;
+    voyages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        source_ref: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        departure_date: z.ZodString;
+        return_date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        duration_nights: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        embarkation_port: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        disembarkation_port: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        per_suite_bookable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    suites: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        category: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        capacity: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        has_balcony: z.ZodOptional<z.ZodBoolean>;
+        size_sqm: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>>;
+    schedule_days: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        day_number: z.ZodNumber;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        port_or_anchorage: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        is_at_sea: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>>>;
+    policies: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            cancellation: "cancellation";
+            payment: "payment";
+            supplier_notes: "supplier_notes";
+            requirements: "requirements";
+            apa: "apa";
+        }>;
+        body: z.ZodString;
+        rules: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CharterContent = z.infer<typeof charterContentSchema>;
+export type CharterSummary = z.infer<typeof charterSummarySchema>;
+export type CharterYachtContent = z.infer<typeof charterYachtSchema>;
+export type CharterVoyageContent = z.infer<typeof charterVoyageSchema>;
+export type CharterSuiteContent = z.infer<typeof charterSuiteSchema>;
+export type CharterScheduleDay = z.infer<typeof charterScheduleDaySchema>;
+export type CharterPolicy = z.infer<typeof charterPolicySchema>;
+export declare function validateCharterContent(payload: unknown): {
+    valid: true;
+    content: CharterContent;
+} | {
+    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,+BAA+B,gBAAgB,CAAA;AAE5D,eAAO,MAAM,oBAAoB;;;;;;;;;;;iBAW/B,CAAA;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;iBAe7B,CAAA;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAW9B,CAAA;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;iBAS7B,CAAA;AAEF,eAAO,MAAM,wBAAwB;;;;;;iBAMnC,CAAA;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;iBAI9B,CAAA;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAO/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AACjE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AACjE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AACpE,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AACtE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAA;AACpE,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,GACf;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAU7E"}

package/dist/content-shape.js

@@ -0,0 +1,104 @@
+/**
+ * Charters content shape — the rich detail-page content shape returned
+ * by `getContent` for sourced charter products.
+ *
+ * The charters content aggregate is `{ charter, yacht, voyages[],
+ * suites[], schedule_days[], policies[] }` — one payload returned by a
+ * single `getContent`. Pricing stays out (volatile-live, flows through
+ * `liveResolve`). Voyages here carry departure dates and structural
+ * info; their fares come through `liveResolve`.
+ *
+ * Charters' MYBA-style products often include APA (Advance
+ * Provisioning Allowance) terms in the policy block — captured under
+ * `policies[].kind: "supplier_notes"` or a structured rule shape. The
+ * synthesizer flattens what the projection knows.
+ *
+ * This module is the pure content contract: schemas, types, version, and
+ * the validator. The `mergeOverlaysIntoCharterContent` overlay
+ * composition stays in the `@voyantjs/charters` runtime package.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §3.2, §3.5.4, §3.6.
+ */
+import { z } from "zod";
+export const CHARTERS_CONTENT_SCHEMA_VERSION = "charters/v1";
+export const charterSummarySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    status: z.string().optional(),
+    description: z.string().nullable().optional(),
+    charter_type: z.string().nullable().optional(), // "per_suite" | "whole_yacht"
+    hero_image_url: z.string().nullable().optional(),
+    highlights: z.array(z.string()).optional(),
+    cruising_area: z.string().nullable().optional(),
+    base_port: z.string().nullable().optional(),
+    duration_nights: z.number().int().nonnegative().nullable().optional(),
+});
+export const charterYachtSchema = z.object({
+    id: z.string().nullable().optional(),
+    name: z.string(),
+    description: z.string().nullable().optional(),
+    type: z.string().nullable().optional(), // motor / sail / catamaran
+    length_meters: z.number().nullable().optional(),
+    beam_meters: z.number().nullable().optional(),
+    capacity_guests: z.number().int().nonnegative().nullable().optional(),
+    capacity_crew: z.number().int().nonnegative().nullable().optional(),
+    cabins: z.number().int().nonnegative().nullable().optional(),
+    year_built: z.number().int().nonnegative().nullable().optional(),
+    builder: z.string().nullable().optional(),
+    flag: z.string().nullable().optional(),
+    amenities: z.array(z.string()).optional().default([]),
+    images: z.array(z.string()).optional().default([]),
+});
+export const charterVoyageSchema = z.object({
+    id: z.string(),
+    source_ref: z.string().nullable().optional(),
+    departure_date: z.string(),
+    return_date: z.string().nullable().optional(),
+    duration_nights: z.number().int().nonnegative().nullable().optional(),
+    status: z.string().nullable().optional(), // "open" | "on_request" | "sold_out"
+    embarkation_port: z.string().nullable().optional(),
+    disembarkation_port: z.string().nullable().optional(),
+    /** Whole-yacht voyages set this to false; per-suite voyages set true. */
+    per_suite_bookable: z.boolean().optional(),
+});
+export const charterSuiteSchema = z.object({
+    id: z.string(),
+    code: z.string().nullable().optional(),
+    name: z.string(),
+    description: z.string().nullable().optional(),
+    category: z.string().nullable().optional(), // "owner" | "vip" | "guest"
+    capacity: z.number().int().nonnegative().nullable().optional(),
+    has_balcony: z.boolean().optional(),
+    size_sqm: z.number().int().nonnegative().nullable().optional(),
+});
+export const charterScheduleDaySchema = z.object({
+    day_number: z.number().int().positive(),
+    date: z.string().nullable().optional(),
+    port_or_anchorage: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    is_at_sea: z.boolean().optional().default(false),
+});
+export const charterPolicySchema = z.object({
+    kind: z.enum(["cancellation", "payment", "supplier_notes", "requirements", "apa"]),
+    body: z.string(),
+    rules: z.unknown().optional(),
+});
+export const charterContentSchema = z.object({
+    charter: charterSummarySchema,
+    yacht: charterYachtSchema.nullable().optional(),
+    voyages: z.array(charterVoyageSchema).default([]),
+    suites: z.array(charterSuiteSchema).default([]),
+    schedule_days: z.array(charterScheduleDaySchema).default([]),
+    policies: z.array(charterPolicySchema).default([]),
+});
+export function validateCharterContent(payload) {
+    const result = charterContentSchema.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,34 @@
+import { describe, expect, it } from "vitest";
+import { CHARTERS_CONTENT_SCHEMA_VERSION, charterContentSchema, validateCharterContent, } from "./index.js";
+describe("@voyantjs/charters-contracts content shape", () => {
+    it("validates the charters/v1 rich content payload", () => {
+        const content = charterContentSchema.parse({
+            charter: { id: "chrt_abc", name: "Aegean Escape", duration_nights: 7 },
+            yacht: { name: "MY Serenity", type: "motor", capacity_guests: 12 },
+            voyages: [{ id: "chvy_001", departure_date: "2026-06-01" }],
+            schedule_days: [{ day_number: 1, port_or_anchorage: "Athens" }],
+            policies: [{ kind: "apa", body: "APA is 30% of charter fee." }],
+        });
+        expect(CHARTERS_CONTENT_SCHEMA_VERSION).toBe("charters/v1");
+        expect(validateCharterContent(content)).toMatchObject({ valid: true });
+        expect(content.suites).toEqual([]);
+        expect(content.yacht?.amenities).toEqual([]);
+    });
+    it("defaults schedule-day is_at_sea to false", () => {
+        const content = charterContentSchema.parse({
+            charter: { id: "chrt_abc", name: "Aegean Escape" },
+            schedule_days: [{ day_number: 2 }],
+        });
+        expect(content.schedule_days[0]?.is_at_sea).toBe(false);
+    });
+    it("rejects payloads missing the required charter summary", () => {
+        expect(validateCharterContent({ voyages: [] })).toMatchObject({ valid: false });
+        expect(validateCharterContent({ charter: { id: "c" } })).toMatchObject({ valid: false });
+    });
+    it("rejects unknown policy kinds", () => {
+        expect(validateCharterContent({
+            charter: { id: "chrt_abc", name: "Aegean Escape" },
+            policies: [{ kind: "loyalty", body: "x" }],
+        })).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/charters-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/charters-contracts"
+  }
+}