extended-typescript-sdk 0.0.5 → 0.0.7

package/README.md

@@ -1,9 +1,33 @@
-# Extended TypeScript Trading SDK
+# Extended TypeScript SDK
 
-**⚠️ Unofficial SDK**: This is an **unofficial TypeScript SDK** for Extended Exchange, built and maintained by the community. It is not officially supported by Extended.
+This is a community-maintained TypeScript SDK for Extended Exchange. It is not officially supported by Extended.
 
 TypeScript client for [Extended Exchange API](https://api.docs.extended.exchange/).
 
+## ✅ Works in Both Node.js and Browser
+
+This SDK is **production-ready** for both backend and frontend applications:
+
+- ✅ **Node.js** (v18+) - Works immediately, no configuration needed
+- ✅ **Browser** (Chrome, Firefox, Safari, Edge) - Requires one-time bundler config
+- ✅ **All Modern Bundlers** (Vite, Webpack, Rollup, Next.js, Parcel)
+- ✅ **Dual Package** - Ships ESM + CommonJS for maximum compatibility
+- ✅ **WASM Crypto** - Pre-built for both Node.js and browser (no Rust needed)
+
+### Package Structure
+
+```
+extended-typescript-sdk/
+├── dist/
+│   ├── esm/          # ES Modules (import)
+│   └── cjs/          # CommonJS (require)
+└── wasm/
+    ├── stark_crypto_wasm.js             # Node.js WASM
+    ├── stark_crypto_wasm_bg.wasm        # Node.js binary
+    ├── stark_crypto_wasm-web.js         # Browser WASM
+    └── stark_crypto_wasm_bg-web.wasm    # Browser binary
+```
+
 ## About Extended Exchange
 
 Extended is a perpetual DEX (Decentralized Exchange), built by an ex-Revolut team. As of now, Extended offers perpetual contracts on both crypto and TradFi assets, with USDC as collateral and leverage of up to 100x.
@@ -16,10 +40,224 @@ This SDK provides full type safety and modern async/await patterns for interacti
 npm install extended-typescript-sdk
 ```
 
+### Node.js Setup (Backend)
+
+✅ **No configuration needed!** Just install and use:
+
+```typescript
+import { initWasm, TESTNET_CONFIG } from 'extended-typescript-sdk';
+
+await initWasm(); // Automatically loads Node.js WASM
+// Ready to trade!
+```
+
+### Browser Setup (Frontend)
+
+1. **Install the SDK:**
+   ```bash
+   npm install extended-typescript-sdk
+   ```
+
+2. **Configure your bundler** (one-time setup):
+   - See bundler configuration below for Vite, Webpack, Next.js, etc.
+
+3. **Use in your app:**
+   ```typescript
+   import { initWasm, TESTNET_CONFIG } from 'extended-typescript-sdk';
+   
+   await initWasm(); // Automatically loads browser WASM
+   // Ready to trade!
+   ```
+
+**✅ Node.js Backend:** Works immediately - no configuration needed!
+
+**⚙️ Browser/Frontend:** Requires one-time bundler configuration (see below)
+
+---
+
+### Browser Bundler Setup
+
+This SDK uses WebAssembly for cryptographic operations. Modern bundlers need minimal configuration to handle WASM files.
+
+#### Quick Setup by Bundler
+
+<details>
+<summary><b>✅ Vite (Recommended)</b></summary>
+
+Vite has excellent WASM support. Add this to `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['extended-typescript-sdk']
+  },
+  assetsInclude: ['**/*.wasm'],
+  build: {
+    target: 'esnext'
+  }
+});
+```
+
+**Optional: Copy WASM files to dist** (for production deployments):
+
+```bash
+npm install --save-dev vite-plugin-static-copy
+```
+
+```typescript
+import { defineConfig } from 'vite';
+import { viteStaticCopy } from 'vite-plugin-static-copy';
+
+export default defineConfig({
+  plugins: [
+    viteStaticCopy({
+      targets: [{
+        src: 'node_modules/extended-typescript-sdk/wasm/*',
+        dest: 'wasm'
+      }]
+    })
+  ],
+  optimizeDeps: {
+    exclude: ['extended-typescript-sdk']
+  }
+});
+```
+
+✅ See [vite.config.example.ts](./vite.config.example.ts) for a complete example
+
+</details>
+
+<details>
+<summary><b>Webpack 5+</b></summary>
+
+Enable async WebAssembly in `webpack.config.js`:
+
+```javascript
+module.exports = {
+  experiments: {
+    asyncWebAssembly: true,
+  },
+  module: {
+    rules: [
+      {
+        test: /\.wasm$/,
+        type: 'webassembly/async',
+      },
+    ],
+  },
+};
+```
+
+</details>
+
+<details>
+<summary><b>Next.js</b></summary>
+
+Add to `next.config.js`:
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  webpack: (config) => {
+    config.experiments = {
+      ...config.experiments,
+      asyncWebAssembly: true,
+    };
+    return config;
+  },
+};
+
+module.exports = nextConfig;
+```
+
+</details>
+
+<details>
+<summary><b>Rollup Configuration</b></summary>
+
+**Install plugin:**
+```bash
+npm install --save-dev @rollup/plugin-wasm
+```
+
+**Configure `rollup.config.js`:**
+```javascript
+import wasm from '@rollup/plugin-wasm';
+
+export default {
+  plugins: [
+    wasm({
+      maxFileSize: 10000000, // 10MB
+      targetEnv: 'auto',
+    }),
+  ],
+};
+```
+
+</details>
+
+---
+
+### Troubleshooting Bundler Issues
+
+**Problem: `Cannot find module 'extended-typescript-sdk/wasm/...'`**
+
+Solution: Add to bundler config:
+```typescript
+optimizeDeps: {
+  exclude: ['extended-typescript-sdk']
+}
+```
+
+**Problem: WASM loading fails in production**
+
+Solution: Ensure WASM files are copied to your dist folder. Use `vite-plugin-static-copy` (Vite) or `copy-webpack-plugin` (Webpack).
+
+**Problem: `WebAssembly module is included in initial chunk`**
+
+Solution: Configure code splitting or external WASM:
+```typescript
+build: {
+  rollupOptions: {
+    external: [/\.wasm$/]
+  }
+}
+```
+
+**Problem: Works in dev but not production**
+
+Solution: Check that WASM files are included in your production build:
+- Vite: Check `dist/wasm/` folder
+- Webpack: Verify WASM files in output bundle
+- Next.js: Check `.next/static/` or public folder
+
+📖 **For detailed troubleshooting**, see [ENVIRONMENT_SUPPORT.md](./ENVIRONMENT_SUPPORT.md)
+
+---
+
 ## Prerequisites
 
 - Node.js 18+ or TypeScript 5.3+
-- **No Rust required** - The SDK ships with pre-built WASM signer
+- **No Rust required** - The SDK ships with pre-built WASM for both Node.js and browser
+
+## Environment Testing
+
+The SDK includes comprehensive tests for both environments:
+
+```bash
+# Test Node.js CommonJS and ESM compatibility
+npm run test:cjs-esm
+
+# Test browser bundler compatibility (Vite)
+npm run test:vite
+
+# Test all compatibility scenarios
+npm run test:compat
+```
+
+All tests pass in both Node.js and browser environments, confirming dual-environment support.
 
 ## Quick Start
 
@@ -182,6 +420,83 @@ for await (const update of accountStream) {
 }
 ```
 
+## Bundler Configuration (Vite, Rollup, Webpack)
+
+If you're using **Vite, Rollup, Webpack, or Next.js**, you may encounter WASM-related build errors. Here's how to fix them:
+
+### Vite Configuration
+
+Add this to your `vite.config.js` or `vite.config.ts`:
+
+```javascript
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  optimizeDeps: {
+    exclude: ['extended-typescript-sdk']
+  },
+  assetsInclude: ['**/*.wasm'],
+});
+```
+
+### Common Build Error
+
+If you see this error:
+```
+Could not resolve "./stark_crypto_wasm_bg.js" from "node_modules/extended-typescript-sdk/wasm/..."
+```
+
+**Solution**: Add the SDK to the `exclude` list in your bundler configuration:
+
+```javascript
+// vite.config.js
+export default {
+  optimizeDeps: {
+    exclude: ['extended-typescript-sdk']
+  }
+}
+```
+
+### Other Bundlers
+
+#### Webpack 5
+```javascript
+module.exports = {
+  experiments: {
+    asyncWebAssembly: true,
+  },
+};
+```
+
+#### Next.js
+```javascript
+// next.config.js
+module.exports = {
+  webpack: (config) => {
+    config.experiments = {
+      ...config.experiments,
+      asyncWebAssembly: true,
+    };
+    return config;
+  },
+};
+```
+
+#### Rollup
+```bash
+npm install --save-dev @rollup/plugin-wasm
+```
+
+```javascript
+import wasm from '@rollup/plugin-wasm';
+
+export default {
+  plugins: [wasm({ targetEnv: 'auto' })],
+};
+```
+
+> 📖 **For detailed bundler configurations and troubleshooting**, see [BUNDLER_CONFIG.md](./BUNDLER_CONFIG.md)
+
 ## WASM Signer
 
 The SDK includes a pre-built WASM signer that works in both **Node.js** and **browser** environments. **No Rust installation is required to use the SDK.**

package/dist/cjs/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AACnD,eAAO,MAAM,WAAW,UAAU,CAAC;AACnC,eAAO,MAAM,UAAU,qCAA8C,CAAC;AAGtE,eAAO,MAAM,cAAc,YAAY,CAAC;AACxC,eAAO,MAAM,cAAc,YAAY,CAAC;AACxC,eAAO,MAAM,cAAc,YAAY,CAAC;AACxC,eAAO,MAAM,cAAc,YAAY,CAAC"}

package/dist/cjs/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEU,QAAA,+BAA+B,GAAG,GAAG,CAAC;AACtC,QAAA,WAAW,GAAG,OAAO,CAAC;AACtB,QAAA,UAAU,GAAG,8BAA8B,mBAAW,EAAE,CAAC;AAEtE,mBAAmB;AACN,QAAA,cAAc,GAAG,SAAS,CAAC;AAC3B,QAAA,cAAc,GAAG,SAAS,CAAC;AAC3B,QAAA,cAAc,GAAG,SAAS,CAAC;AAC3B,QAAA,cAAc,GAAG,SAAS,CAAC"}

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;gBACrB,OAAO,EAAE,MAAM;CAK5B;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,QAAQ;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;gBAChC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,MAAa,QAAS,SAAQ,KAAK;IACjC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;CACF;AAND,4BAMC;AAED;;GAEG;AACH,MAAa,kBAAmB,SAAQ,QAAQ;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC;AAED;;GAEG;AACH,MAAa,sBAAuB,SAAQ,QAAQ;IAClD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AALD,wDAKC;AAED;;GAEG;AACH,MAAa,gBAAiB,SAAQ,QAAQ;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AALD,4CAKC"}

package/dist/{index.d.ts → cjs/index.d.ts}

@@ -8,33 +8,33 @@
  * Extended offers perpetual contracts on both crypto and TradFi assets,
  * with USDC as collateral and leverage of up to 100x.
  */
-export { initWasm } from './perpetual/crypto/signer';
-export { EndpointConfig, StarknetDomain, TESTNET_CONFIG, MAINNET_CONFIG } from './perpetual/configuration';
-export { StarkPerpetualAccount, AccountModel, AccountLeverage, BalanceModel, createStarkPerpetualAccountWithCustomSigner } from './perpetual/accounts';
-export { CustomStarkSigner, SignatureResult, isCustomStarkSigner } from './perpetual/custom-signer';
-export { OrderSide, OrderType, OrderStatus, OrderStatusReason, TimeInForce, OrderTpslType, SelfTradeProtectionLevel, OrderPriceType, OrderTriggerPriceType, NewOrderModel, PlacedOrderModel, OpenOrderModel, CreateOrderTpslTriggerModel, } from './perpetual/orders';
-export { PerpetualTradingClient } from './perpetual/trading-client/trading-client';
-export { AccountModule } from './perpetual/trading-client/account-module';
-export { OrderManagementModule } from './perpetual/trading-client/order-management-module';
-export { MarketsInformationModule } from './perpetual/trading-client/markets-information-module';
-export { InfoModule } from './perpetual/trading-client/info-module';
-export { TestnetModule } from './perpetual/trading-client/testnet-module';
-export { UserClient } from './perpetual/user-client/user-client';
-export { OnBoardedAccount, StarkKeyPair } from './perpetual/user-client/onboarding';
-export { PerpetualStreamClient } from './perpetual/stream-client/stream-client';
-export { PerpetualStreamConnection } from './perpetual/stream-client/perpetual-stream-connection';
-export { PositionModel, PositionHistoryModel, PositionSide, PositionStatus, ExitType } from './perpetual/positions';
-export { AccountTradeModel, PublicTradeModel, TradeType } from './perpetual/trades';
-export { createOrderObject, OrderTpslTriggerParam } from './perpetual/order-object';
-export { MarketModel, MarketStatsModel, TradingConfigModel } from './perpetual/markets';
-export { Asset, AssetOperationType, AssetOperationStatus } from './perpetual/assets';
-export { TradingFeeModel, DEFAULT_FEES } from './perpetual/fees';
-export { X10Error, RateLimitException, NotAuthorizedException, SubAccountExists } from './errors';
-export { WrappedApiResponse, WrappedStreamResponse, StreamDataType } from './utils/http';
-export { X10BaseModel, SettlementSignatureModel } from './utils/model';
-export { generateNonce } from './utils/nonce';
-export { utcNow, toEpochMillis } from './utils/date';
-export * from './utils/env';
-export { sign, pedersenHash, generateKeypairFromEthSignature, getOrderMsgHash, getTransferMsgHash, getWithdrawalMsgHash, } from './perpetual/crypto/signer';
+export { initWasm } from './perpetual/crypto/signer.js';
+export { EndpointConfig, StarknetDomain, TESTNET_CONFIG, MAINNET_CONFIG } from './perpetual/configuration.js';
+export { StarkPerpetualAccount, AccountModel, AccountLeverage, BalanceModel, createStarkPerpetualAccountWithCustomSigner } from './perpetual/accounts.js';
+export { CustomStarkSigner, SignatureResult, isCustomStarkSigner } from './perpetual/custom-signer.js';
+export { OrderSide, OrderType, OrderStatus, OrderStatusReason, TimeInForce, OrderTpslType, SelfTradeProtectionLevel, OrderPriceType, OrderTriggerPriceType, NewOrderModel, PlacedOrderModel, OpenOrderModel, CreateOrderTpslTriggerModel, } from './perpetual/orders.js';
+export { PerpetualTradingClient } from './perpetual/trading-client/trading-client.js';
+export { AccountModule } from './perpetual/trading-client/account-module.js';
+export { OrderManagementModule } from './perpetual/trading-client/order-management-module.js';
+export { MarketsInformationModule } from './perpetual/trading-client/markets-information-module.js';
+export { InfoModule } from './perpetual/trading-client/info-module.js';
+export { TestnetModule } from './perpetual/trading-client/testnet-module.js';
+export { UserClient } from './perpetual/user-client/user-client.js';
+export { OnBoardedAccount, StarkKeyPair } from './perpetual/user-client/onboarding.js';
+export { PerpetualStreamClient } from './perpetual/stream-client/stream-client.js';
+export { PerpetualStreamConnection } from './perpetual/stream-client/perpetual-stream-connection.js';
+export { PositionModel, PositionHistoryModel, PositionSide, PositionStatus, ExitType } from './perpetual/positions.js';
+export { AccountTradeModel, PublicTradeModel, TradeType } from './perpetual/trades.js';
+export { createOrderObject, OrderTpslTriggerParam } from './perpetual/order-object.js';
+export { MarketModel, MarketStatsModel, TradingConfigModel } from './perpetual/markets.js';
+export { Asset, AssetOperationType, AssetOperationStatus } from './perpetual/assets.js';
+export { TradingFeeModel, DEFAULT_FEES } from './perpetual/fees.js';
+export { X10Error, RateLimitException, NotAuthorizedException, SubAccountExists } from './errors.js';
+export { WrappedApiResponse, WrappedStreamResponse, StreamDataType } from './utils/http.js';
+export { X10BaseModel, SettlementSignatureModel } from './utils/model.js';
+export { generateNonce } from './utils/nonce.js';
+export { utcNow, toEpochMillis } from './utils/date.js';
+export * from './utils/env.js';
+export { sign, pedersenHash, generateKeypairFromEthSignature, getOrderMsgHash, getTransferMsgHash, getWithdrawalMsgHash, } from './perpetual/crypto/signer.js';
 export declare const SDK_VERSION = "0.0.1";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAGxD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9G,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,2CAA2C,EAC5C,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACpB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,SAAS,EACT,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,wBAAwB,EACxB,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,8CAA8C,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,8CAA8C,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uDAAuD,CAAC;AAC9F,OAAO,EAAE,wBAAwB,EAAE,MAAM,0DAA0D,CAAC;AACpG,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,8CAA8C,CAAC;AAG7E,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAGvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AACnF,OAAO,EAAE,yBAAyB,EAAE,MAAM,0DAA0D,CAAC;AAGrG,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACvH,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGvF,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGvF,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAG3F,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGxF,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGpE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGrG,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5F,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGxD,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,+BAA+B,EAC/B,eAAe,EACf,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,8BAA8B,CAAC;AAGtC,eAAO,MAAM,WAAW,UAAU,CAAC"}