SDKsSchemas
Surface v1
Surface v1
This page documents the surface discriminated union for the public loyalty widget.
Prerequisites
- Read Surfaces for host-facing field guidance.
- Treat this page as the machine-readable contract for surface options.
- Compare host config objects against the tables and JSON below.
Version
| Item | Value |
|---|---|
| Documentation version | v1 |
| Version rule | Stays v1 until a breaking surface schema change |
| Schema draft | JSON Schema draft-07 |
Trace metadata
Use this table to confirm the page matches the published schema file.
| Field | Value |
|---|---|
| Source filename | augeo-assistant-surface.schema.json |
Schema $id | https://kigo-digital.github.io/augeo-ai-sdks/chat-sdk/augeo-assistant-surface.schema.json |
| Documentation version | v1 |
| Source digest | sha256:f72a6e67872766e7c164029b71dd7af113d00c86377030b5cbfff7d2a1a9db20 |
Root object
Presentation surface for AugeoAssistantOptions.
| Aspect | Value |
|---|---|
| Type | InlineSurface | ModalSurface | SidebarSurface |
| Required fields | type |
| Additional properties | Allowed |
Root fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | "inline" | "modal" | "sidebar" | Yes | — | Required discriminant that selects the presentation shell. |
Definitions
AskAiOptions
Ask AI island injection for launchable modal and sidebar surfaces.
| Aspect | Value |
|---|---|
| Type | object |
| Required fields | button, seedFrom |
| Additional properties | Rejects additional properties. |
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
button | string | Yes | — | CSS selector for the container the Ask AI button is injected into. |
seedFrom | string | Yes | — | CSS selector for the host search input that seeds launch context. |
timeoutMs | number | No | 1500 | Upper bound in milliseconds on waiting for the Ask AI island to attach. |
SidebarWidthAt
| Aspect | Value |
|---|---|
| Type | object |
| Required fields | — |
| Additional properties | Rejects additional properties. |
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
base | string | No | — | — |
min | string | No | — | — |
max | string | No | — | — |
SidebarWidth
Docked sidebar size.
| Aspect | Value |
|---|---|
| Type | object |
| Required fields | — |
| Additional properties | Rejects additional properties. |
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
base | string | No | "clamp(320px, 30vw, 480px)" | Sidebar width when docked. |
min | string | No | — | Minimum clamp for the docked width. |
max | string | No | — | Maximum clamp for the docked width. |
at | object | No | — | — |
InlineSurface
Fills the host mount container.
| Aspect | Value |
|---|---|
| Type | object |
| Required fields | type |
| Additional properties | Rejects additional properties. |
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | const "inline" | Yes | — | Selects the inline shell. |
ModalSurface
Overlay shell with optional FAB and Ask AI island.
| Aspect | Value |
|---|---|
| Type | object |
| Required fields | type |
| Additional properties | Rejects additional properties. |
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | const "modal" | Yes | — | Selects the modal overlay shell. |
openOnMount | boolean | No | false | When true, auto-launches the modal surface on mount. |
askAi | AskAiOptions | No | — | — |
fab | boolean | No | — | Optional boolean override for the floating launcher button, with no boolean default. |
SidebarSurface
Docks beside host content and reflows the page.
| Aspect | Value |
|---|---|
| Type | object |
| Required fields | type |
| Additional properties | Rejects additional properties. |
Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | const "sidebar" | Yes | — | Selects the sidebar shell. |
openOnMount | boolean | No | false | When true, auto-launches the sidebar surface on mount. |
askAi | AskAiOptions | No | — | — |
fab | boolean | No | — | Optional boolean override for the floating launcher button, with no boolean default. |
container | string | No | — | Optional CSS selector for a host-provided sidebar mount element. |
width | SidebarWidth | No | — | — |
side | "left" | "right" | No | "right" | Which side to dock on. |
mobileBreakpoint | integer | No | 767 | Breakpoint in px at or below which the sidebar collapses to overlay. |
Full schema
The JSON below is the complete schema document.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://kigo-digital.github.io/augeo-ai-sdks/chat-sdk/augeo-assistant-surface.schema.json",
"title": "AugeoAssistantSurface",
"description": "Presentation surface for AugeoAssistantOptions. Shell selection depends only on the required type discriminant. inline fills the mount container. modal is the overlay with optional FAB and Ask AI. sidebar docks beside host content.",
"type": "object",
"required": [
"type"
],
"additionalProperties": true,
"properties": {
"type": {
"type": "string",
"enum": [
"inline",
"modal",
"sidebar"
],
"description": "Required discriminant that selects the presentation shell. No other field changes which shell renders."
}
},
"oneOf": [
{
"$ref": "#/definitions/InlineSurface"
},
{
"$ref": "#/definitions/ModalSurface"
},
{
"$ref": "#/definitions/SidebarSurface"
}
],
"definitions": {
"AskAiOptions": {
"type": "object",
"additionalProperties": false,
"required": [
"button",
"seedFrom"
],
"description": "Ask AI island injection for launchable modal and sidebar surfaces.",
"properties": {
"button": {
"type": "string",
"minLength": 1,
"description": "CSS selector for the container the Ask AI button is injected into."
},
"seedFrom": {
"type": "string",
"minLength": 1,
"description": "CSS selector for the host search input that seeds launch context."
},
"timeoutMs": {
"type": "number",
"minimum": 0,
"default": 1500,
"description": "Upper bound in milliseconds on waiting for the Ask AI island to attach."
}
}
},
"SidebarWidthAt": {
"type": "object",
"additionalProperties": false,
"properties": {
"base": {
"type": "string"
},
"min": {
"type": "string"
},
"max": {
"type": "string"
}
}
},
"SidebarWidth": {
"type": "object",
"additionalProperties": false,
"description": "Docked sidebar size. base is the default width; min and max clamp it; at holds per-breakpoint overrides keyed by min-width in px.",
"properties": {
"base": {
"type": "string",
"default": "clamp(320px, 30vw, 480px)",
"description": "Sidebar width when docked."
},
"min": {
"type": "string",
"description": "Minimum clamp for the docked width."
},
"max": {
"type": "string",
"description": "Maximum clamp for the docked width."
},
"at": {
"type": "object",
"propertyNames": {
"pattern": "^(0|[1-9][0-9]*)$"
},
"additionalProperties": {
"$ref": "#/definitions/SidebarWidthAt"
}
}
}
},
"InlineSurface": {
"type": "object",
"additionalProperties": false,
"required": [
"type"
],
"description": "Fills the host mount container. Dismissal handlers are code-only and omitted here.",
"properties": {
"type": {
"const": "inline",
"description": "Selects the inline shell."
}
}
},
"ModalSurface": {
"type": "object",
"additionalProperties": false,
"required": [
"type"
],
"description": "Overlay shell with optional FAB and Ask AI island.",
"properties": {
"type": {
"const": "modal",
"description": "Selects the modal overlay shell."
},
"openOnMount": {
"type": "boolean",
"default": false,
"description": "When true, auto-launches the modal surface on mount."
},
"askAi": {
"$ref": "#/definitions/AskAiOptions"
},
"fab": {
"type": "boolean",
"description": "Optional boolean override for the floating launcher button, with no boolean default."
}
}
},
"SidebarSurface": {
"type": "object",
"additionalProperties": false,
"required": [
"type"
],
"description": "Docks beside host content and reflows the page.",
"properties": {
"type": {
"const": "sidebar",
"description": "Selects the sidebar shell."
},
"openOnMount": {
"type": "boolean",
"default": false,
"description": "When true, auto-launches the sidebar surface on mount."
},
"askAi": {
"$ref": "#/definitions/AskAiOptions"
},
"fab": {
"type": "boolean",
"description": "Optional boolean override for the floating launcher button, with no boolean default."
},
"container": {
"type": "string",
"minLength": 1,
"description": "Optional CSS selector for a host-provided sidebar mount element."
},
"width": {
"$ref": "#/definitions/SidebarWidth"
},
"side": {
"type": "string",
"enum": [
"left",
"right"
],
"default": "right",
"description": "Which side to dock on."
},
"mobileBreakpoint": {
"type": "integer",
"minimum": 0,
"default": 767,
"description": "Breakpoint in px at or below which the sidebar collapses to overlay."
}
}
}
}
}Related links
- Configure the surface: Surfaces
- Configure the widget: Configuration
- Review public types: API