@asiyst/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,301 @@
+interface AsiystEventMap {
+    "asiyst:initialized": {
+        projectId: string;
+    };
+    "asiyst:ready": {
+        projectId: string;
+        configVersion: number;
+    };
+    "asiyst:destroyed": {
+        projectId: string;
+    };
+    "asiyst:avatar:shown": {
+        name: string;
+    };
+    "asiyst:avatar:hidden": {
+        name: string;
+    };
+    "asiyst:avatar:moved": {
+        x: number;
+        y: number;
+    };
+    "asiyst:target:found": {
+        target: TargetRef;
+        elementId: string;
+    };
+    "asiyst:target:not-found": {
+        target: TargetRef;
+    };
+    "asiyst:target:highlighted": {
+        elementId: string;
+        style: HighlightStyle;
+    };
+    "asiyst:user:clicked": {
+        elementId: string | null;
+    };
+    "asiyst:task:started": {
+        taskId: string;
+    };
+    "asiyst:task:step-completed": {
+        taskId: string;
+        stepId: string;
+    };
+    "asiyst:task:completed": {
+        taskId: string;
+    };
+    "asiyst:task:failed": {
+        taskId: string;
+        reason: string;
+    };
+    "asiyst:task:cancelled": {
+        taskId: string;
+    };
+    "asiyst:conversation:started": {
+        conversationId: string;
+    };
+    "asiyst:conversation:message": {
+        role: "user" | "assistant";
+        text: string;
+    };
+    "asiyst:conversation:closed": {
+        conversationId: string;
+    };
+    "asiyst:error": {
+        code: string;
+        message: string;
+    };
+}
+type AsiystEventName = keyof AsiystEventMap;
+
+type AnchorPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+type AssistantMode = "guided" | "assist";
+type ActionKind = "navigate" | "click" | "highlight" | "scroll" | "type" | "select" | "open-menu" | "open-modal" | "search" | "wait" | "explain" | "complete";
+type HighlightStyle = "spotlight" | "outline" | "glow" | "pointer" | "pulse" | "dim";
+type ElementKind = "button" | "link" | "input" | "select" | "textarea" | "form" | "navigation" | "heading" | "menu" | "dialog" | "tab" | "card" | "search" | "section" | "other";
+interface TargetRef {
+    id?: string;
+    role?: string;
+    text?: string;
+    selector?: string;
+}
+type TargetInput = string | TargetRef;
+interface InitOptions {
+    projectId: string;
+    publicKey: string;
+    apiBaseUrl?: string;
+    mode?: AssistantMode;
+    allowedActions?: ActionKind[];
+    observeHistory?: boolean;
+}
+interface ThemeConfig {
+    accent?: string;
+    background?: string;
+    text?: string;
+}
+interface BehaviorConfig {
+    walkingSpeed?: number;
+    idleAnimation?: string;
+    pointingAnimation?: string;
+    greetingAnimation?: string;
+    thinkingAnimation?: string;
+    successAnimation?: string;
+    voiceSpeed?: number;
+    speechBubble?: boolean;
+}
+interface ProjectConfig {
+    schemaVersion: number;
+    version: number;
+    avatarName: string;
+    avatar: string;
+    size: number;
+    position: AnchorPosition;
+    voice?: string;
+    animation?: string;
+    theme: ThemeConfig;
+    personality: Record<string, string>;
+    behavior: BehaviorConfig;
+    mode: AssistantMode;
+    allowedActions: ActionKind[];
+    elementSelectors: Record<string, string>;
+}
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ViewportBox {
+    width: number;
+    height: number;
+    scrollX: number;
+    scrollY: number;
+}
+interface SafeInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface MappedElement {
+    id: string;
+    kind: ElementKind;
+    tagName: string;
+    role: string | null;
+    text: string;
+    label: string;
+    href: string | null;
+    pageUrl: string;
+    rect: Rect;
+    visible: boolean;
+    enabled: boolean;
+    developerDefined: boolean;
+    description: string | null;
+    section: string | null;
+}
+interface WebsiteMapSnapshot {
+    pageUrl: string;
+    path: string;
+    title: string;
+    capturedAt: number;
+    elements: MappedElement[];
+}
+interface TaskStep {
+    id: string;
+    action: ActionKind;
+    target?: TargetRef;
+    message?: string;
+    url?: string;
+    value?: string;
+    waitForUser?: boolean;
+    timeoutMs?: number;
+    highlightStyle?: HighlightStyle;
+}
+interface TaskDefinition {
+    id: string;
+    title?: string;
+    steps: TaskStep[];
+}
+interface WorkflowDefinition {
+    id: string;
+    title?: string;
+    steps: TaskStep[];
+}
+
+declare const Asiyst: {
+    init(options: InitOptions): Promise<void>;
+    destroy(): Promise<void>;
+    open(): void;
+    close(): void;
+    getConfig(): ProjectConfig;
+    avatar: {
+        show(): void;
+        hide(): void;
+        moveTo(target: TargetInput): Promise<void>;
+        pointAt(target: TargetInput): Promise<void>;
+        highlight(target: TargetInput, style?: HighlightStyle): Promise<void>;
+        speak(message: string): void;
+        think(): void;
+        celebrate(): void;
+        setPosition(x: number, y: number): void;
+    };
+    task: {
+        start(input: string | TaskDefinition): Promise<void>;
+        cancel(): void;
+    };
+    workflow: {
+        start(workflowId: string): Promise<void>;
+    };
+    on<K extends keyof AsiystEventMap>(event: K, handler: (payload: AsiystEventMap[K]) => void): () => void;
+    off<K extends keyof AsiystEventMap>(event: K, handler: (payload: AsiystEventMap[K]) => void): void;
+};
+
+declare const SDK_VERSION = "0.1.0";
+
+declare class AsiystError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare class ConfigurationError extends AsiystError {
+    constructor(message: string);
+}
+declare class AuthenticationError extends AsiystError {
+    constructor(message: string);
+}
+declare class InitializationError extends AsiystError {
+    constructor(message: string);
+}
+declare class TargetNotFoundError extends AsiystError {
+    constructor(message: string);
+}
+declare class ActionNotAllowedError extends AsiystError {
+    constructor(message: string);
+}
+declare class NetworkError extends AsiystError {
+    constructor(message: string);
+}
+declare class TaskExecutionError extends AsiystError {
+    constructor(message: string);
+}
+
+declare const TaskStatus: {
+    readonly Idle: "idle";
+    readonly UserRequest: "user_request";
+    readonly IntentDetected: "intent_detected";
+    readonly TaskCreated: "task_created";
+    readonly TargetResolved: "target_resolved";
+    readonly ActionStarted: "action_started";
+    readonly WaitingForUser: "waiting_for_user";
+    readonly UserActionDetected: "user_action_detected";
+    readonly StepCompleted: "step_completed";
+    readonly NextStep: "next_step";
+    readonly TaskCompleted: "task_completed";
+    readonly Failed: "failed";
+    readonly Cancelled: "cancelled";
+    readonly Timeout: "timeout";
+    readonly TargetNotFound: "target_not_found";
+};
+type TaskStatus = (typeof TaskStatus)[keyof typeof TaskStatus];
+declare function canTransition(from: TaskStatus, to: TaskStatus): boolean;
+
+declare function fallbackConfig(): ProjectConfig;
+declare function normalizeProjectConfig(raw: unknown): ProjectConfig;
+declare function validateInitOptions(options: {
+    projectId?: unknown;
+    publicKey?: unknown;
+}): {
+    projectId: string;
+    publicKey: string;
+};
+
+declare function isSafeSelector(selector: string): boolean;
+
+declare function sanitizeText(input: string, maxLength?: number): string;
+
+interface MovementPlan {
+    avatarX: number;
+    avatarY: number;
+    facing: "left" | "right";
+    needsScroll: boolean;
+    scrollLeft: number;
+    scrollTop: number;
+}
+interface MovementInput {
+    target: Rect;
+    viewport: ViewportBox;
+    avatarSize: {
+        width: number;
+        height: number;
+    };
+    insets: SafeInsets;
+    gap?: number;
+}
+declare function computeAvatarDestination(input: MovementInput): MovementPlan;
+declare function anchorToViewport(position: "bottom-right" | "bottom-left" | "top-right" | "top-left", viewport: ViewportBox, avatarSize: {
+    width: number;
+    height: number;
+}, insets: SafeInsets): {
+    x: number;
+    y: number;
+};
+
+export { type ActionKind, ActionNotAllowedError, Asiyst, AsiystError, type AsiystEventMap, type AsiystEventName, type AssistantMode, AuthenticationError, ConfigurationError, type HighlightStyle, type InitOptions, InitializationError, type MappedElement, NetworkError, type ProjectConfig, SDK_VERSION, type TargetInput, TargetNotFoundError, type TargetRef, type TaskDefinition, TaskExecutionError, TaskStatus, type TaskStep, type WebsiteMapSnapshot, type WorkflowDefinition, anchorToViewport, canTransition, computeAvatarDestination, fallbackConfig, isSafeSelector, normalizeProjectConfig, sanitizeText, validateInitOptions };

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+interface AsiystEventMap {
+    "asiyst:initialized": {
+        projectId: string;
+    };
+    "asiyst:ready": {
+        projectId: string;
+        configVersion: number;
+    };
+    "asiyst:destroyed": {
+        projectId: string;
+    };
+    "asiyst:avatar:shown": {
+        name: string;
+    };
+    "asiyst:avatar:hidden": {
+        name: string;
+    };
+    "asiyst:avatar:moved": {
+        x: number;
+        y: number;
+    };
+    "asiyst:target:found": {
+        target: TargetRef;
+        elementId: string;
+    };
+    "asiyst:target:not-found": {
+        target: TargetRef;
+    };
+    "asiyst:target:highlighted": {
+        elementId: string;
+        style: HighlightStyle;
+    };
+    "asiyst:user:clicked": {
+        elementId: string | null;
+    };
+    "asiyst:task:started": {
+        taskId: string;
+    };
+    "asiyst:task:step-completed": {
+        taskId: string;
+        stepId: string;
+    };
+    "asiyst:task:completed": {
+        taskId: string;
+    };
+    "asiyst:task:failed": {
+        taskId: string;
+        reason: string;
+    };
+    "asiyst:task:cancelled": {
+        taskId: string;
+    };
+    "asiyst:conversation:started": {
+        conversationId: string;
+    };
+    "asiyst:conversation:message": {
+        role: "user" | "assistant";
+        text: string;
+    };
+    "asiyst:conversation:closed": {
+        conversationId: string;
+    };
+    "asiyst:error": {
+        code: string;
+        message: string;
+    };
+}
+type AsiystEventName = keyof AsiystEventMap;
+
+type AnchorPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
+type AssistantMode = "guided" | "assist";
+type ActionKind = "navigate" | "click" | "highlight" | "scroll" | "type" | "select" | "open-menu" | "open-modal" | "search" | "wait" | "explain" | "complete";
+type HighlightStyle = "spotlight" | "outline" | "glow" | "pointer" | "pulse" | "dim";
+type ElementKind = "button" | "link" | "input" | "select" | "textarea" | "form" | "navigation" | "heading" | "menu" | "dialog" | "tab" | "card" | "search" | "section" | "other";
+interface TargetRef {
+    id?: string;
+    role?: string;
+    text?: string;
+    selector?: string;
+}
+type TargetInput = string | TargetRef;
+interface InitOptions {
+    projectId: string;
+    publicKey: string;
+    apiBaseUrl?: string;
+    mode?: AssistantMode;
+    allowedActions?: ActionKind[];
+    observeHistory?: boolean;
+}
+interface ThemeConfig {
+    accent?: string;
+    background?: string;
+    text?: string;
+}
+interface BehaviorConfig {
+    walkingSpeed?: number;
+    idleAnimation?: string;
+    pointingAnimation?: string;
+    greetingAnimation?: string;
+    thinkingAnimation?: string;
+    successAnimation?: string;
+    voiceSpeed?: number;
+    speechBubble?: boolean;
+}
+interface ProjectConfig {
+    schemaVersion: number;
+    version: number;
+    avatarName: string;
+    avatar: string;
+    size: number;
+    position: AnchorPosition;
+    voice?: string;
+    animation?: string;
+    theme: ThemeConfig;
+    personality: Record<string, string>;
+    behavior: BehaviorConfig;
+    mode: AssistantMode;
+    allowedActions: ActionKind[];
+    elementSelectors: Record<string, string>;
+}
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ViewportBox {
+    width: number;
+    height: number;
+    scrollX: number;
+    scrollY: number;
+}
+interface SafeInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+interface MappedElement {
+    id: string;
+    kind: ElementKind;
+    tagName: string;
+    role: string | null;
+    text: string;
+    label: string;
+    href: string | null;
+    pageUrl: string;
+    rect: Rect;
+    visible: boolean;
+    enabled: boolean;
+    developerDefined: boolean;
+    description: string | null;
+    section: string | null;
+}
+interface WebsiteMapSnapshot {
+    pageUrl: string;
+    path: string;
+    title: string;
+    capturedAt: number;
+    elements: MappedElement[];
+}
+interface TaskStep {
+    id: string;
+    action: ActionKind;
+    target?: TargetRef;
+    message?: string;
+    url?: string;
+    value?: string;
+    waitForUser?: boolean;
+    timeoutMs?: number;
+    highlightStyle?: HighlightStyle;
+}
+interface TaskDefinition {
+    id: string;
+    title?: string;
+    steps: TaskStep[];
+}
+interface WorkflowDefinition {
+    id: string;
+    title?: string;
+    steps: TaskStep[];
+}
+
+declare const Asiyst: {
+    init(options: InitOptions): Promise<void>;
+    destroy(): Promise<void>;
+    open(): void;
+    close(): void;
+    getConfig(): ProjectConfig;
+    avatar: {
+        show(): void;
+        hide(): void;
+        moveTo(target: TargetInput): Promise<void>;
+        pointAt(target: TargetInput): Promise<void>;
+        highlight(target: TargetInput, style?: HighlightStyle): Promise<void>;
+        speak(message: string): void;
+        think(): void;
+        celebrate(): void;
+        setPosition(x: number, y: number): void;
+    };
+    task: {
+        start(input: string | TaskDefinition): Promise<void>;
+        cancel(): void;
+    };
+    workflow: {
+        start(workflowId: string): Promise<void>;
+    };
+    on<K extends keyof AsiystEventMap>(event: K, handler: (payload: AsiystEventMap[K]) => void): () => void;
+    off<K extends keyof AsiystEventMap>(event: K, handler: (payload: AsiystEventMap[K]) => void): void;
+};
+
+declare const SDK_VERSION = "0.1.0";
+
+declare class AsiystError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+declare class ConfigurationError extends AsiystError {
+    constructor(message: string);
+}
+declare class AuthenticationError extends AsiystError {
+    constructor(message: string);
+}
+declare class InitializationError extends AsiystError {
+    constructor(message: string);
+}
+declare class TargetNotFoundError extends AsiystError {
+    constructor(message: string);
+}
+declare class ActionNotAllowedError extends AsiystError {
+    constructor(message: string);
+}
+declare class NetworkError extends AsiystError {
+    constructor(message: string);
+}
+declare class TaskExecutionError extends AsiystError {
+    constructor(message: string);
+}
+
+declare const TaskStatus: {
+    readonly Idle: "idle";
+    readonly UserRequest: "user_request";
+    readonly IntentDetected: "intent_detected";
+    readonly TaskCreated: "task_created";
+    readonly TargetResolved: "target_resolved";
+    readonly ActionStarted: "action_started";
+    readonly WaitingForUser: "waiting_for_user";
+    readonly UserActionDetected: "user_action_detected";
+    readonly StepCompleted: "step_completed";
+    readonly NextStep: "next_step";
+    readonly TaskCompleted: "task_completed";
+    readonly Failed: "failed";
+    readonly Cancelled: "cancelled";
+    readonly Timeout: "timeout";
+    readonly TargetNotFound: "target_not_found";
+};
+type TaskStatus = (typeof TaskStatus)[keyof typeof TaskStatus];
+declare function canTransition(from: TaskStatus, to: TaskStatus): boolean;
+
+declare function fallbackConfig(): ProjectConfig;
+declare function normalizeProjectConfig(raw: unknown): ProjectConfig;
+declare function validateInitOptions(options: {
+    projectId?: unknown;
+    publicKey?: unknown;
+}): {
+    projectId: string;
+    publicKey: string;
+};
+
+declare function isSafeSelector(selector: string): boolean;
+
+declare function sanitizeText(input: string, maxLength?: number): string;
+
+interface MovementPlan {
+    avatarX: number;
+    avatarY: number;
+    facing: "left" | "right";
+    needsScroll: boolean;
+    scrollLeft: number;
+    scrollTop: number;
+}
+interface MovementInput {
+    target: Rect;
+    viewport: ViewportBox;
+    avatarSize: {
+        width: number;
+        height: number;
+    };
+    insets: SafeInsets;
+    gap?: number;
+}
+declare function computeAvatarDestination(input: MovementInput): MovementPlan;
+declare function anchorToViewport(position: "bottom-right" | "bottom-left" | "top-right" | "top-left", viewport: ViewportBox, avatarSize: {
+    width: number;
+    height: number;
+}, insets: SafeInsets): {
+    x: number;
+    y: number;
+};
+
+export { type ActionKind, ActionNotAllowedError, Asiyst, AsiystError, type AsiystEventMap, type AsiystEventName, type AssistantMode, AuthenticationError, ConfigurationError, type HighlightStyle, type InitOptions, InitializationError, type MappedElement, NetworkError, type ProjectConfig, SDK_VERSION, type TargetInput, TargetNotFoundError, type TargetRef, type TaskDefinition, TaskExecutionError, TaskStatus, type TaskStep, type WebsiteMapSnapshot, type WorkflowDefinition, anchorToViewport, canTransition, computeAvatarDestination, fallbackConfig, isSafeSelector, normalizeProjectConfig, sanitizeText, validateInitOptions };