openapi: 3.1.0
info:
  title: V3 Users Self-Service (Phase 1)
  version: 1.1.0
  description: |
    JWT-authenticated self-service read endpoints for the Intercom/automation BFF flow.
    Authentication uses existing V1 OTP; these endpoints return RFC 38–compliant V3 envelopes.

servers:
  - url: /v3
    description: Aklamio V3 API base path

tags:
  - name: Users Self
    description: Authenticated mittlr self-service reads

paths:
  /users/self/balance:
    get:
      tags: [Users Self]
      summary: Get account balance
      description: |
        Provider-driven wallet snapshot across cash, voucher, donation, and treenation,
        including available, pending, paid-out totals, and line-item payout history.
      operationId: getUsersSelfBalance
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PartnerHeader'
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XRequestId'
        - name: provider
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated fulfillment providers (`cash`, `voucher`, `donation`, `treenation`)
        - name: paidOutFrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter paid-out totals and payout history from this RFC3339 timestamp
        - name: paidOutTo
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter paid-out totals and payout history until this RFC3339 timestamp
        - name: payoutType
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PayoutType'
      responses:
        '200':
          description: Balance retrieved
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: '#/components/schemas/Balance'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthenticationRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /users/self/rewards:
    get:
      tags: [Users Self]
      summary: List rewards / account activities
      description: Full reward history across all promotions ordered newest first, with optional filters and fulfillment metadata.
      operationId: getUsersSelfRewards
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PartnerHeader'
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XRequestId'
        - name: promotionUid
          in: query
          required: false
          schema:
            type: string
        - name: state
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated states (`pending`, `confirmed`, `rejected`)
        - name: type
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated types (`recommendation`, `cashback`, `campaignReward`)
        - name: provider
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated fulfillment providers (`cash`, `voucher`, `donation`, `treenation`)
        - name: payoutType
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PayoutType'
        - name: claimed
          in: query
          required: false
          schema:
            type: boolean
        - name: createdAtFrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter rewards from this RFC3339 timestamp (matches displayed `createdAt` / `original_created_at`)
        - name: createdAtTo
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter rewards until this RFC3339 timestamp (matches displayed `createdAt` / `original_created_at`)
      responses:
        '200':
          description: Rewards retrieved
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RewardItem'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthenticationRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /users/self/link-stats:
    get:
      tags: [Users Self]
      summary: Get link performance stats
      description: |
        Clicks (recommendation follows only) and conversions for recommendations and cashbacks.
        Cashback links never include clicks.
      operationId: getUsersSelfLinkStats
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PartnerHeader'
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/XRequestId'
        - name: createdAtFrom
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter clicks and conversions from this RFC3339 timestamp
        - name: createdAtTo
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter clicks and conversions until this RFC3339 timestamp
        - name: linkType
          in: query
          required: false
          schema:
            type: string
            enum: [recommendation, cashback]
        - name: linkUid
          in: query
          required: false
          schema:
            type: string
        - name: promotionUid
          in: query
          required: false
          schema:
            type: string
        - name: conversionState
          in: query
          required: false
          schema:
            type: string
          description: Comma-separated conversion states (`open`, `confirmed`, `rejected`)
        - name: groupBy
          in: query
          required: false
          schema:
            type: string
            enum: [total, link]
            default: total
      responses:
        '200':
          description: Link stats retrieved
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Content-Language:
              $ref: '#/components/headers/ContentLanguage'
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: '#/components/schemas/LinkStats'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/AuthenticationRequired'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT issued by V1 OTP verify with Partner audience matching the Partner header

  parameters:
    PartnerHeader:
      name: Partner
      in: header
      required: true
      schema:
        type: string
        example: support
    AcceptLanguage:
      name: Accept-Language
      in: header
      required: false
      schema:
        type: string
        enum: [en, de, es, fr, it]
    XRequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
        maxLength: 128
        pattern: '^[a-zA-Z0-9_-]{1,128}$'

  headers:
    XRequestId:
      schema:
        type: string
    ContentLanguage:
      schema:
        type: string
    RateLimitLimit:
      schema:
        type: string
    RateLimitRemaining:
      schema:
        type: string
    RateLimitReset:
      schema:
        type: string

  schemas:
    Money:
      type: object
      required: [amountCents, currency]
      properties:
        amountCents:
          type: integer
          format: int64
        currency:
          type: string

    PayoutType:
      type: string
      enum: [bankTransfer, paypal, giftcard, waylet, voucher, donation, treenation]

    FulfillmentProvider:
      type: string
      enum: [cash, voucher, donation, treenation]

    Balance:
      type: object
      required: [providers, payoutHistory]
      properties:
        blocked:
          $ref: '#/components/schemas/Money'
        providers:
          type: array
          items:
            $ref: '#/components/schemas/BalanceProvider'
        payoutHistory:
          type: array
          items:
            $ref: '#/components/schemas/PayoutHistoryItem'

    BalanceProvider:
      type: object
      required: [type, available, pending, paidOut]
      properties:
        type:
          $ref: '#/components/schemas/FulfillmentProvider'
        available:
          description: Shape depends on provider type
        pending:
          description: Shape depends on provider type
        paidOut:
          description: Aggregated payout totals for the provider
        metadata:
          type: object
          properties:
            paypalAddress:
              type: [string, 'null']

    PayoutHistoryItem:
      type: object
      required: [id, payoutType, amountCents, currency, paidAt]
      properties:
        id:
          type: integer
        payoutType:
          $ref: '#/components/schemas/PayoutType'
        amountCents:
          type: integer
        currency:
          type: string
        paidAt:
          type: string
          format: date-time
        treeCount:
          type: integer
        destination:
          type: object
          properties:
            obfuscatedIban:
              type: string
            obfuscatedEmail:
              type: string
            code:
              type: string
            deliveryUrl:
              type: string
            causeName:
              type: string
            treeCount:
              type: integer

    RewardItem:
      type: object
      required: [id, state, amountCents, currency, type, createdAt]
      properties:
        id:
          type: integer
        state:
          type: string
          enum: [pending, confirmed, rejected]
        amountCents:
          type: integer
        currency:
          type: string
        type:
          type: string
        promotionUid:
          type: string
        createdAt:
          type: string
          format: date-time
        conversion:
          type: object
          properties:
            orderId:
              type: string
        fulfillment:
          $ref: '#/components/schemas/Fulfillment'

    Fulfillment:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/FulfillmentProvider'
        status:
          type: string
          enum: [pending, unclaimed, claimed, expired, refunded, refundClaimed]
        claimedAt:
          type: string
          format: date-time
        payoutType:
          $ref: '#/components/schemas/PayoutType'
        destination:
          type: object

    ConversionCounts:
      type: object
      required: [open, confirmed, rejected, total]
      properties:
        open:
          type: integer
        confirmed:
          type: integer
        rejected:
          type: integer
        total:
          type: integer

    LinkStats:
      type: object
      properties:
        clicks:
          type: integer
          description: Recommendation follows only; omitted for cashback-only queries
        conversions:
          $ref: '#/components/schemas/ConversionCounts'
        period:
          type: object
          properties:
            from:
              type: [string, 'null']
              format: date-time
            to:
              type: [string, 'null']
              format: date-time
        totals:
          type: object
          description: Present when groupBy=link
        links:
          type: array
          description: Present when groupBy=link
          items:
            type: object
            properties:
              linkType:
                type: string
                enum: [recommendation, cashback]
              linkUid:
                type: string
              promotionUid:
                type: string
              title:
                type: string
              clicks:
                type: integer
              conversions:
                $ref: '#/components/schemas/ConversionCounts'

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, requestId]
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
            details:
              type: object

  responses:
    AuthenticationRequired:
      description: Missing or invalid JWT or Partner header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ValidationError:
      description: Invalid query parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
