{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://bot.yoyoo.org/schemas/v1/bot-resource.schema.json",
  "title": "BotResource",
  "description": "Bot 资源完整表示。GET /v1/bots/{id} 与 POST /v1/bots 响应体；secret 仅在创建/轮换时于 BotCredential 中返回一次。",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "object",
    "display_name",
    "matrix_user_id",
    "status",
    "inbound",
    "access_policy",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^bot_[0-9A-HJKMNP-TV-Z]{26}$",
      "description": "Bot 平台唯一 ID。格式 bot_ + ULID（Crockford Base32，26 字符）。"
    },
    "object": {
      "type": "string",
      "const": "bot",
      "description": "资源类型标识。固定 bot，便于与 Stripe/GitHub 风格 API 一致。"
    },
    "display_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Bot 在 Matrix 与 App 中展示的名称。"
    },
    "matrix_user_id": {
      "type": "string",
      "pattern": "^@[^\\s:]+:[^\\s:]+$",
      "description": "Bot 的 Matrix 用户 ID（MXID），例如 @helper:yoyoo.org。用户通过此 ID 发起私聊或 @。"
    },
    "avatar_url": {
      "type": ["string", "null"],
      "format": "uri",
      "description": "头像 HTTPS URL；null 表示使用默认头像。"
    },
    "description": {
      "type": ["string", "null"],
      "maxLength": 512,
      "description": "Bot 简介，展示在机器人资料页。"
    },
    "owner_user_id": {
      "type": "string",
      "pattern": "^@[^\\s:]+:[^\\s:]+$",
      "description": "创建者 Matrix 用户 ID。用于配额与审计。"
    },
    "developer_app_id": {
      "type": ["string", "null"],
      "pattern": "^dapp_[0-9A-HJKMNP-TV-Z]{26}$",
      "description": "可选。所属开发者应用 ID，用于多 Bot 分组管理；null 表示个人 Bot。"
    },
    "status": {
      "type": "string",
      "enum": ["active", "disabled", "suspended"],
      "description": "active：可收发；disabled：所有者停用；suspended：平台封禁。"
    },
    "inbound": {
      "$ref": "#/$defs/InboundDeliveryConfig"
    },
    "access_policy": {
      "$ref": "#/$defs/AccessPolicy"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "创建时间，RFC 3339。"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "最后更新时间，RFC 3339。"
    }
  },
  "$defs": {
    "InboundDeliveryConfig": {
      "type": "object",
      "additionalProperties": false,
      "description": "入站消息投递配置。delivery_mode 与具体字段互斥：同一 Bot 仅一种入站模式生效。",
      "required": ["delivery_mode"],
      "properties": {
        "delivery_mode": {
          "type": "string",
          "enum": ["websocket", "webhook"],
          "description": "websocket：开发者主动连接 wss://bot.yoyoo.org/v1/bots/{id}/stream；webhook：平台 POST 至 webhook_url。"
        },
        "webhook_url": {
          "type": ["string", "null"],
          "format": "uri",
          "description": "delivery_mode=webhook 时必填。须 HTTPS，端口 443。平台向此 URL POST CloudEvent JSON。"
        },
        "webhook_secret": {
          "type": ["string", "null"],
          "description": "delivery_mode=webhook 时必填。用于 HMAC-SHA256 签名（头 X-Yoyoo-Signature-256）。响应体不返回明文，仅创建/轮换时返回一次。"
        },
        "webhook_enabled": {
          "type": "boolean",
          "default": true,
          "description": "delivery_mode=webhook 时是否启用投递；false 时平台暂停 POST 但保留配置。"
        },
        "websocket_last_connected_at": {
          "type": ["string", "null"],
          "format": "date-time",
          "description": "只读。delivery_mode=websocket 时最近一次成功连接时间；null 表示从未连接。"
        }
      },
      "allOf": [
        {
          "if": {
            "properties": { "delivery_mode": { "const": "webhook" } },
            "required": ["delivery_mode"]
          },
          "then": {
            "required": ["webhook_url", "webhook_secret"]
          }
        }
      ]
    },
    "AccessPolicy": {
      "type": "object",
      "additionalProperties": false,
      "description": "谁可以与 Bot 交互。平台在入站前校验，不通过则不下发 CloudEvent。",
      "required": ["direct_message_policy", "group_policy", "require_mention_in_groups"],
      "properties": {
        "direct_message_policy": {
          "type": "string",
          "enum": ["open", "pairing", "allowlist"],
          "description": "open：任意用户可私聊；pairing：陌生用户需配对码批准；allowlist：仅 direct_message_allowlist 内用户。"
        },
        "direct_message_allowlist": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^@[^\\s:]+:[^\\s:]+$"
          },
          "description": "direct_message_policy=allowlist 时生效。MXID 列表；open 时可为空。"
        },
        "group_policy": {
          "type": "string",
          "enum": ["open", "allowlist", "disabled"],
          "description": "open：任意已加入群；allowlist：仅 group_allowlist 房间；disabled：不处理群消息。"
        },
        "group_allowlist": {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^![^\\s:]+:[^\\s:]+$"
          },
          "description": "group_policy=allowlist 时生效。房间 ID 列表。"
        },
        "require_mention_in_groups": {
          "type": "boolean",
          "default": true,
          "description": "群聊中是否必须 @Bot 才投递入站事件。group_policy=open 时可设为 false。"
        }
      }
    }
  }
}