@hypersoniclabs/helix-sdk 0.1.1 → 0.1.9

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.
Files changed (120) hide show
  1. package/README.md +954 -2
  2. package/dist/action-surface.d.ts +182 -0
  3. package/dist/action-surface.js +1032 -0
  4. package/dist/action-surface.js.map +1 -0
  5. package/dist/camera.d.ts +78 -0
  6. package/dist/camera.js +640 -0
  7. package/dist/camera.js.map +1 -0
  8. package/dist/dev-shell/criteria.d.ts +46 -0
  9. package/dist/dev-shell/criteria.js +98 -0
  10. package/dist/dev-shell/criteria.js.map +1 -0
  11. package/dist/dev-shell/index.d.ts +189 -0
  12. package/dist/dev-shell/index.js +287 -0
  13. package/dist/dev-shell/index.js.map +1 -0
  14. package/dist/dev-shell/keys.d.ts +14 -0
  15. package/dist/dev-shell/keys.js +78 -0
  16. package/dist/dev-shell/keys.js.map +1 -0
  17. package/dist/dev-shell/simulator.d.ts +436 -0
  18. package/dist/dev-shell/simulator.js +1634 -0
  19. package/dist/dev-shell/simulator.js.map +1 -0
  20. package/dist/dev-shell/state.d.ts +148 -0
  21. package/dist/dev-shell/state.js +196 -0
  22. package/dist/dev-shell/state.js.map +1 -0
  23. package/dist/device-definition-resolver.d.ts +34 -0
  24. package/dist/device-definition-resolver.js +172 -0
  25. package/dist/device-definition-resolver.js.map +1 -0
  26. package/dist/device-trial.d.ts +3 -0
  27. package/dist/device-trial.js +132 -0
  28. package/dist/device-trial.js.map +1 -0
  29. package/dist/devices.d.ts +228 -0
  30. package/dist/devices.js +198 -0
  31. package/dist/devices.js.map +1 -0
  32. package/dist/dreamerAudio.d.ts +126 -0
  33. package/dist/dreamerAudio.js +135 -0
  34. package/dist/dreamerAudio.js.map +1 -0
  35. package/dist/generated/runtime-contract.d.ts +15529 -0
  36. package/dist/generated/runtime-contract.js +20470 -0
  37. package/dist/generated/runtime-contract.js.map +1 -0
  38. package/dist/index.d.ts +364 -3
  39. package/dist/index.js +1954 -13
  40. package/dist/index.js.map +1 -1
  41. package/dist/interaction-mode.d.ts +172 -0
  42. package/dist/interaction-mode.js +553 -0
  43. package/dist/interaction-mode.js.map +1 -0
  44. package/dist/internal/avatar-pose.d.ts +25 -0
  45. package/dist/internal/avatar-pose.js +46 -0
  46. package/dist/internal/avatar-pose.js.map +1 -0
  47. package/dist/internal/keyed-collection.d.ts +2 -0
  48. package/dist/internal/keyed-collection.js +12 -0
  49. package/dist/internal/keyed-collection.js.map +1 -0
  50. package/dist/internal/vehicle-detach-action.d.ts +2 -0
  51. package/dist/internal/vehicle-detach-action.js +6 -0
  52. package/dist/internal/vehicle-detach-action.js.map +1 -0
  53. package/dist/matchmaking.d.ts +433 -0
  54. package/dist/matchmaking.js +1487 -0
  55. package/dist/matchmaking.js.map +1 -0
  56. package/dist/materials.d.ts +122 -0
  57. package/dist/materials.js +217 -0
  58. package/dist/materials.js.map +1 -0
  59. package/dist/multiplayer-accessors.d.ts +100 -0
  60. package/dist/multiplayer-accessors.js +200 -0
  61. package/dist/multiplayer-accessors.js.map +1 -0
  62. package/dist/multiplayer-contract/avatar-pose.d.ts +112 -0
  63. package/dist/multiplayer-contract/avatar-pose.js +250 -0
  64. package/dist/multiplayer-contract/avatar-pose.js.map +1 -0
  65. package/dist/multiplayer-contract/credential.d.ts +80 -0
  66. package/dist/multiplayer-contract/credential.js +5 -0
  67. package/dist/multiplayer-contract/credential.js.map +1 -0
  68. package/dist/multiplayer-contract/final-rest.d.ts +66 -0
  69. package/dist/multiplayer-contract/final-rest.js +38 -0
  70. package/dist/multiplayer-contract/final-rest.js.map +1 -0
  71. package/dist/multiplayer-contract/index.d.ts +20 -0
  72. package/dist/multiplayer-contract/index.js +41 -0
  73. package/dist/multiplayer-contract/index.js.map +1 -0
  74. package/dist/multiplayer-contract/messages.d.ts +731 -0
  75. package/dist/multiplayer-contract/messages.js +237 -0
  76. package/dist/multiplayer-contract/messages.js.map +1 -0
  77. package/dist/multiplayer-contract/room.d.ts +177 -0
  78. package/dist/multiplayer-contract/room.js +17 -0
  79. package/dist/multiplayer-contract/room.js.map +1 -0
  80. package/dist/multiplayer-contract/state.d.ts +241 -0
  81. package/dist/multiplayer-contract/state.js +15 -0
  82. package/dist/multiplayer-contract/state.js.map +1 -0
  83. package/dist/multiplayer-final-rest.d.ts +32 -0
  84. package/dist/multiplayer-final-rest.js +217 -0
  85. package/dist/multiplayer-final-rest.js.map +1 -0
  86. package/dist/multiplayer.d.ts +624 -0
  87. package/dist/multiplayer.js +2503 -0
  88. package/dist/multiplayer.js.map +1 -0
  89. package/dist/package.json +3 -0
  90. package/dist/protocol.d.ts +859 -1
  91. package/dist/protocol.js +117 -5
  92. package/dist/protocol.js.map +1 -1
  93. package/dist/runtime-contract/index.d.ts +15 -0
  94. package/dist/runtime-contract/index.js +12 -0
  95. package/dist/runtime-contract/index.js.map +1 -0
  96. package/dist/server-clock.d.ts +25 -0
  97. package/dist/server-clock.js +88 -0
  98. package/dist/server-clock.js.map +1 -0
  99. package/dist/tsconfig.build.tsbuildinfo +1 -1
  100. package/dist/universal-vehicles.d.ts +111 -0
  101. package/dist/universal-vehicles.js +2 -0
  102. package/dist/universal-vehicles.js.map +1 -0
  103. package/dist/vault.d.ts +562 -0
  104. package/dist/vault.js +365 -0
  105. package/dist/vault.js.map +1 -0
  106. package/dist/vehicle-specialty-placement.d.ts +28 -0
  107. package/dist/vehicle-specialty-placement.js +154 -0
  108. package/dist/vehicle-specialty-placement.js.map +1 -0
  109. package/dist/vehicle-specialty-transport.d.ts +78 -0
  110. package/dist/vehicle-specialty-transport.js +183 -0
  111. package/dist/vehicle-specialty-transport.js.map +1 -0
  112. package/dist/voice.d.ts +229 -0
  113. package/dist/voice.js +1348 -0
  114. package/dist/voice.js.map +1 -0
  115. package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
  116. package/generated/runtime-contract/known-answer.json +20471 -0
  117. package/generated/runtime-contract/known-answer.schema.json +630 -0
  118. package/generated/runtime-contract/runtime-contract.schema.json +607 -0
  119. package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
  120. package/package.json +44 -5
@@ -0,0 +1,562 @@
1
+ /**
2
+ * Engine-agnostic access to durable HELIX Vault assets.
3
+ *
4
+ * Persist `VaultAssetHandle` (assetId + immutable integer version), never an
5
+ * artifact URL. URLs are resolution results and may change when the serving
6
+ * host changes.
7
+ */
8
+ export declare const VAULT_ASSET_KINDS: readonly ["prop", "character", "animation", "audio", "texture", "material", "environment", "terrain", "vfx", "decal", "sky", "gaussian_splat", "scene", "unreal_package"];
9
+ export type VaultAssetKind = (typeof VAULT_ASSET_KINDS)[number];
10
+ export type VaultRuntime = 'web' | 'unreal';
11
+ export type VaultSplatScope = 'object' | 'environment';
12
+ export type VaultPerformanceTier = 'mobile' | 'desktop' | 'cinematic' | 'unknown';
13
+ export type VaultRankMode = 'relevance' | 'performance' | 'reuse';
14
+ export type VaultAssetHandle = {
15
+ assetId: string;
16
+ /** Immutable, one-based Vault version. */
17
+ version: number;
18
+ };
19
+ export type VaultImmutableArtifactReference = VaultAssetHandle & {
20
+ checksumSha256: string;
21
+ };
22
+ export type VaultArtifactMetadata = {
23
+ format: string;
24
+ mimeType: string;
25
+ sourceBytes: number;
26
+ };
27
+ export type VaultPerformanceMetadata = {
28
+ costScore: number | null;
29
+ tier: VaultPerformanceTier;
30
+ downloadBytes: number;
31
+ qualityScore: number | null;
32
+ rankingSignals: string[];
33
+ triangles?: number;
34
+ drawCalls?: number;
35
+ maxTextureEdge?: number;
36
+ memoryBytes?: number | null;
37
+ };
38
+ type VaultMetadataBase = {
39
+ schemaVersion: '1' | string;
40
+ subtype: string;
41
+ artifact: VaultArtifactMetadata;
42
+ performance: VaultPerformanceMetadata;
43
+ [key: string]: unknown;
44
+ };
45
+ export type VaultPropMetadata = VaultMetadataBase & {
46
+ prop: {
47
+ static: true;
48
+ coordinateSystem: string;
49
+ units: 'meters' | string;
50
+ dimensionsMeters: [number, number, number];
51
+ triangleCount: number;
52
+ materialCount: number;
53
+ maxTextureEdge: number;
54
+ fileSizeBytes: number;
55
+ lods: Array<{
56
+ level: number;
57
+ triangles: number;
58
+ format: string;
59
+ }>;
60
+ limits: {
61
+ maxFileBytes: number;
62
+ maxTextureEdge: number;
63
+ generated: boolean;
64
+ [key: string]: unknown;
65
+ };
66
+ [key: string]: unknown;
67
+ };
68
+ };
69
+ export type VaultCharacterMetadata = VaultMetadataBase & {
70
+ character: {
71
+ skinned: boolean;
72
+ meshCount: number;
73
+ triangleCount: number | null;
74
+ boneCount: number;
75
+ };
76
+ };
77
+ export type VaultAnimationMetadata = VaultMetadataBase & {
78
+ animation: {
79
+ clipCount: number;
80
+ clips: string[];
81
+ durationSeconds: number | null;
82
+ frameCount: number | null;
83
+ framesPerSecond: number | null;
84
+ rig: string;
85
+ loop: boolean;
86
+ rootMotion: boolean;
87
+ };
88
+ };
89
+ /** Which ElevenLabs-backed mode produced this audio asset. */
90
+ export type VaultAudioGenerationMode = 'sound_effect' | 'music' | 'text_to_speech';
91
+ export type VaultAudioMetadata = VaultMetadataBase & {
92
+ audio: {
93
+ format: string;
94
+ durationSeconds: number | null;
95
+ loop: boolean;
96
+ /** Present on generated (ElevenLabs) assets; absent on uploads. */
97
+ mode?: VaultAudioGenerationMode;
98
+ model?: string;
99
+ outputFormat?: string;
100
+ /** Text-to-speech only. */
101
+ voiceId?: string;
102
+ /** Measured vendor usage/cost this specific generation was billed for. */
103
+ measuredUsage?: {
104
+ creditsCharged: number;
105
+ measured: boolean;
106
+ providerCostUsd: number;
107
+ };
108
+ [key: string]: unknown;
109
+ };
110
+ };
111
+ export type VaultTextureMetadata = VaultMetadataBase & {
112
+ texture: {
113
+ semantic: 'albedo' | 'normal' | 'roughness' | 'metallic' | 'ambient-occlusion' | 'emissive' | 'height' | 'mask' | 'unspecified';
114
+ colorSpace: 'srgb' | 'linear' | 'unspecified';
115
+ };
116
+ };
117
+ export type VaultMaterialMetadata = VaultMetadataBase & {
118
+ material: {
119
+ schemaVersion: string;
120
+ materialId: string;
121
+ materialType: 'pbr' | 'procedural_glass' | 'procedural_water';
122
+ mapSemantics: string[];
123
+ };
124
+ };
125
+ export type VaultEnvironmentMetadata = VaultMetadataBase & {
126
+ environment: {
127
+ representation: 'mesh' | 'gaussian-splat';
128
+ scope?: 'environment';
129
+ meshCount?: number;
130
+ triangleCount?: number;
131
+ dimensionsMeters?: [number, number, number] | null;
132
+ materialCount?: number;
133
+ };
134
+ gaussianSplat?: VaultGaussianSplatMetadata['gaussianSplat'];
135
+ };
136
+ export type VaultTerrainMetadata = VaultMetadataBase & {
137
+ terrain: {
138
+ representation: 'heightmap' | 'mesh';
139
+ sourceFormat?: 'png16' | 'raw16' | 'exr' | 'glb';
140
+ dimensionsMeters: [number, number, number] | null;
141
+ triangleCount?: number | null;
142
+ schemaVersion?: string;
143
+ };
144
+ };
145
+ export type VaultVfxMetadata = VaultMetadataBase & {
146
+ vfx: {
147
+ schemaVersion: string;
148
+ deviceTier: 'mobile' | 'desktop' | 'cinematic';
149
+ effectType: 'particle' | 'beam' | 'trail' | 'flipbook';
150
+ boundsMeters: [number, number, number];
151
+ portability: 'renderer-neutral-contract-draft';
152
+ runtimeCompatibility: VaultRuntime[];
153
+ loop: boolean;
154
+ maxParticles: number;
155
+ drawCalls: number;
156
+ decodedTextureMemoryBytes: number;
157
+ limits: {
158
+ maxParticles: number;
159
+ spawnRatePerSecond: number;
160
+ lifetimeSeconds: number;
161
+ speedMetersPerSecond: number;
162
+ sizeMeters: number;
163
+ boundsMeters: number;
164
+ beamLengthMeters: number;
165
+ beamSegments: number;
166
+ trailPoints: number;
167
+ };
168
+ textures: Array<{
169
+ role: 'sprite' | 'flipbook' | 'beam' | 'trail' | 'distortion';
170
+ artifact: VaultImmutableArtifactReference;
171
+ resolvedKind: 'texture' | 'decal';
172
+ colorSpace: 'srgb' | 'linear';
173
+ frames: {
174
+ columns: number;
175
+ rows: number;
176
+ frameCount: number;
177
+ framesPerSecond: number;
178
+ } | null;
179
+ }>;
180
+ particle: {
181
+ textureRole: string;
182
+ shape: 'point' | 'sphere' | 'box' | 'cone';
183
+ spawnRatePerSecond: number;
184
+ lifetimeSeconds: [number, number];
185
+ speedMetersPerSecond: [number, number];
186
+ sizeMeters: [number, number];
187
+ blendMode: 'alpha' | 'additive' | 'multiply';
188
+ billboard: 'camera' | 'velocity' | 'world';
189
+ } | null;
190
+ beam: {
191
+ textureRole: string;
192
+ widthMeters: [number, number];
193
+ lengthMeters: [number, number];
194
+ maxSegments: number;
195
+ noiseAmplitudeMeters: number;
196
+ blendMode: 'alpha' | 'additive' | 'multiply';
197
+ } | null;
198
+ trail: {
199
+ textureRole: string;
200
+ lifetimeSeconds: number;
201
+ widthMeters: [number, number];
202
+ maxPoints: number;
203
+ minVertexDistanceMeters: number;
204
+ blendMode: 'alpha' | 'additive' | 'multiply';
205
+ } | null;
206
+ flipbook: {
207
+ textureRole: string;
208
+ sizeMeters: [number, number];
209
+ blendMode: 'alpha' | 'additive' | 'multiply';
210
+ } | null;
211
+ };
212
+ };
213
+ export type VaultDecalMetadata = VaultMetadataBase & {
214
+ decal: {
215
+ projection: 'planar' | 'box';
216
+ widthMeters: number;
217
+ heightMeters: number;
218
+ blendMode: 'normal' | 'multiply' | 'additive';
219
+ };
220
+ };
221
+ export type VaultSkyMetadata = VaultMetadataBase & {
222
+ sky: {
223
+ schemaVersion: string;
224
+ sourceFormat: 'hdr' | 'exr';
225
+ projection: 'equirectangular' | 'cubemap';
226
+ colorSpace: 'linear-srgb' | 'acescg';
227
+ dynamicRangeStops: number;
228
+ exposureEv: number;
229
+ resolution: {
230
+ width: number;
231
+ height: number;
232
+ };
233
+ backdropRenditions: unknown[];
234
+ lightingRenditions: unknown[];
235
+ channelsSeparated: true;
236
+ };
237
+ };
238
+ export type VaultGaussianSplatMetadata = VaultMetadataBase & {
239
+ gaussianSplat: {
240
+ format: 'spz';
241
+ scope: VaultSplatScope;
242
+ pointCount: number | null;
243
+ boundsMeters: [number, number, number] | null;
244
+ pointDensityPerCubicMeter: number | null;
245
+ sphericalHarmonicsDegree: number | null;
246
+ quality: 'mobile' | 'balanced' | 'high' | 'cinematic' | 'unverified';
247
+ lodCount: number;
248
+ compression: {
249
+ format: 'spz';
250
+ level: unknown;
251
+ };
252
+ capture: {
253
+ provider: unknown;
254
+ source: unknown;
255
+ metersPerUnit: number;
256
+ upAxis: 'x' | 'y' | 'z';
257
+ };
258
+ performance: {
259
+ downloadBytes: number;
260
+ memoryBytes: number | null;
261
+ };
262
+ };
263
+ };
264
+ export type VaultSceneMetadata = VaultMetadataBase & {
265
+ scene: {
266
+ schemaVersion: string;
267
+ nodeCount: number;
268
+ references: Array<VaultImmutableArtifactReference & {
269
+ kind: 'prop' | 'character' | 'environment' | 'scene' | 'terrain' | 'vfx';
270
+ }>;
271
+ runtimeBundles: Array<{
272
+ runtime: VaultRuntime;
273
+ format: string;
274
+ artifact: VaultImmutableArtifactReference;
275
+ }>;
276
+ budget: {
277
+ deviceTier: 'mobile' | 'desktop' | 'cinematic';
278
+ derivedTotals: {
279
+ uniqueMaterials: number;
280
+ drawCalls: number;
281
+ decodedTextureMemoryBytes: number;
282
+ triangles: number;
283
+ particles: number;
284
+ };
285
+ basis: 'server-resolved-immutable-artifacts';
286
+ limits: {
287
+ uniqueMaterials: number;
288
+ drawCalls: number;
289
+ decodedTextureMemoryBytes: number;
290
+ triangles: number;
291
+ particles: number;
292
+ };
293
+ costScore: number;
294
+ withinBudget: true;
295
+ };
296
+ };
297
+ };
298
+ export type VaultUnrealPackageMetadata = VaultMetadataBase;
299
+ export type VaultMetadataByKind = {
300
+ prop: VaultPropMetadata;
301
+ character: VaultCharacterMetadata;
302
+ animation: VaultAnimationMetadata;
303
+ audio: VaultAudioMetadata;
304
+ texture: VaultTextureMetadata;
305
+ material: VaultMaterialMetadata;
306
+ environment: VaultEnvironmentMetadata;
307
+ terrain: VaultTerrainMetadata;
308
+ vfx: VaultVfxMetadata;
309
+ decal: VaultDecalMetadata;
310
+ sky: VaultSkyMetadata;
311
+ gaussian_splat: VaultGaussianSplatMetadata;
312
+ scene: VaultSceneMetadata;
313
+ unreal_package: VaultUnrealPackageMetadata;
314
+ };
315
+ export type VaultCompatibility = {
316
+ skeleton?: string;
317
+ skeletonVerification?: 'verified' | 'declared' | string;
318
+ skeletonBonesMatched?: number;
319
+ system?: string;
320
+ engines?: VaultRuntime[];
321
+ };
322
+ export type VaultCanonicalThumbnail = {
323
+ provenance?: string;
324
+ rendererVersion?: string;
325
+ artifactChecksumSha256?: string;
326
+ [key: string]: unknown;
327
+ };
328
+ export type VaultSelectionExplanation = {
329
+ rankMode: VaultRankMode;
330
+ lexical: {
331
+ matchedTerms: string[];
332
+ matchedFields: string[];
333
+ };
334
+ hardFilters: Record<string, unknown>;
335
+ performance: {
336
+ tier: VaultPerformanceTier | null;
337
+ costScore: number | null;
338
+ qualityScore: number | null;
339
+ };
340
+ reuse: {
341
+ worldUsageCount: number;
342
+ usageCount: number;
343
+ lastUsedAt: string | null;
344
+ };
345
+ availability: {
346
+ performanceMeasured: boolean;
347
+ qualityMeasured: boolean;
348
+ reuseObserved: boolean;
349
+ };
350
+ };
351
+ export type VaultAssetSummary<K extends VaultAssetKind = VaultAssetKind> = {
352
+ assetId: string;
353
+ slug: string;
354
+ title: string;
355
+ description: string | null;
356
+ kind: K;
357
+ license: 'helix_standard' | 'cc0' | 'cc_by' | 'all_rights_reserved';
358
+ compatibility: VaultCompatibility;
359
+ metadata: VaultMetadataByKind[K];
360
+ tags: string[];
361
+ source: 'manual' | 'dreamer' | 'world_generation' | 'import';
362
+ origin: 'generated' | 'uploaded';
363
+ visibility: 'public' | 'private' | 'held';
364
+ currentVersion: number;
365
+ thumbnailUrl: string | null;
366
+ thumbnailGenerator: string | null;
367
+ canonicalThumbnail: VaultCanonicalThumbnail | null;
368
+ artifactUrl: string | null;
369
+ artifactMimeType: string | null;
370
+ artifactSizeBytes: number | null;
371
+ contentRating: string;
372
+ contentRatingStatus: string | null;
373
+ worldUsageCount: number;
374
+ usageCount: number;
375
+ lastUsedAt: string | null;
376
+ creatorId: string;
377
+ createdAt: string;
378
+ updatedAt: string;
379
+ selectionExplanation?: VaultSelectionExplanation | null;
380
+ };
381
+ export type VaultRelatedArtifact = {
382
+ role: string;
383
+ url: string | null;
384
+ mimeType: string;
385
+ sizeBytes: number;
386
+ checksumSha256: string | null;
387
+ };
388
+ export type VaultResolvedArtifact = {
389
+ assetId: string;
390
+ version: number;
391
+ url: string | null;
392
+ urlKind: 'cdn' | 'unavailable';
393
+ mimeType: string;
394
+ sizeBytes: number;
395
+ checksumSha256: string | null;
396
+ relatedArtifacts: VaultRelatedArtifact[];
397
+ };
398
+ export type VaultAssetDetail<K extends VaultAssetKind = VaultAssetKind> = VaultAssetSummary<K> & {
399
+ artifact: VaultResolvedArtifact;
400
+ usedInWorlds: Array<{
401
+ worldId: string;
402
+ slug: string;
403
+ title: string;
404
+ }>;
405
+ };
406
+ export type VaultAssetVersion = {
407
+ handle: VaultAssetHandle;
408
+ url: string | null;
409
+ mimeType: string;
410
+ sizeBytes: number;
411
+ checksumSha256: string | null;
412
+ notes: string | null;
413
+ createdAt: string;
414
+ };
415
+ export type VaultSearchQuery = {
416
+ q?: string;
417
+ kind?: VaultAssetKind | VaultAssetKind[];
418
+ subtype?: string;
419
+ scope?: VaultSplatScope;
420
+ format?: string;
421
+ performanceTier?: VaultPerformanceTier;
422
+ skeleton?: 'humanoid' | 'quadruped';
423
+ engine?: VaultRuntime;
424
+ license?: VaultAssetSummary['license'];
425
+ source?: VaultAssetSummary['source'];
426
+ origin?: VaultAssetSummary['origin'];
427
+ creatorId?: string;
428
+ rank?: VaultRankMode;
429
+ page?: number;
430
+ limit?: number;
431
+ };
432
+ export type VaultSearchResult = {
433
+ items: VaultAssetSummary[];
434
+ totalItems: number;
435
+ };
436
+ export type VaultResolvedAsset<K extends VaultAssetKind = VaultAssetKind> = {
437
+ handle: VaultAssetHandle;
438
+ asset: VaultAssetDetail<K>;
439
+ artifact: VaultResolvedArtifact;
440
+ /**
441
+ * False only for a historical version: the backend currently exposes related
442
+ * artifacts on current-version detail, not version-history rows.
443
+ */
444
+ relatedArtifactsComplete: boolean;
445
+ };
446
+ export type VaultArtifactReference = {
447
+ role: 'primary' | string;
448
+ url: string | null;
449
+ mimeType: string;
450
+ sizeBytes: number;
451
+ checksumSha256: string | null;
452
+ };
453
+ export type VaultLoadPlan = {
454
+ loader: 'gltf';
455
+ purpose: 'prop' | 'character' | 'animation' | 'environment' | 'terrain';
456
+ handle: VaultAssetHandle;
457
+ primary: VaultArtifactReference;
458
+ related: VaultArtifactReference[];
459
+ } | {
460
+ loader: 'image';
461
+ purpose: 'texture' | 'decal';
462
+ handle: VaultAssetHandle;
463
+ primary: VaultArtifactReference;
464
+ related: VaultArtifactReference[];
465
+ } | {
466
+ loader: 'audio';
467
+ purpose: 'audio';
468
+ handle: VaultAssetHandle;
469
+ primary: VaultArtifactReference;
470
+ related: VaultArtifactReference[];
471
+ } | {
472
+ loader: 'hdr-environment';
473
+ purpose: 'sky';
474
+ format: 'hdr' | 'exr';
475
+ handle: VaultAssetHandle;
476
+ primary: VaultArtifactReference;
477
+ related: VaultArtifactReference[];
478
+ } | {
479
+ loader: 'gaussian-splat';
480
+ purpose: 'gaussian_splat' | 'environment';
481
+ format: 'spz';
482
+ scope: VaultSplatScope;
483
+ handle: VaultAssetHandle;
484
+ primary: VaultArtifactReference;
485
+ related: VaultArtifactReference[];
486
+ } | {
487
+ loader: 'helix-descriptor';
488
+ purpose: 'material' | 'scene' | 'terrain' | 'vfx' | 'sky';
489
+ schema: 'helix-material@1' | 'helix-scene@1' | 'helix-terrain@1' | 'helix-vfx@1' | 'helix-sky@1';
490
+ handle: VaultAssetHandle;
491
+ primary: VaultArtifactReference;
492
+ related: VaultArtifactReference[];
493
+ };
494
+ export type VaultDownloadedArtifact = {
495
+ reference: VaultArtifactReference;
496
+ bytes: ArrayBuffer;
497
+ checksumVerified: boolean;
498
+ };
499
+ export type VaultInstallResult = {
500
+ asset: VaultResolvedAsset;
501
+ plan: VaultLoadPlan;
502
+ primary: VaultDownloadedArtifact;
503
+ related: VaultDownloadedArtifact[];
504
+ };
505
+ export type VaultClientOptions = {
506
+ /**
507
+ * HELIX API origin (the client appends `/api/v1/vault`) or a full Vault API
508
+ * base ending in `/api/v1/vault`.
509
+ */
510
+ apiBaseUrl: string;
511
+ fetch?: typeof fetch;
512
+ accessToken?: string | null | (() => string | null | Promise<string | null>);
513
+ /** Optional portable SHA-256 implementation; output must be lowercase hex. */
514
+ sha256?: (bytes: ArrayBuffer) => Promise<string>;
515
+ };
516
+ export type VaultInstallOptions = {
517
+ /** Related rendition roles to fetch. Omit to fetch no related artifacts. */
518
+ relatedRoles?: string[];
519
+ /** Defaults to true whenever the server supplied a checksum. */
520
+ verifyChecksum?: boolean;
521
+ };
522
+ export declare class VaultApiError extends Error {
523
+ readonly status: number;
524
+ readonly url: string;
525
+ readonly responseBody: string;
526
+ constructor(status: number, url: string, responseBody: string);
527
+ }
528
+ export declare class VaultArtifactUnavailableError extends Error {
529
+ readonly handle: VaultAssetHandle;
530
+ constructor(handle: VaultAssetHandle);
531
+ }
532
+ export declare class VaultChecksumMismatchError extends Error {
533
+ readonly expected: string;
534
+ readonly actual: string;
535
+ constructor(expected: string, actual: string);
536
+ }
537
+ export declare class VaultUnsupportedRuntimeError extends Error {
538
+ readonly kind: VaultAssetKind;
539
+ readonly mimeType: string;
540
+ constructor(kind: VaultAssetKind, mimeType: string, reason: string);
541
+ }
542
+ export declare class VaultCapabilityUnavailableError extends Error {
543
+ readonly capability: 'fetch' | 'sha256';
544
+ constructor(capability: 'fetch' | 'sha256');
545
+ }
546
+ /**
547
+ * Convert a resolved Vault artifact into a renderer-neutral loader handoff.
548
+ * The SDK never imports or guesses a rendering engine.
549
+ */
550
+ export declare function createVaultLoadPlan(resolved: VaultResolvedAsset): VaultLoadPlan;
551
+ export type VaultClient = {
552
+ search(query?: VaultSearchQuery): Promise<VaultSearchResult>;
553
+ get<K extends VaultAssetKind = VaultAssetKind>(assetId: string): Promise<VaultAssetDetail<K>>;
554
+ versions(assetId: string): Promise<VaultAssetVersion[]>;
555
+ resolve<K extends VaultAssetKind = VaultAssetKind>(handleOrAssetId: VaultAssetHandle | string): Promise<VaultResolvedAsset<K>>;
556
+ createLoadPlan(resolved: VaultResolvedAsset): VaultLoadPlan;
557
+ download(handleOrAssetId: VaultAssetHandle | string, options?: Pick<VaultInstallOptions, 'verifyChecksum'>): Promise<VaultDownloadedArtifact>;
558
+ downloadArtifact(reference: VaultArtifactReference, options?: Pick<VaultInstallOptions, 'verifyChecksum'>): Promise<VaultDownloadedArtifact>;
559
+ install(handleOrAssetId: VaultAssetHandle | string, options?: VaultInstallOptions): Promise<VaultInstallResult>;
560
+ };
561
+ export declare function createVaultClient(options: VaultClientOptions): VaultClient;
562
+ export {};