openapi: 3.1.0
info:
  title: Kichijitsu Calendar API
  version: "1.0.1"
  description: |
    ## Japanese Auspicious Day Calendar API

    Get comprehensive Japanese calendar data including holidays, rokuyō (six-day fortune),
    lunar calendar, 24 solar terms, zodiac (eto), nine stars (kyūsei), 28 mansions,
    72 micro-seasons, and traditional notes (暦注下段).

    **Perfect for**
    - Calendar & scheduling apps
    - Wedding & event planning
    - Culture & education
    - Fortune-telling & astrology

    **Data Coverage:** 2020–2030 (expanding)  
    **Timezone:** Asia/Tokyo (UTC+9)

    ### Plans (recommended on Rapid)
    - **Free (Lite)**: basic fields, up to 31 days per request
    - **Pro**: all fields, range up to 366 days, bulk by year(s)
    - **Ultra**: Pro + higher rate limits & priority support
  termsOfService: https://api.omajinai.co.jp/terms/
  contact:
    name: Omajinai Support
    url: https://api.omajinai.co.jp/contact/
  license:
    name: Proprietary
    url: https://omajinai.co.jp/license

servers:
  - url: https://api.omajinai.co.jp
    description: Production

security:
  - RapidAPIKey: []     # Rapid 側で自動付与される購読キー

tags:
  - name: Health
    description: API health and status
  - name: Calendar
    description: Calendar data retrieval endpoints

paths:
  /rapid.php:
    get:
      summary: Get calendar data (query style)
      description: |
        Main endpoint with a function switch via `fn` query.

        **Functions**
        - `health` — API health
        - `day` — one day
        - `range` — date range (Lite ≤31d / Pro ≤366d)
        - `bulk` — full years (Pro only)
      operationId: getCalendarDataQuery
      tags: [Calendar]
      parameters:
        - $ref: '#/components/parameters/FnParam'
        - $ref: '#/components/parameters/ViewParam'
        - $ref: '#/components/parameters/DateParam'
        - $ref: '#/components/parameters/StartDateParam'
        - $ref: '#/components/parameters/EndDateParam'
        - $ref: '#/components/parameters/YearsParam'
        - $ref: '#/components/parameters/TokenParam'
      responses:
        "200":
          $ref: '#/components/responses/Success'
        "304":
          description: Not Modified (ETag/Last-Modified)
        "400":
          $ref: '#/components/responses/BadRequest'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'

  /rapid/health:
    get:
      summary: Health check
      operationId: health
      tags: [Health]
      security: []   # ヘルスは認証不要
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HealthResponse' }

  /rapid/day/{date}:
    get:
      summary: Get one day (pretty URL)
      description: |
        Get calendar data for a specific date.
        For paid plans, pass token by header `Authorization: Bearer YOUR_TOKEN` or `?token=YOUR_TOKEN`.
      operationId: getDayPretty
      tags: [Calendar]
      parameters:
        - $ref: '#/components/parameters/DatePathParam'
        - $ref: '#/components/parameters/ViewParam'
        - $ref: '#/components/parameters/TokenParam'
      responses:
        "200":
          $ref: '#/components/responses/Success'
        "304":
          description: Not Modified
        "400":
          $ref: '#/components/responses/BadRequest'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'

  /rapid/range/{start}/{end}:
    get:
      summary: Get date range (pretty URL)
      description: |
        Get calendar data for a date range (Lite ≤31d / Pro ≤366d).
        For paid plans, pass token by header `Authorization: Bearer YOUR_TOKEN` or `?token=YOUR_TOKEN`.
      operationId: getRangePretty
      tags: [Calendar]
      parameters:
        - $ref: '#/components/parameters/StartDatePathParam'
        - $ref: '#/components/parameters/EndDatePathParam'
        - $ref: '#/components/parameters/ViewParam'
        - $ref: '#/components/parameters/TokenParam'
      responses:
        "200":
          $ref: '#/components/responses/Success'
        "304":
          description: Not Modified
        "400":
          $ref: '#/components/responses/BadRequest'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'

  /rapid/bulk/{years}:
    get:
      summary: Get multiple years (Pro only, pretty URL)
      description: |
        Get multiple full years of data (Pro/Ultra only).
        For paid plans, pass token by header `Authorization: Bearer YOUR_TOKEN` or `?token=YOUR_TOKEN`.
      operationId: getBulkPretty
      tags: [Calendar]
      parameters:
        - $ref: '#/components/parameters/YearsPathParam'
        - $ref: '#/components/parameters/TokenParam'
      responses:
        "200":
          $ref: '#/components/responses/Success'
        "304":
          description: Not Modified
        "400":
          $ref: '#/components/responses/BadRequest'
        "403":
          $ref: '#/components/responses/Forbidden'
        "404":
          $ref: '#/components/responses/NotFound'
        "429":
          $ref: '#/components/responses/TooManyRequests'

components:
  parameters:
    FnParam:
      name: fn
      in: query
      required: true
      description: Function to execute
      schema: { type: string, enum: [health, day, range, bulk] }
      example: day

    ViewParam:
      name: view
      in: query
      required: false
      description: Data view level (Lite/Pro). Rapid プラン連動も可。
      schema: { type: string, enum: [lite, pro], default: lite }

    DateParam:
      name: date
      in: query
      required: false
      description: Required when `fn=day` (YYYY-MM-DD)
      schema: { type: string, format: date }

    StartDateParam:
      name: start
      in: query
      required: false
      description: Required when `fn=range` (YYYY-MM-DD)
      schema: { type: string, format: date }

    EndDateParam:
      name: end
      in: query
      required: false
      description: Required when `fn=range` (YYYY-MM-DD)
      schema: { type: string, format: date }

    YearsParam:
      name: years
      in: query
      required: false
      description: Required when `fn=bulk`. Comma separated years like `2025,2026`.
      schema: { type: string, pattern: '^[0-9]{4}(,[0-9]{4})*$' }

    TokenParam:
      name: Authorization
      in: header
      required: false
      description: |
        **Pro direct access** token (when not via Rapid).
        Format: `Authorization: Bearer YOUR_TOKEN`
        You may also pass it as a query parameter: `?token=YOUR_TOKEN`
      schema: { type: string }

    DatePathParam:
      name: date
      in: path
      required: true
      schema: { type: string, format: date }
      example: "2026-01-01"

    StartDatePathParam:
      name: start
      in: path
      required: true
      schema: { type: string, format: date }
      example: "2026-01-01"

    EndDatePathParam:
      name: end
      in: path
      required: true
      schema: { type: string, format: date }
      example: "2026-01-31"

    YearsPathParam:
      name: years
      in: path
      required: true
      description: Comma separated years like `2025,2026`
      schema: { type: string, pattern: '^[0-9]{4}(,[0-9]{4})*$' }
      example: "2025,2026"

  securitySchemes:
    RapidAPIKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: RapidAPI subscription key (added by Rapid platform).
    RapidAPIProxySecret:
      type: apiKey
      in: header
      name: X-RapidAPI-Proxy-Secret
      description: |
        Optional internal validation. On Rapid, this header is set by the proxy
        and verified on server (`RAPIDAPI_SECRET` in .env).

  responses:
    Success:
      description: Successful response
      headers:
        X-Upgrade-Info:
          description: Upgrade hint (Lite only)
          schema: { type: string }
        Cache-Control:
          schema: { type: string }
          description: Cache policy
        ETag:
          schema: { type: string }
          description: Entity tag for conditional requests
        Last-Modified:
          schema: { type: string }
          description: Last modified timestamp (HTTP-date)
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/HealthResponse'
              - $ref: '#/components/schemas/DayResponse'
              - $ref: '#/components/schemas/RangeResponse'
              - $ref: '#/components/schemas/BulkResponse'

    BadRequest:
      description: Bad request (invalid parameters)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }

    Forbidden:
      description: Forbidden (plan limits or auth failure)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }

    NotFound:
      description: Not found (date/data missing)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }

    TooManyRequests:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema: { type: string }
          description: Seconds to wait before retry
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }

  schemas:
    HealthResponse:
      type: object
      required: [ok, service, time, view]
      properties:
        ok: { type: boolean, example: true }
        service: { type: string, example: "Kichijitsu API" }
        time: { type: string, format: date-time, example: "2025-10-01T12:00:00+09:00" }
        view: { type: string, enum: [lite, pro], example: "lite" }

    DayResponse:
      type: object
      required: [ok, view, date, day]
      properties:
        ok: { type: boolean, example: true }
        view: { type: string, enum: [lite, pro] }
        date: { type: string, format: date }
        day:
          oneOf:
            - $ref: '#/components/schemas/LiteDay'
            - $ref: '#/components/schemas/ProDay'

    RangeResponse:
      type: object
      required: [ok, view, range, count, days]
      properties:
        ok: { type: boolean, example: true }
        view: { type: string, enum: [lite, pro] }
        range:
          type: object
          required: [start, end, tz]
          properties:
            start: { type: string, format: date }
            end: { type: string, format: date }
            tz: { type: string, example: "Asia/Tokyo" }
        count: { type: integer, example: 7 }
        days:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/LiteDay'
              - $ref: '#/components/schemas/ProDay'

    BulkResponse:
      type: object
      required: [ok, view, years, data]
      properties:
        ok: { type: boolean, example: true }
        view: { type: string, enum: [pro], example: "pro" }
        years:
          type: array
          items: { type: integer }
          example: [2025, 2026]
        data:
          type: object
          additionalProperties:
            type: array
            items: { $ref: '#/components/schemas/ProDay' }

    LiteDay:
      type: object
      description: Minimal calendar data (Lite)
      required: [iso, y, m, d]
      properties:
        iso: { type: string, format: date, example: "2026-01-01" }
        date: { type: string, format: date, description: Alternative date field }
        y: { type: integer, example: 2026 }
        m: { type: integer, example: 1 }
        d: { type: integer, example: 1 }
        youbi:
          type: string
          enum: ["月","火","水","木","金","土","日"]
          example: "木"
        holiday: { type: string, example: "元日" }
        rokuyou:
          type: string
          enum: ["大安","友引","先勝","先負","赤口","仏滅"]
          example: "大安"
        kyureki: { type: string, example: "11月13日" }
        sekki: { type: string, example: "小寒" }
        moonmark:
          type: string
          enum: ["", "新月", "満月"]
          example: ""

    ProDay:
      allOf:
        - $ref: '#/components/schemas/LiteDay'
        - type: object
          description: Complete calendar data (Pro)
          properties:
            nengo: { type: string, example: "令和8年" }
            kyusei: { type: string, example: "三碧木星" }
            eto: { type: string, example: "乙亥" }
            eto_year: { type: string, example: "乙巳" }
            eto_month: { type: string, example: "戊子" }
            kyusei_year: { type: string, example: "二黒土星" }
            kyusei_month: { type: string, example: "一白水星" }
            junichoku: { type: string, example: "閉" }
            shuku28: { type: string, example: "井" }
            kou72: { type: string, example: "雪下出麦" }
            notes_arr:
              type: array
              description: Lucky/Unlucky notes, e.g., 一粒万倍日/不成就日/重日…
              items:
                oneOf:
                  - type: string
                  - type: object
                    properties:
                      id: { type: string, example: "ichiryu_manbai" }
                      label: { type: string, example: "一粒万倍日" }
                      kind: { type: string, example: "plus" }
            periods:
              type: array
              description: Period flags like 天一天上/八専/十方暮/土用…
              items:
                type: object
                properties:
                  name: { type: string, example: "大土" }
                  from: { type: string, format: date, example: "2025-12-27" }
                  to: { type: string, format: date, example: "2026-01-02" }
                  includes_end: { type: boolean, example: true }

    ErrorResponse:
      type: object
      required: [ok, error]
      properties:
        ok: { type: boolean, example: false }
        error: { type: string, example: "date is required (YYYY-MM-DD)" }
        code: { type: string, example: "DATE_REQUIRED" }
        date: { type: string }
        start: { type: string }
        end: { type: string }
        maxDays: { type: integer }
        year: { type: integer }