{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/codai-ro/json-schema/codai-ro-account-view-schema.json",
  "title": "Account view",
  "description": "Full account card returned by `GET /v1/account`.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/codai-ro-gateway-openapi.yml#/components/schemas/AccountView",
  "allOf": [
    {
      "$ref": "#/$defs/AccountGrowth"
    },
    {
      "type": "object",
      "required": [
        "user_id",
        "email",
        "training_opt_out",
        "consents",
        "user",
        "key",
        "plan",
        "usage",
        "referral_redeem_until",
        "features",
        "billing_url"
      ],
      "properties": {
        "user_id": {
          "type": "string",
          "format": "uuid"
        },
        "email": {
          "type": "string",
          "format": "email"
        },
        "training_opt_out": {
          "type": "boolean",
          "description": "GDPR training flag. `true` means NOT consented (the default)."
        },
        "consents": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AccountConsent"
          }
        },
        "user": {
          "type": "object",
          "required": [
            "id",
            "email",
            "name",
            "username",
            "suggested_username"
          ],
          "properties": {
            "id": {
              "type": "string",
              "format": "uuid"
            },
            "email": {
              "type": "string",
              "format": "email"
            },
            "name": {
              "type": [
                "string",
                "null"
              ]
            },
            "username": {
              "type": [
                "string",
                "null"
              ]
            },
            "suggested_username": {
              "type": [
                "string",
                "null"
              ],
              "description": "A free suggestion derived from the email, only while no username is set."
            }
          }
        },
        "key": {
          "type": "object",
          "required": [
            "id",
            "app_id"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "Internal API key id (empty string for the legacy compat key)."
            },
            "app_id": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid"
            }
          }
        },
        "plan": {
          "type": "object",
          "required": [
            "tier",
            "status",
            "current_period_end",
            "cancel_at_period_end",
            "has_billing_account",
            "max_routing_tier"
          ],
          "properties": {
            "tier": {
              "type": [
                "string",
                "null"
              ],
              "description": "Active subscription tier slug, or `null` if none."
            },
            "status": {
              "type": "string",
              "description": "Subscription status; `active` when a tier exists without a subscription row, `none` when neither."
            },
            "current_period_end": {
              "type": [
                "string",
                "null"
              ],
              "format": "date-time"
            },
            "cancel_at_period_end": {
              "type": "boolean"
            },
            "has_billing_account": {
              "type": "boolean",
              "description": "True when a Stripe customer is attached."
            },
            "max_routing_tier": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "small",
                "medium",
                "large",
                "frontier",
                null
              ],
              "description": "Upstream-quality ceiling for the `codai` smart router; `null` = uncapped."
            }
          }
        },
        "usage": {
          "type": "object",
          "required": [
            "tasks_today",
            "tasks_per_day",
            "tasks_month",
            "tasks_per_month",
            "budget_eur_per_day",
            "budget_eur_per_month",
            "credits"
          ],
          "properties": {
            "tasks_today": {
              "type": "integer"
            },
            "tasks_per_day": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Daily task budget; `null` = unlimited."
            },
            "tasks_month": {
              "type": "integer"
            },
            "tasks_per_month": {
              "type": [
                "integer",
                "null"
              ],
              "description": "Monthly task budget; `null` = not month-capped."
            },
            "budget_eur_per_day": {
              "type": [
                "number",
                "null"
              ]
            },
            "budget_eur_per_month": {
              "type": [
                "number",
                "null"
              ]
            },
            "credits": {
              "type": "number",
              "description": "Legacy credit-ledger balance (0 on lookup failure)."
            }
          }
        },
        "referral_redeem_until": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Until when a `referral_code` can still be redeemed (7 days after signup); `null` once closed."
        },
        "features": {
          "type": "object",
          "required": [
            "byok",
            "subagents",
            "persistent_memory",
            "limits_exempt"
          ],
          "properties": {
            "byok": {
              "type": "boolean",
              "description": "Bring-your-own-key providers unlocked (tier `byok|pro|power|team|custom`, key flag or limits-exempt)."
            },
            "subagents": {
              "type": "boolean"
            },
            "persistent_memory": {
              "type": "boolean"
            },
            "limits_exempt": {
              "type": "boolean"
            }
          }
        },
        "billing_url": {
          "type": "string",
          "format": "uri",
          "enum": [
            "https://codai.ro/api/mobile/billing"
          ]
        }
      }
    }
  ],
  "$defs": {
    "AccountConsent": {
      "type": "object",
      "title": "Consent record",
      "description": "Accepted terms/privacy versions for one client surface.",
      "required": [
        "surface",
        "terms_version",
        "privacy_version",
        "accepted_at"
      ],
      "properties": {
        "surface": {
          "type": "string",
          "enum": [
            "desktop",
            "phone",
            "console",
            "ios"
          ]
        },
        "terms_version": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "description": "Opaque label chosen by the client, e.g. `1.1` or a dated slug."
        },
        "privacy_version": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64
        },
        "accepted_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "AccountGrowth": {
      "type": "object",
      "title": "Growth block",
      "description": "Wallet, promotion and referral data shared by GET and PATCH responses. Each block is `null` when its lookup fails or nothing applies.",
      "required": [
        "wallet",
        "promo",
        "referral"
      ],
      "properties": {
        "wallet": {
          "oneOf": [
            {
              "$ref": "#/$defs/AccountWallet"
            },
            {
              "type": "null"
            }
          ]
        },
        "promo": {
          "oneOf": [
            {
              "$ref": "#/$defs/AccountPromo"
            },
            {
              "type": "null"
            }
          ]
        },
        "referral": {
          "oneOf": [
            {
              "$ref": "#/$defs/AccountReferral"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "AccountPromo": {
      "type": "object",
      "title": "Active promotion",
      "description": "The best (lowest multiplier) promotion applicable to the user right now.",
      "required": [
        "slug",
        "title",
        "banner_en",
        "banner_ro",
        "multiplier",
        "ends_at"
      ],
      "properties": {
        "slug": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "banner_en": {
          "type": [
            "string",
            "null"
          ]
        },
        "banner_ro": {
          "type": [
            "string",
            "null"
          ]
        },
        "multiplier": {
          "type": "number",
          "description": "Price multiplier while the promotion is live (`0.5` = half price)."
        },
        "ends_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "AccountReferral": {
      "type": "object",
      "title": "Referral stats",
      "description": "Referral programme status for the caller as a referrer.",
      "required": [
        "username",
        "consented",
        "share_url",
        "invited",
        "rewarded",
        "pending",
        "flagged",
        "earned_eur",
        "month_remaining",
        "lifetime_remaining",
        "reward_eur",
        "referee_reward_eur",
        "qualify_spend_eur"
      ],
      "properties": {
        "username": {
          "type": [
            "string",
            "null"
          ]
        },
        "consented": {
          "type": "boolean",
          "description": "Whether the user opted into the referral programme."
        },
        "share_url": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "`https://codai.ro/r/<username>` once a username is set."
        },
        "invited": {
          "type": "integer"
        },
        "rewarded": {
          "type": "integer"
        },
        "pending": {
          "type": "integer",
          "description": "Referrals in `pending` or `qualified` state."
        },
        "flagged": {
          "type": "integer"
        },
        "earned_eur": {
          "type": "number"
        },
        "month_remaining": {
          "type": "integer",
          "description": "Rewarded referrals still allowed this UTC month."
        },
        "lifetime_remaining": {
          "type": "integer"
        },
        "reward_eur": {
          "type": "number",
          "description": "EUR granted to the referrer per qualified referral."
        },
        "referee_reward_eur": {
          "type": "number",
          "description": "EUR granted to the referee on redeem."
        },
        "qualify_spend_eur": {
          "type": "number",
          "description": "Spend the referee must reach before the referrer is rewarded."
        }
      }
    },
    "AccountWallet": {
      "type": "object",
      "title": "EUR wallet",
      "description": "Spendable EUR balance, promo-grant headroom and recent ledger history.",
      "required": [
        "balance_eur",
        "next_expiry_at",
        "promo_granted_eur",
        "promo_cap_eur",
        "history"
      ],
      "properties": {
        "balance_eur": {
          "type": "number",
          "description": "Spendable balance in EUR (integer micros converted at the edge)."
        },
        "next_expiry_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the next promo lot expires, or `null` if none."
        },
        "promo_granted_eur": {
          "type": "number",
          "description": "Total promotional EUR granted so far."
        },
        "promo_cap_eur": {
          "type": "number",
          "description": "Lifetime cap on promotional grants for this account."
        },
        "history": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AccountWalletHistoryEntry"
          }
        }
      }
    },
    "AccountWalletHistoryEntry": {
      "type": "object",
      "title": "Wallet ledger entry",
      "description": "One line of the EUR wallet ledger (last 180 days, newest first, max 20).",
      "required": [
        "id",
        "delta_eur",
        "source",
        "expires_at",
        "promo",
        "multiplier",
        "list_eur",
        "note",
        "created_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "delta_eur": {
          "type": "number",
          "description": "Positive for grants, negative for charges, in EUR."
        },
        "source": {
          "type": "string",
          "enum": [
            "welcome_grant",
            "referral_referee_grant",
            "referral_referrer_grant",
            "promo_grant",
            "admin_grant",
            "admin_revoke",
            "purchase",
            "usage_charge",
            "expiry",
            "auto_topup",
            "task_refund",
            "task_success_charge",
            "credit_migration",
            "compute_charge",
            "sandbox_charge"
          ]
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "For grants, when the remaining balance of this lot becomes void."
        },
        "promo": {
          "type": [
            "string",
            "null"
          ],
          "description": "Promotion slug applied to a charge, if any."
        },
        "multiplier": {
          "type": [
            "number",
            "null"
          ],
          "description": "Price multiplier applied to a charge (1 = list price)."
        },
        "list_eur": {
          "type": [
            "number",
            "null"
          ],
          "description": "List price of the charge before the promotion multiplier, in EUR."
        },
        "note": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}