@v-office/website-chat 0.0.0 → 1.0.0

package/README.md

@@ -1,3 +1,55 @@
 # @v-office/website-chat
 
-Placeholder that holds the name on npm until the first release.
+The AI chat of a v-office website. A visitor asks for a stay; the chat searches the agency's rentals,
+shows them as cards with the PMS's prices, and links each stay to its rental page with the dates and party
+filled in. It never books and has no form of its own.
+
+**Peers:** React `^19.2.3`, `@v-office/website-headless` `>=1.1.0 <2`. Sites pin exact versions.
+
+## Entry points
+
+| Import                           | Contents                                                        |
+| :------------------------------- | :-------------------------------------------------------------- |
+| `@v-office/website-chat`         | `WebsiteChat`, `DEFAULT_COPY`, `CHAT_THEMES`, `CHAT_LOCALES`    |
+| `@v-office/website-chat/catalog` | the json-render catalog and wire protocol, for the chat service |
+
+## Adding the chat to a site
+
+Render `WebsiteChat` once in the layout as a client island; see `instructions/versions/1.0.0/MIGRATION.md`.
+
+```astro
+<WebsiteChat client:idle endpoint={import.meta.env.PUBLIC_CHAT_ENDPOINT} locale="de"
+  searchPath="/suche" contactPath="/kontakt" />
+```
+
+| Prop          | Required | Meaning                                                                  |
+| :------------ | :------- | :----------------------------------------------------------------------- |
+| `endpoint`    | yes      | `import.meta.env.PUBLIC_CHAT_ENDPOINT`, which AI Studio's builds set     |
+| `locale`      | yes      | `"de"` or `"en"`                                                         |
+| `searchPath`  | yes      | the site's search, for a rental without a page and when the chat is down |
+| `contactPath` | yes      | the site's contact page                                                  |
+| `theme`       | no       | `classic` (default), `soft` or `minimal`                                 |
+| `colors`      | no       | `{ primary, secondary }`, any CSS colour (buttons; visitor messages)     |
+| `position`    | no       | the entry pill and the panel on the `right` (default) or `left`          |
+| `copy`        | no       | overrides of single fields of `DEFAULT_COPY` (strings, `suggestions`)    |
+
+The chat stays hidden until an agent switches it on for the website in AI Studio.
+
+A site with a sticky header sets `--chat-top` (its height) on any element around the widget, such as
+`:root`: the dimmed page and the panel start below it. `--chat-width` widens the panel on wide screens
+(default `600px`).
+
+The service places these components in replies: `RentalCard` (photo gallery, rating, the wishes the
+search that found it applied), `RentalCarousel`, `Compare`, `StayQuote`, `PriceBreakdown`,
+`AlternativeStays`, `AvailabilityCalendar`, `PriceCalendar`, `ReviewSummary`, `RentalFacts`,
+`RentalMap`, `StayLink`, `ContactLink` and `QuickReplies`. They all read the PMS's data by id; none takes a price, a URL or
+free text from the AI (QuickReplies' short answers excepted). `RentalMap` loads its map (MapLibre,
+OpenFreeMap tiles) only when the visitor taps it.
+
+## Development
+
+```sh
+pnpm check && pnpm build && pnpm test
+```
+
+See `AGENTS.md` and `docs/internal/releasing/overview.md`.

package/dist/catalog-RXKmEmMW.js

@@ -0,0 +1,183 @@
+import { defineCatalog } from "@json-render/core";
+import { schema } from "@json-render/react/schema";
+import { z } from "zod";
+//#region src/state.ts
+/** See {@link StateKey}. */
+const stateKey = (id) => id.replaceAll("~", "~0").replaceAll("/", "~1");
+/** See {@link StatePath}. */
+const statePath = (section, id) => `/${section}/${stateKey(id)}`;
+//#endregion
+//#region src/catalog.ts
+const id = z.string().min(1).max(200);
+/** A rental, with the stay to show for it when there is one. */
+const offer = z.object({
+	rentalId: id,
+	stayId: id.nullable()
+});
+/** Every component of the chat. `Stack` is the service's root; the others the model places. */
+const chatCatalog = defineCatalog(schema, {
+	components: {
+		Stack: {
+			props: z.object({}),
+			slots: ["default"],
+			description: "Stacks what the reply shows. Placed by the service, never by the model."
+		},
+		RentalCard: {
+			props: offer,
+			description: "One rental with its photos, rating and facts; with a stayId also that stay's dates, price and a booking button."
+		},
+		RentalCarousel: {
+			props: z.object({ items: z.array(offer).min(2).max(8) }),
+			description: "Several rentals side by side, swipeable, each as a RentalCard. Use it for search results instead of several RentalCards."
+		},
+		StayQuote: {
+			props: z.object({ stayId: id }),
+			description: "One priced stay: the rental, the dates, the party, the total and a booking button."
+		},
+		PriceBreakdown: {
+			props: z.object({ stayId: id }),
+			description: "What a quoted stay's total is made of (nights, cleaning, pets, …), line by line. Only for a stay from quote_stay."
+		},
+		AlternativeStays: {
+			props: z.object({
+				rentalId: id,
+				stayIds: z.array(id).min(1).max(6)
+			}),
+			description: "Free periods of one rental as tappable choices with their prices: other dates when the asked ones are taken, or the periods a flexible search found."
+		},
+		AvailabilityCalendar: {
+			props: z.object({
+				rentalId: id,
+				stayId: id.nullable()
+			}),
+			description: "A rental's month calendar of free and taken days, with a stay's dates marked when there is one. Only after get_availability."
+		},
+		PriceCalendar: {
+			props: z.object({ rentalId: id }),
+			description: "One rental's total for the same length of stay at the arrivals around the asked one, cheapest marked; tapping one asks for it. Only after price_calendar."
+		},
+		ReviewSummary: {
+			props: z.object({ rentalId: id }),
+			description: "A rental's guest rating as the booking system sums it up, its category ratings and a few review texts. Only after get_reviews."
+		},
+		RentalFacts: {
+			props: z.object({
+				rentalId: id,
+				groups: z.array(z.string().trim().min(1).max(80)).min(1).max(4)
+			}),
+			description: "The facts of one rental in the groups get_rental listed (by their label, such as Haustiere or Lage), for a question about pets, the kitchen or the surroundings."
+		},
+		RentalMap: {
+			props: z.object({ rentalId: id }),
+			description: "Where one rental is: a map the visitor loads with a tap, and a link to its page."
+		},
+		Compare: {
+			props: z.object({ items: z.array(offer).min(2).max(3) }),
+			description: "Two or three rentals side by side: rating, rooms, highlights, the stay and its price."
+		},
+		StayLink: {
+			props: z.object({
+				rentalId: id,
+				stayId: id.nullable()
+			}),
+			description: "A button to the rental's page on this website, with the stay filled in, to book there."
+		},
+		ContactLink: {
+			props: z.object({}),
+			description: "A link to this website's contact page."
+		},
+		QuickReplies: {
+			props: z.object({ options: z.array(z.string().trim().min(1).max(40)).min(1).max(4) }),
+			description: "Up to four short answers the visitor can tap to send as their next message (\"Nur mit Sauna\", \"Andere Termine\"). Never a fact or a price."
+		}
+	},
+	actions: {}
+});
+/** The components the model may place; `Stack` is the service's. */
+const PLACEABLE_COMPONENTS = [
+	"RentalCard",
+	"RentalCarousel",
+	"StayQuote",
+	"PriceBreakdown",
+	"AlternativeStays",
+	"AvailabilityCalendar",
+	"PriceCalendar",
+	"ReviewSummary",
+	"RentalFacts",
+	"RentalMap",
+	"Compare",
+	"StayLink",
+	"ContactLink",
+	"QuickReplies"
+];
+/** The package version each component was added in. A minor adds components (and optional props, which an
+*  older renderer ignores); the service offers a widget only what its version has. */
+const COMPONENT_SINCE = {
+	Stack: "1.0.0",
+	RentalCard: "1.0.0",
+	RentalCarousel: "1.0.0",
+	StayQuote: "1.0.0",
+	PriceBreakdown: "1.0.0",
+	AlternativeStays: "1.0.0",
+	AvailabilityCalendar: "1.0.0",
+	PriceCalendar: "1.0.0",
+	ReviewSummary: "1.0.0",
+	RentalFacts: "1.0.0",
+	RentalMap: "1.0.0",
+	Compare: "1.0.0",
+	StayLink: "1.0.0",
+	ContactLink: "1.0.0",
+	QuickReplies: "1.0.0"
+};
+const versionOf = (version) => {
+	const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+	return match ? [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	] : null;
+};
+/** See {@link ComponentsFor}. */
+const componentsFor = (clientVersion) => {
+	const client = versionOf(clientVersion);
+	if (!client) return [];
+	return PLACEABLE_COMPONENTS.filter((name) => {
+		const since = versionOf(COMPONENT_SINCE[name]);
+		if (since[0] !== client[0]) return false;
+		return since[1] < client[1] || since[1] === client[1] && since[2] <= client[2];
+	});
+};
+/** See {@link ParseItem}. */
+const parseItem = (item, allowed) => {
+	if (typeof item !== "object" || item === null) return null;
+	const { type, props } = item;
+	const name = allowed.find((candidate) => candidate === type);
+	if (!name) return null;
+	const parsed = chatCatalog.data.components[name].props.safeParse(props ?? {});
+	return parsed.success ? {
+		type: name,
+		props: parsed.data
+	} : null;
+};
+/** See {@link ChatSpec}. */
+const chatSpec = (items, state) => {
+	const keys = items.map((_, index) => `item-${index}`);
+	return {
+		root: "root",
+		elements: {
+			root: {
+				type: "Stack",
+				props: {},
+				children: keys
+			},
+			...Object.fromEntries(items.map((item, index) => [keys[index], {
+				type: item.type,
+				props: { ...item.props },
+				children: []
+			}]))
+		},
+		state: { ...state }
+	};
+};
+//#endregion
+export { componentsFor as a, statePath as c, chatSpec as i, PLACEABLE_COMPONENTS as n, parseItem as o, chatCatalog as r, stateKey as s, COMPONENT_SINCE as t };

package/dist/catalog.d.ts

@@ -0,0 +1,303 @@
+import { a as ChatLocale, c as MAX_MESSAGE_CHARS, i as ChatEvent, l as SESSION_TTL_S, n as CHAT_PATH, o as ChatRequest, r as ChatAvailability, s as ChatUnavailableReason, t as CHAT_LOCALES } from "./protocol-Bmb_uxVQ.js";
+import { Spec } from "@json-render/core";
+import { z } from "zod";
+import { Party } from "@v-office/website-headless";
+//#region src/state.d.ts
+/** One photo of a rental, as the PMS serves it. */
+interface ChatImage {
+  readonly src: string;
+  /** The PMS's description; empty when it has none. */
+  readonly alt: string;
+}
+/** A rental as the chat shows it: facts from the PMS, never from the model. */
+interface ChatRental {
+  readonly id: string;
+  readonly name: string;
+  /** Its first photos (at most 8), in the PMS's order; empty without any. */
+  readonly images: readonly ChatImage[];
+  /** Where it is, as the PMS names the place. */
+  readonly place: string | null;
+  /** Short facts the PMS highlights ("Sauna", "4 Gäste"). */
+  readonly highlights: readonly string[];
+  /** The review summary as the PMS formats it ("4,8", "36"); `null` without reviews. */
+  readonly rating: {
+    readonly value: string;
+    readonly count: string;
+  } | null;
+  /** The rooms as the PMS sums them up ("3 Schlafzimmer"); empty when unknown. */
+  readonly rooms: readonly string[];
+  /** Where it is, as the PMS publishes it; absent or `null` without coordinates. */
+  readonly location?: {
+    readonly lat: number;
+    readonly lng: number;
+  } | null;
+}
+/** A stay of one rental for one party, priced by the PMS. */
+interface ChatStay {
+  readonly id: string;
+  readonly rentalId: string;
+  /** `YYYY-MM-DD`. */
+  readonly start: string;
+  /** `YYYY-MM-DD`, after `start`. */
+  readonly end: string;
+  readonly party: Party;
+  /** The total as the SDK formats it ("1.234,00 €"); `null` when the PMS gave none. */
+  readonly total: string | null;
+  /** Whether the PMS can book this stay as asked. */
+  readonly bookable: boolean;
+  /** The total's lines as the PMS's quote lists them ("Endreinigung", "120,00 €"); empty when only
+   *  the total is known (a search result). */
+  readonly lines: readonly {
+    readonly label: string;
+    readonly amount: string;
+  }[];
+}
+/** A day of a rental's calendar: bookable, taken, or outside what can be booked (past, closed). */
+type ChatDayStatus = "free" | "booked" | "closed";
+/** A rental's calendar for a stretch of days, as the PMS answered it. */
+interface ChatCalendar {
+  /** `YYYY-MM-DD`, the first day asked for. */
+  readonly from: string;
+  /** `YYYY-MM-DD`, the last day asked for. */
+  readonly through: string;
+  /** Every day from `from` through `through`. */
+  readonly days: Readonly<Record<string, ChatDayStatus>>;
+}
+/** One stay length's totals for the arrivals around the asked one, as the PMS priced them. */
+interface ChatPriceCalendar {
+  readonly nights: number;
+  /** In date order. A taken or unbookable arrival has no stay. */
+  readonly options: readonly {
+    readonly start: string;
+    readonly end: string;
+    readonly stayId: string | null;
+    /** The total relative to the dearest option, 0 to 1, for the bar; `null` when unknown. */
+    readonly level: number | null;
+  }[];
+  /** The arrival the visitor asked for. */
+  readonly asked: string;
+  /** The cheapest option's stay, only where it saves: below the asked stay, or below another option
+   *  when the asked one has no price. `null` otherwise (equal totals, the asked stay already the
+   *  cheapest, nothing priced): `null` does not mean nothing is bookable. */
+  readonly cheapest: string | null;
+}
+/** A rental's reviews as the PMS summarises them, with a few of their texts. */
+interface ChatReviews {
+  /** As the PMS formats them ("4,8", "36"). */
+  readonly rating: string;
+  readonly count: string;
+  /** The PMS's verbal grade ("Hervorragend"); empty when it has none. */
+  readonly grade: string;
+  readonly categories: readonly {
+    readonly label: string;
+    readonly rating: string;
+  }[];
+  /** At most three, shortened, without the reviewer's name: newest first where the PMS dates its
+   *  reviews (v10), otherwise in its order. */
+  readonly excerpts: readonly {
+    readonly text: string;
+  }[];
+}
+/** One group of a rental's facts as the PMS lists them ("Küche", "Lage"). */
+interface ChatFactGroup {
+  readonly label: string;
+  readonly items: readonly string[];
+}
+/** The state of one spec: everything its components read, keyed by the raw id. */
+interface ChatState {
+  readonly rentals: Readonly<Record<string, ChatRental>>;
+  readonly stays: Readonly<Record<string, ChatStay>>;
+  /** A rental's page on this website in the visitor's language; absent without one. */
+  readonly pages: Readonly<Record<string, string>>;
+  /** A rental's calendar, by rental id; only for rentals whose calendar was asked for. */
+  readonly availability: Readonly<Record<string, ChatCalendar>>;
+  /** A rental's price calendar, by rental id (PriceCalendar). */
+  readonly priceCalendars: Readonly<Record<string, ChatPriceCalendar>>;
+  /** A rental's reviews, by rental id (ReviewSummary). */
+  readonly reviews: Readonly<Record<string, ChatReviews>>;
+  /** A rental's fact groups, by rental id (RentalFacts). */
+  readonly facts: Readonly<Record<string, readonly ChatFactGroup[]>>;
+  /** The visitor's wishes the latest search that found a rental applied ("Sauna", "Haustiere
+   *  erlaubt"), as the PMS labels its filters, by rental id: the rental has each. With dates or
+   *  without; absent when that search applied none. */
+  readonly wishes: Readonly<Record<string, readonly string[]>>;
+}
+/** An id as one JSON Pointer token (RFC 6901): a v10 rental id may contain `/` or `~`, which would
+ *  otherwise change the path a component reads. State stays keyed by the raw id; only paths escape it. */
+type StateKey = (id: string) => string;
+/** The pointer a component reads one entry from (`/rentals/<escaped id>`). */
+type StatePath = (section: keyof ChatState, id: string) => string;
+/** See {@link StateKey}. */
+export declare const stateKey: StateKey;
+/** See {@link StatePath}. */
+export declare const statePath: StatePath;
+//#endregion
+//#region src/catalog.d.ts
+/** Every component of the chat. `Stack` is the service's root; the others the model places. */
+export declare const chatCatalog: import("@json-render/core").Catalog<{
+  spec: import("@json-render/core").SchemaType<"object", {
+    root: import("@json-render/core").SchemaType<"string", unknown>;
+    elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
+      type: import("@json-render/core").SchemaType<"ref", string>;
+      props: import("@json-render/core").SchemaType<"propsOf", string>;
+      children: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
+      slots: {
+        optional: true;
+        kind: "record";
+        inner?: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>> | undefined;
+      };
+      visible: {
+        optional: true;
+        kind: "any";
+        inner?: unknown;
+      };
+      repeat: {
+        optional: true;
+        kind: "any";
+        inner?: unknown;
+      };
+    }>>;
+  }>;
+  catalog: import("@json-render/core").SchemaType<"object", {
+    components: import("@json-render/core").SchemaType<"map", {
+      props: import("@json-render/core").SchemaType<"zod", unknown>;
+      slots: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
+      description: import("@json-render/core").SchemaType<"string", unknown>;
+      example: import("@json-render/core").SchemaType<"any", unknown>;
+    }>;
+    actions: import("@json-render/core").SchemaType<"map", {
+      params: import("@json-render/core").SchemaType<"zod", unknown>;
+      description: import("@json-render/core").SchemaType<"string", unknown>;
+    }>;
+  }>;
+}, {
+  components: {
+    Stack: {
+      props: z.ZodObject<{}, z.core.$strip>;
+      slots: string[];
+      description: string;
+    };
+    RentalCard: {
+      props: z.ZodObject<{
+        rentalId: z.ZodString;
+        stayId: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>;
+      description: string;
+    };
+    RentalCarousel: {
+      props: z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+          rentalId: z.ZodString;
+          stayId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+      }, z.core.$strip>;
+      description: string;
+    };
+    StayQuote: {
+      props: z.ZodObject<{
+        stayId: z.ZodString;
+      }, z.core.$strip>;
+      description: string;
+    };
+    PriceBreakdown: {
+      props: z.ZodObject<{
+        stayId: z.ZodString;
+      }, z.core.$strip>;
+      description: string;
+    };
+    AlternativeStays: {
+      props: z.ZodObject<{
+        rentalId: z.ZodString;
+        stayIds: z.ZodArray<z.ZodString>;
+      }, z.core.$strip>;
+      description: string;
+    };
+    AvailabilityCalendar: {
+      props: z.ZodObject<{
+        rentalId: z.ZodString;
+        stayId: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>;
+      description: string;
+    };
+    PriceCalendar: {
+      props: z.ZodObject<{
+        rentalId: z.ZodString;
+      }, z.core.$strip>;
+      description: string;
+    };
+    ReviewSummary: {
+      props: z.ZodObject<{
+        rentalId: z.ZodString;
+      }, z.core.$strip>;
+      description: string;
+    };
+    RentalFacts: {
+      props: z.ZodObject<{
+        rentalId: z.ZodString;
+        groups: z.ZodArray<z.ZodString>;
+      }, z.core.$strip>;
+      description: string;
+    };
+    RentalMap: {
+      props: z.ZodObject<{
+        rentalId: z.ZodString;
+      }, z.core.$strip>;
+      description: string;
+    };
+    Compare: {
+      props: z.ZodObject<{
+        items: z.ZodArray<z.ZodObject<{
+          rentalId: z.ZodString;
+          stayId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+      }, z.core.$strip>;
+      description: string;
+    };
+    StayLink: {
+      props: z.ZodObject<{
+        rentalId: z.ZodString;
+        stayId: z.ZodNullable<z.ZodString>;
+      }, z.core.$strip>;
+      description: string;
+    };
+    ContactLink: {
+      props: z.ZodObject<{}, z.core.$strip>;
+      description: string;
+    };
+    QuickReplies: {
+      props: z.ZodObject<{
+        options: z.ZodArray<z.ZodString>;
+      }, z.core.$strip>;
+      description: string;
+    };
+  };
+  actions: {};
+}>;
+export type ChatComponent = keyof typeof chatCatalog.data.components;
+/** The components the model may place; `Stack` is the service's. */
+export declare const PLACEABLE_COMPONENTS: readonly ["RentalCard", "RentalCarousel", "StayQuote", "PriceBreakdown", "AlternativeStays", "AvailabilityCalendar", "PriceCalendar", "ReviewSummary", "RentalFacts", "RentalMap", "Compare", "StayLink", "ContactLink", "QuickReplies"];
+export type PlaceableComponent = (typeof PLACEABLE_COMPONENTS)[number];
+/** The package version each component was added in. A minor adds components (and optional props, which an
+ *  older renderer ignores); the service offers a widget only what its version has. */
+export declare const COMPONENT_SINCE: Readonly<Record<ChatComponent, string>>;
+/** One component the model asked to show, as the service's `show` tool takes it. */
+export interface ChatItem {
+  readonly type: PlaceableComponent;
+  readonly props: Readonly<Record<string, unknown>>;
+}
+/** The placeable components a widget of `clientVersion` renders: same major, added at or before it.
+ *  An unreadable version gets none, so an unknown widget is never sent what it cannot draw. */
+type ComponentsFor = (clientVersion: string) => PlaceableComponent[];
+/** An item's props checked against its component (json-render checks props only for one-component
+ *  catalogs). `null` when the type is not allowed or the props do not fit. */
+type ParseItem = (item: unknown, allowed: readonly PlaceableComponent[]) => ChatItem | null;
+/** The spec of one reply: the items stacked under the service's root, and the state they read. */
+type ChatSpec = (items: readonly ChatItem[], state: ChatState) => Spec;
+/** See {@link ComponentsFor}. */
+export declare const componentsFor: ComponentsFor;
+/** See {@link ParseItem}. */
+export declare const parseItem: ParseItem;
+/** See {@link ChatSpec}. */
+export declare const chatSpec: ChatSpec;
+//#endregion
+export { CHAT_LOCALES, CHAT_PATH, type ChatAvailability, type ChatCalendar, type ChatDayStatus, type ChatEvent, type ChatFactGroup, type ChatImage, type ChatLocale, type ChatPriceCalendar, type ChatRental, type ChatRequest, type ChatReviews, type ChatState, type ChatStay, type ChatUnavailableReason, MAX_MESSAGE_CHARS, SESSION_TTL_S };

package/dist/catalog.js

@@ -0,0 +1,3 @@
+import { i as SESSION_TTL_S, n as CHAT_PATH, r as MAX_MESSAGE_CHARS, t as CHAT_LOCALES } from "./protocol-BuNqZAMt.js";
+import { a as componentsFor, c as statePath, i as chatSpec, n as PLACEABLE_COMPONENTS, o as parseItem, r as chatCatalog, s as stateKey, t as COMPONENT_SINCE } from "./catalog-RXKmEmMW.js";
+export { CHAT_LOCALES, CHAT_PATH, COMPONENT_SINCE, MAX_MESSAGE_CHARS, PLACEABLE_COMPONENTS, SESSION_TTL_S, chatCatalog, chatSpec, componentsFor, parseItem, stateKey, statePath };