REFERENCE

API and security

Review the public runtime, trusted-server boundary, exported modules, contracts, and failure behavior before shipping.

TypeScript strictNode 18+ESM + CommonJSMIT

API surface

API	Runtime	Purpose
`PlaystateClient`	Client / server	Local decisions, rules, events, sessions.
`PlaystateServerClient`	Server	AI and authenticated mutations.
`director.decide`	Both	Create a validated decision.
`director.addRule`	Both	Register a deterministic rule.
`events.track`	Both	Validate and ingest telemetry.
`sessions.start/add/end`	Both	Build session summaries.
`server.ai.*`	Server	Structured generation and fallback.
`server.claimReward`	Server	Authorized reward mutation.

Exported modules

client

Runtime and server clients, HTTP transport.

director

Difficulty, encounters, quests, rewards, events.

rules

Conditions, actions, builders, evaluation.

Provider, prompts, schemas, fallbacks.

events / runtime

Telemetry, sessions, validated state.

adapters

Unity, Godot, Unreal, generic payloads.

types

Public contracts and typed errors.

utils

Retries, cache, logging, validation, IDs.

Core public types

type DecisionSource = "rules" | "ai" | "fallback";
type DecisionPriority = "low" | "medium" | "high";

interface DirectorAction {
  type: DirectorActionType;
  priority: DecisionPriority;
  reason: string;
  payload: Record<string, unknown>;
}

Public input schemas reject unknown or malformed state at the boundary. Keep custom payloads JSON-serializable for engine adapters.

Security model

01Untrusted game→

02Authenticated backend→

03Server client→

04PlayState / provider→

05Sanitized response

Capability	Game client	Trusted server
Local deterministic decisions	Yes	Yes
Non-sensitive telemetry	Yes	Yes
OpenAI generation	No	Yes
Profile mutation	No	Yes
Reward and event admin	No	Yes
Hold API keys	Never	Yes

Errors, retries, and caching

Error	Meaning	Response
`ValidationError`	Invalid public input	Fix request; do not retry.
`HttpError`	Non-success API response	Inspect status.
`TimeoutError`	Deadline exceeded	Retry or fall back.
`RateLimitError`	Quota exceeded	Backoff with jitter.
`ProviderUnavailableError`	AI unavailable	Use structured fallback.
`ServerOnlyError`	Trusted API used in client	Move operation to backend.

try {
  await playstate.events.track(event);
} catch (error) {
  if (error instanceof ValidationError) reportInvalidTelemetry(error.details);
  else if (error instanceof RateLimitError) scheduleRetry(error.retryAfterMs);
  else if (error instanceof PlaystateError) logger.error(error.code, error.message);
}

Production shipping checklist

Keep every secret out of game builds and client-visible configuration.
Authenticate and authorize all sensitive backend requests.
Allowlist actions and validate payloads inside the game.
Set explicit timeouts, retries, cache TTL, and a redacting logger.
Test rules, provider failure, malformed output, and offline fallback.
Audit rewards, profile updates, and live-event administration.