@holdem-api/holdem-sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Baker
+
+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

@@ -1,3 +1,152 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Holdem SDK
+
+Server-side JavaScript/TypeScript client for Node.js 20+. Zero runtime dependencies, ESM and TypeScript declarations. All requests use `POST /api/actions`.
+
+## Install
+
+In your **backend/server project** (for Blitzfold, use `blitzfold-server`):
+
+```sh
+npm install @holdem-api/holdem-sdk
+```
+
+No repository clone, local archive, or SDK build step is required. Node.js 20+ is required. The package is ESM-only. JavaScript `.mjs` files can import it directly. CommonJS applications can use native `await import('@holdem-api/holdem-sdk')` inside an async function; TypeScript compiling to CommonJS must preserve that native import rather than rewriting it to require().
+
+Verify installation without an API key or network request:
+
+```sh
+node --input-type=module -e "import { HoldemClient, RangeStore } from '@holdem-api/holdem-sdk'; console.log('SDK ready:', typeof HoldemClient, typeof RangeStore)"
+```
+
+Expected output: `SDK ready: function function`.
+
+## Configure your API access
+
+Obtain a Holdem API key and the origin of the API deployment you are authorized to use. Installing this package does not create an API account, provision a server, or include credentials. Configure these variables on your backend:
+
+```dotenv
+HOLDEM_API_KEY=your_api_key
+HOLDEM_API_URL=https://your-api-host.example
+```
+
+Replace the example host with your actual deployment origin, without `/api`. Keep `.env` out of version control. Node 20.6+ can load it using `node --env-file=.env your-script.mjs`; on earlier Node 20 versions set environment variables in your shell or use your application's environment loader. Never put the key in browser code.
+
+## First live request
+
+Save this as `holdem-smoke.mjs` in the project where you installed the SDK:
+
+```js
+import { readFile } from 'node:fs/promises'
+import { HoldemClient } from '@holdem-api/holdem-sdk'
+
+const { HOLDEM_API_KEY: apiKey, HOLDEM_API_URL: baseUrl } = process.env
+if (!apiKey || !baseUrl || !process.argv[2]) {
+  throw new Error('Set HOLDEM_API_KEY and HOLDEM_API_URL; supply a request JSON file')
+}
+const client = new HoldemClient({ apiKey, baseUrl })
+const request = JSON.parse(await readFile(process.argv[2], 'utf8'))
+const result = await client.actions(request)
+console.log({
+  chosenAction: result.chosenAction,
+  probabilities: result.output,
+  equity: result.equity,
+  expectedValues: result.expectedValues,
+  rangeCount: Object.keys(result.range).length,
+})
+```
+
+Export a real pre-decision game state using the policy encoding below into `actions-request.json`, with top-level `{ "hand": "AsAh", "policy": { "schemaVersion": "holdem-public-board-joint-v1", "context": [...], "history": [...], "legalMask": [0,1,1] } }`. The ellipses describe encoder output; replace them with actual arrays. Do not use made-up features or an empty context. Then run:
+
+```sh
+node --env-file=.env holdem-smoke.mjs actions-request.json
+```
+
+This makes one live request and may consume API quota. It does not execute an action in your game. If this fails, 401/403 indicates an access/authentication issue; 400 indicates invalid input; 502/503 can indicate unavailable equity/model services. Inspect the SDK error status and your API configuration.
+
+## Integrate decisions and track ranges
+
+```ts
+import { HoldemClient, RangeStore } from '@holdem-api/holdem-sdk'
+import type { PublicPolicy } from '@holdem-api/holdem-sdk'
+
+const holdem = new HoldemClient({
+  apiKey: process.env.HOLDEM_API_KEY!,
+  baseUrl: process.env.HOLDEM_API_URL!, // origin without /api
+})
+const ranges = new RangeStore()
+
+async function decide(handId: string, playerId: string, policy: PublicPolicy) {
+  const result = await holdem.actions({
+    policy,
+    hand: 'AsAh',
+    range: ranges.get(handId, playerId),
+    // opponentRanges: [ranges.get(handId, opponentId) ?? null],
+  })
+  // Your engine executes result.chosenAction, sampling sizes/weights on aggression.
+  // Only AFTER successful execution of that action:
+  // ranges.record(handId, playerId, result, executedAction)
+  return result
+}
+```
+
+`predictActions` is an alias with the same request and response. This replaces the original unpublished SDK's legacy state-based prediction, separate range-update, and equity methods.
+
+Supply the exact public encoder output as `policy`: schemaVersion `holdem-public-board-joint-v1`, 316 context features, chronological history of at most 512 events with 32 features each, and legalMask `[fold, passive, aggressive]`. Use the API/parser public encoder; an ordinary game snapshot is not that encoding. Context has board slots (260), actor (9), street (4), six log-scaled amounts/counts, nine public seat records (36), and remaining opponents / 9. Amount scaling is `log1p(max(0,value))/log1p(400)`.
+
+## Complete response
+
+- `equity`, `uniformEquity`, `equityBasis`, optional `opponentEquity`.
+- `output`: hand-specific action probabilities; `population`: public model targets.
+- `chosenAction`: sampled fold/call/raise or check/bet. No size is sampled.
+- `sizes` and `weights`: conditional aggression sizing distribution. Your engine applies legal payments, raises, all-ins and side pots.
+- `range`: normalized actor posterior conditioned on chosenAction.
+- `expectedValues`: simplified uniform heads-up showdown benchmark in BB. Assumes one caller, no fold equity, no future betting, no rake or side pots; not strategic or opponent-range-aware EV.
+- Optional `learnedExpectedValues`: experimental observed-action historical returns, only when configured on the API server. Not validated counterfactual action values.
+- `improvementPotential`, `improvement`, allocation identifiers, and all additional server fields are preserved.
+
+## Ranges
+
+`WeightedRange` maps exact two-card combos to nonnegative weights. Omit `range` for a uniform board-compatible actor population. Pass a prior to track a reached range; the actual hand must have positive mass. Do not initialize a range with just the known hand. Optional `opponentRanges` has one map or null (uniform) per remaining opponent; never send revealed opponents' actual cards.
+
+`RangeStore` provides `set`, `get`, `record`, and `clear(handId?)`. It copies snapshots and isolates each hand/player. It is in memory; persist snapshots using your application's database if they must survive restarts. Explicitly record a posterior only after executing chosenAction. A different action requires a different posterior that this request did not return. Serialize calls/updates per player to prevent stale writes. Clear completed hands. The API itself stores no ranges. This SDK does not infer ranges for observed opponent actions.
+
+## Errors
+
+`HoldemValidationError` rejects local invalid input before sending. `HoldemApiError` includes status and body. `HoldemResponseError` rejects malformed successful responses. `HoldemTransportError` wraps network, timeout and cancellation failures. Methods accept `{signal}` as the second argument. Default timeout is 60 seconds and covers body reading. No automatic retries. Keys use `x-api-key`; keep credentials on your backend.
+
+## SDK maintainers: build and publish
+
+```sh
+npm ci
+npm test
+npm pack
+```
+
+The package is configured for public publication as `@holdem-api/holdem-sdk` under the MIT license. For publication:
+
+1. Create or obtain access to the `holdem-api` npm organization. The package name is configured as `@holdem-api/holdem-sdk`. The public access setting and MIT license are already configured.
+2. Run `npm login` and complete npm's browser authentication/2FA.
+3. Run `npm test` and `npm pack --dry-run` to inspect contents.
+4. Run `npm publish --access public` and complete any npm verification prompt.
+5. In the consuming project, run `npm install @holdem-api/holdem-sdk`.
+
+Do not put credentials in source or the package. Before publishing another release, bump the version with `npm version patch` (requires a clean git checkout) or edit the version and update the lockfile.
+
+## Public policy encoding reference
+
+The SDK accepts encoded public features; it does not reconstruct betting state. Use consistent seat IDs 0�8 throughout a hand. Cards are indexed by `rankIndex * 4 + suitIndex`, ranks `23456789TJQKA`, suits `cdhs`. Street indexes are preflop=0, flop=1, turn=2, river=3. A one-hot block has exactly one 1; an empty board slot is all zeros. Board slots retain deal order. All amounts below are BB unless a count is specified; scale amounts/counts using `log1p(max(0,x))/log1p(400)`.
+
+| Context indexes | Encoding |
+| --- | --- |
+| 0�259 | Five ordered 52-value board one-hot slots |
+| 260�268 | Actor seat one-hot |
+| 269�272 | Street one-hot |
+| 273�278 | Scaled pot, facing amount, call payment, min raise-to, max raise-to, number of seats |
+| 279�314 | Nine seat records: present flag, scaled remaining stack, scaled current-street contribution, active flag; absent seats have four zeros |
+| 315 | Remaining active opponent count divided by 9 |
+
+Each history event has 32 values: actor seat one-hot (9), street one-hot (4), action one-hot (6, ordered posts/folds/checks/calls/bets/raises), four scaled values (payment added, raise-to or 0, live post or 0, dead post or 0), and nine scaled refund amounts indexed by seat. Sum multiple refunds to the same seat after the event before scaling. History must contain all actual preceding events in order, across streets, excluding the current decision. Send no artificial padding; empty history is supported. Maximum history length is 512. LegalMask is `[fold, passive, aggressive]` derived from actual engine legality, with only 0/1 values and at least one allowed action. Do not include opponents' private cards or future events. Encode call payment, contributions, and raise limits from actual engine state; do not infer them from incomplete logs.
+
+## Blitzfold migration checklist
+
+Install in the server. Replace the `/api/equity_actions` request with `client.actions(payload)` using the existing public encoder. Preserve the full response, including `range`; remove any code deleting it. Use `chosenAction` directly instead of sampling the action category a second time. Sample only the conditional size after aggression and enforce engine legality. Commit the actor range only after that same category executes successfully; reject stale hand/turn responses and clear completed hands. Select optional player styles locally and send them with the request, so decisions need only `/api/actions`. Keep error/cooldown handling and the game's timeout budget. Verify both the development runner and the compiled server can load this ESM package.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export * from './types.js';
+export { HoldemValidationError } from './validation.js';
+import type { CallOptions, ClientOptions, ActionsInput, ActionsResult } from './types.js';
+export { RangeStore } from './ranges.js';
+export declare class HoldemApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare class HoldemTransportError extends Error {
+    constructor(message: string, cause: unknown);
+}
+export declare class HoldemResponseError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+/** Server-side client. Credentials are sent only in the x-api-key header. No automatic retries. */
+export declare class HoldemClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly transport;
+    constructor(config: ClientOptions);
+    /** Returns the complete action response without dropping analysis or optional fields. */
+    actions(input: ActionsInput, call?: CallOptions): Promise<ActionsResult>;
+    /** Alias for actions; uses the same /api/actions contract. */
+    predictActions(input: ActionsInput, call?: CallOptions): Promise<ActionsResult>;
+    private post;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEzF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,qBAAa,cAAe,SAAQ,KAAK;aACM,MAAM,EAAE,MAAM;aAAkB,IAAI,EAAE,OAAO;gBAA9E,OAAO,EAAE,MAAM,EAAkB,MAAM,EAAE,MAAM,EAAkB,IAAI,EAAE,OAAO;CAG3F;AACD,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAC5C;AACD,qBAAa,mBAAoB,SAAQ,KAAK;aAChB,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAC3C;AAkBD,mGAAmG;AACnG,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBACvC,MAAM,EAAE,aAAa;IAWjC,yFAAyF;IACnF,OAAO,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAI9E,8DAA8D;IACxD,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;YAGvE,IAAI;CA2BnB"}

package/dist/index.js

@@ -0,0 +1,123 @@
+export * from './types.js';
+export { HoldemValidationError } from './validation.js';
+import { check, validateActions, range } from './validation.js';
+export { RangeStore } from './ranges.js';
+export class HoldemApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'HoldemApiError';
+    }
+}
+export class HoldemTransportError extends Error {
+    constructor(message, cause) { super(message, { cause }); this.name = 'HoldemTransportError'; }
+}
+export class HoldemResponseError extends Error {
+    status;
+    constructor(status) {
+        super('Holdem API returned an invalid response');
+        this.status = status;
+        this.name = 'HoldemResponseError';
+    }
+}
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const probability = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;
+function validActions(v) {
+    if (!object(v) || v.ok !== true || typeof v.facingBet !== 'boolean' || !object(v.output))
+        return false;
+    const keys = v.facingBet ? ['fold', 'call', 'raise'] : ['check', 'bet'];
+    const output = v.output;
+    if (!keys.every(k => probability(output[k])) || Math.abs(keys.reduce((s, k) => s + Number(output[k]), 0) - 1) > 1e-6)
+        return false;
+    if (!keys.includes(String(v.chosenAction)) || !(Number(output[String(v.chosenAction)]) > 0))
+        return false;
+    try {
+        range(v.range, []);
+    }
+    catch {
+        return false;
+    }
+    return object(v.range) && Math.abs(Object.values(v.range).reduce((s, n) => s + Number(n), 0) - 1) < 1e-6 &&
+        typeof v.requestId === 'string' && typeof v.hand === 'string' && probability(v.equity) && probability(v.uniformEquity) &&
+        typeof v.equityBasis === 'string' && object(v.expectedValues) && object(v.expectedValues.output) &&
+        object(v.population) && ['fold', 'passive', 'aggressive'].every(k => probability(v.population[k])) &&
+        Array.isArray(v.sizes) && v.sizes.every(x => typeof x === 'string') &&
+        Array.isArray(v.weights) && v.weights.length === v.sizes.length && v.weights.every(probability);
+}
+/** Server-side client. Credentials are sent only in the x-api-key header. No automatic retries. */
+export class HoldemClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    transport;
+    constructor(config) {
+        check(typeof config.apiKey === 'string' && config.apiKey.trim().length > 0, 'apiKey is required');
+        let url;
+        try {
+            url = new URL(config.baseUrl);
+        }
+        catch {
+            throw new Error('baseUrl must be an absolute HTTP(S) URL');
+        }
+        check(['http:', 'https:'].includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash, 'Invalid baseUrl');
+        this.baseUrl = url.href.replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+        this.timeoutMs = config.timeoutMs ?? 60_000;
+        check(Number.isInteger(this.timeoutMs) && this.timeoutMs > 0 && this.timeoutMs <= 2147483647, 'Invalid timeoutMs');
+        this.transport = config.fetch ?? globalThis.fetch;
+        check(typeof this.transport === 'function', 'fetch is required');
+    }
+    /** Returns the complete action response without dropping analysis or optional fields. */
+    async actions(input, call) {
+        validateActions(input);
+        return this.post('/api/actions', input, validActions, call);
+    }
+    /** Alias for actions; uses the same /api/actions contract. */
+    async predictActions(input, call) {
+        return this.actions(input, call);
+    }
+    async post(path, payload, valid, call) {
+        const controller = new AbortController();
+        const abort = () => controller.abort(call?.signal?.reason);
+        if (call?.signal?.aborted)
+            abort();
+        else
+            call?.signal?.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(() => controller.abort(new Error('Holdem request timed out')), this.timeoutMs);
+        try {
+            let response;
+            let body;
+            try {
+                response = await this.transport(`${this.baseUrl}${path}`, {
+                    method: 'POST', redirect: 'error', signal: controller.signal,
+                    headers: { 'Content-Type': 'application/json', 'x-api-key': this.apiKey },
+                    body: JSON.stringify(payload),
+                });
+                const raw = await response.text();
+                try {
+                    body = JSON.parse(raw);
+                }
+                catch {
+                    body = null;
+                }
+            }
+            catch (cause) {
+                throw new HoldemTransportError('Holdem request failed, timed out, or was cancelled', cause);
+            }
+            if (!response.ok || (object(body) && body.ok === false)) {
+                throw new HoldemApiError(`Holdem API request failed (${response.status})`, response.status, body);
+            }
+            if (!valid(body))
+                throw new HoldemResponseError(response.status);
+            return body;
+        }
+        finally {
+            clearTimeout(timer);
+            call?.signal?.removeEventListener('abort', abort);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/ranges.d.ts

@@ -0,0 +1,11 @@
+import type { ActionType, ActionsResult, WeightedRange } from './types.js';
+/** In-memory ranges keyed by hand and player. Persist get() snapshots in your application if needed. */
+export declare class RangeStore {
+    private readonly hands;
+    get(handId: string, playerId: string): WeightedRange | undefined;
+    set(handId: string, playerId: string, value: WeightedRange): void;
+    /** Call after the engine executes the returned action. Serialize updates per player. */
+    record(handId: string, playerId: string, result: ActionsResult, executedAction: ActionType): void;
+    clear(handId?: string): void;
+}
+//# sourceMappingURL=ranges.d.ts.map

package/dist/ranges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranges.d.ts","sourceRoot":"","sources":["../src/ranges.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG1E,wGAAwG;AACxG,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgD;IACtE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAC,SAAS;IAI9D,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI;IAOjE,wFAAwF;IACxF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,GAAG,IAAI;IAIjG,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;CAI7B"}

package/dist/ranges.js

@@ -0,0 +1,31 @@
+import { check, range } from './validation.js';
+/** In-memory ranges keyed by hand and player. Persist get() snapshots in your application if needed. */
+export class RangeStore {
+    hands = new Map();
+    get(handId, playerId) {
+        const value = this.hands.get(handId)?.get(playerId);
+        return value === undefined ? undefined : { ...value };
+    }
+    set(handId, playerId, value) {
+        check(handId.length > 0 && playerId.length > 0, 'handId and playerId are required');
+        range(value, []);
+        let players = this.hands.get(handId);
+        if (!players) {
+            players = new Map();
+            this.hands.set(handId, players);
+        }
+        players.set(playerId, { ...value });
+    }
+    /** Call after the engine executes the returned action. Serialize updates per player. */
+    record(handId, playerId, result, executedAction) {
+        check(executedAction === result.chosenAction, 'Range is conditioned on chosenAction; executed action differs');
+        this.set(handId, playerId, result.range);
+    }
+    clear(handId) {
+        if (handId === undefined)
+            this.hands.clear();
+        else
+            this.hands.delete(handId);
+    }
+}
+//# sourceMappingURL=ranges.js.map

package/dist/ranges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranges.js","sourceRoot":"","sources":["../src/ranges.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAE9C,wGAAwG;AACxG,MAAM,OAAO,UAAU;IACJ,KAAK,GAAG,IAAI,GAAG,EAAsC,CAAA;IACtE,GAAG,CAAC,MAAc,EAAE,QAAgB;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAA;QACnD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAA;IACvD,CAAC;IACD,GAAG,CAAC,MAAc,EAAE,QAAgB,EAAE,KAAoB;QACxD,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,kCAAkC,CAAC,CAAA;QACnF,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;QAChB,IAAI,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QACpC,IAAI,CAAC,OAAO,EAAE,CAAC;YAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;YAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAAC,CAAC;QACtE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,KAAK,EAAE,CAAC,CAAA;IACrC,CAAC;IACD,wFAAwF;IACxF,MAAM,CAAC,MAAc,EAAE,QAAgB,EAAE,MAAqB,EAAE,cAA0B;QACxF,KAAK,CAAC,cAAc,KAAK,MAAM,CAAC,YAAY,EAAE,+DAA+D,CAAC,CAAA;QAC9G,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;IAC1C,CAAC;IACD,KAAK,CAAC,MAAe;QACnB,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAA;;YACvC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAChC,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+export type Rank = '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'T' | 'J' | 'Q' | 'K' | 'A';
+export type Card = `${Rank}${'c' | 'd' | 'h' | 's'}`;
+export type WeightedRange = Readonly<Record<string, number>>;
+export type ActionType = 'fold' | 'check' | 'call' | 'bet' | 'raise';
+export type PlayerStyle = 'tight-passive' | 'tight-aggressive' | 'loose-passive' | 'loose-aggressive';
+/** Exact public encoder output. No private-card features. */
+export interface PublicPolicy {
+    schemaVersion: 'holdem-public-board-joint-v1';
+    context: readonly number[];
+    history: readonly (readonly number[])[];
+    legalMask: readonly [0 | 1, 0 | 1, 0 | 1];
+}
+export interface ActionsInput {
+    policy: PublicPolicy;
+    hand: string;
+    range?: WeightedRange;
+    opponentRanges?: readonly (WeightedRange | null)[];
+    gateSlope?: number;
+    style?: PlayerStyle;
+    policyVersion?: string;
+}
+export interface CallOptions {
+    signal?: AbortSignal;
+}
+export interface ClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+export type ActionOutput<T> = {
+    fold: T;
+    call: T;
+    raise: T;
+} | {
+    check: T;
+    bet: T;
+};
+export interface ExpectedValues {
+    units: 'BB';
+    model: string;
+    output: ActionOutput<number | null>;
+    sizing: {
+        size: string;
+        paymentBB: number | null;
+        evBB: number | null;
+    }[];
+    assumptions?: string[];
+    [key: string]: unknown;
+}
+export interface ActionsResult {
+    ok: true;
+    requestId: string;
+    hand: string;
+    equity: number;
+    uniformEquity: number;
+    equityBasis: 'uniform-heads-up' | 'opponent-ranges-pot-share';
+    facingBet: boolean;
+    output: ActionOutput<number>;
+    chosenAction: ActionType;
+    /** Posterior conditioned on chosenAction; save only after executing that action. */
+    range: Record<string, number>;
+    population: {
+        fold: number;
+        passive: number;
+        aggressive: number;
+    };
+    sizes: string[];
+    weights: number[];
+    expectedValues: ExpectedValues;
+    learnedExpectedValues?: ExpectedValues;
+    opponentEquity?: {
+        equity: number;
+        [key: string]: unknown;
+    };
+    improvementPotential: number;
+    improvement: {
+        method: string;
+        equityGainThreshold: number;
+        samplesPerNextCard: number | null;
+        applicable: boolean;
+        samplesPerCandidate?: number;
+    };
+    gateSlope: number;
+    allocationVersion: string;
+    allocationCalibration: string;
+    allocationPopulation: string;
+    policyVersion?: string;
+    style?: PlayerStyle;
+    [key: string]: unknown;
+}
+export type PredictActionsInput = ActionsInput;
+export type PredictActionsResult = ActionsResult;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validation.d.ts

@@ -0,0 +1,10 @@
+import type { ActionsInput, WeightedRange } from './types.js';
+export declare class HoldemValidationError extends Error {
+    constructor(message: string);
+}
+export declare function check(condition: unknown, message: string): asserts condition;
+export declare function amount(value: number, label: string): void;
+export declare function cards(values: readonly string[]): void;
+export declare function range(value: WeightedRange | undefined, board: readonly string[]): void;
+export declare function validateActions(input: ActionsInput): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC7D,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAC5B;AACD,wBAAgB,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAE5E;AACD,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAEzD;AACD,wBAAgB,KAAK,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAGrD;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,aAAa,GAAC,SAAS,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAcpF;AACD,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CA0BzD"}

package/dist/validation.js

@@ -0,0 +1,69 @@
+export class HoldemValidationError extends Error {
+    constructor(message) { super(message); this.name = 'HoldemValidationError'; }
+}
+export function check(condition, message) {
+    if (!condition)
+        throw new HoldemValidationError(message);
+}
+export function amount(value, label) {
+    check(Number.isFinite(value) && value >= 0, `${label} must be finite and nonnegative`);
+}
+export function cards(values) {
+    check(Array.isArray(values) && values.every(c => typeof c === 'string' && /^[2-9TJQKA][cdhs]$/.test(c)), 'Invalid card notation');
+    check(new Set(values).size === values.length, 'Duplicate physical card');
+}
+export function range(value, board) {
+    if (value === undefined)
+        return;
+    check(value !== null && typeof value === 'object' && !Array.isArray(value), 'Range must be a combo-weight map');
+    let mass = 0;
+    const seen = new Set();
+    for (const [combo, weight] of Object.entries(value)) {
+        check(/^[2-9TJQKA][cdhs][2-9TJQKA][cdhs]$/.test(combo), `Invalid combo: ${combo}`);
+        const pair = [combo.slice(0, 2), combo.slice(2)];
+        cards(pair);
+        amount(weight, 'Range weight');
+        const key = pair.slice().sort().join('');
+        check(!seen.has(key), `Duplicate reversed combo: ${combo}`);
+        seen.add(key);
+        if (!pair.some(c => board.includes(c)))
+            mass += weight;
+    }
+    check(Number.isFinite(mass) && mass > 0, 'Range must have positive unblocked mass');
+}
+export function validateActions(input) {
+    check(input && typeof input === 'object', 'Actions input is required');
+    const policy = input.policy;
+    check(policy && policy.schemaVersion === 'holdem-public-board-joint-v1', 'Invalid public policy schema');
+    check(Array.isArray(policy.context) && policy.context.length === 316 && policy.context.every(Number.isFinite), 'context requires 316 finite features');
+    check(Array.isArray(policy.history) && policy.history.length <= 512 && policy.history.every(row => Array.isArray(row) && row.length === 32 && row.every(Number.isFinite)), 'history requires at most 512 events of 32 finite features');
+    check(Array.isArray(policy.legalMask) && policy.legalMask.length === 3 && policy.legalMask.every(x => x === 0 || x === 1) && policy.legalMask.some(x => x === 1), 'Invalid legalMask');
+    check(typeof input.hand === 'string' && /^[2-9TJQKA][cdhs][2-9TJQKA][cdhs]$/.test(input.hand), 'hand requires an exact combo');
+    const board = [];
+    let empty = false;
+    for (let slot = 0; slot < 5; slot++) {
+        const block = policy.context.slice(slot * 52, (slot + 1) * 52);
+        check(block.every(x => x === 0 || x === 1) && block.reduce((s, n) => s + n, 0) <= 1, 'Board slots must be one-hot or empty');
+        const index = block.indexOf(1);
+        if (index < 0)
+            empty = true;
+        else {
+            check(!empty, 'Board slots must be contiguous');
+            board.push('23456789TJQKA'[Math.floor(index / 4)] + 'cdhs'[index % 4]);
+        }
+    }
+    cards([input.hand.slice(0, 2), input.hand.slice(2), ...board]);
+    range(input.range, board);
+    if (input.range)
+        check((input.range[input.hand] ?? input.range[input.hand.slice(2) + input.hand.slice(0, 2)] ?? 0) > 0, 'Hand must have positive range weight');
+    if (input.opponentRanges !== undefined) {
+        check(Array.isArray(input.opponentRanges) && Math.abs(input.opponentRanges.length - policy.context[315] * 9) < 1e-6, 'opponentRanges must match remaining opponents');
+        input.opponentRanges.forEach(r => { if (r !== null)
+            range(r, board); });
+    }
+    if (input.gateSlope !== undefined)
+        check(Number.isFinite(input.gateSlope) && input.gateSlope > 0 && input.gateSlope <= 200, 'gateSlope must be in (0, 200]');
+    if (input.style !== undefined)
+        check(['tight-passive', 'tight-aggressive', 'loose-passive', 'loose-aggressive'].includes(input.style), 'Invalid style');
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

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

package/package.json

@@ -1,6 +1,33 @@
-{
-  "name": "@holdem-api/holdem-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@holdem-api/holdem-sdk",
+  "version": "0.1.1",
+  "description": "Typed server-side client for Holdem API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/client.test.mjs"
+  },
+  "devDependencies": {
+    "typescript": "5.7.3"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}