galaxy-game/user/docs/examples.md

Contract Examples

ensure-by-email

Request:

{
  "email": "pilot@example.com",
  "registration_context": {
    "preferred_language": "en",
    "time_zone": "Europe/Kaliningrad"
  }
}

Created response:

{
  "outcome": "created",
  "user_id": "user-123"
}

Existing response:

{
  "outcome": "existing",
  "user_id": "user-123"
}

Blocked response:

{
  "outcome": "blocked",
  "block_reason_code": "policy_blocked"
}

account aggregate

{
  "account": {
    "user_id": "user-123",
    "email": "pilot@example.com",
    "race_name": "Pilot Nova",
    "preferred_language": "en",
    "time_zone": "Europe/Kaliningrad",
    "declared_country": "DE",
    "entitlement": {
      "plan_code": "free",
      "is_paid": false,
      "source": "auth_registration",
      "actor": {
        "type": "service",
        "id": "user-service"
      },
      "reason_code": "initial_free_entitlement",
      "starts_at": "2026-04-09T10:00:00Z",
      "updated_at": "2026-04-09T10:00:00Z"
    },
    "active_sanctions": [],
    "active_limits": [],
    "created_at": "2026-04-09T10:00:00Z",
    "updated_at": "2026-04-09T10:00:00Z"
  }
}

update profile

Request:

{
  "race_name": "Nova Prime"
}

Success:

{
  "account": {
    "user_id": "user-123",
    "email": "pilot@example.com",
    "race_name": "Nova Prime",
    "preferred_language": "en",
    "time_zone": "Europe/Kaliningrad",
    "entitlement": {
      "plan_code": "free",
      "is_paid": false,
      "source": "auth_registration",
      "actor": {
        "type": "service",
        "id": "user-service"
      },
      "reason_code": "initial_free_entitlement",
      "starts_at": "2026-04-09T10:00:00Z",
      "updated_at": "2026-04-09T10:00:00Z"
    },
    "active_sanctions": [],
    "active_limits": [],
    "created_at": "2026-04-09T10:00:00Z",
    "updated_at": "2026-04-09T10:05:00Z"
  }
}

Conflict:

{
  "error": {
    "code": "conflict",
    "message": "request conflicts with current state"
  }
}

update settings

Request:

{
  "preferred_language": "fr-FR",
  "time_zone": "Europe/Paris"
}

admin lookup by e-mail

Request:

{
  "email": "pilot@example.com"
}

Success:

{
  "user": {
    "user_id": "user-123",
    "email": "pilot@example.com",
    "race_name": "Pilot Nova",
    "preferred_language": "en",
    "time_zone": "Europe/Kaliningrad",
    "entitlement": {
      "plan_code": "free",
      "is_paid": false,
      "source": "auth_registration",
      "actor": {
        "type": "service",
        "id": "user-service"
      },
      "reason_code": "initial_free_entitlement",
      "starts_at": "2026-04-09T10:00:00Z",
      "updated_at": "2026-04-09T10:00:00Z"
    },
    "active_sanctions": [],
    "active_limits": [],
    "created_at": "2026-04-09T10:00:00Z",
    "updated_at": "2026-04-09T10:00:00Z"
  }
}

declared-country sync

Request:

{
  "declared_country": "DE"
}

Response:

{
  "user_id": "user-123",
  "declared_country": "DE",
  "updated_at": "2026-04-09T10:10:00Z"
}

shared error envelope

{
  "error": {
    "code": "invalid_request",
    "message": "request is invalid"
  }
}