@8xlabsai/hekaya-sdk-core

Vanilla-JS embeddable widget runtime for Hekaya — chat panel + live-demo execution on visitor sites. Ships with Guide mode (highlight + bilingual ar+en tooltip) and Drive mode (auto-execute click / fill / navigate / scroll / wait, with a hard safety floor for password inputs, payment buttons, and cross-origin iframes). Includes selector resilience: 3-tier tuple resolution, shadow-DOM piercing, MutationObserver wait-for-element (3s SPA window).

Install

pnpm add @8xlabsai/hekaya-sdk-core

Or use the script-tag CDN drop (no bundler):

<script>
  window.HEKAYA_CONFIG = {
    tenantPublicKey: 'pk_live_…',
    orchestratorUrl: 'https://api.hekaya.ai',
  };
</script>
<script src="https://cdn.hekaya.ai/loader.iife.js" async></script>

Quickstart (ESM)

import { mount, unmount } from '@8xlabsai/hekaya-sdk-core';

await mount({
  tenantPublicKey: 'pk_live_…',
  orchestratorUrl: 'https://api.hekaya.ai',
  // Optional overrides (server-side widget_config wins by default):
  branding: {
    color_primary: '#0F1B2D',
    color_accent: '#5B8DEF',
    position: 'bottom-right',
    radius: 12,
  },
});

// Later (e.g., on route change in a SPA):
unmount();

The widget mounts a Shadow-DOM-isolated launcher + chat panel. When the orchestrator emits agent_response.actions[], the runtime resolves selectors and executes Guide highlights or Drive primitives automatically.

Direct Guide / Drive APIs (advanced)

For custom integrations that don't want the chat UI:

import {
  resolveSelectorAsync,
  showHighlight,
  executeDriveAction,
  isInExternalFrame,
} from '@8xlabsai/hekaya-sdk-core';

const target = await resolveSelectorAsync({
  primary: { kind: 'aria_role_text', role: 'button', text: 'Sign up' },
  fallback: { kind: 'css', path: 'button[type="submit"]' },
});

if (target && !isInExternalFrame(target)) {
  showHighlight(target, { ar: 'اضغط هنا', en: 'Click here' });
}

Safety policy (Drive mode, non-overridable)

• Never auto-fill <input type="password"> (or autocomplete="*-password").
• Never auto-click in cross-origin iframes (Stripe, Calendly, etc.).
• Never auto-navigate to a different origin.
• Never auto-click payment-intent buttons (regex over text: pay, checkout, confirm payment, place order, إدفع, إتمام الشراء).

Any violation degrades gracefully to a Guide-mode highlight with action_ack { ok: true, executed_kind: 'highlight', degraded: true, error: '<reason>' }.

Source

Monorepo: github.com/8xlabs-ai/hekaya.ai → packages/sdk-core/.

License

MIT