pip install kitefrost-game-narrative   # or kitefrost-ttrpg-gm

from kitefrost_game_narrative import GameNarrativeClient

client = GameNarrativeClient.from_api_key("sk_your_key_here")

# every per-pack client exposes the shared core at .core
health = client.core.health.check()
print(health)  # {"status": "ok", "version": "..."}

client.core.health.check()  # liveness probe - no auth required

client.core.auth.whoami()  # introspect the current API key

client.core.projects.list()
client.core.projects.get(project_id)
client.core.projects.create({"name": "my-project"})

client.core.keys.list()
client.core.keys.create({"scopes": ["read", "write"]})
client.core.keys.revoke(key_id)

client.core.billing.usage()

# Send a client/telemetry event
client.core.events.send({"event_type": "...", "payload": {...}})

client.core.context.get(project_id)

client.core.byok.list()
client.core.byok.set({"provider": "...", "api_key": "..."})

client.core.webhooks.list()
client.core.webhooks.create({"url": "https://your-server.com/hook", "events": [...]})
client.core.webhooks.delete(webhook_id)

KiteFrostError
├── AuthError        (401/403) - missing, invalid, or under-permissioned API key
├── NotFoundError     (404)    - project/entity/resource not found
├── ValidationError   (422)    - malformed request payload
├── RateLimited       (429)    - too many requests; check .retry_after
└── ServerError       (5xx)    - unexpected server error

from kitefrost_core import RateLimited, ValidationError, KiteFrostError

try:
    client.core.projects.create({"name": "my-project"})
except RateLimited as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Bad request: {e.message}")
except KiteFrostError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.feedback_id:
        print(f"Feedback reference: {e.feedback_id}")