@holdem-api/holdem-sdk 0.1.0 → 0.1.1

package/README.md

@@ -2,6 +2,69 @@
 
 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'
@@ -51,7 +114,7 @@ Supply the exact public encoder output as `policy`: schemaVersion `holdem-public
 
 `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
+## SDK maintainers: build and publish
 
 ```sh
 npm ci
@@ -69,4 +132,21 @@ The package is configured for public publication as `@holdem-api/holdem-sdk` und
 
 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.
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holdem-api/holdem-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Typed server-side client for Holdem API",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,8 +21,7 @@
   "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"
+    "test": "npm run build && node --test test/client.test.mjs"
   },
   "devDependencies": {
     "typescript": "5.7.3"