@sevenfold/setto-client 0.26.0 → 0.28.0

package/dist/SettoMap.d.ts

@@ -0,0 +1,27 @@
+import { type CSSProperties } from 'react';
+export interface SettoMapProps {
+    /**
+     * i18n key prefix holding `lat`, `lng`, optional `zoom` (1–19, default 15)
+     * and optional `title`. A static string literal, like every other key.
+     */
+    k: string;
+    className?: string;
+    style?: CSSProperties;
+    /** The iframe's loading strategy. Default `lazy`. */
+    loading?: 'lazy' | 'eager';
+}
+/**
+ * A map whose location is content.
+ *
+ * Rendered as an OpenStreetMap embed with a marker on the point, because a
+ * hand-written embed with a guessed pin in the middle of a fjord is what the
+ * build agent produced without it, and nobody could move that pin. Here the
+ * point lives in the locale, so it publishes like text, and in edit mode the
+ * tools Setto serves (`map-tools`) sit over the map to move it.
+ *
+ * The wrapper carries the site's classes in both modes and the iframe fills
+ * it, so a map sized with `h-72 w-full` is the same box whether or not anybody
+ * is editing. Without a usable location the wrapper renders empty — no iframe
+ * pointing at 0,0 — and still takes the tools, so the owner can set one.
+ */
+export declare function SettoMap({ k, className, style, loading }: SettoMapProps): import("react/jsx-runtime").JSX.Element;

package/dist/index.d.ts

@@ -21,6 +21,9 @@ export { SETTO_MODULES } from './modules';
 export type { SettoModule } from './modules';
 export { SettoVideo } from './SettoVideo';
 export type { SettoVideoProps } from './SettoVideo';
+export { SettoMap } from './SettoMap';
+export type { SettoMapProps } from './SettoMap';
+export type { MapLocation, MapToolsProps, MapToolsComponent } from './map-tools';
 export { SettoAnimation } from './SettoAnimation';
 export type { SettoAnimationProps } from './SettoAnimation';
 export { useSectionTheme } from './use-section-theme';

package/dist/lib/map-location.d.ts

@@ -0,0 +1,80 @@
+import type { MapLocation } from '../map-tools';
+import type { I18nStore } from './i18n-store';
+/**
+ * Where a `SettoMap` points, and how that becomes an OpenStreetMap embed.
+ *
+ * The location is content, stored under the map's key in every locale file:
+ * `{ lat, lng, zoom, title }`, all strings, because every other value in those
+ * files is. Pure on purpose — the component, the editor's tools and the tests
+ * all agree on one reading of what the build agent wrote.
+ */
+/** What a locale file holds under a map's key. Every field may be missing. */
+export interface RawMapContent {
+    lat?: unknown;
+    lng?: unknown;
+    zoom?: unknown;
+}
+export declare const MAP_MIN_ZOOM = 1;
+export declare const MAP_MAX_ZOOM = 19;
+export declare const MAP_DEFAULT_ZOOM = 15;
+export declare const MAP_DEFAULT_TITLE = "Kart";
+/** Web mercator stops here; a map centred further north cannot be drawn. */
+export declare const MERCATOR_MAX_LAT = 85.0511287798066;
+/**
+ * The frame the zoom is chosen for.
+ *
+ * The embed is told a bounding box, not a zoom, and fits that box into
+ * whatever size the iframe has. A box sized for a small frame keeps the zoom
+ * the owner chose on anything larger — a phone-width map or a wide `h-72` band
+ * both open at it — where a box sized for a desktop would zoom a phone out.
+ */
+export declare const MAP_ASSUMED_WIDTH = 320;
+export declare const MAP_ASSUMED_HEIGHT = 240;
+/**
+ * A coordinate as the locale spells it.
+ *
+ * Strict about shape, because `Number('')` is 0 and a map of the Gulf of
+ * Guinea is the wrong way to say a value is missing. A decimal comma is
+ * accepted: the owner is Norwegian and so is their keyboard.
+ */
+export declare function parseCoordinate(value: unknown): number | null;
+/**
+ * The zoom, forgiving where the coordinates are not.
+ *
+ * A missing or unreadable zoom still gives a usable map, so it falls back to
+ * the default; a readable one out of range is clamped and rounded rather than
+ * thrown away.
+ */
+export declare function parseZoom(value: unknown): number;
+/** A location, or null when the coordinates are missing, unreadable or off the map. */
+export declare function parseMapLocation(raw: RawMapContent | null | undefined): MapLocation | null;
+/** Six decimals is about ten centimetres; more is noise in a content file. */
+export declare function formatCoordinate(n: number): string;
+/** The strings a location is stored as. */
+export declare function serialiseMapLocation(location: MapLocation): {
+    lat: string;
+    lng: string;
+    zoom: string;
+};
+export interface MapBbox {
+    minLng: number;
+    minLat: number;
+    maxLng: number;
+    maxLat: number;
+}
+/**
+ * The box a frame of `width` × `height` pixels would show, centred on the
+ * location at its zoom. Longitude is linear in web mercator; latitude is not,
+ * so it goes through world pixels and back.
+ */
+export declare function mapBbox(location: MapLocation, width?: number, height?: number): MapBbox;
+/** The OpenStreetMap embed for a location, marker on the point itself. */
+export declare function mapEmbedUrl(location: MapLocation): string;
+/**
+ * Write a location to every language at once.
+ *
+ * A place is not translated, so the same numbers go into each locale, the way
+ * `SettoImage` writes an image path. The title is left alone: that one is
+ * words, and belongs to each language.
+ */
+export declare function writeMapLocation(store: Pick<I18nStore, 'set' | 'batch'>, languages: readonly string[], key: string, location: MapLocation): void;

package/dist/map-tools.d.ts

@@ -0,0 +1,24 @@
+import type { ComponentType } from 'react';
+/**
+ * The contract between a map on the customer's page and the tools Setto
+ * serves for moving it.
+ *
+ * Same split as the form field tools: the search, the draggable preview and
+ * the buttons live in setto-server's chrome and change with a deploy, while
+ * `SettoMap` — compiled into the customer's bundle — applies what they hand
+ * back. So this is the pinned part, and it is deliberately plain data.
+ */
+/** A point on the map and how close to it the map opens. WGS84 degrees; zoom 1–19. */
+export interface MapLocation {
+    lat: number;
+    lng: number;
+    zoom: number;
+}
+export interface MapToolsProps {
+    /** Where the map points now, or null when the content has no usable location. */
+    location: MapLocation | null;
+    /** Move the map. `SettoMap` writes it to every language as a draft. */
+    onChange: (next: MapLocation) => void;
+}
+/** What the chrome registers under `mountSlot('map-tools', …)`. */
+export type MapToolsComponent = ComponentType<MapToolsProps>;

package/dist/modules/chat/SettoChat.d.ts

@@ -7,6 +7,8 @@ type Message = {
     id?: string;
     role: 'visitor' | 'assistant' | 'human' | 'system';
     content: string;
+    /** Server insert time; absent on local optimistic and streaming turns. */
+    created_at?: string;
     reveal?: boolean;
     avatarUrl?: string | null;
     authorName?: string | null;
@@ -23,6 +25,19 @@ export declare function isAtChatBottom(scrollHeight: number, scrollTop: number,
 export declare function AgentJoinedEvent({ message }: {
     message: Message;
 }): import("react/jsx-runtime").JSX.Element;
+/**
+ * A teammate is composing. The row opts out of the transcript's polite live
+ * region so start/stop bursts are not announced, while its label stays
+ * readable when a screen-reader user browses the log.
+ */
+export declare function TeamTypingRow({ label, avatarUrl }: {
+    label: string;
+    avatarUrl: string | null;
+}): import("react/jsx-runtime").JSX.Element;
+/** "Sett"/"Seen" under the visitor's latest message; not announced live. */
+export declare function SeenMarker({ label }: {
+    label: string;
+}): import("react/jsx-runtime").JSX.Element;
 export declare function SiteChatMarkdown({ content, reveal }: {
     content: string;
     reveal?: boolean;

package/dist/modules/chat/realtime.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Pure decisions behind the visitor widget's Realtime doorbell, typing
+ * indicators and read markers. Realtime carries no chat data: every event only
+ * prompts the widget to refetch through the visitor-bound HTTP API, so these
+ * helpers never see message text, names or ids in a payload.
+ */
+/** Fallback poll while no Realtime channel is subscribed (today's cadence). */
+export declare const POLL_FALLBACK_MS = 5000;
+/** Slow safety poll while the conversation channel is subscribed. */
+export declare const POLL_SUBSCRIBED_MS = 30000;
+/** Bursts of `changed` events collapse into one refetch. */
+export declare const CHANGED_DEBOUNCE_MS = 250;
+/** A visitor sends `typing: true` at most this often while composing. */
+export declare const TYPING_THROTTLE_MS = 2500;
+/** A team typing row disappears this long after the last `typing: true`. */
+export declare const TYPING_EXPIRY_MS = 6000;
+export type ChatSide = 'team' | 'visitor';
+export type TypingSignal = {
+    side: ChatSide;
+    typing: boolean;
+};
+export type ReadSignal = {
+    side: ChatSide;
+    at: string;
+};
+/** The subset of a transcript message these decisions read. */
+export type TimelineMessage = {
+    id?: string;
+    role: string;
+    kind?: string;
+    created_at?: string;
+    authorName?: string | null;
+    avatarUrl?: string | null;
+};
+export declare function pollIntervalMs(subscribed: boolean): number;
+/** Only a server-issued conversation topic is joined; clients never build one. */
+export declare function conversationTopic(value: unknown): string | null;
+export declare function parseTypingSignal(payload: unknown): TypingSignal | null;
+export declare function parseReadSignal(payload: unknown): ReadSignal | null;
+/**
+ * Epoch milliseconds with sub-millisecond precision. Postgres returns
+ * microseconds (`…:05.123456+00:00`), which engines may truncate or reject, so
+ * the fraction is added separately and a missing zone is read as UTC.
+ */
+export declare function timestampValue(value: string | null | undefined): number | null;
+/** Monotonic merge: keep whichever valid timestamp is later. */
+export declare function laterTimestamp(current: string | null, next: string | null | undefined): string | null;
+export type TypingSender = {
+    /** Call on every draft change. */
+    update(draft: string): void;
+    /** Draft emptied, message sent, composer blurred or channel leaving. */
+    stop(): void;
+    /** Forget local state without sending (the channel is gone). */
+    reset(): void;
+};
+/**
+ * Throttles visitor typing signals. `send` returns false when the channel is
+ * not subscribed, in which case nothing is considered sent.
+ */
+export declare function createTypingSender(send: (typing: boolean) => boolean, now?: () => number): TypingSender;
+/** The widget shows only team typing; returns the new expiry deadline. */
+export declare function nextTeamTypingDeadline(current: number | null, signal: TypingSignal, now: number): number | null;
+/** Identity of the newest human reply, used to hide typing once it lands. */
+export declare function latestHumanMessageKey(messages: readonly TimelineMessage[]): string | null;
+/** First name and photo of the latest teammate who replied or joined. */
+export declare function teamTypingIdentity(messages: readonly TimelineMessage[]): {
+    name: string | null;
+    avatarUrl: string | null;
+};
+export declare function teamTypingLabel(norwegian: boolean, name: string | null): string;
+/**
+ * Index of the visitor message that carries "Sett"/"Seen", or -1. Only the
+ * latest visitor message qualifies, and only once it has a server timestamp
+ * that a teammate's read receipt has reached.
+ */
+export declare function seenVisitorMessageIndex(messages: readonly TimelineMessage[], humanJoined: boolean, teamReadAt: string | null): number;
+export type ReadMarkerContext = {
+    humanJoined: boolean;
+    chatOpen: boolean;
+    pageVisible: boolean;
+    /** The latest `through` already sent or in flight for this conversation. */
+    lastSent: string | null;
+};
+/**
+ * The `through` value to POST as the visitor's read marker, or null when no
+ * marker should be sent: no human has joined, the chat is closed or hidden, or
+ * nothing newer than the last marker has arrived from Barista or the team.
+ */
+export declare function readMarkerThrough(messages: readonly TimelineMessage[], context: ReadMarkerContext): string | null;
+export type RefreshTicket = {
+    conversationId: string | null;
+    /** Increments whenever a visitor turn starts. */
+    turn: number;
+    /** Increments whenever a newer refetch or conversation load starts. */
+    request: number;
+};
+/**
+ * What to do with a conversation refetch when it resolves. A response that
+ * lands during (or overlapped) a visitor turn would replace the locally
+ * streaming answer, so it is deferred and re-requested once the turn ends.
+ */
+export declare function refreshOutcome(started: RefreshTicket, current: RefreshTicket & {
+    busy: boolean;
+}): 'apply' | 'defer' | 'drop';