openapi: 3.1.0
info:
  title: Poker360 Platform API
  version: 1.0.0
  description: >-
    Versioned Poker360 discovery, subscription, integration, and signed-in
    player entitlement contracts. Partner write operations are not part of
    this public surface.
servers:
  - url: https://poker360.app/api/v1
paths:
  /:
    get:
      operationId: discoverApi
      summary: Discover the Poker360 API
      responses:
        "200":
          description: API metadata and canonical resource links
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DiscoveryResponse"
  /subscriptions:
    get:
      operationId: listSubscriptionPlans
      summary: List Poker360 player and partner plans
      responses:
        "200":
          description: The current public subscription catalog
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscriptionCatalogResponse"
  /integrations:
    get:
      operationId: listIntegrations
      summary: List published Poker360 integration capabilities
      responses:
        "200":
          description: Public integration descriptions without infrastructure details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IntegrationCatalogResponse"
  /me/entitlements:
    get:
      operationId: getMyEntitlements
      summary: Resolve the signed-in player's server-issued plan
      description: >-
        Requires both a current Firebase ID token and a Firebase App Check
        token. Missing or invalid plan claims fail safely to Poker360 Free;
        clients cannot select a plan through this operation.
      security:
        - FirebaseIdToken: []
          FirebaseAppCheck: []
      responses:
        "200":
          description: The effective player plan, entitlements, and limits
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlayerEntitlementResponse"
        "401":
          description: The Firebase ID token is missing, invalid, or revoked
        "403":
          description: The App Check token is missing or invalid
components:
  securitySchemes:
    FirebaseIdToken:
      type: http
      scheme: bearer
      bearerFormat: Firebase ID token
      description: A current Poker360 Firebase Authentication ID token.
    FirebaseAppCheck:
      type: apiKey
      in: header
      name: X-Firebase-AppCheck
      description: A current Firebase App Check token for the Poker360 client.
  schemas:
    Meta:
      type: object
      required: [apiVersion, catalogVersion]
      properties:
        apiVersion:
          const: v1
        catalogVersion:
          type: string
    DiscoveryResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          type: object
          required: [name, status, resources]
          properties:
            name:
              const: Poker360 Platform API
            status:
              const: available
            resources:
              type: object
              additionalProperties:
                type: string
        meta:
          $ref: "#/components/schemas/Meta"
    SubscriptionCatalogResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SubscriptionPlan"
        meta:
          allOf:
            - $ref: "#/components/schemas/Meta"
            - type: object
              required: [paidCheckoutAvailable]
              properties:
                paidCheckoutAvailable:
                  type: boolean
    SubscriptionPlan:
      type: object
      required: [id, name, audience, summary, availability, price, entitlements, limits]
      properties:
        id:
          type: string
        name:
          type: string
        audience:
          enum: [player, partner]
        summary:
          type: string
        availability:
          enum: [available, preview, contact_sales]
        price:
          oneOf:
            - $ref: "#/components/schemas/Money"
            - type: "null"
        entitlements:
          type: array
          items:
            type: string
        limits:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
    Money:
      type: object
      required: [currency, amountMinor, interval]
      properties:
        currency:
          const: INR
        amountMinor:
          type: integer
          minimum: 0
        interval:
          const: month
    IntegrationCatalogResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Integration"
        meta:
          $ref: "#/components/schemas/Meta"
    Integration:
      type: object
      required: [id, name, relationship, status, authentication, capabilities]
      properties:
        id:
          type: string
        name:
          type: string
        relationship:
          enum: [first_party, platform_service]
        status:
          enum: [available, preview]
        authentication:
          enum: [iam_oidc, oauth2_client_credentials]
        capabilities:
          type: array
          items:
            type: string
    PlayerEntitlementResponse:
      type: object
      required: [data, meta]
      properties:
        data:
          type: object
          required: [plan, entitlement, paidCheckoutAvailable]
          properties:
            plan:
              $ref: "#/components/schemas/SubscriptionPlan"
            entitlement:
              $ref: "#/components/schemas/PlayerEntitlement"
            paidCheckoutAvailable:
              const: false
        meta:
          type: object
          required: [apiVersion]
          properties:
            apiVersion:
              const: v1
    PlayerEntitlement:
      type: object
      required:
        - schemaVersion
        - planId
        - status
        - source
        - entitlements
        - limits
        - catalogVersion
      properties:
        schemaVersion:
          const: 1
        planId:
          type: string
        status:
          const: active
        source:
          enum: [default, custom_claim]
        entitlements:
          type: array
          items:
            type: string
        limits:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
        catalogVersion:
          type: string