@asiyst/sdk 0.1.31 → 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 +99 -42
- package/dist/index.cjs +8614 -2114
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1580 -17
- package/dist/index.d.ts +1580 -17
- package/dist/index.js +8577 -2115
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,73 +1,130 @@
|
|
|
1
1
|
# @asiyst/sdk
|
|
2
2
|
|
|
3
|
-
Client-side
|
|
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
|
|
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
|
-
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
8
10
|
|
|
9
11
|
```bash
|
|
10
12
|
npm install @asiyst/sdk
|
|
11
13
|
```
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
Connect your project using the CLI:
|
|
14
16
|
|
|
15
17
|
```bash
|
|
16
|
-
npx @asiyst/cli
|
|
18
|
+
npx @asiyst/cli connect <PROJECT_ID>
|
|
17
19
|
```
|
|
18
20
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
## Usage
|
|
21
|
+
---
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
## Quick Start
|
|
24
24
|
|
|
25
25
|
```ts
|
|
26
|
-
import { Asiyst } from "@asiyst/sdk";
|
|
26
|
+
import { Asiyst, asiystInit } from "@asiyst/sdk";
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
|
|
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
|
-
|
|
97
|
+
```ts
|
|
98
|
+
// Direct avatar animation
|
|
99
|
+
Asiyst.avatar.playAnimation("wave", { speed: 1.0 });
|
|
39
100
|
|
|
40
|
-
|
|
101
|
+
// Movement
|
|
102
|
+
await Asiyst.avatar.moveTo(800, 600);
|
|
103
|
+
await Asiyst.avatar.moveToElement("#pricing-table");
|
|
104
|
+
Asiyst.avatar.stopMoving();
|
|
41
105
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
|
|
113
|
+
// Programmatic navigation
|
|
114
|
+
await Asiyst.avatar.navigateTo("/pricing");
|
|
50
115
|
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
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
|
-
|
|
126
|
+
---
|
|
64
127
|
|
|
65
|
-
##
|
|
128
|
+
## License
|
|
66
129
|
|
|
67
|
-
|
|
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
|