@asiyst/sdk 0.1.32 → 0.1.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,73 +1,130 @@
1
1
  # @asiyst/sdk
2
2
 
3
- Client-side runtime that connects a website to Asiyst Cloud.
3
+ Client-side 3D Avatar Runtime and AI Assistant SDK that connects websites to Asiyst Cloud.
4
4
 
5
- This package does not contain model keys, database credentials, or other server secrets. Identify the project with `projectId` and `publicKey` only. Those values are public project credentials, not secrets.
5
+ This package does not contain model keys, database credentials, or private server secrets. Websites configure public credentials (`projectId` and `publicKey`) to initialize the runtime session, render 3D character avatars with external animation FBX/GLB assets, ingest sanitized DOM page context, execute structured AI action plans, and speak to visitors.
6
6
 
7
- ## Install
7
+ ---
8
+
9
+ ## Installation
8
10
 
9
11
  ```bash
10
12
  npm install @asiyst/sdk
11
13
  ```
12
14
 
13
- Then connect the project:
15
+ Connect your project using the CLI:
14
16
 
15
17
  ```bash
16
- npx @asiyst/cli init
18
+ npx @asiyst/cli connect <PROJECT_ID>
17
19
  ```
18
20
 
19
- `asiyst init` opens [https://asiyst.com](https://asiyst.com) so you can create a project and copy credentials. Avatar appearance and behavior live in Asiyst Cloud so you can change them without redeploying the site.
20
-
21
- ## Usage
21
+ ---
22
22
 
23
- Project ID is required. The value must be the public Project ID for the target Asiyst project, not the developer account user ID and not the internal Supabase UUID.
23
+ ## Quick Start
24
24
 
25
25
  ```ts
26
- import { Asiyst } from "@asiyst/sdk";
26
+ import { Asiyst, asiystInit } from "@asiyst/sdk";
27
27
 
28
- await Asiyst.init({
29
- projectId: "<PUBLIC_PROJECT_ID>",
30
- publicKey: "<PUBLIC_KEY>",
31
- avatarId: "<PUBLIC_AVATAR_ID>",
28
+ // Initialize the avatar runtime
29
+ const asiyst = await asiystInit({
30
+ projectId: "proj_your_project_id",
31
+ publicKey: "pk_live_your_public_key",
32
+ avatarId: "avatar_custom_001", // optional
32
33
  });
34
+
35
+ // Open conversational assistant
33
36
  Asiyst.open();
34
37
  ```
35
38
 
36
- Do not pass a secret API key as `publicKey` or omit `projectId`.
39
+ ---
40
+
41
+ ## Architecture & Features
42
+
43
+ ### 1. Authoritative Runtime Session
44
+ - Registers with `POST /api/v1/runtime/register` upon startup.
45
+ - Obtains ephemeral scoped session token stored exclusively in memory (zero localStorage/cookie persistence).
46
+ - Handles re-authorization automatically upon token expiration.
47
+
48
+ ### 2. Dual FBX & GLB Asset Pipeline
49
+ - Supports FBX character models (binary/ASCII) and separately uploaded FBX animations.
50
+ - Full backwards-compatibility with Manifest 1.0 GLB single/separate animations.
51
+ - Intelligent Mixamo skeleton retargeting (`retargetClipToModel`) with namespace stripping (`mixamorig:Hips` -> `Hips`).
52
+ - Strictly confines position tracks to root/pelvis to prevent skeletal dislocation across models of varying proportions.
53
+ - Rejects incompatible skeletons with code `INCOMPATIBLE_SKELETON`.
54
+ - In-flight request deduplication and memory caching.
55
+
56
+ ### 3. 7-Step Animation Intent Resolution
57
+ When playing animations or fulfilling AI action plans, the runtime resolves clips using a strict 7-step priority:
58
+ 1. Exact external animation ID
59
+ 2. Exact clip name (case-insensitive)
60
+ 3. Normalized clip name
61
+ 4. Manifest intent match (`idle`, `greeting`, `walk`, `run`, `talk`, `gesture`, etc.)
62
+ 5. Manifest animation name match
63
+ 6. Manifest category match
64
+ 7. Intent-to-category mapping (e.g. `walking` -> `movement`)
65
+ 8. Safe idle fallback
66
+
67
+ ### 4. DOM Context Ingestion & Privacy
68
+ - Observes website DOM structure via `TargetRegistry`.
69
+ - Collects viewport bounds, page type (`home`, `catalog`, `pricing`, `checkout`, `documentation`), and interactive targets.
70
+ - Enforces strict privacy boundaries: automatically strips password fields, credit card numbers (`cc-number`), CVVs, API keys, tokens, SSNs, and sensitive form elements.
71
+ - Caps context snapshots at 100 targets and 50 KB payload size.
72
+ - Reports sanitized context snapshots to `POST /api/v1/runtime/context`.
73
+
74
+ ### 5. AI Action Execution Engine (Protocol 1.0)
75
+ Executes structured avatar action plans returned by Asiyst Cloud with Kahn's algorithm topological dependency sorting:
76
+ - **Avatar actions:** `play_animation`, `stop_animation`, `set_animation_speed`, `set_idle_animation`, `set_behavior_state`.
77
+ - **Movement actions:** `move_to`, `move_to_element`, `walk_to`, `run_to`, `stop_movement`, `face_direction`, `look_at`.
78
+ - **Speech actions:** `speak`, `stop_speech`, `pause_speech`, `resume_speech` (using browser Web Speech API).
79
+ - **Interaction actions:** `point_to_element`, `highlight_element`, `hover_element`, `click_element`, `focus_element`, `scroll_to_element`, `wait_for_element`, `verify_action`.
80
+ - **Navigation actions:** `navigate_to_url`, `navigate_to_route`, `navigate_to_element`, `navigate_back`, `navigate_forward`.
81
+ - **Context actions:** `refresh_context`, `get_page_context`, `find_element`.
82
+
83
+ ### 6. High-Risk Action Confirmation
84
+ - High-risk actions (such as `click_element`) present an on-screen consent dialog to the visitor.
85
+ - Acquires single-use, signed tokens from `POST /api/v1/runtime/actions/confirm`.
86
+ - Reports execution acknowledgements with timing metrics to `POST /api/v1/runtime/actions/ack`.
87
+
88
+ ### 7. Visitor Greetings & Speech
89
+ - Browser Web Speech API audio synthesis with speaking rate, pitch, language, and interruption control.
90
+ - `GreetingManager` evaluates runtime configuration (`greeting.enabled`, `firstVisitBehavior`, `initialDelayMs`, `cooldownSeconds`, `maxAutomaticGreetings`).
91
+ - Automatically cancels pending greetings if the visitor interacts with the page before the delay expires.
92
+
93
+ ---
94
+
95
+ ## Public Avatar API
37
96
 
38
- `avatarId` is a public identifier, not an authorization credential. The server remains authoritative for project and installation authorization.
97
+ ```ts
98
+ // Direct avatar animation
99
+ Asiyst.avatar.playAnimation("wave", { speed: 1.0 });
39
100
 
40
- Knowledge sources, including optional GitHub repositories, are configured in Asiyst Web. The SDK does not receive GitHub credentials and does not copy Knowledge Base content into the website. It initializes the verified project/avatar and retrieves authorized knowledge through the Asiyst backend.
101
+ // Movement
102
+ await Asiyst.avatar.moveTo(800, 600);
103
+ await Asiyst.avatar.moveToElement("#pricing-table");
104
+ Asiyst.avatar.stopMoving();
41
105
 
42
- ```ts
43
- await Asiyst.init({
44
- publicKey: "<PUBLIC_KEY>",
45
- });
46
- // throws: Asiyst SDK: projectId is required.
47
- ```
106
+ // Speech
107
+ Asiyst.avatar.speak("Take a look at our Pro Plan!");
108
+
109
+ // Highlighting and pointing
110
+ await Asiyst.avatar.pointAt("#checkout-button");
111
+ await Asiyst.avatar.highlight("#checkout-button", "glow");
48
112
 
49
- Mark important controls so the assistant can find them across layouts:
113
+ // Programmatic navigation
114
+ await Asiyst.avatar.navigateTo("/pricing");
50
115
 
51
- ```html
52
- <button data-asiyst="pricing">Pricing</button>
53
- <button
54
- data-asiyst="checkout"
55
- data-asiyst-description="Proceed to checkout"
56
- >
57
- Checkout
58
- </button>
116
+ // Context snapshot
117
+ const snapshot = await Asiyst.avatar.submitContext();
59
118
  ```
60
119
 
61
- The production API base is `https://nqhxpgsjofzqudyqkqib.supabase.co/functions/v1/api`. It is used by default and can only be overridden explicitly through `apiBaseUrl` for a controlled non-production deployment.
120
+ ---
121
+
122
+ ## SSR & Framework Compatibility
123
+
124
+ Safe for Server-Side Rendering (Next.js, Remix, Astro, Nuxt, SvelteKit). Browser globals (`window`, `document`, WebGL) are never accessed at module import time. Call `Asiyst.init()` inside client lifecycle hooks (`useEffect`, `onMounted`, etc.).
62
125
 
63
- If runtime config is unavailable, the SDK retains its local or eligible cached fallback config. `getConnectionStatus()` reports runtime verification separately. Visitor chat requires a verified installation and runtime token. Cloud task planning, workflows, telemetry, and website-map upload are not part of the current approved contract and are not sent.
126
+ ---
64
127
 
65
- ## Documentation
128
+ ## License
66
129
 
67
- - Architecture: `docs/ARCHITECTURE.md`
68
- - API and events: `docs/API.md`
69
- - Security: `docs/SECURITY.md`
70
- - Runtime contract: `docs/sdk-cli-contract.md`
71
- - Runtime details: `docs/sdk-runtime.md`
72
- - Installation: `docs/sdk-installation.md`
73
- - Troubleshooting: `docs/TROUBLESHOOTING.md`
130
+ MIT