Build a better game with the right AI prompts.

# Task: Create a reusable TypeScript SDK for my game backend

You are a senior TypeScript library engineer.

## Context

- Backend repository or API documentation: [LINK OR PATH]
- Authentication method: [JWT / SESSION / API TOKEN / UNKNOWN]
- Consumers: [WEB GAME / NODE SERVER / ADMIN APP / GAME ENGINE BRIDGE]
- Package manager: [NPM / PNPM / YARN / USE THE EXISTING ONE]

## Requirements

1. Inspect the backend routes, schemas, error formats, authentication flow, and existing clients before designing the SDK.
2. Keep the SDK in a separate package or repository unless the current workspace has an established monorepo convention.
3. Make it usable from both browser and server-side TypeScript without exposing server-only secrets to browser bundles.
4. Provide typed clients for the backend's supported public and authenticated operations.
5. Centralize request configuration, authentication, retries, timeouts, cancellation, pagination, validation, and error normalization.
6. Do not hide backend errors. Return actionable, typed errors while avoiding sensitive information leaks.
7. Make request retries safe. Do not automatically replay non-idempotent mutations unless the API explicitly supports idempotency.
8. Add unit tests, mocked protocol tests, and end-to-end tests against a test backend.
9. Generate clear usage documentation and examples for each supported environment.
10. Add a versioning and release strategy so backend changes do not silently break game clients.

## Deliverables

- SDK architecture and package structure.
- Typed implementation.
- Authentication and configuration examples.
- Complete tests and test commands.
- API reference and upgrade guidance.
- A short example showing the game client using the SDK instead of making raw requests.

## Internationalization and localization architecture

Build internationalization into the existing architecture before gameplay and UI content multiply. Do not create a separate localization application or bolt translation onto finished screens.

- Centralize player-facing text behind stable translation keys and locale resources. Do not hard-code display strings in gameplay, menus, tutorials, errors, notifications, subtitles, or content data.
- Define a fallback locale, missing-key behavior, resource ownership, extraction and validation commands, translator notes, and a safe process for adding or updating a language.
- Support Unicode, plural/select rules through an ICU-style message system or the engine's equivalent, locale-aware number/date/time/currency/unit formatting, and invariant internal IDs for saves, networking, analytics, achievements, and game rules.
- Plan for right-to-left layout and bidirectional text, CJK and other line-breaking rules, diacritics, input methods and IME where players type, font fallback and glyph coverage, translated text expansion, subtitles/captions, localized audio or asset variants where required, and runtime language selection with a persisted preference.
- Keep localization data separate from trusted game rules. Servers, SDKs, automation, and analytics should exchange stable language-independent identifiers while clients turn them into localized player-readable text.
- Add pseudolocalization, missing/unused-key validation, fallback-locale tests, long-string and text-expansion tests, right-to-left tests, font/glyph checks, and representative locale screenshots to the normal test and CI strategy.

Document the supported launch locales, later-locale workflow, ownership, file locations, naming rules, formatting rules, font and audio strategy, platform limitations, and exact commands another developer or translator uses.

## Player-readable output requirement

Everything shown to a player must be written and presented for a human player, not for a developer or debugger. This includes menus, HUD labels, buttons, prompts, tutorials, objectives, dialogue, tooltips, loading and save states, empty states, confirmations, warnings, errors, rewards, notifications, accessibility messages, and connection or recovery states.

Use concise plain language, the game's established terminology and tone, recognizable icons with text where meaning could be ambiguous, and a clear next action. A player-facing error should explain what happened in useful terms, whether progress is safe, and what the player can do next.

Never expose raw exceptions, stack traces, JSON, database IDs, internal event names, enum or variable names, file paths, debug coordinates, HTTP status codes without explanation, server implementation details, developer TODOs, placeholder text, or raw telemetry on a player-facing surface. Send technical details to development-only logs, diagnostics, telemetry, or an authenticated support view. A short support reference code may be shown to the player only when it helps support locate the private diagnostic record.

Verify representative success, failure, offline, loading, empty, permission, validation, timeout, save, reconnect, and recovery states from the player's perspective. Developer documentation and final engineering reports may remain technical; this requirement applies to anything the game presents to players.

## Required game documentation

Documentation is part of the definition of done for this task.

Before finishing:

1. Read the existing README, docs directory, architecture notes, decision records, and AI instructions that apply to this system.
2. Update the existing relevant documentation instead of creating a competing document or a second source of truth.
3. If no relevant document exists, create a clearly named Markdown document in the game's established documentation directory. Use docs/ when the project has no existing convention.
4. Document the current system, the decisions made, ownership and lifecycle rules, configuration, files or assets changed, commands and tests run, known limitations, and how another developer should extend or troubleshoot the work.
5. Update AI_INSTRUCTIONS.md or the project's equivalent when this task changes architectural boundaries, required workflows, naming rules, or validation commands.
6. Keep documentation accurate to the implementation. Do not claim support, measurements, or test coverage that was not verified.
7. In the final report, list every documentation file created or updated.