openapi: 3.1.0
info:
  title: DYO.gg API — Internal Endpoints
  version: 1.0.0
  summary: TrustScore, Scam Report, Build Analyzer, Damage Calculator, Leaderboard, Archive, Assets.
servers:
  - url: https://api.dyogg.com
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  schemas:
    TrustScore:
      type: object
      properties:
        uid: { type: string }
        game: { type: string, enum: [genshin, hsr, zzz] }
        score: { type: integer, minimum: 0, maximum: 100 }
        tier: { type: string, enum: [trusted, neutral, caution, flagged] }
        components:
          type: object
          properties:
            report_penalty: { type: integer }
            verified_owner_bonus: { type: integer }
            account_age_bonus: { type: integer }
            activity_bonus: { type: integer }
        last_updated: { type: string, format: date-time }
    ScamReport:
      type: object
      required: [reported_uid, reporter_uid, game, category, description]
      properties:
        reported_uid: { type: string }
        reporter_uid: { type: string }
        game: { type: string, enum: [genshin, hsr, zzz] }
        category:
          type: string
          enum: [rmt, phishing, boosting, harassment, impersonation, other]
        description: { type: string, minLength: 50, maxLength: 2000 }
        evidence_urls:
          type: array
          maxItems: 5
          items: { type: string, format: uri }
        contact_platform:
          type: string
          enum: [whatsapp, discord, telegram, hoyolab, other]
paths:
  /v1/trust-score/{game}/{uid}:
    get:
      tags: [TrustScore]
      summary: Get TrustScore for UID
      parameters:
        - in: path
          name: game
          required: true
          schema: { type: string, enum: [genshin, hsr, zzz] }
        - in: path
          name: uid
          required: true
          schema: { type: string, pattern: '^[0-9]{9,10}$' }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { $ref: '#/components/schemas/TrustScore' }
  /v1/trust-score/{game}/{uid}/timeline:
    get:
      tags: [TrustScore]
      summary: Get TrustScore timeline
      parameters:
        - in: path
          name: game
          required: true
          schema: { type: string, enum: [genshin, hsr, zzz] }
        - in: path
          name: uid
          required: true
          schema: { type: string }
      responses:
        '200': { description: OK }
  /v1/scam-report:
    post:
      tags: [ScamReport]
      summary: Submit scam report
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ScamReport' }
      responses:
        '201':
          description: Report created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id: { type: string, example: rpt_01H8YZ }
                      status: { type: string, enum: [pending_review] }
        '409':
          description: Duplicate report
        '422':
          description: Reporter melapor UID sendiri / quota exceeded
  /v1/scam-reports:
    get:
      tags: [ScamReport]
      summary: Query public scam report queue
      parameters:
        - in: query
          name: game
          schema: { type: string, enum: [genshin, hsr, zzz] }
        - in: query
          name: status
          schema: { type: string, enum: [pending_review, confirmed, dismissed], default: confirmed }
        - in: query
          name: cursor
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
      responses:
        '200': { description: OK }
  /v1/build-analyzer/analyze:
    post:
      tags: [BuildAnalyzer]
      summary: Analyze character build
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                game: { type: string, enum: [genshin, hsr, zzz] }
                avatar_id: { type: integer }
                level: { type: integer }
                weapon: { type: object }
                artifacts: { type: array }
                role: { type: string, enum: [dps, sub_dps, support, healer, shielder] }
      responses:
        '200':
          description: Analysis result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      score: { type: integer, minimum: 0, maximum: 100 }
                      grade: { type: string, enum: [F, D, C, B, A, S, SS, SSS] }
                      breakdown: { type: object }
                      recommendations: { type: array }
  /v1/damage-calculator/simulate:
    post:
      tags: [DamageCalculator]
      summary: Simulate damage rotation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                game: { type: string, enum: [genshin, hsr, zzz] }
                actor: { type: object }
                enemy: { type: object }
                rotation: { type: array }
      responses:
        '200': { description: Simulation result }
  /v1/leaderboard/{game}/{avatar_id}:
    get:
      tags: [Leaderboard]
      summary: Global leaderboard per character
      parameters:
        - in: path
          name: game
          required: true
          schema: { type: string, enum: [genshin, hsr, zzz] }
        - in: path
          name: avatar_id
          required: true
          schema: { type: integer }
        - in: query
          name: metric
          schema: { type: string, enum: [crit_stat, damage, atk, hp], default: crit_stat }
        - in: query
          name: region
          schema: { type: string, enum: [global, asia, europe, america, tw_hk_mo, cn], default: global }
      responses:
        '200': { description: OK }
  /v1/archive/notices:
    get:
      tags: [Archive]
      summary: HoYoLab notice board
      parameters:
        - in: query
          name: game
          required: true
          schema: { type: string, enum: [genshin, hsr, zzz] }
      responses:
        '200': { description: OK }
  /v1/assets/{game}/character/{avatar_id}:
    get:
      tags: [Assets]
      summary: Character asset URL
      parameters:
        - in: path
          name: game
          required: true
          schema: { type: string, enum: [genshin, hsr, zzz] }
        - in: path
          name: avatar_id
          required: true
          schema: { type: integer }
        - in: query
          name: variant
          schema: { type: string, enum: [icon, side, portrait, splash, chibi], default: icon }
      responses:
        '200': { description: OK }