@suigar/sdk 2.0.0-beta.10 → 2.0.0-beta.12

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @suigar/sdk
 
+## 2.0.0-beta.12
+
+### Patch Changes
+
+- 85ae057: Refine public validation failures to use `RangeError` and `TypeError` instead
+  of generic `Error` for unsupported networks, unsupported game or PvP action
+  inputs, unsupported configured coin types, bounded integer helpers, and
+  `parseCoinType()` parsing failures.
+
+## 2.0.0-beta.11
+
+### Patch Changes
+
+- c7685d2: Add `client.suigar.getGameParameters(game, options?)` for reading live onchain game parameter objects, such as min/max stake and game-specific config bounds, directly from SweetHouse settings.
+
+  The lookup first reads the selected game's settings object from SweetHouse, then reads that game's coin-specific `Parameters<T>` object, parses it with the correct return type for the requested game, and caches the result for SDK integrations that need to display or validate current game limits without repeatedly querying the same onchain objects.
+
+  This update also broadens the public numeric helpers in `@suigar/sdk/utils`: `toBigInt()` accepts booleans and non-negative integer strings in addition to numbers and `bigint`, `toU8()` accepts plain integer strings such as `'1'` for parsed config ids and other `u8` values, and `toU16()` provides the same validation pattern for `u16` values.
+
 ## 2.0.0-beta.10
 
 ### Patch Changes

package/README.md

@@ -48,9 +48,33 @@ import {
 	RANGE_POINT_LIMIT,
 	toBigInt,
 	toU8,
+	toU16,
 } from '@suigar/sdk/utils';
 ```
 
+Numeric helper behavior:
+
+- `toBigInt(value)` accepts `bigint`, finite `number`, non-negative integer
+  `string`, and `boolean` inputs and returns a normalized non-negative `bigint`
+  while throwing `TypeError` for invalid input shapes and `RangeError` for
+  negative values
+- `toU8(value)` accepts a finite integer `number` or plain integer `string` in
+  the inclusive `0..255` range, throwing `TypeError` for non-numeric input and
+  `RangeError` for booleans, fractional values, or out-of-range integers
+- `toU16(value)` accepts a finite integer `number` or plain integer `string`
+  in the inclusive `0..65535` range, throwing `TypeError` for non-numeric
+  input and `RangeError` for booleans, fractional values, or out-of-range
+  integers
+- `fromMoveI64(value)` converts a generated Move `i64` wrapper into a
+  JavaScript `number`
+- `fromMoveFloat(value)` converts a generated Move float struct into a
+  JavaScript `number`
+- `parseCoinType(type)` extracts the normalized first generic coin type from a
+  Move object type string and throws `TypeError` when no coin type can be parsed
+- `parseGameDetails(gameDetails)` decodes standard `BetResultEvent.game_details`
+  byte arrays into the expected string, number, and boolean values while
+  preserving the original onchain keys
+
 Game-specific type exports are available from the dedicated `games` subpath:
 
 ```ts
@@ -105,6 +129,9 @@ const base64 = await client.suigar.serializeTransactionToBase64(tx);
 
 Creates a named Sui client extension. By default, it registers under `client.suigar`.
 
+The extension constructor throws `RangeError` when the connected client network
+is not one of the SDK's supported Sui networks.
+
 ### Partner Setup
 
 > **Important:** `partner` is the partner wallet address. Configure it once
@@ -147,17 +174,22 @@ Supported override areas:
 
 - `name`
 - `partner`
+- `cacheTtl`
 
 If `partner` is configured, the SDK automatically writes that partner wallet
 address into the onchain metadata vec-map. Transaction builder options may also
 include `metadata`, but reserved keys such as `partner` and `referrer` are
 ignored with a warning when provided manually.
 
+`cacheTtl` controls the SDK cache for onchain reads such as parsed game
+parameters. It is expressed in milliseconds and defaults to 30 minutes.
+
 ## Runtime Surface
 
 The registered extension instance exposes the main runtime surface:
 
 - `getConfig()`
+- `getGameParameters(game, options?)`
 - `serializeTransactionToBase64(transaction, options?)`
 - `getPvPCoinflipGames(options?)`
 - `bcs`
@@ -182,6 +214,32 @@ const config = client.suigar.getConfig();
 console.log(config.packageIds);
 ```
 
+### `getGameParameters(game, options?)`
+
+Returns the onchain `Parameters<T>` object for any supported game and coin type.
+The return type is inferred from `game`.
+
+The SDK first reads the selected game's settings object from the configured
+SweetHouse object, then reads that game's coin-specific `Parameters<T>` object.
+This is useful for displaying or validating current limits such as min/max
+stake, house edge, or game-specific config bounds. The parsed result is cached
+using the extension `cacheTtl`.
+
+When a parameter field is a generated Move float struct, such as
+`min_target_multiplier`, `max_target_multiplier`, `min_rtp`, or `max_rtp`, use
+`fromMoveFloat()` before treating it as a normal JavaScript number.
+
+```ts
+const parameters = await client.suigar.getGameParameters('coinflip', {
+	coinType: '0x2::sui::SUI',
+});
+
+console.log(parameters.min_stake);
+```
+
+Pass `ignoreCache: true` to refresh the onchain read and replace the cached
+value.
+
 ### `serializeTransactionToBase64(transaction, options?)`
 
 Builds a transaction with the configured Sui client and returns base64-encoded transaction bytes.
@@ -273,6 +331,12 @@ Shared behavior:
 - the SDK resolves the price info object from the configured supported-coin mapping
 - the reward object is transferred back to `playerAddress`
 
+Error behavior:
+
+- `RangeError` when `gameId` is unsupported
+- `RangeError` when `coinType` is not in the resolved supported-coin config for the active network
+- `RangeError` from bounded numeric helpers such as `toU8()` when `plinko` or `wheel` `configId` is out of range or not an integer
+
 Per-game options:
 
 - `coinflip`: `side: 'heads' | 'tails'`
@@ -372,6 +436,11 @@ Action-specific options:
 - `join`: `gameId`
 - `cancel`: `gameId`
 
+Error behavior:
+
+- `RangeError` when `action` is unsupported
+- `RangeError` when `coinType` is not in the resolved supported-coin config for the active network
+
 ## `bcs`
 
 BCS helpers live under `client.suigar.bcs`.
@@ -390,6 +459,7 @@ These are generated Move event decoders. Use them to parse Suigar event payloads
 - `fromMoveI64(float.exp)` converts a generated Move `i64` exponent to a JavaScript number
 - `fromMoveFloat(float)` converts a generated Move `Float` struct to a JavaScript number
 - `parseCoinType(type)` extracts the normalized coin type from generic Move object type strings such as PvP coinflip `Game<T>`
+  and throws `TypeError` when the type string does not include a first generic coin type
 - `parseGameDetails(game_details)` decodes `BetResultEvent.game_details` entries into the expected string, number, and boolean values
 
 ### Parse PvP Coinflip Game Object Data

package/dist/{chunk-PPUDLRHA.js → chunk-7N55D2TV.js}

@@ -9,36 +9,48 @@ var RANGE_POINT_LIMIT = DEFAULT_RANGE_SCALE * 100;
 var DEFAULT_LIMBO_MULTIPLIER_SCALE = 100;
 
 // src/utils/numeric.ts
-function isFiniteNumber(value, message) {
-  if (typeof value !== "number") {
-    throw new Error(`${message}: ${String(value)}`);
-  }
-  if (!Number.isFinite(value)) {
-    throw new Error(`Value must be a finite number: ${value}`);
+function assertFiniteNumber(value, errorMessage) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new TypeError(`${errorMessage}: ${String(value)}`);
   }
 }
 function toBigInt(value) {
-  if (typeof value === "bigint") {
-    if (value < 0n) {
-      throw new Error(`Value must be non-negative: ${value}`);
+  let result;
+  try {
+    if (typeof value === "bigint" || typeof value === "string" || typeof value === "boolean") {
+      result = BigInt(value);
+    } else {
+      assertFiniteNumber(
+        value,
+        "Value must be a bigint, number, integer string, or boolean"
+      );
+      result = BigInt(Math.trunc(value));
     }
-    return value;
+  } catch {
+    throw new TypeError(
+      `Value must be a bigint, number, integer string, or boolean: ${value}`
+    );
   }
-  isFiniteNumber(value, "Value must be a bigint or number");
-  if (value < 0) {
-    throw new Error(`Value must be a finite non-negative number: ${value}`);
+  if (result < 0n) {
+    throw new RangeError(`Value must be non-negative: ${value}`);
   }
-  return BigInt(Math.trunc(value));
+  return result;
 }
-function toU8(value) {
-  isFiniteNumber(value, "Value must be a number");
-  if (!Number.isInteger(value)) {
-    throw new Error(`Value must be an integer: ${value}`);
-  }
-  if (value < 0 || value > 255) {
-    throw new Error(`Value must be an integer between 0 and 255: ${value}`);
+function toBoundedInt(value, max, typeName) {
+  const num = typeof value === "string" && value.trim() === "" ? NaN : Number(value);
+  assertFiniteNumber(num, "Value must be a finite number or integer string");
+  if (typeof value === "boolean" || value == null || !Number.isInteger(num) || num < 0 || num > max) {
+    throw new RangeError(
+      `Value must be a ${typeName} integer (0-${max}): ${value}`
+    );
   }
-  return value;
+  return num;
+}
+function toU8(value) {
+  return toBoundedInt(value, 255, "u8");
+}
+function toU16(value) {
+  return toBoundedInt(value, 65535, "u16");
 }
 var MOVE_STDLIB_ADDRESS = normalizeSuiAddress("0x1");
 var SUI_FRAMEWORK_ADDRESS = normalizeSuiAddress("0x2");
@@ -292,7 +304,7 @@ function fromMoveFloat(float) {
 function parseCoinType(type) {
   const coinType = parseStructTag(type).typeParams[0];
   if (!coinType) {
-    throw new Error(`Unable to parse coin type from ${type}`);
+    throw new TypeError(`Unable to parse coin type from ${type}`);
   }
   return normalizeStructTag(coinType);
 }
@@ -328,4 +340,4 @@ function parseGameDetails(gameDetails) {
   }, {});
 }
 
-export { DEFAULT_GAS_BUDGET_MIST, DEFAULT_LIMBO_MULTIPLIER_SCALE, DEFAULT_RANGE_SCALE, Float, MoveStruct, RANGE_POINT_LIMIT, fromMoveFloat, fromMoveI64, normalizeMoveArguments, parseCoinType, parseGameDetails, toBigInt, toU8 };
+export { DEFAULT_GAS_BUDGET_MIST, DEFAULT_LIMBO_MULTIPLIER_SCALE, DEFAULT_RANGE_SCALE, Float, MoveStruct, RANGE_POINT_LIMIT, fromMoveFloat, fromMoveI64, normalizeMoveArguments, parseCoinType, parseGameDetails, toBigInt, toU16, toU8 };

package/dist/{games-BccpPyWd.d.cts → games-BHYRg31e.d.cts}

@@ -12,7 +12,19 @@ type BetMetadataInput = Record<string, BetMetadataValue | null | undefined>;
 
 interface SuigarExtensionOptions<Name = 'suigar'> {
     name?: Name;
+    /**
+     * Partner wallet address injected into bet metadata for attribution.
+     *
+     * Configure this once when registering the `suigar()` client extension
+     * instead of passing partner data through per-transaction metadata.
+     */
     partner?: string;
+    /**
+     * Cache TTL in milliseconds for SDK-managed on-chain config lookups.
+     *
+     * Defaults to 30 minutes.
+     */
+    cacheTtl?: number;
 }
 type SuigarCoin = 'sui' | 'usdc';
 type SuigarCoinTypes = Record<SuigarCoin, string>;
@@ -83,4 +95,4 @@ type BuildCancelPvPCoinflipTransactionOptions = SharedPvPCoinflipTransactionOpti
 };
 type BuildPvPCoinflipTransactionOptions<Action extends PvPCoinflipAction = PvPCoinflipAction> = Action extends 'create' ? BuildCreatePvPCoinflipTransactionOptions : Action extends 'join' ? BuildJoinPvPCoinflipTransactionOptions : Action extends 'cancel' ? BuildCancelPvPCoinflipTransactionOptions : never;
 
-export type { BuildCoinflipTransactionOptions as B, CoinSide as C, PvPCoinflipAction as P, StandardGame as S, WithThrowOnError as W, BuildWheelTransactionOptions as a, BuildLimboTransactionOptions as b, BuildPlinkoTransactionOptions as c, BuildRangeTransactionOptions as d, SuigarConfig as e, BuildPvPCoinflipTransactionOptions as f, SuigarExtensionOptions as g, BuildCancelPvPCoinflipTransactionOptions as h, BuildCreatePvPCoinflipTransactionOptions as i, BuildJoinPvPCoinflipTransactionOptions as j };
+export type { BuildCoinflipTransactionOptions as B, CoinSide as C, Game as G, PvPCoinflipAction as P, StandardGame as S, WithThrowOnError as W, BuildWheelTransactionOptions as a, BuildLimboTransactionOptions as b, BuildPlinkoTransactionOptions as c, BuildRangeTransactionOptions as d, SuigarConfig as e, BuildPvPCoinflipTransactionOptions as f, SuigarExtensionOptions as g, BuildCancelPvPCoinflipTransactionOptions as h, BuildCreatePvPCoinflipTransactionOptions as i, BuildJoinPvPCoinflipTransactionOptions as j };

package/dist/{games-BccpPyWd.d.ts → games-BHYRg31e.d.ts}

@@ -12,7 +12,19 @@ type BetMetadataInput = Record<string, BetMetadataValue | null | undefined>;
 
 interface SuigarExtensionOptions<Name = 'suigar'> {
     name?: Name;
+    /**
+     * Partner wallet address injected into bet metadata for attribution.
+     *
+     * Configure this once when registering the `suigar()` client extension
+     * instead of passing partner data through per-transaction metadata.
+     */
     partner?: string;
+    /**
+     * Cache TTL in milliseconds for SDK-managed on-chain config lookups.
+     *
+     * Defaults to 30 minutes.
+     */
+    cacheTtl?: number;
 }
 type SuigarCoin = 'sui' | 'usdc';
 type SuigarCoinTypes = Record<SuigarCoin, string>;
@@ -83,4 +95,4 @@ type BuildCancelPvPCoinflipTransactionOptions = SharedPvPCoinflipTransactionOpti
 };
 type BuildPvPCoinflipTransactionOptions<Action extends PvPCoinflipAction = PvPCoinflipAction> = Action extends 'create' ? BuildCreatePvPCoinflipTransactionOptions : Action extends 'join' ? BuildJoinPvPCoinflipTransactionOptions : Action extends 'cancel' ? BuildCancelPvPCoinflipTransactionOptions : never;
 
-export type { BuildCoinflipTransactionOptions as B, CoinSide as C, PvPCoinflipAction as P, StandardGame as S, WithThrowOnError as W, BuildWheelTransactionOptions as a, BuildLimboTransactionOptions as b, BuildPlinkoTransactionOptions as c, BuildRangeTransactionOptions as d, SuigarConfig as e, BuildPvPCoinflipTransactionOptions as f, SuigarExtensionOptions as g, BuildCancelPvPCoinflipTransactionOptions as h, BuildCreatePvPCoinflipTransactionOptions as i, BuildJoinPvPCoinflipTransactionOptions as j };
+export type { BuildCoinflipTransactionOptions as B, CoinSide as C, Game as G, PvPCoinflipAction as P, StandardGame as S, WithThrowOnError as W, BuildWheelTransactionOptions as a, BuildLimboTransactionOptions as b, BuildPlinkoTransactionOptions as c, BuildRangeTransactionOptions as d, SuigarConfig as e, BuildPvPCoinflipTransactionOptions as f, SuigarExtensionOptions as g, BuildCancelPvPCoinflipTransactionOptions as h, BuildCreatePvPCoinflipTransactionOptions as i, BuildJoinPvPCoinflipTransactionOptions as j };

package/dist/games.d.cts

@@ -1,2 +1,2 @@
-export { h as BuildCancelPvPCoinflipTransactionOptions, B as BuildCoinflipTransactionOptions, i as BuildCreatePvPCoinflipTransactionOptions, j as BuildJoinPvPCoinflipTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, a as BuildWheelTransactionOptions, C as CoinSide, P as PvPCoinflipAction } from './games-BccpPyWd.cjs';
+export { h as BuildCancelPvPCoinflipTransactionOptions, B as BuildCoinflipTransactionOptions, i as BuildCreatePvPCoinflipTransactionOptions, j as BuildJoinPvPCoinflipTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, a as BuildWheelTransactionOptions, C as CoinSide, P as PvPCoinflipAction } from './games-BHYRg31e.cjs';
 import '@mysten/sui/transactions';

package/dist/games.d.ts

@@ -1,2 +1,2 @@
-export { h as BuildCancelPvPCoinflipTransactionOptions, B as BuildCoinflipTransactionOptions, i as BuildCreatePvPCoinflipTransactionOptions, j as BuildJoinPvPCoinflipTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, a as BuildWheelTransactionOptions, C as CoinSide, P as PvPCoinflipAction } from './games-BccpPyWd.js';
+export { h as BuildCancelPvPCoinflipTransactionOptions, B as BuildCoinflipTransactionOptions, i as BuildCreatePvPCoinflipTransactionOptions, j as BuildJoinPvPCoinflipTransactionOptions, b as BuildLimboTransactionOptions, c as BuildPlinkoTransactionOptions, d as BuildRangeTransactionOptions, a as BuildWheelTransactionOptions, C as CoinSide, P as PvPCoinflipAction } from './games-BHYRg31e.js';
 import '@mysten/sui/transactions';