@steerprotocol/app-loader 2.1.1 → 3.0.1

package/README.md

@@ -1 +1,141 @@
-# Steer Protocol App Loader
+# Steer Protocol App Loader
+
+Load and execute Steer wasm bundles in Node.js and browser environments.
+
+Node 18+ is required.
+
+## Install
+
+```bash
+npm install @steerprotocol/app-loader
+```
+
+## Runtime Support
+
+- Root import `@steerprotocol/app-loader`
+  - Node: resolves to the Node entrypoint
+  - Browser bundlers: resolves to the browser entrypoint through the `browser` export condition
+- Explicit browser import: `@steerprotocol/app-loader/browser`
+- Explicit Node import: `@steerprotocol/app-loader/node`
+
+## Usage
+
+### Node
+
+Use the root import for typical Node usage.
+
+```ts
+import { loadWasm } from '@steerprotocol/app-loader';
+
+const bundle = await loadWasm('/absolute/path/to/bundle.wasm');
+bundle.initialize('{"example":true}');
+```
+
+Node supports:
+
+- filesystem paths
+- `ArrayBuffer`
+- remote URLs
+
+Node runtime note:
+
+- native `fetch` is required
+- Node 18+ is the supported baseline
+
+If you want an explicit Node-only import:
+
+```ts
+import { loadWasm } from '@steerprotocol/app-loader/node';
+```
+
+### Browser
+
+The browser entry supports `ArrayBuffer` and remote URL loading.
+
+```ts
+import { loadWasm } from '@steerprotocol/app-loader';
+
+const response = await fetch('/bundle.wasm');
+const bundle = await loadWasm(await response.arrayBuffer());
+bundle.initialize('{"example":true}');
+```
+
+If you want to pin the browser-specific entrypoint:
+
+```ts
+import { loadWasm } from '@steerprotocol/app-loader/browser';
+```
+
+### Browser `ccxt`
+
+In browsers, `ccxt` is expected on `globalThis.ccxt`.
+
+If you load `ccxt` from a CDN or hosted bundle, make sure it is available before executing wasm that depends on it.
+
+```html
+<script src="https://unpkg.com/ccxt@4.5.46/dist/ccxt.browser.min.js"></script>
+```
+
+The hosted browser build is covered by the default test suite with a live network smoke test against the same unpkg URL.
+
+### Node `ccxt`
+
+In Node, `ccxt` is loaded from the installed module automatically.
+
+## API
+
+Main exports:
+
+- `loadWasm(input, imports?)`
+- `loadWasmSync(input, imports?)`
+- `Candle`
+- `RawTradeData`
+
+The returned wasm wrapper exposes the module surface when available, including:
+
+- `initialize(config)`
+- `execute(...args)`
+- `config()`
+- `transform()`
+- `reset()`
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Unit And Integration Tests
+
+```bash
+npm test
+```
+
+An env-gated live repro for the deprecated Sushi Polygon v2 connector is enabled when
+`STEER_SUBGRAPH_STUDIO_KEY` is set (or `STEER_SUBGRAPH_GATEWAY_KEY` for local debugging). This connector is kept as historical evidence of a
+known-broken path and is not part of the supported execution contract.
+
+### Packed Consumer Smoke Tests
+
+These tests validate the packed artifact in real consumer fixtures for:
+
+- Node ESM
+- Node CJS
+- Vite browser builds
+
+```bash
+npm run test:consumers
+```
+
+This command builds the package, packs it, installs the tarball into fixture apps, and runs each fixture check.
+
+## Migration Notes
+
+Version 2 changes the package runtime contract.
+
+- Browser consumers should rely on the root import only when their bundler honors the `browser` export condition.
+- Browser `ccxt` integration now expects the hosted browser build on `globalThis.ccxt`.
+- Node consumers should use the root import or `@steerprotocol/app-loader/node`.
+- Browser consumers can use `@steerprotocol/app-loader/browser` to pin the browser-safe entrypoint explicitly.

package/lib/WasmModule-D9evRq1D.d.mts

@@ -0,0 +1,74 @@
+/**
+ * Trade point model used as candle-generation input.
+ */
+declare class RawTradeData {
+    timestamp: number;
+    price: number;
+    volume: number;
+    /**
+     * Creates a raw trade data point.
+     * @param timestamp - Trade timestamp.
+     * @param price - Trade price.
+     * @param volume - Trade volume.
+     */
+    constructor(timestamp: number, price: number, volume: number);
+}
+
+/**
+ * OHLCV candle model.
+ */
+declare class Candle {
+    timestamp: number;
+    high: number;
+    low: number;
+    open: number;
+    close: number;
+    volume: number;
+    /**
+     * Creates a candle instance.
+     * @param timestamp - Candle open timestamp in milliseconds.
+     * @param high - Highest traded price.
+     * @param low - Lowest traded price.
+     * @param open - Opening price.
+     * @param close - Closing price.
+     * @param volume - Total traded volume.
+     */
+    constructor(timestamp: number, high: number, low: number, open: number, close: number, volume: number);
+    /**
+     * Serializes the candle as JSON.
+     * @returns The candle as a JSON string.
+     */
+    toString(): string;
+}
+
+/**
+ * Type declarations for the wasm exports surfaced by this package.
+ */
+declare function responseHandler(body: ArrayBuffer, statusCode: number, redirected: number, callbackID: number): void;
+declare function initialize(config: string): boolean;
+declare function config(): string;
+declare function version(): number;
+declare function transform(): string;
+declare function execute(...params: Array<number | string | ArrayBuffer | null>): Promise<string | null>;
+declare function __new(size: number, id: number): number;
+declare function __pin(ptr: number): number;
+declare function __unpin(ptr: number): number;
+declare function reset(): void;
+/**
+ * Public shape of the wrapped wasm exports.
+ */
+type WasmModule = {
+    responseHandler: typeof responseHandler;
+    initialize: typeof initialize;
+    execute: typeof execute;
+    config: typeof config;
+    version: typeof version;
+    transform: typeof transform;
+    memory: WebAssembly.Memory;
+    __new: typeof __new;
+    __pin: typeof __pin;
+    __unpin: typeof __unpin;
+    reset: typeof reset;
+};
+
+export { Candle as C, RawTradeData as R, type WasmModule as W };

package/lib/WasmModule-D9evRq1D.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Trade point model used as candle-generation input.
+ */
+declare class RawTradeData {
+    timestamp: number;
+    price: number;
+    volume: number;
+    /**
+     * Creates a raw trade data point.
+     * @param timestamp - Trade timestamp.
+     * @param price - Trade price.
+     * @param volume - Trade volume.
+     */
+    constructor(timestamp: number, price: number, volume: number);
+}
+
+/**
+ * OHLCV candle model.
+ */
+declare class Candle {
+    timestamp: number;
+    high: number;
+    low: number;
+    open: number;
+    close: number;
+    volume: number;
+    /**
+     * Creates a candle instance.
+     * @param timestamp - Candle open timestamp in milliseconds.
+     * @param high - Highest traded price.
+     * @param low - Lowest traded price.
+     * @param open - Opening price.
+     * @param close - Closing price.
+     * @param volume - Total traded volume.
+     */
+    constructor(timestamp: number, high: number, low: number, open: number, close: number, volume: number);
+    /**
+     * Serializes the candle as JSON.
+     * @returns The candle as a JSON string.
+     */
+    toString(): string;
+}
+
+/**
+ * Type declarations for the wasm exports surfaced by this package.
+ */
+declare function responseHandler(body: ArrayBuffer, statusCode: number, redirected: number, callbackID: number): void;
+declare function initialize(config: string): boolean;
+declare function config(): string;
+declare function version(): number;
+declare function transform(): string;
+declare function execute(...params: Array<number | string | ArrayBuffer | null>): Promise<string | null>;
+declare function __new(size: number, id: number): number;
+declare function __pin(ptr: number): number;
+declare function __unpin(ptr: number): number;
+declare function reset(): void;
+/**
+ * Public shape of the wrapped wasm exports.
+ */
+type WasmModule = {
+    responseHandler: typeof responseHandler;
+    initialize: typeof initialize;
+    execute: typeof execute;
+    config: typeof config;
+    version: typeof version;
+    transform: typeof transform;
+    memory: WebAssembly.Memory;
+    __new: typeof __new;
+    __pin: typeof __pin;
+    __unpin: typeof __unpin;
+    reset: typeof reset;
+};
+
+export { Candle as C, RawTradeData as R, type WasmModule as W };