@helix3/helix-sdk 0.1.1-helix3.20

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hypersonic Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @hypersoniclabs/helix-sdk
+
+The **HELIX Instant browser SDK** — the runtime a world embeds to talk to the HELIX shell
+(the play page that iframes it). v0.1 provides identity; later versions add multiplayer, voice,
+wallet, and inventory.
+
+A world is a static bundle that runs inside a **sandboxed iframe**. The shell hands it a
+short-lived, world-scoped session token (minted by the backend at
+`POST /api/v1/instant-worlds/:worldId/session`) over `postMessage`. The SDK wraps that handshake.
+
+## Install
+
+```bash
+npm install @hypersoniclabs/helix-sdk
+```
+
+## Usage
+
+```ts
+import { Helix } from '@hypersoniclabs/helix-sdk';
+
+const { embedded, world, user } = await Helix.init(); // call once, at startup
+
+if (Helix.auth.isAuthenticated()) {
+  const me = await Helix.auth.getUser(); // { id, username, displayName }
+}
+
+// Raise the shell's login overlay (no-op reload — world state is preserved):
+loginButton.onclick = async () => {
+  try {
+    const user = await Helix.auth.requestLogin();
+    console.log('signed in as', user.username);
+  } catch {
+    /* dismissed or unavailable */
+  }
+};
+
+Helix.auth.onAuthChanged((user) => updateUi(user)); // login + logout
+
+// Ask the HELIX shell to render native status notifications.
+Helix.notify.success('Prize claimed', 'Welcome Chip added to inventory');
+Helix.notify.failure('Purchase failed', 'Not enough LIX');
+Helix.notify.notification('Quest updated', 'Return to the VIP lounge');
+Helix.notify.message('Nova', 'Meet me by the arcade machines');
+
+// Publish a current interaction prompt without tying your world to a renderer.
+Helix.prompts.set({
+  id: 'fortune-arcade.vip',
+  title: 'VIP Room',
+  description: 'Buy a keycard to enter.',
+  input: { key: 'E', label: 'Interact' },
+  actionLabel: 'Buy keycard',
+  state: 'available',
+});
+Helix.prompts.clear('fortune-arcade.vip');
+```
+
+When the world is opened directly (e.g. a local `vite dev` server with no shell), `init()` resolves
+with `embedded: false` and all identity APIs return `null`/`false` — so the same build runs locally
+and embedded.
+
+### API
+
+- `Helix.init(): Promise<{ embedded, world, user }>` — handshake; call once before anything else.
+- `Helix.auth.getUser(): Promise<HelixUser | null>`
+- `Helix.auth.isAuthenticated(): boolean`
+- `Helix.auth.requestLogin(): Promise<HelixUser>` — resolves on login, rejects on dismiss/unavailable.
+- `Helix.auth.onAuthChanged(fn): () => void` — fires on login and logout; returns an unsubscribe fn.
+- `Helix.notify.show({ kind, title, message?, timeoutMs?, actionLabel?, actionHref? }): boolean`
+- `Helix.notify.success|failure|notification|message(title, message?): boolean` — returns `false` when
+  the world is running standalone without a shell.
+- `Helix.prompts.set({ id, title, description?, input?, actionLabel?, state?, priority? }): boolean`
+- `Helix.prompts.clear(promptId?): boolean`
+- `Helix.getSessionToken(): string | null` — the world-scoped token, for advanced direct API calls.
+
+### Economy & items (v2, shell-mediated)
+
+All of these are **server-authoritative**: the world *requests*, the shell (which holds the player's
+session) settles with the backend and renders the purchase popup. Reads degrade to empty defaults
+when not embedded; a purchase returns `Unauthorized` (never a fake success).
+
+```ts
+const { lix, coins } = await Helix.wallet.getBalance();
+Helix.wallet.onBalanceChanged((b) => updateHud(b));
+
+// Buy a marketplace item or a world-registered product. completed === player owns it now.
+const res = await Helix.marketplace.purchaseItem('premium_sword_001');
+if (res.completed) equip('premium_sword_001');         // Granted | Claimed | AlreadyOwned
+else showToast(res.status);                            // InsufficientFunds | Cancelled | …
+
+await Helix.marketplace.purchaseProduct('golden_key'); // a world product
+const items = await Helix.marketplace.getListings({ kind: 'home_item' });
+
+// Ownership gating — works across worlds & creators (VIP / season passes).
+if (await Helix.inventory.hasItem('vip_pass_001')) openBackstage();
+const owned = await Helix.inventory.getMyItems();
+await Helix.inventory.equipItem('vip_hat_001');
+Helix.inventory.onInventoryChanged(refreshInventory);
+```
+
+- `Helix.wallet.getBalance()` / `onBalanceChanged(fn)`
+- `Helix.marketplace.purchaseItem(itemId)` / `purchaseProduct(productId)` / `getListings(query?)` / `getPurchaseContext(ref)`
+- `Helix.inventory.hasItem(id)` / `getQuantity(id)` / `getMyItems()` / `equipItem(id)` / `onInventoryChanged(fn)`
+
+The SDK mints a stable idempotency key per purchase (reused across the popup's retries) so a dropped
+network can never double-charge. See the backend `/api/v1/iwp/*` endpoints for the settlement layer.
+
+### Interaction prompts
+
+`Helix.prompts` is intentionally engine-agnostic. A Three.js, Phaser, Unity WebGL, or plain DOM world
+can all publish the same contract: a stable prompt id, display text, optional keyboard/gamepad labels,
+and a coarse state (`default`, `available`, `locked`, or `busy`). The shell decides how to render it.
+
+## Protocol
+
+[`src/protocol.ts`](src/protocol.ts) is the wire contract (`postMessage` messages between world and
+shell) and is imported by both sides. Any breaking change must bump `PROTOCOL_VERSION`. The
+`HelixSession` shape matches the backend's `InstantWorldSessionResponseDto`, so the shell forwards
+the backend response verbatim.
+
+## Develop
+
+```bash
+npm install
+npm test       # jest + jsdom
+npm run build  # tsc → dist/ (ESM)
+npm run lint
+```

package/dist/camera.d.ts

@@ -0,0 +1,14 @@
+import type { CameraAspect } from './protocol';
+export type CaptureOptions = {
+    aspect?: CameraAspect;
+    type?: string;
+    quality?: number;
+};
+export type CropRect = {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+};
+export declare function cropRectForAspect(w: number, h: number, aspect?: CameraAspect): CropRect;
+export declare function captureCanvas(source: HTMLCanvasElement, opts?: CaptureOptions): Promise<Blob>;

package/dist/camera.js

@@ -0,0 +1,72 @@
+// Camera capture helpers — the in-iframe pixel side of the universal world camera.
+//
+// The SDK core (index.ts) owns the shell-mediated `Helix.camera.savePhoto`. This
+// file holds the pure/DOM-only capture glue so it can be unit-tested without the
+// postMessage shell: the crop math is pure; `captureCanvas` is the one DOM call.
+//
+// WebGL gotcha: the drawing buffer is cleared after each frame, so reading a
+// WebGL canvas a frame later yields black. Callers must either render into the
+// canvas immediately before capturing (same tick), capture inside the rAF right
+// after the world's render, or create the context with preserveDrawingBuffer.
+// Aspect ratios as width/height. `free`/`square` are handled in cropRectForAspect.
+const ASPECT_RATIO = {
+    portrait: 3 / 4,
+    landscape: 4 / 3,
+};
+// Centre-crop rectangle for a source canvas of (w×h) at the requested aspect.
+// `free` returns the full frame; `square` is 1:1. Pure — no DOM.
+export function cropRectForAspect(w, h, aspect = 'free') {
+    if (w <= 0 || h <= 0)
+        return { sx: 0, sy: 0, sw: Math.max(0, w), sh: Math.max(0, h) };
+    if (aspect === 'free')
+        return { sx: 0, sy: 0, sw: w, sh: h };
+    const target = aspect === 'square' ? 1 : ASPECT_RATIO[aspect];
+    const current = w / h;
+    let sw = w;
+    let sh = h;
+    if (current > target) {
+        // too wide → crop width
+        sw = Math.round(h * target);
+    }
+    else {
+        // too tall → crop height
+        sh = Math.round(w / target);
+    }
+    const sx = Math.round((w - sw) / 2);
+    const sy = Math.round((h - sh) / 2);
+    return { sx, sy, sw, sh };
+}
+// Capture a (rendered) canvas to an encoded Blob, centre-cropped to `aspect`.
+// DOM-only. Throws if the environment has no 2D canvas (non-browser) or the
+// canvas is empty. The caller is responsible for rendering into `source` first.
+export async function captureCanvas(source, opts = {}) {
+    const type = opts.type ?? 'image/jpeg';
+    const quality = opts.quality ?? 0.92;
+    const { sx, sy, sw, sh } = cropRectForAspect(source.width, source.height, opts.aspect ?? 'free');
+    if (sw <= 0 || sh <= 0) {
+        throw new Error('Helix.camera: nothing to capture (empty canvas)');
+    }
+    // Crop via an offscreen 2D canvas. When aspect is 'free' and no crop is needed
+    // we still copy through a 2D canvas so toBlob works uniformly across a WebGL
+    // source canvas.
+    const out = typeof OffscreenCanvas !== 'undefined'
+        ? new OffscreenCanvas(sw, sh)
+        : Object.assign(document.createElement('canvas'), { width: sw, height: sh });
+    const ctx = out.getContext('2d');
+    if (!ctx)
+        throw new Error('Helix.camera: 2D canvas context unavailable');
+    ctx.drawImage(source, sx, sy, sw, sh, 0, 0, sw, sh);
+    return canvasToBlob(out, type, quality);
+}
+function canvasToBlob(canvas, type, quality) {
+    // OffscreenCanvas exposes convertToBlob; HTMLCanvasElement exposes toBlob.
+    const offscreen = canvas;
+    if (typeof offscreen.convertToBlob === 'function') {
+        return offscreen.convertToBlob({ type, quality });
+    }
+    const el = canvas;
+    return new Promise((resolve, reject) => {
+        el.toBlob((blob) => blob ? resolve(blob) : reject(new Error('Helix.camera: toBlob returned null')), type, quality);
+    });
+}
+//# sourceMappingURL=camera.js.map

package/dist/camera.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"camera.js","sourceRoot":"","sources":["../src/camera.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import { HelixInteractionPrompt, HelixNotification, HelixWorldContext, HelixUser, DebugLogEntry, Balance, PurchaseResult, PurchaseContext, InventoryItem, EquippedAvatar, AvatarLoadout, AvatarLoadoutPatch, MarketplaceListing, MarketplaceQuery, CameraAspect, SavedPhoto } from './protocol';
+import { HelixMultiplayer } from './multiplayer';
+import { CaptureOptions } from './camera';
+export type { HelixInteractionPrompt, HelixNotification, HelixNotificationKind, HelixPromptState, HelixDeviceFormFactor, HelixWorldContext, HelixSession, HelixUser, DebugLogEntry, DebugLogLevel, Balance, PurchaseResult, PurchaseStatus, PurchaseContext, InventoryItem, EquippedAvatar, AvatarLoadout, AvatarLoadoutPatch, MarketplaceListing, MarketplaceQuery, CameraAspect, SavedPhoto, } from './protocol';
+export type { CaptureOptions, CropRect } from './camera';
+export { cropRectForAspect, captureCanvas } from './camera';
+export type { HelixRoom, JoinRoomOptions, ReplicaInput } from './multiplayer';
+export * from './multiplayer-contract';
+export type HelixInitResult = {
+    embedded: boolean;
+    world: HelixWorldContext | null;
+    user: HelixUser | null;
+};
+type AuthListener = (user: HelixUser | null) => void;
+type AnalyticsEventName = 'world_entered' | 'world_loaded' | 'world_load_failed' | 'world_exited' | 'world_heartbeat' | 'instance_joined' | 'instance_left' | 'creator_product_viewed' | 'client_error_seen' | 'api_error_seen';
+type AnalyticsTrackInput = {
+    eventId?: string;
+    instanceId?: string | null;
+    itemId?: string | null;
+    inviteId?: string | null;
+    referrer?: string | null;
+    properties?: Record<string, string | number | boolean | null | undefined>;
+};
+declare class HelixSdk {
+    private shellOrigin;
+    private session;
+    private world;
+    private initialized;
+    private listeners;
+    private debugEnabled;
+    private debugRing;
+    private debugListeners;
+    private consoleHooked;
+    private pendingLogins;
+    private pendingRequests;
+    private balanceListeners;
+    private inventoryListeners;
+    private avatarListeners;
+    init(): Promise<HelixInitResult>;
+    readonly multiplayer: HelixMultiplayer;
+    readonly debug: {
+        enabled: () => boolean;
+        log: (...args: unknown[]) => void;
+        onLog: (cb: (entry: DebugLogEntry) => void) => (() => void);
+        recent: () => DebugLogEntry[];
+    };
+    readonly auth: {
+        getUser: () => Promise<HelixUser | null>;
+        isAuthenticated: () => boolean;
+        requestLogin: () => Promise<HelixUser>;
+        onAuthChanged: (listener: AuthListener) => (() => void);
+    };
+    readonly notify: {
+        show: (notification: HelixNotification) => boolean;
+        success: (title: string, message?: string) => boolean;
+        failure: (title: string, message?: string) => boolean;
+        notification: (title: string, message?: string) => boolean;
+        message: (title: string, message?: string) => boolean;
+    };
+    readonly prompts: {
+        set: (prompt: HelixInteractionPrompt) => boolean;
+        clear: (promptId?: string) => boolean;
+    };
+    readonly device: {
+        openTablet: () => boolean;
+        openPhone: () => boolean;
+    };
+    getSessionToken(): string | null;
+    readonly wallet: {
+        getBalance: () => Promise<Balance>;
+        onBalanceChanged: (cb: (b: Balance) => void) => (() => void);
+    };
+    readonly marketplace: {
+        purchaseItem: (itemId: string) => Promise<PurchaseResult>;
+        purchaseProduct: (productId: string) => Promise<PurchaseResult>;
+        getListings: (query?: MarketplaceQuery) => Promise<MarketplaceListing[]>;
+        getPurchaseContext: (ref: string) => Promise<PurchaseContext | null>;
+    };
+    readonly analytics: {
+        track: (eventName: AnalyticsEventName, input?: AnalyticsTrackInput) => Promise<void>;
+    };
+    readonly inventory: {
+        hasItem: (itemId: string) => Promise<boolean>;
+        getQuantity: (itemId: string) => Promise<number>;
+        getMyItems: () => Promise<InventoryItem[]>;
+        equipItem: (itemId: string) => Promise<void>;
+        onInventoryChanged: (cb: () => void) => (() => void);
+    };
+    readonly dataStore: {
+        get: <T = unknown>(key: string) => Promise<T | null>;
+        set: <T = unknown>(key: string, value: T) => Promise<void>;
+        delete: (key: string) => Promise<void>;
+        list: (prefix?: string) => Promise<string[]>;
+    };
+    readonly camera: {
+        available: () => boolean;
+        capture: (canvas: HTMLCanvasElement, opts?: CaptureOptions) => Promise<Blob>;
+        savePhoto: (image: Blob | ArrayBuffer | Uint8Array, meta?: {
+            caption?: string;
+            aspect?: CameraAspect;
+            contentType?: string;
+        }) => Promise<SavedPhoto | null>;
+    };
+    readonly avatar: {
+        openCreator: () => Promise<boolean>;
+        getLoadout: () => Promise<AvatarLoadout | null>;
+        updateLoadout: (patch: AvatarLoadoutPatch) => Promise<AvatarLoadout | null>;
+        getEquipped: () => Promise<EquippedAvatar | null>;
+        onAvatarChanged: (cb: () => void) => (() => void);
+    };
+    private purchase;
+    private trackAnalytics;
+    private safeAnalyticsProperties;
+    private openDevice;
+    private onKeyDown;
+    private request;
+    private newId;
+    private fetchAvatarLoadout;
+    private emitAvatarChanged;
+    private snapshot;
+    private assertInitialized;
+    private waitForInit;
+    private onMessage;
+    private setSession;
+    private enableDebug;
+    private hookConsole;
+    private captureLog;
+    private post;
+    private postToShell;
+}
+export declare const Helix: HelixSdk;