@susilkumar006/widgets-test 1.0.0

package/dist/types/api.d.cts

@@ -0,0 +1,60 @@
+/**
+ * Contracts for how the SDK reaches the FacePe backend: what the host supplies
+ * to `<FacePeProvider>`, and the session event it receives back.
+ */
+import type { FacePeNavigationRequest } from './events.cjs';
+import type { FacePeFormValues } from './form.cjs';
+import type { FacePePickerOption } from './picker.cjs';
+import type { FacePeTimelineItem } from './timeline.cjs';
+/** HTTP methods the SDK's API client sends. */
+export type FacePeHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** What the SDK tells the host when it asks for a token. */
+export type FacePeTokenRequest = {
+    /**
+     * The audience the token must be exchanged for at the identity layer
+     * (architecture §7.4): always `'app-b'`, the FacePe service.
+     */
+    readonly audience: 'app-b';
+    /**
+     * `true` after the backend rejected the previous token (HTTP 401): return a
+     * fresh token rather than a cached one.
+     */
+    readonly forceRefresh: boolean;
+};
+/**
+ * Supplies the access token for API requests. Implemented by the host — the
+ * SDK never signs in, and never stores the token it is given.
+ */
+export type FacePeTokenProvider = (request: FacePeTokenRequest) => string | Promise<string>;
+/** Payload of the provider's `sessionExpired` event. Carries no credentials. */
+export type FacePeSessionExpiredPayload = {
+    /** The request that was refused even with a fresh token. */
+    readonly method: FacePeHttpMethod;
+    readonly path: string;
+};
+/**
+ * Events `<FacePeProvider>` delivers: `sessionExpired` from its API client,
+ * and every component's `navigate` request (the context-bridge navigation
+ * callback, so the host can wire its router once).
+ */
+export type FacePeProviderEvents = {
+    readonly sessionExpired: FacePeSessionExpiredPayload;
+    readonly navigate: FacePeNavigationRequest;
+};
+/**
+ * Gateway payloads (architecture §6.1, §7.5): the data the components fetch
+ * from the FacePe gateway when an entity is passed by `entityId`. Validated at
+ * runtime on arrival; unknown fields are ignored. A JSON Schema of each ships
+ * in the package (`@facepe/widgets/schemas/<TypeName>.schema.json`).
+ */
+/** `GET /orders/:id/timeline` — an order's status history, oldest first. */
+export type FacePeTimelinePayload = {
+    readonly items: readonly FacePeTimelineItem[];
+    readonly orderNumber?: string;
+};
+/** `GET /locations/:id/categories` — the menu categories offered at a location. */
+export type FacePePickerOptionsPayload = {
+    readonly options: readonly FacePePickerOption[];
+};
+/** `GET` and `PUT /orders/:id/customer` — an order's customer details and notes. */
+export type FacePeCustomerPayload = FacePeFormValues;

package/dist/types/api.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Contracts for how the SDK reaches the FacePe backend: what the host supplies
+ * to `<FacePeProvider>`, and the session event it receives back.
+ */
+import type { FacePeNavigationRequest } from './events.js';
+import type { FacePeFormValues } from './form.js';
+import type { FacePePickerOption } from './picker.js';
+import type { FacePeTimelineItem } from './timeline.js';
+/** HTTP methods the SDK's API client sends. */
+export type FacePeHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** What the SDK tells the host when it asks for a token. */
+export type FacePeTokenRequest = {
+    /**
+     * The audience the token must be exchanged for at the identity layer
+     * (architecture §7.4): always `'app-b'`, the FacePe service.
+     */
+    readonly audience: 'app-b';
+    /**
+     * `true` after the backend rejected the previous token (HTTP 401): return a
+     * fresh token rather than a cached one.
+     */
+    readonly forceRefresh: boolean;
+};
+/**
+ * Supplies the access token for API requests. Implemented by the host — the
+ * SDK never signs in, and never stores the token it is given.
+ */
+export type FacePeTokenProvider = (request: FacePeTokenRequest) => string | Promise<string>;
+/** Payload of the provider's `sessionExpired` event. Carries no credentials. */
+export type FacePeSessionExpiredPayload = {
+    /** The request that was refused even with a fresh token. */
+    readonly method: FacePeHttpMethod;
+    readonly path: string;
+};
+/**
+ * Events `<FacePeProvider>` delivers: `sessionExpired` from its API client,
+ * and every component's `navigate` request (the context-bridge navigation
+ * callback, so the host can wire its router once).
+ */
+export type FacePeProviderEvents = {
+    readonly sessionExpired: FacePeSessionExpiredPayload;
+    readonly navigate: FacePeNavigationRequest;
+};
+/**
+ * Gateway payloads (architecture §6.1, §7.5): the data the components fetch
+ * from the FacePe gateway when an entity is passed by `entityId`. Validated at
+ * runtime on arrival; unknown fields are ignored. A JSON Schema of each ships
+ * in the package (`@facepe/widgets/schemas/<TypeName>.schema.json`).
+ */
+/** `GET /orders/:id/timeline` — an order's status history, oldest first. */
+export type FacePeTimelinePayload = {
+    readonly items: readonly FacePeTimelineItem[];
+    readonly orderNumber?: string;
+};
+/** `GET /locations/:id/categories` — the menu categories offered at a location. */
+export type FacePePickerOptionsPayload = {
+    readonly options: readonly FacePePickerOption[];
+};
+/** `GET` and `PUT /orders/:id/customer` — an order's customer details and notes. */
+export type FacePeCustomerPayload = FacePeFormValues;

package/dist/types/avatar.d.cts

@@ -0,0 +1,102 @@
+/**
+ * Contracts of `<FacePeAvatar>`: the FacePe avatar conversation, embedded.
+ */
+import type { FacePeComponentProps, FacePeHandleMethod } from './components.cjs';
+import type { FacePeStandardEvents } from './events.cjs';
+import type { FacePeFallbackContext } from './placement.cjs';
+/** An avatar the signed-in user may use (from the gateway). */
+export type FacePeAvatarInfo = {
+    /** The avatar_id. */
+    readonly id: string;
+    readonly name: string;
+    readonly gender: string;
+    readonly previewUrl?: string | null;
+    readonly description?: string | null;
+    /** Languages it speaks (ISO 639-1); empty means all supported ones. */
+    readonly languages: readonly string[];
+};
+/** Where the conversation stands. */
+export type FacePeAvatarStatus = 'idle' | 'connecting' | 'live' | 'ended' | 'error';
+/** One line of the conversation. */
+export type FacePeTranscriptLine = {
+    readonly role: 'user' | 'assistant';
+    readonly text: string;
+    readonly id?: string;
+};
+/** Payload of `sessionStart`. */
+export type FacePeAvatarSession = {
+    readonly avatarId: string;
+    /** The usage record of this conversation (minutes and points are counted on it). */
+    readonly usageId: string | null;
+};
+/** Payload of `sessionEnd`. */
+export type FacePeAvatarSessionEnd = {
+    readonly avatarId: string;
+    readonly usageId: string | null;
+    /** `ended`: by the user or `end()`; `disconnected`: the stream dropped; `unmounted`: the component went away. */
+    readonly reason: 'ended' | 'disconnected' | 'unmounted';
+};
+/** Events `<FacePeAvatar>` emits. `ready` carries no data (`null`). */
+export type FacePeAvatarEvents = {
+    readonly ready: null;
+    readonly sessionStart: FacePeAvatarSession;
+    readonly sessionEnd: FacePeAvatarSessionEnd;
+    readonly transcript: FacePeTranscriptLine;
+    /** The order the conversation has built so far (avatars trained to take orders). */
+    readonly orderUpdate: {
+        readonly items: readonly {
+            readonly name: string;
+            readonly qty: number;
+        }[];
+    };
+    readonly error: FacePeStandardEvents['error'];
+};
+/** What the `controls` slot's render function receives. */
+export type FacePeAvatarControlsContext = {
+    readonly status: FacePeAvatarStatus;
+    readonly muted: boolean;
+    start(): void;
+    end(): void;
+    setMuted(muted: boolean): void;
+};
+/**
+ * Host-rendered regions: `header` above the avatar; `controls` replacing the
+ * built-in Start / Mute / End bar; `fallback` in place of the component if it
+ * fails to render. @default none
+ */
+export type FacePeAvatarSlots = {
+    readonly header: void;
+    readonly controls: FacePeAvatarControlsContext;
+    readonly fallback: FacePeFallbackContext;
+};
+/** Props of `<FacePeAvatar>`. */
+export type FacePeAvatarProps = FacePeComponentProps<FacePeAvatarEvents, FacePeAvatarSlots> & {
+    /**
+     * The avatar_id to talk to; it must be assigned to the user whose keys the
+     * host uses. Without one (here or on the provider), the component loads
+     * the user's assigned avatars itself and lets the user choose one.
+     * @default the provider's `avatarId`, else the user's avatars
+     */
+    readonly avatarId?: string;
+    /** The language the user will speak (ISO 639-1, e.g. `'en'`, `'hi'`). @default the avatar's default */
+    readonly language?: string;
+    /**
+     * Start the conversation on mount. Browsers allow sound and the microphone
+     * only after a user gesture, so by default the user presses Start.
+     * @default false
+     */
+    readonly autoStart?: boolean;
+    /** Show the latest lines of the conversation under the avatar. @default true */
+    readonly captions?: boolean;
+};
+/** Imperative handle of `<FacePeAvatar>`, reached through a React `ref`. */
+export interface FacePeAvatarHandle {
+    /** Moves keyboard focus to the main control (Start, or End while live). */
+    readonly focus: FacePeHandleMethod;
+    /** Starts the conversation (as the Start button does). */
+    readonly start: FacePeHandleMethod;
+    /** Ends the conversation and frees the session. */
+    readonly end: FacePeHandleMethod;
+    /** Mutes or unmutes the user's microphone. */
+    readonly setMuted: FacePeHandleMethod<[muted: boolean]>;
+}

package/dist/types/avatar.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Contracts of `<FacePeAvatar>`: the FacePe avatar conversation, embedded.
+ */
+import type { FacePeComponentProps, FacePeHandleMethod } from './components.js';
+import type { FacePeStandardEvents } from './events.js';
+import type { FacePeFallbackContext } from './placement.js';
+/** An avatar the signed-in user may use (from the gateway). */
+export type FacePeAvatarInfo = {
+    /** The avatar_id. */
+    readonly id: string;
+    readonly name: string;
+    readonly gender: string;
+    readonly previewUrl?: string | null;
+    readonly description?: string | null;
+    /** Languages it speaks (ISO 639-1); empty means all supported ones. */
+    readonly languages: readonly string[];
+};
+/** Where the conversation stands. */
+export type FacePeAvatarStatus = 'idle' | 'connecting' | 'live' | 'ended' | 'error';
+/** One line of the conversation. */
+export type FacePeTranscriptLine = {
+    readonly role: 'user' | 'assistant';
+    readonly text: string;
+    readonly id?: string;
+};
+/** Payload of `sessionStart`. */
+export type FacePeAvatarSession = {
+    readonly avatarId: string;
+    /** The usage record of this conversation (minutes and points are counted on it). */
+    readonly usageId: string | null;
+};
+/** Payload of `sessionEnd`. */
+export type FacePeAvatarSessionEnd = {
+    readonly avatarId: string;
+    readonly usageId: string | null;
+    /** `ended`: by the user or `end()`; `disconnected`: the stream dropped; `unmounted`: the component went away. */
+    readonly reason: 'ended' | 'disconnected' | 'unmounted';
+};
+/** Events `<FacePeAvatar>` emits. `ready` carries no data (`null`). */
+export type FacePeAvatarEvents = {
+    readonly ready: null;
+    readonly sessionStart: FacePeAvatarSession;
+    readonly sessionEnd: FacePeAvatarSessionEnd;
+    readonly transcript: FacePeTranscriptLine;
+    /** The order the conversation has built so far (avatars trained to take orders). */
+    readonly orderUpdate: {
+        readonly items: readonly {
+            readonly name: string;
+            readonly qty: number;
+        }[];
+    };
+    readonly error: FacePeStandardEvents['error'];
+};
+/** What the `controls` slot's render function receives. */
+export type FacePeAvatarControlsContext = {
+    readonly status: FacePeAvatarStatus;
+    readonly muted: boolean;
+    start(): void;
+    end(): void;
+    setMuted(muted: boolean): void;
+};
+/**
+ * Host-rendered regions: `header` above the avatar; `controls` replacing the
+ * built-in Start / Mute / End bar; `fallback` in place of the component if it
+ * fails to render. @default none
+ */
+export type FacePeAvatarSlots = {
+    readonly header: void;
+    readonly controls: FacePeAvatarControlsContext;
+    readonly fallback: FacePeFallbackContext;
+};
+/** Props of `<FacePeAvatar>`. */
+export type FacePeAvatarProps = FacePeComponentProps<FacePeAvatarEvents, FacePeAvatarSlots> & {
+    /**
+     * The avatar_id to talk to; it must be assigned to the user whose keys the
+     * host uses. Without one (here or on the provider), the component loads
+     * the user's assigned avatars itself and lets the user choose one.
+     * @default the provider's `avatarId`, else the user's avatars
+     */
+    readonly avatarId?: string;
+    /** The language the user will speak (ISO 639-1, e.g. `'en'`, `'hi'`). @default the avatar's default */
+    readonly language?: string;
+    /**
+     * Start the conversation on mount. Browsers allow sound and the microphone
+     * only after a user gesture, so by default the user presses Start.
+     * @default false
+     */
+    readonly autoStart?: boolean;
+    /** Show the latest lines of the conversation under the avatar. @default true */
+    readonly captions?: boolean;
+};
+/** Imperative handle of `<FacePeAvatar>`, reached through a React `ref`. */
+export interface FacePeAvatarHandle {
+    /** Moves keyboard focus to the main control (Start, or End while live). */
+    readonly focus: FacePeHandleMethod;
+    /** Starts the conversation (as the Start button does). */
+    readonly start: FacePeHandleMethod;
+    /** Ends the conversation and frees the session. */
+    readonly end: FacePeHandleMethod;
+    /** Mutes or unmutes the user's microphone. */
+    readonly setMuted: FacePeHandleMethod<[muted: boolean]>;
+}

package/dist/types/common.d.cts

@@ -0,0 +1,42 @@
+/**
+ * Building blocks shared by every FacePe contract.
+ */
+/** Identifier of an entity the component fetches itself (never the entity's data). */
+export type EntityId = string;
+/** Identifier that ties an event or result back to the request that caused it. */
+export type CorrelationId = string;
+/** BCP 47 language tag, e.g. "en", "en-IN", "ta-IN". */
+export type FacePeLocale = string;
+/** Whether a component only presents data or lets the user change it. */
+export type FacePeMode = 'view' | 'edit';
+/** Spacing density of a component, to fit dense or spacious host layouts. */
+export type FacePeDensity = 'compact' | 'comfortable';
+/** Named on/off switches. A flag the component does not know is ignored. */
+export type FacePeFeatureFlags = Readonly<Record<string, boolean>>;
+/** Any value that survives JSON serialisation unchanged. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+export type JsonArray = readonly JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+/**
+ * Constraint for data objects passed in or out of the SDK.
+ *
+ * Payload interfaces must be JSON-serialisable so they can be described by a
+ * JSON Schema and recorded as contract-test fixtures. Unknown fields are
+ * ignored, which keeps additions backwards compatible.
+ */
+export type FacePeDataObject = JsonObject;
+/**
+ * The one error shape used across the SDK: in failed results and in the
+ * payload of `error` events.
+ */
+export interface FacePeError {
+    /** Stable, machine-readable code, e.g. "NOT_FOUND". Safe to branch on. */
+    readonly code: string;
+    /** Human-readable description. For logs, not for display to end users. */
+    readonly message: string;
+    /** Optional structured detail. */
+    readonly details?: JsonValue;
+}

package/dist/types/common.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Building blocks shared by every FacePe contract.
+ */
+/** Identifier of an entity the component fetches itself (never the entity's data). */
+export type EntityId = string;
+/** Identifier that ties an event or result back to the request that caused it. */
+export type CorrelationId = string;
+/** BCP 47 language tag, e.g. "en", "en-IN", "ta-IN". */
+export type FacePeLocale = string;
+/** Whether a component only presents data or lets the user change it. */
+export type FacePeMode = 'view' | 'edit';
+/** Spacing density of a component, to fit dense or spacious host layouts. */
+export type FacePeDensity = 'compact' | 'comfortable';
+/** Named on/off switches. A flag the component does not know is ignored. */
+export type FacePeFeatureFlags = Readonly<Record<string, boolean>>;
+/** Any value that survives JSON serialisation unchanged. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+export type JsonArray = readonly JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+/**
+ * Constraint for data objects passed in or out of the SDK.
+ *
+ * Payload interfaces must be JSON-serialisable so they can be described by a
+ * JSON Schema and recorded as contract-test fixtures. Unknown fields are
+ * ignored, which keeps additions backwards compatible.
+ */
+export type FacePeDataObject = JsonObject;
+/**
+ * The one error shape used across the SDK: in failed results and in the
+ * payload of `error` events.
+ */
+export interface FacePeError {
+    /** Stable, machine-readable code, e.g. "NOT_FOUND". Safe to branch on. */
+    readonly code: string;
+    /** Human-readable description. For logs, not for display to end users. */
+    readonly message: string;
+    /** Optional structured detail. */
+    readonly details?: JsonValue;
+}

package/dist/types/components.d.cts

@@ -0,0 +1,53 @@
+/**
+ * Generic contracts that concrete FacePe components build on: props, slots
+ * and imperative handles. Components themselves are added in later tasks.
+ */
+import type { ReactNode } from 'react';
+import type { FacePeConfig } from './config.cjs';
+import type { FacePeEventHandlers, FacePeEventMap, FacePeStandardEvents } from './events.cjs';
+import type { AsyncResult } from './results.cjs';
+/**
+ * A host-rendered region inside a component (header, footer, empty state,
+ * row renderer, …): either fixed content, or a render function that receives
+ * the component's context for that region.
+ */
+export type FacePeSlot<TContext = void> = [TContext] extends [void] ? ReactNode : ReactNode | ((context: TContext) => ReactNode);
+/** Map of slot name → the context that slot's render function receives. */
+export type FacePeSlotMap = Readonly<Record<string, unknown>>;
+/** The optional slot props derived from a slot map. */
+export type FacePeSlots<TSlots extends FacePeSlotMap> = {
+    readonly [K in keyof TSlots]?: FacePeSlot<TSlots[K]>;
+};
+/** Visual prominence of a component (customization rung L2). */
+export type FacePeEmphasis = 'subtle' | 'default' | 'strong';
+/** Size of a component's type scale (customization rung L2). */
+export type FacePeSize = 'small' | 'medium' | 'large';
+/**
+ * The props every FacePe component accepts: shared configuration, typed
+ * event handlers, host-rendered slots, and the L2 presentation variants.
+ *
+ * @typeParam TEvents - the component's event map (defaults to the standard events).
+ * @typeParam TSlots - the component's slot map (defaults to none).
+ */
+export type FacePeComponentProps<TEvents extends FacePeEventMap = FacePeStandardEvents, TSlots extends FacePeSlotMap = Record<never, never>> = FacePeConfig & FacePeEventHandlers<TEvents> & {
+    /** Host-rendered regions inside the component. */
+    readonly slots?: FacePeSlots<TSlots>;
+    /**
+     * `subtle`: no frame; `default`: a bordered frame; `strong`: a framed,
+     * elevated surface. @default 'default'
+     */
+    readonly emphasis?: FacePeEmphasis;
+    /** Type scale relative to the host's text size. @default 'medium' */
+    readonly size?: FacePeSize;
+};
+/**
+ * One method of an imperative handle. It is asynchronous and resolves to a
+ * `Result`, so it never throws across the component boundary.
+ */
+export type FacePeHandleMethod<TArgs extends readonly unknown[] = [], TData = void> = (...args: TArgs) => AsyncResult<TData>;
+/**
+ * Constraint for a component's imperative handle (reached through a React
+ * `ref`): an object whose members are all handle methods. Kept deliberately
+ * small; most interaction goes through props and events.
+ */
+export type FacePeHandle = Readonly<Record<string, FacePeHandleMethod<never[], unknown>>>;

package/dist/types/components.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Generic contracts that concrete FacePe components build on: props, slots
+ * and imperative handles. Components themselves are added in later tasks.
+ */
+import type { ReactNode } from 'react';
+import type { FacePeConfig } from './config.js';
+import type { FacePeEventHandlers, FacePeEventMap, FacePeStandardEvents } from './events.js';
+import type { AsyncResult } from './results.js';
+/**
+ * A host-rendered region inside a component (header, footer, empty state,
+ * row renderer, …): either fixed content, or a render function that receives
+ * the component's context for that region.
+ */
+export type FacePeSlot<TContext = void> = [TContext] extends [void] ? ReactNode : ReactNode | ((context: TContext) => ReactNode);
+/** Map of slot name → the context that slot's render function receives. */
+export type FacePeSlotMap = Readonly<Record<string, unknown>>;
+/** The optional slot props derived from a slot map. */
+export type FacePeSlots<TSlots extends FacePeSlotMap> = {
+    readonly [K in keyof TSlots]?: FacePeSlot<TSlots[K]>;
+};
+/** Visual prominence of a component (customization rung L2). */
+export type FacePeEmphasis = 'subtle' | 'default' | 'strong';
+/** Size of a component's type scale (customization rung L2). */
+export type FacePeSize = 'small' | 'medium' | 'large';
+/**
+ * The props every FacePe component accepts: shared configuration, typed
+ * event handlers, host-rendered slots, and the L2 presentation variants.
+ *
+ * @typeParam TEvents - the component's event map (defaults to the standard events).
+ * @typeParam TSlots - the component's slot map (defaults to none).
+ */
+export type FacePeComponentProps<TEvents extends FacePeEventMap = FacePeStandardEvents, TSlots extends FacePeSlotMap = Record<never, never>> = FacePeConfig & FacePeEventHandlers<TEvents> & {
+    /** Host-rendered regions inside the component. */
+    readonly slots?: FacePeSlots<TSlots>;
+    /**
+     * `subtle`: no frame; `default`: a bordered frame; `strong`: a framed,
+     * elevated surface. @default 'default'
+     */
+    readonly emphasis?: FacePeEmphasis;
+    /** Type scale relative to the host's text size. @default 'medium' */
+    readonly size?: FacePeSize;
+};
+/**
+ * One method of an imperative handle. It is asynchronous and resolves to a
+ * `Result`, so it never throws across the component boundary.
+ */
+export type FacePeHandleMethod<TArgs extends readonly unknown[] = [], TData = void> = (...args: TArgs) => AsyncResult<TData>;
+/**
+ * Constraint for a component's imperative handle (reached through a React
+ * `ref`): an object whose members are all handle methods. Kept deliberately
+ * small; most interaction goes through props and events.
+ */
+export type FacePeHandle = Readonly<Record<string, FacePeHandleMethod<never[], unknown>>>;

package/dist/types/config.d.cts

@@ -0,0 +1,27 @@
+/**
+ * Configuration: static, serialisable inputs every FacePe component accepts.
+ */
+import type { EntityId, FacePeDensity, FacePeFeatureFlags, FacePeLocale, FacePeMode } from './common.cjs';
+/**
+ * Configuration shared by all FacePe components.
+ *
+ * Every field is optional and has a documented default, so new fields can be
+ * added in a minor release without breaking existing hosts.
+ */
+export interface FacePeConfig {
+    /**
+     * The entity the component works on. It is passed by id only: the
+     * component fetches the entity itself, so host and component never disagree
+     * about freshness or authorisation.
+     * @default undefined (the component starts without an entity)
+     */
+    readonly entityId?: EntityId;
+    /** @default 'view' */
+    readonly mode?: FacePeMode;
+    /** @default the browser's language (`navigator.language`) */
+    readonly locale?: FacePeLocale;
+    /** @default 'comfortable' */
+    readonly density?: FacePeDensity;
+    /** @default {} (every flag off) */
+    readonly featureFlags?: FacePeFeatureFlags;
+}

package/dist/types/config.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Configuration: static, serialisable inputs every FacePe component accepts.
+ */
+import type { EntityId, FacePeDensity, FacePeFeatureFlags, FacePeLocale, FacePeMode } from './common.js';
+/**
+ * Configuration shared by all FacePe components.
+ *
+ * Every field is optional and has a documented default, so new fields can be
+ * added in a minor release without breaking existing hosts.
+ */
+export interface FacePeConfig {
+    /**
+     * The entity the component works on. It is passed by id only: the
+     * component fetches the entity itself, so host and component never disagree
+     * about freshness or authorisation.
+     * @default undefined (the component starts without an entity)
+     */
+    readonly entityId?: EntityId;
+    /** @default 'view' */
+    readonly mode?: FacePeMode;
+    /** @default the browser's language (`navigator.language`) */
+    readonly locale?: FacePeLocale;
+    /** @default 'comfortable' */
+    readonly density?: FacePeDensity;
+    /** @default {} (every flag off) */
+    readonly featureFlags?: FacePeFeatureFlags;
+}

package/dist/types/events.d.cts

@@ -0,0 +1,85 @@
+/**
+ * Events: how a component reports outcomes to the host.
+ *
+ * Every event is an envelope of `type`, `payload` and `meta`. Components declare
+ * their events as a map of event name → payload type; the typed `on…`
+ * handler props are derived from that map, so handler names and event types
+ * cannot drift apart.
+ */
+import type { CorrelationId, EntityId, FacePeError } from './common.cjs';
+/** Metadata stamped on every event. Never carries credentials. */
+export interface FacePeEventMeta {
+    /**
+     * Version of the envelope's shape (`type`, `payload`, `meta`). Changes only
+     * if that shape changes incompatibly, independently of `sdkVersion`.
+     */
+    readonly schemaVersion: 1;
+    /** Ties the event to the request and gateway log entries that caused it. */
+    readonly correlationId: CorrelationId;
+    /** When the event was emitted, as an ISO 8601 timestamp. */
+    readonly timestamp: string;
+    /** Version of the SDK that emitted the event. */
+    readonly sdkVersion: string;
+    /** Name of the emitting component, e.g. "FacePeForm". */
+    readonly source: string;
+    /** The entity the emitting component works on, when it was given an `entityId`. */
+    readonly entityId?: EntityId;
+}
+/**
+ * A request to navigate, raised by a component and carried out by the host's
+ * router (the SDK never changes the URL itself).
+ */
+export type FacePeNavigationRequest = {
+    /** Destination, as the host's routing understands it (a route name, path or deep link). */
+    readonly to: string;
+    /** Route parameters. @default none */
+    readonly params?: Readonly<Record<string, string>>;
+    /** Replace the current history entry instead of pushing one. @default false */
+    readonly replace?: boolean;
+};
+/**
+ * The envelope every FacePe event is delivered in.
+ *
+ * @typeParam TType - the event name, e.g. "submit".
+ * @typeParam TPayload - the event's data.
+ */
+export interface FacePeEvent<TType extends string = string, TPayload = unknown> {
+    readonly type: TType;
+    readonly payload: TPayload;
+    readonly meta: FacePeEventMeta;
+}
+/** Map of event name → payload type that a component emits. */
+export type FacePeEventMap = Readonly<Record<string, unknown>>;
+/**
+ * The standard events defined by the architecture, by category:
+ * - lifecycle: `ready`, `error`
+ * - intent: `select`, `submit`, `cancel`
+ * - navigation: `navigate`
+ *
+ * `error` and `navigate` have fixed payloads; the others are `unknown` here,
+ * and a component narrows the ones it emits by intersecting this map with its
+ * own, e.g. `FacePeStandardEvents & { submit: MyFormValues }`.
+ */
+export type FacePeStandardEvents = {
+    readonly ready: unknown;
+    readonly select: unknown;
+    readonly submit: unknown;
+    readonly cancel: unknown;
+    readonly navigate: FacePeNavigationRequest;
+    readonly error: FacePeError;
+};
+/** The name of a standard event. */
+export type FacePeEventType = keyof FacePeStandardEvents;
+/** A callback receiving one event envelope. */
+export type FacePeEventHandler<TEvent extends FacePeEvent> = (event: TEvent) => void;
+/**
+ * The optional `on…` handler props derived from an event map:
+ * `{ submit: X }` becomes `{ onSubmit?: (event: FacePeEvent<'submit', X>) => void }`.
+ */
+export type FacePeEventHandlers<TEvents extends FacePeEventMap = FacePeStandardEvents> = {
+    readonly [K in keyof TEvents & string as `on${Capitalize<K>}`]?: FacePeEventHandler<FacePeEvent<K, TEvents[K]>>;
+};
+/** Union of every event envelope a component with this event map can emit. */
+export type FacePeEventOf<TEvents extends FacePeEventMap = FacePeStandardEvents> = {
+    [K in keyof TEvents & string]: FacePeEvent<K, TEvents[K]>;
+}[keyof TEvents & string];