openapi: 3.1.0
info:
    title: GivingService API
    version: 1.0.0
paths:
    /api/giving/v1/get-giving-summary:
        get:
            tags:
                - GivingService
            summary: GetGivingSummary
            description: GetGivingSummary retrieves a composite global giving activity index and platform breakdowns.
            operationId: GetGivingSummary
            parameters:
                - name: platform_limit
                  in: query
                  description: Number of platforms to include (0 = all).
                  required: false
                  schema:
                    type: integer
                    format: int32
                - name: category_limit
                  in: query
                  description: Number of category breakdowns to include (0 = all).
                  required: false
                  schema:
                    type: integer
                    format: int32
            responses:
                "200":
                    description: Successful response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetGivingSummaryResponse'
                "400":
                    description: Validation error
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ValidationError'
                default:
                    description: Error response
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Error'
components:
    schemas:
        Error:
            type: object
            properties:
                message:
                    type: string
                    description: Error message (e.g., 'user not found', 'database connection failed')
            description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.
        FieldViolation:
            type: object
            properties:
                field:
                    type: string
                    description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')
                description:
                    type: string
                    description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')
            required:
                - field
                - description
            description: FieldViolation describes a single validation error for a specific field.
        ValidationError:
            type: object
            properties:
                violations:
                    type: array
                    items:
                        $ref: '#/components/schemas/FieldViolation'
                    description: List of validation violations
            required:
                - violations
            description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.
        GetGivingSummaryRequest:
            type: object
            properties:
                platformLimit:
                    type: integer
                    format: int32
                    description: Number of platforms to include (0 = all).
                categoryLimit:
                    type: integer
                    format: int32
                    description: Number of category breakdowns to include (0 = all).
            description: GetGivingSummaryRequest specifies parameters for retrieving the global giving summary.
        GetGivingSummaryResponse:
            type: object
            properties:
                summary:
                    $ref: '#/components/schemas/GivingSummary'
            description: GetGivingSummaryResponse contains the global giving activity summary.
        GivingSummary:
            type: object
            properties:
                generatedAt:
                    type: string
                    description: Timestamp of the summary generation (ISO 8601).
                activityIndex:
                    type: number
                    format: double
                    description: Global giving activity index (0-100 composite score).
                trend:
                    type: string
                    description: Index trend direction.
                estimatedDailyFlowUsd:
                    type: number
                    format: double
                    description: Estimated daily global giving flow in USD (directional, not precise).
                platforms:
                    type: array
                    items:
                        $ref: '#/components/schemas/PlatformGiving'
                categories:
                    type: array
                    items:
                        $ref: '#/components/schemas/CategoryBreakdown'
                crypto:
                    $ref: '#/components/schemas/CryptoGivingSummary'
                institutional:
                    $ref: '#/components/schemas/InstitutionalGiving'
            description: GivingSummary represents a global overview of personal giving activity across platforms.
        PlatformGiving:
            type: object
            properties:
                platform:
                    type: string
                    minLength: 1
                    description: Platform name (e.g., "GoFundMe", "GlobalGiving", "JustGiving").
                dailyVolumeUsd:
                    type: number
                    format: double
                    description: Estimated daily donation volume in USD.
                activeCampaignsSampled:
                    type: integer
                    format: int32
                    description: Number of active campaigns being sampled.
                newCampaigns24h:
                    type: integer
                    format: int32
                    description: New campaigns created in the last 24 hours.
                donationVelocity:
                    type: number
                    format: double
                    description: Average donation velocity (donations per hour).
                dataFreshness:
                    type: string
                    description: 'Data freshness: "live", "daily", "weekly", "annual".'
                lastUpdated:
                    type: string
                    description: Last data update timestamp (ISO 8601).
            required:
                - platform
            description: PlatformGiving represents aggregated giving data from a single crowdfunding platform.
        CategoryBreakdown:
            type: object
            properties:
                category:
                    type: string
                    description: Category name (e.g., "Medical", "Disaster Relief", "Education").
                share:
                    type: number
                    format: double
                    description: Share of total giving activity (0-1).
                change24h:
                    type: number
                    format: double
                    description: 24-hour change in share percentage points.
                activeCampaigns:
                    type: integer
                    format: int32
                    description: Number of active campaigns in this category.
                trending:
                    type: boolean
                    description: Trending indicator.
            description: CategoryBreakdown represents giving activity within a specific cause category.
        CryptoGivingSummary:
            type: object
            properties:
                dailyInflowUsd:
                    type: number
                    format: double
                    description: Total 24h inflow to tracked charity wallets (USD equivalent).
                trackedWallets:
                    type: integer
                    format: int32
                    description: Number of tracked charity wallets.
                transactions24h:
                    type: integer
                    format: int32
                    description: Number of transactions in the last 24 hours.
                topReceivers:
                    type: array
                    items:
                        type: string
                        description: Top receiving platforms / DAOs.
                pctOfTotal:
                    type: number
                    format: double
                    description: Percentage of total giving that is on-chain.
            description: CryptoGivingSummary tracks transparent on-chain philanthropy.
        InstitutionalGiving:
            type: object
            properties:
                oecdOdaAnnualUsdBn:
                    type: number
                    format: double
                    description: Latest OECD ODA total (annual, USD billions).
                oecdDataYear:
                    type: integer
                    format: int32
                    description: Year of latest OECD data.
                cafWorldGivingIndex:
                    type: number
                    format: double
                    description: CAF World Giving Index score (latest).
                cafDataYear:
                    type: integer
                    format: int32
                    description: Year of latest CAF data.
                candidGrantsTracked:
                    type: integer
                    format: int32
                    description: Number of foundation grants tracked (Candid).
                dataLag:
                    type: string
                    description: Data lag description (e.g., "Quarterly", "Annual").
            description: InstitutionalGiving tracks large-scale structured philanthropy and ODA.
