Augeo AI Docs
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

ItemValue
Documentation versionv1
Version ruleStays v1 until a breaking surface schema change
Schema draftJSON Schema draft-07

Trace metadata

Use this table to confirm the page matches the published schema file.

FieldValue
Source filenameaugeo-assistant-surface.schema.json
Schema $idhttps://kigo-digital.github.io/augeo-ai-sdks/chat-sdk/augeo-assistant-surface.schema.json
Documentation versionv1
Source digestsha256:f72a6e67872766e7c164029b71dd7af113d00c86377030b5cbfff7d2a1a9db20

Root object

Presentation surface for AugeoAssistantOptions.

AspectValue
TypeInlineSurface | ModalSurface | SidebarSurface
Required fieldstype
Additional propertiesAllowed

Root fields

FieldTypeRequiredDefaultDescription
type"inline" | "modal" | "sidebar"Yes—Required discriminant that selects the presentation shell.

Definitions

AskAiOptions

Ask AI island injection for launchable modal and sidebar surfaces.

AspectValue
Typeobject
Required fieldsbutton, seedFrom
Additional propertiesRejects additional properties.

Fields

FieldTypeRequiredDefaultDescription
buttonstringYes—CSS selector for the container the Ask AI button is injected into.
seedFromstringYes—CSS selector for the host search input that seeds launch context.
timeoutMsnumberNo1500Upper bound in milliseconds on waiting for the Ask AI island to attach.

SidebarWidthAt

AspectValue
Typeobject
Required fields—
Additional propertiesRejects additional properties.

Fields

FieldTypeRequiredDefaultDescription
basestringNo——
minstringNo——
maxstringNo——

SidebarWidth

Docked sidebar size.

AspectValue
Typeobject
Required fields—
Additional propertiesRejects additional properties.

Fields

FieldTypeRequiredDefaultDescription
basestringNo"clamp(320px, 30vw, 480px)"Sidebar width when docked.
minstringNo—Minimum clamp for the docked width.
maxstringNo—Maximum clamp for the docked width.
atobjectNo——

InlineSurface

Fills the host mount container.

AspectValue
Typeobject
Required fieldstype
Additional propertiesRejects additional properties.

Fields

FieldTypeRequiredDefaultDescription
typeconst "inline"Yes—Selects the inline shell.

ModalSurface

Overlay shell with optional FAB and Ask AI island.

AspectValue
Typeobject
Required fieldstype
Additional propertiesRejects additional properties.

Fields

FieldTypeRequiredDefaultDescription
typeconst "modal"Yes—Selects the modal overlay shell.
openOnMountbooleanNofalseWhen true, auto-launches the modal surface on mount.
askAiAskAiOptionsNo——
fabbooleanNo—Optional boolean override for the floating launcher button, with no boolean default.

SidebarSurface

Docks beside host content and reflows the page.

AspectValue
Typeobject
Required fieldstype
Additional propertiesRejects additional properties.

Fields

FieldTypeRequiredDefaultDescription
typeconst "sidebar"Yes—Selects the sidebar shell.
openOnMountbooleanNofalseWhen true, auto-launches the sidebar surface on mount.
askAiAskAiOptionsNo——
fabbooleanNo—Optional boolean override for the floating launcher button, with no boolean default.
containerstringNo—Optional CSS selector for a host-provided sidebar mount element.
widthSidebarWidthNo——
side"left" | "right"No"right"Which side to dock on.
mobileBreakpointintegerNo767Breakpoint 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."
        }
      }
    }
  }
}