@8xlabsai/hekaya-playbook-schema

Zod schema for Hekaya live-demo playbooks. Defines the canonical step format (navigate, highlight, click, fill, branch, cta) shared by the SDK runtime, Chrome extension recorder, and orchestrator post-processor. Ships with a universal default playbook (8 steps, bilingual ar+en Khaleeji narration) so every tenant has a working live demo from day 1.

Install

pnpm add @8xlabsai/hekaya-playbook-schema

Quickstart

Validate a playbook before serving it to the SDK:

import {
  PlaybookSchema,
  loadDefaultPlaybook,
  type Playbook,
} from '@8xlabsai/hekaya-playbook-schema';

// Load the universal default (parsed + validated):
const defaultPlaybook = loadDefaultPlaybook();
console.log(defaultPlaybook.playbook_id, 'v' + defaultPlaybook.version);
// → "hekaya-default-explore v1"

// Validate a tenant-authored playbook:
const tenantJson = await fetch('/api/playbooks/face-id-demo').then((r) => r.json());
const result = PlaybookSchema.safeParse(tenantJson);
if (!result.success) {
  console.error('Invalid playbook:', result.error.flatten());
  process.exit(1);
}
const playbook: Playbook = result.data;

// Walk the steps:
for (const step of playbook.steps) {
  console.log(step.step_id, step.type);
  if ('selectors' in step) console.log(' ', step.selectors.primary);
  if ('narration' in step) console.log(' ', step.narration.en);
}

What's exported

• PlaybookSchema — top-level zod object: playbook_id, version, scenario (intent + tags + trigger_examples + threshold), mode (guide / drive), voice (style + WPM + pause), steps[].
• StepSchema — discriminated union over six kinds: navigate, highlight, click, fill, branch (conditions + jump_to), cta (offer_meeting / capture_email / human_handoff).
• SelectorTupleSchema — primary → secondary → fallback. Selector kinds: aria_role_text, data_attr, text, css, xpath.
• NarrationSchema — { ar, en, audio_cache_key? }.
• loadDefaultPlaybook() — returns the parsed universal default.
• TypeScript types — Playbook, PlaybookStep, Narration, SelectorTuple, Selector.

Source

Monorepo: github.com/8xlabs-ai/hekaya.ai → packages/playbook-schema/.

License

MIT