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

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,72 @@
-# 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`.
+
+```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.
+
+## Build, package 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.
+
+For a live smoke test, set HOLDEM_API_KEY and HOLDEM_API_URL, place a valid encoded request in a JSON file, then run `node examples/quickstart.mjs path/to/request.json`. This consumes API quota.

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,34 @@
-{
-  "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.0",
+  "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",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "5.7.3"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}