openapi.yaml

openapi: 3.1.0
info:
  title: Islamic Toolkit API
  version: 1.0.0
  summary: Prayer times, Qibla direction, Hijri conversion, Islamic holidays, 99 Names of Allah, and Zakat calculations.
  description: |
    A halal-focused developer utility API built on Cloudflare Workers.

    The API combines six practical Islamic endpoints in a single edge deployment:
    prayer times with multiple calculation methods, Qibla direction, Hijri and Gregorian
    conversion, curated Islamic holiday data, the 99 Names of Allah, and a Zakat calculator.
  contact:
    name: Hassan Makhloufi
  license:
    name: MIT
servers:
  - url: https://islamic-toolkit-api.hassanmakhloufi.workers.dev
    description: Production Cloudflare Worker
tags:
  - name: Utility
    description: General Islamic utilities and metadata
  - name: Prayer
    description: Prayer times and Qibla functionality
  - name: Calendar
    description: Hijri and holiday calendar endpoints
  - name: Finance
    description: Zakat calculation
components:
  schemas:
    ApiError:
      type: object
      required: [error, message]
      properties:
        error:
          type: string
        message:
          type: string
    TimeValue:
      type: object
      required: [formatted, iso, unix]
      properties:
        formatted:
          type: string
          example: "06:03"
        iso:
          type: string
          format: date-time
          example: "2025-01-01T06:03:00.000Z"
        unix:
          type: integer
          example: 1735711380
    GregorianDateInfo:
      type: object
      required: [year, month, day, iso, month_name_en, weekday_en]
      properties:
        year:
          type: integer
        month:
          type: integer
        day:
          type: integer
        iso:
          type: string
          format: date
        month_name_en:
          type: string
        weekday_en:
          type: string
    HijriDateInfo:
      type: object
      required: [year, month, day, iso, month_name_en, month_name_ar]
      properties:
        year:
          type: integer
        month:
          type: integer
        day:
          type: integer
        iso:
          type: string
          example: "1446-07-01"
        month_name_en:
          type: string
        month_name_ar:
          type: string
    PrayerTimesResponse:
      type: object
      required:
        - cached
        - coordinates
        - date
        - settings
        - timings
        - sunnah
        - current_prayer
        - next_prayer
      properties:
        cached:
          type: boolean
        coordinates:
          type: object
          required: [latitude, longitude, timezone, timezone_source]
          properties:
            latitude:
              type: number
            longitude:
              type: number
            timezone:
              type: string
            timezone_source:
              type: string
              enum: [query, coordinates]
        date:
          type: object
          required: [gregorian, hijri]
          properties:
            gregorian:
              $ref: "#/components/schemas/GregorianDateInfo"
            hijri:
              $ref: "#/components/schemas/HijriDateInfo"
        settings:
          type: object
          required: [method, madhab, high_latitude_rule]
          properties:
            method:
              type: string
            madhab:
              type: string
              enum: [Shafi, Hanafi]
            high_latitude_rule:
              type: string
        timings:
          type: object
          required: [fajr, sunrise, dhuhr, asr, sunset, maghrib, isha]
          properties:
            fajr:
              $ref: "#/components/schemas/TimeValue"
            sunrise:
              $ref: "#/components/schemas/TimeValue"
            dhuhr:
              $ref: "#/components/schemas/TimeValue"
            asr:
              $ref: "#/components/schemas/TimeValue"
            sunset:
              $ref: "#/components/schemas/TimeValue"
            maghrib:
              $ref: "#/components/schemas/TimeValue"
            isha:
              $ref: "#/components/schemas/TimeValue"
        sunnah:
          type: object
          required: [middle_of_the_night, last_third_of_the_night]
          properties:
            middle_of_the_night:
              $ref: "#/components/schemas/TimeValue"
            last_third_of_the_night:
              $ref: "#/components/schemas/TimeValue"
        current_prayer:
          type: string
          nullable: true
        next_prayer:
          nullable: true
          oneOf:
            - type: "null"
            - type: object
              required: [name, time]
              properties:
                name:
                  type: string
                time:
                  $ref: "#/components/schemas/TimeValue"
    QiblaResponse:
      type: object
      required: [coordinates, direction, compass]
      properties:
        coordinates:
          type: object
          required: [latitude, longitude]
          properties:
            latitude:
              type: number
            longitude:
              type: number
        direction:
          type: number
          example: 58.48
        compass:
          type: string
          enum: [N, NE, E, SE, S, SW, W, NW]
    HijriConversionResponse:
      type: object
      required: [direction, input, output]
      properties:
        direction:
          type: string
          enum: [toHijri, toGregorian]
        input:
          oneOf:
            - $ref: "#/components/schemas/GregorianDateInfo"
            - $ref: "#/components/schemas/HijriDateInfo"
        output:
          oneOf:
            - $ref: "#/components/schemas/GregorianDateInfo"
            - $ref: "#/components/schemas/HijriDateInfo"
    HolidayEntry:
      type: object
      required:
        [slug, name_en, name_ar, category, description, hijri, gregorian]
      properties:
        slug:
          type: string
        name_en:
          type: string
        name_ar:
          type: string
        category:
          type: string
          enum: [holiday, observance, season]
        description:
          type: string
        hijri:
          $ref: "#/components/schemas/HijriDateInfo"
        gregorian:
          $ref: "#/components/schemas/GregorianDateInfo"
    HolidaysResponse:
      type: object
      required: [calendar, year, holidays]
      properties:
        calendar:
          type: string
          enum: [hijri, gregorian]
        year:
          type: integer
        holidays:
          type: array
          items:
            $ref: "#/components/schemas/HolidayEntry"
    NameOfAllah:
      type: object
      required: [number, arabic, transliteration, meaning_en]
      properties:
        number:
          type: integer
          minimum: 1
          maximum: 99
        arabic:
          type: string
        transliteration:
          type: string
        meaning_en:
          type: string
    NamesResponse:
      type: object
      required: [count, items]
      properties:
        count:
          type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/NameOfAllah"
    ZakatResponse:
      type: object
      required:
        [
          assets,
          nisab,
          total_wealth,
          zakat_rate,
          zakat_due,
          is_obligatory,
          standards,
        ]
      properties:
        assets:
          type: object
          required:
            [savings, gold_grams, silver_grams, gold_value, silver_value]
          properties:
            savings:
              type: number
            gold_grams:
              type: number
            silver_grams:
              type: number
            gold_value:
              type: number
            silver_value:
              type: number
        nisab:
          type: object
          required: [gold_standard, silver_standard, preferred_threshold]
          properties:
            gold_standard:
              type: number
            silver_standard:
              type: number
            preferred_threshold:
              type: number
        total_wealth:
          type: number
        zakat_rate:
          type: number
          example: 0.025
        zakat_due:
          type: number
        is_obligatory:
          type: boolean
        standards:
          type: object
          required: [gold, silver]
          properties:
            gold:
              type: boolean
            silver:
              type: boolean
paths:
  /health:
    get:
      tags: [Utility]
      summary: Health check
      description: Returns a lightweight liveness payload for the deployed Worker.
      responses:
        "200":
          description: Healthy response
          content:
            application/json:
              schema:
                type: object
                required: [status, version, runtime, timestamp]
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                    example: 1.0.0
                  runtime:
                    type: string
                    example: Cloudflare Workers
                  timestamp:
                    type: string
                    format: date-time
  /logo.svg:
    get:
      tags: [Utility]
      summary: Listing logo asset
      description: Returns the SVG logo used by the interactive tester and marketplace listing.
      responses:
        "200":
          description: SVG image
          content:
            image/svg+xml:
              schema:
                type: string
                format: binary
  /prayer-times:
    get:
      tags: [Prayer]
      summary: Calculate prayer times
      parameters:
        - name: latitude
          in: query
          required: true
          schema:
            type: number
            minimum: -90
            maximum: 90
        - name: longitude
          in: query
          required: true
          schema:
            type: number
            minimum: -180
            maximum: 180
        - name: date
          in: query
          required: false
          description: Gregorian date in YYYY-MM-DD. Defaults to the current day in the resolved timezone.
          schema:
            type: string
            format: date
        - name: timezone
          in: query
          required: false
          description: Optional IANA timezone override, for example Europe/London.
          schema:
            type: string
        - name: method
          in: query
          required: false
          schema:
            type: string
            enum:
              [
                MuslimWorldLeague,
                Egyptian,
                Karachi,
                UmmAlQura,
                Dubai,
                Qatar,
                Kuwait,
                MoonsightingCommittee,
                Singapore,
                Turkey,
                Tehran,
                NorthAmerica,
              ]
        - name: madhab
          in: query
          required: false
          schema:
            type: string
            enum: [Shafi, Hanafi]
        - name: highLatitudeRule
          in: query
          required: false
          schema:
            type: string
            enum:
              [Recommended, MiddleOfTheNight, SeventhOfTheNight, TwilightAngle]
        - name: nocache
          in: query
          required: false
          schema:
            type: string
            enum: ["0", "1"]
      responses:
        "200":
          description: Prayer times with Gregorian and Hijri date metadata
          headers:
            X-Cache:
              schema:
                type: string
                enum: [HIT, MISS]
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrayerTimesResponse"
        "400":
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Missing or invalid proxy secret
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /qibla:
    get:
      tags: [Prayer]
      summary: Calculate Qibla direction
      parameters:
        - name: latitude
          in: query
          required: true
          schema:
            type: number
            minimum: -90
            maximum: 90
        - name: longitude
          in: query
          required: true
          schema:
            type: number
            minimum: -180
            maximum: 180
      responses:
        "200":
          description: Direction toward the Kaaba in degrees from north
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QiblaResponse"
        "400":
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Missing or invalid proxy secret
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /hijri:
    get:
      tags: [Calendar]
      summary: Convert between Gregorian and Hijri dates
      parameters:
        - name: date
          in: query
          required: true
          description: Date in YYYY-MM-DD, interpreted according to the direction value.
          schema:
            type: string
        - name: direction
          in: query
          required: false
          schema:
            type: string
            enum: [toHijri, toGregorian]
      responses:
        "200":
          description: Converted date pair
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HijriConversionResponse"
        "400":
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Missing or invalid proxy secret
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /holidays:
    get:
      tags: [Calendar]
      summary: List Islamic holidays for a Gregorian or Hijri year
      parameters:
        - name: year
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
            maximum: 3000
        - name: calendar
          in: query
          required: false
          schema:
            type: string
            enum: [gregorian, hijri]
      responses:
        "200":
          description: Holiday list with both calendar systems per item
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HolidaysResponse"
        "400":
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Missing or invalid proxy secret
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /names:
    get:
      tags: [Utility]
      summary: Retrieve the 99 Names of Allah
      parameters:
        - name: number
          in: query
          required: false
          description: Optional single-name lookup from 1 to 99.
          schema:
            type: integer
            minimum: 1
            maximum: 99
      responses:
        "200":
          description: One or more Names of Allah
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NamesResponse"
        "400":
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Missing or invalid proxy secret
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
  /zakat:
    get:
      tags: [Finance]
      summary: Calculate Zakat due
      parameters:
        - name: savings
          in: query
          required: true
          schema:
            type: number
            minimum: 0
        - name: gold_grams
          in: query
          required: false
          schema:
            type: number
            minimum: 0
        - name: silver_grams
          in: query
          required: false
          schema:
            type: number
            minimum: 0
        - name: gold_price_per_gram
          in: query
          required: true
          schema:
            type: number
            minimum: 0
        - name: silver_price_per_gram
          in: query
          required: true
          schema:
            type: number
            minimum: 0
      responses:
        "200":
          description: Zakat calculation summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ZakatResponse"
        "400":
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Missing or invalid proxy secret
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"