@my-swu/simulator-client 0.1.0

package/dist/validators.js

@@ -0,0 +1,85 @@
+import { SdkValidationError } from './internal/errors.js';
+import { compileSchemas, describeValidationErrors, getFastValidator } from './validators/ajv.js';
+import { hasUnknownDiscriminant, warmDiscriminants } from './validators/discriminants.js';
+/**
+ * Validates one unknown payload against one generated schema.
+ *
+ * Use this for custom transports, persisted payload checks, tests, or tools that
+ * need the same runtime validation the SDK applies at the network boundary.
+ *
+ * @example
+ * ```ts
+ * import { parseSchema } from '@my-swu/simulator-client'
+ *
+ * const health = parseSchema('health-response', { status: 'ok' })
+ * console.log(health.status)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/errors
+ * @see https://simulator-sdk.my-swu.com/guide/versioning
+ */
+export function parseSchema(name, value) {
+    const validate = getFastValidator(name);
+    if (validate == null) {
+        throw new Error(`missing validator for schema ${name}`);
+    }
+    if (!validate(value)) {
+        throw new SdkValidationError(`payload does not match schema ${name}`, name, 
+        // The hot-path validator stops at the first error; only a payload that is
+        // already being rejected pays for the full list. See `./validators/ajv.ts`.
+        describeValidationErrors(name, value, validate.errors));
+    }
+    return value;
+}
+/**
+ * Socket protocol roots warmed by default, in first-frame order.
+ *
+ * These are the schemas a connect handshake validates: every session type
+ * checks its protocol root before anything else reaches a consumer. Warming
+ * them is what keeps the ~215 ms first compile out of the connect path;
+ * `server-message` leads because it is the largest and therefore pulls in the
+ * shared definition pool the other three then reuse for a few ms each.
+ */
+const CONNECT_PATH_SCHEMAS = [
+    'server-message',
+    'lobby-server-message',
+    'tournament-room-server-message',
+    'lobby-list-server-message',
+];
+/**
+ * Builds the schema-backed validator for `createSimulatorClient`.
+ *
+ * Boundary validation is off by default. Naming this function is what opts a
+ * build in — and what makes the generated schema map plus Ajv reachable from
+ * the client, which is roughly 90% of the SDK's minified bundle. Leave it
+ * unreferenced and a bundler removes both.
+ *
+ * The returned validator carries a `warmUp`, which `createSimulatorClient`
+ * schedules on an idle callback so the first schema compile does not land on
+ * the first server frame.
+ *
+ * @example
+ * ```ts
+ * import { createSchemaValidator, createSimulatorClient } from '@my-swu/simulator-client'
+ *
+ * const simulatorClient = createSimulatorClient({
+ *   baseUrl: 'http://127.0.0.1:4000',
+ *   validate: createSchemaValidator(),
+ * })
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/client-api
+ */
+export function createSchemaValidator() {
+    return {
+        hasUnknownDiscriminant,
+        parse: parseSchema,
+        // Both of the boundary's lazy caches, because a frame pays both: the
+        // Ajv compile behind `parse` and the discriminant scan behind
+        // `hasUnknownDiscriminant`.
+        warmUp: (names = CONNECT_PATH_SCHEMAS) => {
+            compileSchemas(names);
+            warmDiscriminants(names);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@my-swu/simulator-client",
+  "version": "0.1.0",
+  "description": "Typed TypeScript client for the swu-simulator HTTP and WebSocket engine.",
+  "keywords": [
+    "swu",
+    "star-wars-unlimited",
+    "sdk",
+    "typescript",
+    "websocket",
+    "game-engine",
+    "simulator"
+  ],
+  "license": "MIT",
+  "author": "Guillaume Chau <guillaume@akryum.dev>",
+  "homepage": "https://github.com/Akryum/swu-simulator#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Akryum/swu-simulator.git",
+    "directory": "packages/ts-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Akryum/swu-simulator/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./generated": {
+      "types": "./dist/generated/index.d.ts",
+      "import": "./dist/generated/index.js"
+    },
+    "./schema/*": "./schema/*",
+    "./package.json": "./package.json",
+    "./local": {
+      "types": "./dist/local/index.d.ts",
+      "import": "./dist/local/index.js"
+    },
+    "./local/worker": {
+      "types": "./dist/local/worker.d.ts",
+      "import": "./dist/local/worker.js"
+    },
+    "./local/assets": {
+      "types": "./dist/local/assets.d.ts",
+      "import": "./dist/local/assets.js"
+    },
+    "./local/routing": {
+      "types": "./dist/local/routing.d.ts",
+      "import": "./dist/local/routing.js"
+    },
+    "./generated/version": {
+      "types": "./dist/generated/version.d.ts",
+      "import": "./dist/generated/version.js"
+    }
+  },
+  "sideEffects": [
+    "**/local/worker.js",
+    "**/local/worker.ts"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
+  "scripts": {
+    "generate": "node ./scripts/generate.mjs",
+    "build": "pnpm run generate && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "cargo build --quiet --manifest-path ../../Cargo.toml --bin swu-simulator && pnpm run generate && pnpm run typecheck && vitest run",
+    "docs:api": "pnpm run build && typedoc && node ./scripts/inject-api-examples.mjs && node ./scripts/check-api-examples.mjs",
+    "docs:guides": "node ./scripts/check-guide-examples.mjs",
+    "release:check": "pnpm run typecheck && pnpm run test && pnpm --dir ../.. docs:build"
+  }
+}

package/schema/abandon-match-request.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AbandonMatchRequest",
+  "description": "Authenticated request to permanently abandon one solo AI match.",
+  "type": "object",
+  "properties": {
+    "seatToken": {
+      "description": "Host seat token returned by match creation or restore.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "seatToken"
+  ]
+}

package/schema/abandon-match-response.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AbandonMatchResponse",
+  "description": "Confirmation that a solo AI runtime was closed.",
+  "type": "object",
+  "properties": {
+    "matchId": {
+      "type": "string",
+      "format": "uuid"
+    }
+  },
+  "required": [
+    "matchId"
+  ]
+}

package/schema/add-lobby-ai-player-request.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AddLobbyAiPlayerRequest",
+  "type": "object",
+  "properties": {
+    "deck": {
+      "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/DeckInput"
+    },
+    "deckId": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "deckSource": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "deckTitle": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "difficulty": {
+      "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/AiDifficulty"
+    },
+    "formatSetup": {
+      "anyOf": [
+        {
+          "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/FormatSetupInput"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "playerToken": {
+      "type": "string"
+    },
+    "trilogyFormatMode": {
+      "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/AiTrilogyFormatMode"
+    }
+  },
+  "required": [
+    "playerToken",
+    "difficulty",
+    "deck",
+    "trilogyFormatMode"
+  ]
+}

package/schema/api-error-response.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ApiErrorResponse",
+  "type": "object",
+  "properties": {
+    "error": {
+      "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/ErrorPayload"
+    }
+  },
+  "required": [
+    "error"
+  ]
+}

package/schema/card-catalog-refresh-response.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CardCatalogRefreshResponse",
+  "description": "Result returned after this replica has refreshed its catalog.",
+  "type": "object",
+  "properties": {
+    "expansionCount": {
+      "description": "Number of app-authoritative expansion rows applied.",
+      "type": "integer",
+      "format": "uint",
+      "minimum": 0
+    },
+    "refreshedAtMs": {
+      "description": "Epoch milliseconds when this replica accepted the refresh.",
+      "type": "integer",
+      "format": "uint64",
+      "minimum": 0
+    },
+    "suspensionCount": {
+      "description": "Number of suspended cards applied from app-owned effective lists.",
+      "type": "integer",
+      "format": "uint",
+      "minimum": 0
+    }
+  },
+  "required": [
+    "expansionCount",
+    "suspensionCount",
+    "refreshedAtMs"
+  ]
+}

package/schema/cards-response.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CardsResponse",
+  "description": "Card-metadata list response served by `GET /api/cards` (and the offline\nlocal host).",
+  "type": "object",
+  "properties": {
+    "cards": {
+      "type": "array",
+      "items": {
+        "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/CardMetadataView"
+      }
+    }
+  },
+  "required": [
+    "cards"
+  ]
+}

package/schema/client-message.schema.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ClientMessage",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "ready"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/GameCommand"
+        },
+        "type": {
+          "type": "string",
+          "const": "command"
+        }
+      },
+      "required": [
+        "type",
+        "payload"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/FormatEventCommand"
+        },
+        "type": {
+          "type": "string",
+          "const": "formatEvent"
+        }
+      },
+      "required": [
+        "type",
+        "payload"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/FormatEventCommand"
+        },
+        "type": {
+          "type": "string",
+          "const": "aiFormatEvent"
+        }
+      },
+      "required": [
+        "type",
+        "payload"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/CardInteractionCueRequest"
+        },
+        "type": {
+          "type": "string",
+          "const": "interactionCue"
+        }
+      },
+      "required": [
+        "type",
+        "payload"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "type": "object",
+          "properties": {
+            "message": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "message"
+          ]
+        },
+        "type": {
+          "type": "string",
+          "const": "chat"
+        }
+      },
+      "required": [
+        "type",
+        "payload"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "undo"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    {
+      "description": "Answer (or cancel, when sent by the requester) a pending undo\napproval request.",
+      "type": "object",
+      "properties": {
+        "payload": {
+          "type": "object",
+          "properties": {
+            "approve": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "approve"
+          ]
+        },
+        "type": {
+          "type": "string",
+          "const": "undoResponse"
+        }
+      },
+      "required": [
+        "type",
+        "payload"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "type": "object",
+          "properties": {
+            "paused": {
+              "type": "boolean"
+            }
+          },
+          "required": [
+            "paused"
+          ]
+        },
+        "type": {
+          "type": "string",
+          "const": "setAiPaused"
+        }
+      },
+      "required": [
+        "type",
+        "payload"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "syncRequest"
+        }
+      },
+      "required": [
+        "type"
+      ]
+    },
+    {
+      "type": "object",
+      "properties": {
+        "payload": {
+          "type": "object",
+          "properties": {
+            "nonce": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        },
+        "type": {
+          "type": "string",
+          "const": "ping"
+        }
+      },
+      "required": [
+        "type",
+        "payload"
+      ]
+    }
+  ]
+}

package/schema/close-tournament-room-request.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CloseTournamentRoomRequest",
+  "description": "Host-only request for closing a tournament room.",
+  "type": "object",
+  "properties": {
+    "activeMatches": {
+      "$ref": "https://simulator-sdk.my-swu.com/schema/common.json#/$defs/CloseTournamentRoomActiveMatches"
+    },
+    "playerToken": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "playerToken",
+    "activeMatches"
+  ]
+}