@asiyst/sdk 0.1.31 → 0.1.32

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/dist/index.d.cts CHANGED
@@ -142,9 +142,38 @@ interface AsiystEventMap {
142
142
  name: string;
143
143
  error: string;
144
144
  };
145
+ "asiyst:animation:failed": {
146
+ animationId?: string;
147
+ name: string;
148
+ error: string;
149
+ };
145
150
  "asiyst:error": {
146
151
  code: string;
147
152
  message: string;
153
+ hint?: string;
154
+ };
155
+ "state": AsiystSDKState | {
156
+ state: AsiystSDKState;
157
+ previousState?: AsiystSDKState;
158
+ details?: Record<string, unknown>;
159
+ };
160
+ "asiyst:state": {
161
+ state: AsiystSDKState;
162
+ previousState?: AsiystSDKState;
163
+ details?: Record<string, unknown>;
164
+ };
165
+ "asiyst:avatar:state": {
166
+ state: AvatarLifecycleState;
167
+ };
168
+ "asiyst:chat:state": {
169
+ state: ChatLifecycleState;
170
+ };
171
+ "progress": AsiystProgress;
172
+ "asiyst:progress": AsiystProgress;
173
+ "error": {
174
+ code: string;
175
+ message: string;
176
+ hint?: string;
148
177
  };
149
178
  }
150
179
  type AsiystEventName = keyof AsiystEventMap;
@@ -161,6 +190,55 @@ interface TargetRef {
161
190
  selector?: string;
162
191
  }
163
192
  type TargetInput = string | TargetRef;
193
+ type AsiystSDKState = "idle" | "registering" | "authorizing" | "fetching-config" | "loading-avatar" | "ready" | "error";
194
+ type AvatarLifecycleState = "initializing" | "loading" | "ready" | "error" | "unavailable";
195
+ type ChatLifecycleState = "initializing" | "ready" | "error" | "unavailable";
196
+ interface AsiystProgress {
197
+ stage: string;
198
+ loadedBytes?: number;
199
+ totalBytes?: number;
200
+ percentage?: number;
201
+ assetName?: string;
202
+ }
203
+ interface AsiystFallbackOptions {
204
+ mode: "image" | "2d" | "chat-only";
205
+ imageUrl?: string;
206
+ }
207
+ interface DiagnosticResult {
208
+ ok: boolean;
209
+ status?: number;
210
+ code?: string;
211
+ message?: string;
212
+ durationMs?: number;
213
+ }
214
+ interface AsiystDiagnosticReport {
215
+ sdkVersion: string;
216
+ origin: string;
217
+ state: AsiystSDKState;
218
+ registration: DiagnosticResult;
219
+ authorization: DiagnosticResult;
220
+ runtimeConfig: DiagnosticResult;
221
+ avatar?: {
222
+ avatarId: string;
223
+ format?: string;
224
+ assets: Array<{
225
+ name: string;
226
+ format: string;
227
+ sizeBytes?: number;
228
+ loaded: boolean;
229
+ }>;
230
+ };
231
+ webgl: {
232
+ supported: boolean;
233
+ rendererAvailable: boolean;
234
+ };
235
+ errors: Array<{
236
+ code: string;
237
+ message: string;
238
+ hint?: string;
239
+ }>;
240
+ durationMs: number;
241
+ }
164
242
  interface InitOptions {
165
243
  projectId: string;
166
244
  publicKey: string;
@@ -172,6 +250,8 @@ interface InitOptions {
172
250
  allowedActions?: ActionKind[];
173
251
  observeHistory?: boolean;
174
252
  visitorSessionId?: string;
253
+ debug?: boolean;
254
+ fallback?: AsiystFallbackOptions;
175
255
  }
176
256
  interface ThemeConfig {
177
257
  accent?: string;
@@ -319,6 +399,10 @@ interface WorkflowDefinition {
319
399
  declare const Asiyst: {
320
400
  init(options: InitOptions): Promise<void>;
321
401
  destroy(): Promise<void>;
402
+ getState(): AsiystSDKState;
403
+ getAvatarState(): AvatarLifecycleState;
404
+ getChatState(): ChatLifecycleState;
405
+ diagnose(): Promise<AsiystDiagnosticReport>;
322
406
  open(): void;
323
407
  close(): void;
324
408
  getConfig(): ProjectConfig;
@@ -355,9 +439,20 @@ declare const Asiyst: {
355
439
 
356
440
  declare const SDK_VERSION: string;
357
441
 
442
+ type AsiystErrorCode = "DOMAIN_NOT_APPROVED" | "ORIGIN_NOT_APPROVED" | "PROJECT_NOT_FOUND" | "AVATAR_NOT_FOUND" | "AVATAR_NOT_READY" | "ASSET_TIMEOUT" | "NETWORK_ERROR" | "WEBGL_UNAVAILABLE" | "ASSET_PARSE_FAILED" | "CONFIG_INVALID" | "AUTHENTICATION_FAILED" | "TOKEN_EXPIRED" | "OPERATION_CANCELLED" | "ASSET_LOAD_CANCELLED" | "UNKNOWN_ERROR";
443
+ interface AsiystErrorOptions {
444
+ code: AsiystErrorCode | string;
445
+ message: string;
446
+ hint?: string;
447
+ status?: number;
448
+ cause?: unknown;
449
+ }
358
450
  declare class AsiystError extends Error {
359
- readonly code: string;
360
- constructor(code: string, message: string);
451
+ readonly code: AsiystErrorCode | string;
452
+ readonly hint?: string;
453
+ readonly status?: number;
454
+ readonly cause?: unknown;
455
+ constructor(optionsOrCode: AsiystErrorOptions | string, legacyMessage?: string, hint?: string);
361
456
  }
362
457
  declare class ConfigurationError extends AsiystError {
363
458
  constructor(message: string);
@@ -460,6 +555,21 @@ declare function evaluateActionPermission(action: ActionKind, config: ProjectCon
460
555
  };
461
556
  declare function isActionAllowed(action: ActionKind, config: ProjectConfig, source: "developer" | "cloud" | "local", currentUrl?: string, target?: string): boolean;
462
557
 
558
+ interface AssetTimeoutConfig {
559
+ connectTimeoutMs?: number;
560
+ stallTimeoutMs?: number;
561
+ totalTimeoutMs?: number;
562
+ }
563
+ interface AssetLoadOptions {
564
+ signal?: AbortSignal;
565
+ timeoutMs?: number;
566
+ timeouts?: AssetTimeoutConfig;
567
+ integrity?: string;
568
+ expectedFormat?: "fbx" | "glb";
569
+ assetName?: string;
570
+ onProgress?: (progress: AsiystProgress) => void;
571
+ maxRetries?: number;
572
+ }
463
573
  interface ParsedGlbMesh {
464
574
  name?: string;
465
575
  positions: Float32Array;
@@ -505,12 +615,7 @@ declare class AssetLoader {
505
615
  private readonly createdObjectUrls;
506
616
  private readonly inFlightLoads;
507
617
  private readonly cachedAssets;
508
- load(assetUrl: string, options?: {
509
- signal?: AbortSignal;
510
- timeoutMs?: number;
511
- integrity?: string;
512
- expectedFormat?: "fbx" | "glb";
513
- }): Promise<LoadedAvatarAsset>;
618
+ load(assetUrl: string, options?: AssetLoadOptions): Promise<LoadedAvatarAsset>;
514
619
  private performLoad;
515
620
  isFbxBuffer(buffer: ArrayBuffer): boolean;
516
621
  parseFbxHeader(buffer: ArrayBuffer): {
@@ -565,6 +670,7 @@ declare class FbxRenderer {
565
670
  private mixer;
566
671
  private allAnimations;
567
672
  private readonly animationMetadataList;
673
+ private readonly failedAnimations;
568
674
  private readonly assetLoader;
569
675
  private currentAction;
570
676
  private animFrameId;
@@ -579,6 +685,12 @@ declare class FbxRenderer {
579
685
  setPose(pose: AvatarPose): void;
580
686
  startInitialIdleAnimation(config?: Partial<ProjectConfig>): boolean;
581
687
  loadExternalAnimations(animations: AvatarAnimation[], targetAnimationName?: string): Promise<void>;
688
+ getFailedAnimations(): Array<{
689
+ name: string;
690
+ id?: string;
691
+ error: string;
692
+ code?: string;
693
+ }>;
582
694
  retargetClip(clip: THREE.AnimationClip, targetObject: THREE.Object3D): THREE.AnimationClip | null;
583
695
  playAnimation(nameOrIntent: string, loopMode?: string, crossFadeDuration?: number): boolean;
584
696
  isRendered(): boolean;
@@ -624,12 +736,19 @@ declare class CssAvatarRenderer implements AvatarRenderer {
624
736
  private lastErrorMessage;
625
737
  private renderMetrics;
626
738
  private metricsTracker?;
739
+ private fallbackOptions?;
740
+ setFallbackOptions(opts?: AsiystFallbackOptions): void;
627
741
  setMetricsTracker(tracker: AvatarMetricsTracker): void;
628
742
  mount(container: HTMLElement, config: ProjectConfig): void;
629
743
  unmount(): void;
630
744
  applyConfig(config: ProjectConfig): void;
631
745
  setPanelOpen(open: boolean): void;
632
- loadAsset(config: ProjectConfig, metricsTracker?: AvatarMetricsTracker): Promise<boolean>;
746
+ loadAsset(config: ProjectConfig, metricsTracker?: AvatarMetricsTracker, options?: {
747
+ onProgress?: (p: AsiystProgress) => void;
748
+ fallback?: AsiystFallbackOptions;
749
+ }): Promise<boolean>;
750
+ updateProgress(progress: AsiystProgress): void;
751
+ renderErrorState(error: AsiystError | Error, fallbackOptions?: AsiystFallbackOptions): void;
633
752
  renderLoader(): void;
634
753
  private renderLoadedAsset;
635
754
  private renderLoadingPlaceholder;
@@ -661,4 +780,4 @@ declare class CssAvatarRenderer implements AvatarRenderer {
661
780
  getNameTag(): HTMLElement | undefined;
662
781
  }
663
782
 
664
- export { type ActionKind, ActionNotAllowedError, Asiyst, AsiystError, type AsiystEventMap, type AsiystEventName, AssetLoader, type AssistantMode, AuthenticationError, type AvatarAnimation, type AvatarBranding, type AvatarLoadingTimestamps, AvatarMetricsTracker, type AvatarPerformanceMetrics, ConfigurationError, CssAvatarRenderer, FbxRenderer, 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, canNavigateTo, canTransition, computeAvatarDestination, evaluateActionPermission, fallbackConfig, isActionAllowed, isSafeSelector, normalizeProjectConfig, sanitizeText, validateInitOptions, validateWebsiteDomain };
783
+ export { type ActionKind, ActionNotAllowedError, Asiyst, type AsiystDiagnosticReport, AsiystError, type AsiystErrorCode, type AsiystEventMap, type AsiystEventName, type AsiystFallbackOptions, type AsiystProgress, type AsiystSDKState, AssetLoader, type AssistantMode, AuthenticationError, type AvatarAnimation, type AvatarBranding, type AvatarLifecycleState, type AvatarLoadingTimestamps, AvatarMetricsTracker, type AvatarPerformanceMetrics, type ChatLifecycleState, ConfigurationError, CssAvatarRenderer, type DiagnosticResult, FbxRenderer, 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, canNavigateTo, canTransition, computeAvatarDestination, evaluateActionPermission, fallbackConfig, isActionAllowed, isSafeSelector, normalizeProjectConfig, sanitizeText, validateInitOptions, validateWebsiteDomain };
package/dist/index.d.ts CHANGED
@@ -142,9 +142,38 @@ interface AsiystEventMap {
142
142
  name: string;
143
143
  error: string;
144
144
  };
145
+ "asiyst:animation:failed": {
146
+ animationId?: string;
147
+ name: string;
148
+ error: string;
149
+ };
145
150
  "asiyst:error": {
146
151
  code: string;
147
152
  message: string;
153
+ hint?: string;
154
+ };
155
+ "state": AsiystSDKState | {
156
+ state: AsiystSDKState;
157
+ previousState?: AsiystSDKState;
158
+ details?: Record<string, unknown>;
159
+ };
160
+ "asiyst:state": {
161
+ state: AsiystSDKState;
162
+ previousState?: AsiystSDKState;
163
+ details?: Record<string, unknown>;
164
+ };
165
+ "asiyst:avatar:state": {
166
+ state: AvatarLifecycleState;
167
+ };
168
+ "asiyst:chat:state": {
169
+ state: ChatLifecycleState;
170
+ };
171
+ "progress": AsiystProgress;
172
+ "asiyst:progress": AsiystProgress;
173
+ "error": {
174
+ code: string;
175
+ message: string;
176
+ hint?: string;
148
177
  };
149
178
  }
150
179
  type AsiystEventName = keyof AsiystEventMap;
@@ -161,6 +190,55 @@ interface TargetRef {
161
190
  selector?: string;
162
191
  }
163
192
  type TargetInput = string | TargetRef;
193
+ type AsiystSDKState = "idle" | "registering" | "authorizing" | "fetching-config" | "loading-avatar" | "ready" | "error";
194
+ type AvatarLifecycleState = "initializing" | "loading" | "ready" | "error" | "unavailable";
195
+ type ChatLifecycleState = "initializing" | "ready" | "error" | "unavailable";
196
+ interface AsiystProgress {
197
+ stage: string;
198
+ loadedBytes?: number;
199
+ totalBytes?: number;
200
+ percentage?: number;
201
+ assetName?: string;
202
+ }
203
+ interface AsiystFallbackOptions {
204
+ mode: "image" | "2d" | "chat-only";
205
+ imageUrl?: string;
206
+ }
207
+ interface DiagnosticResult {
208
+ ok: boolean;
209
+ status?: number;
210
+ code?: string;
211
+ message?: string;
212
+ durationMs?: number;
213
+ }
214
+ interface AsiystDiagnosticReport {
215
+ sdkVersion: string;
216
+ origin: string;
217
+ state: AsiystSDKState;
218
+ registration: DiagnosticResult;
219
+ authorization: DiagnosticResult;
220
+ runtimeConfig: DiagnosticResult;
221
+ avatar?: {
222
+ avatarId: string;
223
+ format?: string;
224
+ assets: Array<{
225
+ name: string;
226
+ format: string;
227
+ sizeBytes?: number;
228
+ loaded: boolean;
229
+ }>;
230
+ };
231
+ webgl: {
232
+ supported: boolean;
233
+ rendererAvailable: boolean;
234
+ };
235
+ errors: Array<{
236
+ code: string;
237
+ message: string;
238
+ hint?: string;
239
+ }>;
240
+ durationMs: number;
241
+ }
164
242
  interface InitOptions {
165
243
  projectId: string;
166
244
  publicKey: string;
@@ -172,6 +250,8 @@ interface InitOptions {
172
250
  allowedActions?: ActionKind[];
173
251
  observeHistory?: boolean;
174
252
  visitorSessionId?: string;
253
+ debug?: boolean;
254
+ fallback?: AsiystFallbackOptions;
175
255
  }
176
256
  interface ThemeConfig {
177
257
  accent?: string;
@@ -319,6 +399,10 @@ interface WorkflowDefinition {
319
399
  declare const Asiyst: {
320
400
  init(options: InitOptions): Promise<void>;
321
401
  destroy(): Promise<void>;
402
+ getState(): AsiystSDKState;
403
+ getAvatarState(): AvatarLifecycleState;
404
+ getChatState(): ChatLifecycleState;
405
+ diagnose(): Promise<AsiystDiagnosticReport>;
322
406
  open(): void;
323
407
  close(): void;
324
408
  getConfig(): ProjectConfig;
@@ -355,9 +439,20 @@ declare const Asiyst: {
355
439
 
356
440
  declare const SDK_VERSION: string;
357
441
 
442
+ type AsiystErrorCode = "DOMAIN_NOT_APPROVED" | "ORIGIN_NOT_APPROVED" | "PROJECT_NOT_FOUND" | "AVATAR_NOT_FOUND" | "AVATAR_NOT_READY" | "ASSET_TIMEOUT" | "NETWORK_ERROR" | "WEBGL_UNAVAILABLE" | "ASSET_PARSE_FAILED" | "CONFIG_INVALID" | "AUTHENTICATION_FAILED" | "TOKEN_EXPIRED" | "OPERATION_CANCELLED" | "ASSET_LOAD_CANCELLED" | "UNKNOWN_ERROR";
443
+ interface AsiystErrorOptions {
444
+ code: AsiystErrorCode | string;
445
+ message: string;
446
+ hint?: string;
447
+ status?: number;
448
+ cause?: unknown;
449
+ }
358
450
  declare class AsiystError extends Error {
359
- readonly code: string;
360
- constructor(code: string, message: string);
451
+ readonly code: AsiystErrorCode | string;
452
+ readonly hint?: string;
453
+ readonly status?: number;
454
+ readonly cause?: unknown;
455
+ constructor(optionsOrCode: AsiystErrorOptions | string, legacyMessage?: string, hint?: string);
361
456
  }
362
457
  declare class ConfigurationError extends AsiystError {
363
458
  constructor(message: string);
@@ -460,6 +555,21 @@ declare function evaluateActionPermission(action: ActionKind, config: ProjectCon
460
555
  };
461
556
  declare function isActionAllowed(action: ActionKind, config: ProjectConfig, source: "developer" | "cloud" | "local", currentUrl?: string, target?: string): boolean;
462
557
 
558
+ interface AssetTimeoutConfig {
559
+ connectTimeoutMs?: number;
560
+ stallTimeoutMs?: number;
561
+ totalTimeoutMs?: number;
562
+ }
563
+ interface AssetLoadOptions {
564
+ signal?: AbortSignal;
565
+ timeoutMs?: number;
566
+ timeouts?: AssetTimeoutConfig;
567
+ integrity?: string;
568
+ expectedFormat?: "fbx" | "glb";
569
+ assetName?: string;
570
+ onProgress?: (progress: AsiystProgress) => void;
571
+ maxRetries?: number;
572
+ }
463
573
  interface ParsedGlbMesh {
464
574
  name?: string;
465
575
  positions: Float32Array;
@@ -505,12 +615,7 @@ declare class AssetLoader {
505
615
  private readonly createdObjectUrls;
506
616
  private readonly inFlightLoads;
507
617
  private readonly cachedAssets;
508
- load(assetUrl: string, options?: {
509
- signal?: AbortSignal;
510
- timeoutMs?: number;
511
- integrity?: string;
512
- expectedFormat?: "fbx" | "glb";
513
- }): Promise<LoadedAvatarAsset>;
618
+ load(assetUrl: string, options?: AssetLoadOptions): Promise<LoadedAvatarAsset>;
514
619
  private performLoad;
515
620
  isFbxBuffer(buffer: ArrayBuffer): boolean;
516
621
  parseFbxHeader(buffer: ArrayBuffer): {
@@ -565,6 +670,7 @@ declare class FbxRenderer {
565
670
  private mixer;
566
671
  private allAnimations;
567
672
  private readonly animationMetadataList;
673
+ private readonly failedAnimations;
568
674
  private readonly assetLoader;
569
675
  private currentAction;
570
676
  private animFrameId;
@@ -579,6 +685,12 @@ declare class FbxRenderer {
579
685
  setPose(pose: AvatarPose): void;
580
686
  startInitialIdleAnimation(config?: Partial<ProjectConfig>): boolean;
581
687
  loadExternalAnimations(animations: AvatarAnimation[], targetAnimationName?: string): Promise<void>;
688
+ getFailedAnimations(): Array<{
689
+ name: string;
690
+ id?: string;
691
+ error: string;
692
+ code?: string;
693
+ }>;
582
694
  retargetClip(clip: THREE.AnimationClip, targetObject: THREE.Object3D): THREE.AnimationClip | null;
583
695
  playAnimation(nameOrIntent: string, loopMode?: string, crossFadeDuration?: number): boolean;
584
696
  isRendered(): boolean;
@@ -624,12 +736,19 @@ declare class CssAvatarRenderer implements AvatarRenderer {
624
736
  private lastErrorMessage;
625
737
  private renderMetrics;
626
738
  private metricsTracker?;
739
+ private fallbackOptions?;
740
+ setFallbackOptions(opts?: AsiystFallbackOptions): void;
627
741
  setMetricsTracker(tracker: AvatarMetricsTracker): void;
628
742
  mount(container: HTMLElement, config: ProjectConfig): void;
629
743
  unmount(): void;
630
744
  applyConfig(config: ProjectConfig): void;
631
745
  setPanelOpen(open: boolean): void;
632
- loadAsset(config: ProjectConfig, metricsTracker?: AvatarMetricsTracker): Promise<boolean>;
746
+ loadAsset(config: ProjectConfig, metricsTracker?: AvatarMetricsTracker, options?: {
747
+ onProgress?: (p: AsiystProgress) => void;
748
+ fallback?: AsiystFallbackOptions;
749
+ }): Promise<boolean>;
750
+ updateProgress(progress: AsiystProgress): void;
751
+ renderErrorState(error: AsiystError | Error, fallbackOptions?: AsiystFallbackOptions): void;
633
752
  renderLoader(): void;
634
753
  private renderLoadedAsset;
635
754
  private renderLoadingPlaceholder;
@@ -661,4 +780,4 @@ declare class CssAvatarRenderer implements AvatarRenderer {
661
780
  getNameTag(): HTMLElement | undefined;
662
781
  }
663
782
 
664
- export { type ActionKind, ActionNotAllowedError, Asiyst, AsiystError, type AsiystEventMap, type AsiystEventName, AssetLoader, type AssistantMode, AuthenticationError, type AvatarAnimation, type AvatarBranding, type AvatarLoadingTimestamps, AvatarMetricsTracker, type AvatarPerformanceMetrics, ConfigurationError, CssAvatarRenderer, FbxRenderer, 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, canNavigateTo, canTransition, computeAvatarDestination, evaluateActionPermission, fallbackConfig, isActionAllowed, isSafeSelector, normalizeProjectConfig, sanitizeText, validateInitOptions, validateWebsiteDomain };
783
+ export { type ActionKind, ActionNotAllowedError, Asiyst, type AsiystDiagnosticReport, AsiystError, type AsiystErrorCode, type AsiystEventMap, type AsiystEventName, type AsiystFallbackOptions, type AsiystProgress, type AsiystSDKState, AssetLoader, type AssistantMode, AuthenticationError, type AvatarAnimation, type AvatarBranding, type AvatarLifecycleState, type AvatarLoadingTimestamps, AvatarMetricsTracker, type AvatarPerformanceMetrics, type ChatLifecycleState, ConfigurationError, CssAvatarRenderer, type DiagnosticResult, FbxRenderer, 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, canNavigateTo, canTransition, computeAvatarDestination, evaluateActionPermission, fallbackConfig, isActionAllowed, isSafeSelector, normalizeProjectConfig, sanitizeText, validateInitOptions, validateWebsiteDomain };