@gala-chain/launchpad-sdk 3.31.2 → 4.0.0

package/dist/utils/token-parser.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Safe Token Parser - Comprehensive token format validation and parsing
+ *
+ * Handles STRICT parsing of token formats received from APIs:
+ * - Pipe-delimited: "GALA|Unit|none|none"
+ * - Dollar-delimited: "GALA$Unit$none$none"
+ * - Dollar with $ in collection: "$MUSIC$Unit$none$none" (parses from END)
+ *
+ * CRITICAL SECURITY NOTE:
+ * Plain strings like "GALA" are REJECTED by default - they are not valid token formats!
+ * Token formats MUST be explicitly delimited with | or $.
+ * This prevents dangerous assumptions about token structure.
+ *
+ * @packageDocumentation
+ */
+import type { TokenClassKey } from '../types/common';
+/**
+ * PERFORMANCE CHARACTERISTICS:
+ *
+ * Fast-path (O(n) where n = token length):
+ * - Pipe-delimited tokens: Direct split() call, minimal string operations
+ * - Dollar-delimited tokens: Reverse algorithm, ~2x string operations
+ *
+ * Slow-path (format detection):
+ * - Plain strings without delimiters: Requires fallback logic
+ * - Type validation: Object instanceof checks for already-parsed tokens
+ *
+ * Recommendation: Pre-detect format when parsing large token batches:
+ * ```typescript
+ * import { isPipeDelimited, isDollarDelimited } from './token-parser';
+ *
+ * if (isPipeDelimited(token)) {
+ *   return parsePipeDelimitedToken(token);  // Fastest path
+ * } else if (isDollarDelimited(token)) {
+ *   return parseDollarDelimitedTokenSafe(token);  // Fast path
+ * }
+ * ```
+ */
+/**
+ * Parse token from ANY format (pipe/dollar delimited) into TokenClassKey
+ *
+ * Accepts:
+ * - Pipe format: "GALA|Unit|none|none"
+ * - Dollar format: "GALA$Unit$none$none"
+ * - Dollar with $ in collection: "$MUSIC$Unit$none$none"
+ * - TokenClassKey objects: { collection, category, type, additionalKey }
+ *
+ * REJECTS:
+ * - Plain strings like "GALA" (DANGEROUS - no delimiters!)
+ * - Null/undefined values
+ * - Invalid formats
+ *
+ * ⚠️ SECURITY ENFORCEMENT (v3.33.0+):
+ * Plain token strings are NO LONGER accepted. All tokens must use explicit delimiters.
+ * This is a breaking change to enforce secure token format validation.
+ *
+ * @param token Token string to parse
+ * @returns TokenClassKey with { collection, category, type, additionalKey }
+ * @throws ValidationError if format is invalid or if plain string is provided
+ *
+ * @example
+ * ```typescript
+ * // Pipe-delimited (RECOMMENDED)
+ * parseToken("GALA|Unit|none|none")
+ * // → { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" }
+ *
+ * // Dollar-delimited
+ * parseToken("GALA$Unit$none$none")
+ * // → { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" }
+ *
+ * // Dollar with $ in collection (EDGE CASE)
+ * parseToken("$MUSIC$Unit$none$none")
+ * // → { collection: "$MUSIC", category: "Unit", type: "none", additionalKey: "none" }
+ *
+ * // TokenClassKey object
+ * parseToken({ collection: "GALA", category: "Unit", type: "none", additionalKey: "none" })
+ * // → { collection: "GALA", category: "Unit", type: "none", additionalKey: "none" }
+ *
+ * // Plain string - PERMANENTLY REJECTED
+ * parseToken("GALA")  // Throws ValidationError
+ * ```
+ *
+ * @since 3.32.0
+ * @updated 3.33.0 - Removed allowPlainStrings parameter, enforce strict delimiter-only parsing
+ */
+export declare function parseToken(token: string | TokenClassKey | undefined | null): TokenClassKey;
+/**
+ * Parse pipe-delimited token: "GALA|Unit|none|none"
+ *
+ * @internal Used by parseToken()
+ * @throws ValidationError if format is invalid
+ */
+export declare function parsePipeDelimitedToken(token: string): TokenClassKey;
+/**
+ * REVERSE-PARSING ALGORITHM FOR DOLLAR-DELIMITED TOKENS
+ *
+ * Problem: Tokens like "$MUSIC$Unit$none$none" contain $ in the collection name
+ * Standard left-to-right parsing fails because it can't distinguish where collection ends
+ *
+ * Solution: Parse from RIGHT-TO-LEFT
+ *
+ * ```
+ * Input token: "$MUSIC$Unit$none$none"
+ *              [   1  ][2  ][3  ][4  ]   ← parts array (5 elements)
+ *
+ * Step 1: Split by '$'
+ *   parts = ['', 'MUSIC', 'Unit', 'none', 'none']
+ *
+ * Step 2: Take last 3 parts (from right)
+ *   category = parts[2] = 'Unit'
+ *   type     = parts[3] = 'none'
+ *   additionalKey = parts[4] = 'none'
+ *
+ * Step 3: Everything BEFORE those 3 parts = collection (rejoin with '$')
+ *   collectionParts = parts[0:2] = ['', 'MUSIC']
+ *   collection = '$MUSIC' (rejoin with '$')
+ *
+ * Result: { collection: "$MUSIC", category: "Unit", type: "none", additionalKey: "none" } ✓
+ * ```
+ *
+ * Why this works:
+ * - Handles ANY number of $ characters in collection
+ * - Guarantees exactly 4 components (collection, category, type, additionalKey)
+ * - Clear error messages when format is invalid
+ *
+ * Edge cases handled:
+ * - "$MUSIC$Unit$none$none" → collection: "$MUSIC" ✓
+ * - "COLLECTION$WITH$DOLLARS$Unit$symbol$additionalKey" → works ✓
+ * - "NotEnoughParts$Unit$none" → throws ValidationError ✓
+ *
+ * Performance: O(n) where n = token length (single split + slice + rejoin operations)
+ */
+/**
+ * Parse dollar-delimited token: "GALA$Unit$none$none"
+ *
+ * ⚠️ CRITICAL: Handles edge case where $ is part of collection name
+ * Example: "$MUSIC$Unit$none$none" → { collection: "$MUSIC", ... }
+ *
+ * Solution: Parse from END backwards
+ * - Last 3 parts (from right): category, type, additionalKey
+ * - Everything else: collection
+ *
+ * @internal Used by parseToken()
+ * @throws ValidationError if format is invalid
+ */
+export declare function parseDollarDelimitedTokenSafe(token: string): TokenClassKey;
+/**
+ * Check if token string is in pipe-delimited format
+ *
+ * @example
+ * ```typescript
+ * isPipeDelimited("GALA|Unit|none|none") // → true
+ * isPipeDelimited("GALA") // → false
+ * ```
+ */
+export declare function isPipeDelimited(token: string): boolean;
+/**
+ * Check if token string is in dollar-delimited format
+ *
+ * @example
+ * ```typescript
+ * isDollarDelimited("GALA$Unit$none$none") // → true
+ * isDollarDelimited("$MUSIC$Unit$none$none") // → true
+ * isDollarDelimited("GALA") // → false
+ * ```
+ */
+export declare function isDollarDelimited(token: string): boolean;
+/**
+ * Check if token is in ANY valid delimited format (pipe or dollar)
+ *
+ * @example
+ * ```typescript
+ * isDelimited("GALA|Unit|none|none") // → true
+ * isDelimited("GALA$Unit$none$none") // → true
+ * isDelimited("GALA") // → false
+ * ```
+ */
+export declare function isDelimited(token: string): boolean;
+/**
+ * Check if a value is a valid token format (string OR TokenClassKey object)
+ *
+ * @param token Token to validate
+ * @returns true if token is valid format (pipe/dollar delimited OR TokenClassKey object)
+ *
+ * @example
+ * ```typescript
+ * isValidTokenFormat("GALA|Unit|none|none")  // → true
+ * isValidTokenFormat("GALA$Unit$none$none")  // → true
+ * isValidTokenFormat({ collection: "GALA", ... })  // → true
+ * isValidTokenFormat("GALA")  // → false (plain string, not delimited)
+ * ```
+ */
+export declare function isValidTokenFormat(token: unknown): boolean;
+/**
+ * Check if token is a plain symbol string (NOT a delimited format)
+ *
+ * Plain token symbols are simple strings like "GALA", "USDC", etc.
+ * These are REJECTED by default by parseToken() for security reasons.
+ * Use parseToken(symbol, true) to parse plain symbols.
+ *
+ * @param token Token to check
+ * @returns true if token is plain symbol (no delimiters)
+ *
+ * @example
+ * ```typescript
+ * isPlainTokenSymbol("GALA")  // → true
+ * isPlainTokenSymbol("GALA|Unit|none|none")  // → false
+ * isPlainTokenSymbol("GALA$Unit$none$none")  // → false
+ * ```
+ *
+ * @security WARNING: Plain tokens are inherently ambiguous!
+ * Always use delimited formats when possible.
+ */
+export declare function isPlainTokenSymbol(token: unknown): boolean;
+/**
+ * Type guard: Check if value is a TokenClassKey object
+ *
+ * @param token Value to check
+ * @returns true if token is a valid TokenClassKey object with all required properties
+ *
+ * @example
+ * ```typescript
+ * const value: string | TokenClassKey = getToken();
+ *
+ * if (isTokenClassKey(value)) {
+ *   // TypeScript now knows value is TokenClassKey
+ *   console.log(value.collection, value.category, value.type, value.additionalKey);
+ * } else {
+ *   // value is string
+ *   console.log(parseToken(value));
+ * }
+ * ```
+ */
+export declare function isTokenClassKey(token: unknown): token is TokenClassKey;
+//# sourceMappingURL=token-parser.d.ts.map

package/dist/utils/token-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-parser.d.ts","sourceRoot":"","sources":["../../src/utils/token-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,IAAI,GAC/C,aAAa,CAyCf;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CA6CpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CA8C1E;AA2DD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAe1D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAgBtE"}

package/dist/utils/transfer-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transfer-validation.d.ts","sourceRoot":"","sources":["../../src/utils/transfer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAc3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAqB9D"}
+{"version":3,"file":"transfer-validation.d.ts","sourceRoot":"","sources":["../../src/utils/transfer-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;GAKG;AACH,qBAAa,wBAAwB;IACnC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAc3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;CAqB9D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gala-chain/launchpad-sdk",
-  "version": "3.31.2",
+  "version": "4.0.0",
   "description": "TypeScript SDK for Gala Launchpad Backend API - 72 methods supporting optional wallet (read-only and full-access modes). Production-ready DeFi token launchpad integration with AgentConfig setup, GalaChain trading, GSwap DEX integration, price history, token creation, DEX pool discovery, WebSocket event watchers, and comprehensive user operations. Multi-format output (ESM, CJS, UMD).",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
@@ -38,19 +38,39 @@
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "test:ci": "jest --coverage --ci --watchAll=false",
-    "demo": "tsx examples/complete-sdk-demo.ts",
-    "demo:read-only": "tsx examples/read-only-operations.ts",
-    "demo:authenticated": "tsx examples/authenticated-operations.ts",
-    "demo:privatekey-override": "tsx examples/privatekey-override-pattern.ts",
-    "demo:trades": "tsx examples/demo-trades.ts",
-    "demo:liquidity": "tsx examples/demo-liquidity-positions.ts",
-    "demo:liquidity:detailed": "tsx examples/demo-liquidity-detailed.ts",
-    "demo:cache": "tsx examples/demo-cache.ts",
-    "demo:fetch-all-pools": "tsx examples/demo-fetch-all-pools.ts",
-    "demo:dex-trades": "tsx examples/demo-dex-trades.ts",
-    "demo:dex-pool-discovery": "tsx examples/demo-dex-pool-discovery.ts",
-    "demo:watch-pools": "tsx examples/demo-watch-pools.ts",
-    "demo:watch-tokens": "tsx examples/demo-watch-tokens.ts",
+    "test:integration": "jest --config jest.integration.config.js --forceExit",
+    "demo": "tsx examples/core/complete-sdk-demo.ts",
+    "demo:read-only": "tsx examples/core/read-only-operations.ts",
+    "demo:authenticated": "tsx examples/core/authenticated-operations.ts",
+    "demo:privatekey-override": "tsx examples/core/privatekey-override-pattern.ts",
+    "demo:trades": "tsx examples/bonding-curve/basic-trading.ts",
+    "demo:liquidity": "tsx examples/liquidity/positions-cli.ts",
+    "demo:liquidity:all": "tsx examples/liquidity/orchestrator.ts",
+    "demo:liquidity:detailed": "tsx examples/liquidity/detailed.ts",
+    "demo:liquidity:ticks": "tsx examples/liquidity/ticks.ts",
+    "demo:liquidity:portfolio": "tsx examples/liquidity/multi-position.ts",
+    "demo:liquidity:apr": "tsx examples/liquidity/apr-calculator.ts",
+    "demo:liquidity:errors": "tsx examples/liquidity/errors.ts",
+    "demo:liquidity:fetch-all": "tsx examples/liquidity/demo-fetch-all-positions.ts",
+    "demo:liquidity:positions-with-prices": "tsx examples/liquidity/demo-positions-with-chunked-pricing.ts",
+    "demo:cache": "tsx examples/utilities/demo-cache.ts",
+    "demo:dex": "tsx examples/dex/swap-workflow.ts",
+    "demo:dex:pools": "tsx examples/dex/pool-discovery.ts",
+    "demo:dex:pricing": "tsx examples/dex/pools-with-pricing.ts",
+    "demo:dex:quotes": "tsx examples/dex/quote-comparison.ts",
+    "demo:dex:roundtrip": "tsx examples/dex/demo-roundtrip-liquidity.ts",
+    "demo:watch": "tsx examples/monitoring/demo-watch-pools.ts",
+    "demo:watch:tokens": "tsx examples/monitoring/demo-watch-tokens.ts",
+    "demo:fees": "tsx examples/fees/demo-fee-generation-and-collection.ts",
+    "demo:fees:high-volume": "tsx examples/fees/demo-fees-high-volume.ts",
+    "demo:fees:test": "tsx examples/fees/complete-fee-test.ts",
+    "demo:fees:trade-collect": "tsx examples/fees/trade-and-collect-fees.ts",
+    "demo:liquidity:bundler-test": "tsx examples/liquidity/test-bundler-operations.ts",
+    "demo:liquidity:roundtrip-remove": "tsx examples/liquidity/demo-roundtrip-remove.ts",
+    "demo:liquidity:direct": "tsx examples/liquidity/demo-position-direct.ts",
+    "demo:token-supply": "tsx examples/utilities/demo-token-supply.ts",
+    "debug:websocket:stage": "ENVIRONMENT=stage tsx examples/debug/websocket-monitor.ts",
+    "debug:websocket:prod": "ENVIRONMENT=prod tsx examples/debug/websocket-monitor.ts",
     "lint": "eslint src tests scripts --ext .ts,.tsx --fix",
     "lint:check": "eslint src tests scripts --ext .ts,.tsx",
     "typecheck": "tsc --noEmit",
@@ -139,6 +159,7 @@
   "peerDependencies": {
     "@gala-chain/api": "^2.4.3",
     "@gala-chain/connect": "^2.4.3",
+    "@gala-chain/dex": "^1.0.26",
     "axios": "^1.12.2",
     "bignumber.js": "^9.1.2",
     "ethers": "^6.15.0",
@@ -154,7 +175,7 @@
   "dependencies": {
     "@gala-chain/api": "^2.4.3",
     "@gala-chain/connect": "^2.4.3",
-    "@gala-chain/gswap-sdk": "^0.0.9",
+    "@gala-chain/dex": "^1.0.26",
     "@types/uuid": "^10.0.0",
     "axios": "^1.12.2",
     "bignumber.js": "^9.1.2",