openapi: 3.1.0
# Canonical path: ./common/primitives.yaml
info:
  title: Quub Exchange - Primitive Types
  version: 2.0.0
  description: Atomic IDs, enums, and primitive value objects used across all Quub services
  license:
    name: Proprietary
    url: https://quub.exchange/license

servers:
  - url: https://api.quub.exchange
    description: Placeholder (this file contains only reusable components)

paths: {} # This file contains only reusable components

components:
  # ============================================================================
  # ID TYPES (Branded IDs)
  # ============================================================================
  schemas:
    AccountId:
      type: string
      description: Unique account identifier
      example: "acc_a1b2c3d4e5f6"
      pattern: "^acc_[a-z0-9]{12}$"

    OrgId:
      type: string
      description: Organization identifier
      example: "org_x1y2z3a4b5c6"
      pattern: "^org_[a-z0-9]{12}$"

    ProjectId:
      type: string
      description: Project identifier
      example: "prj_m1n2o3p4q5r6"
      pattern: "^prj_[a-z0-9]{12}$"

    TokenClassId:
      type: string
      description: Token class identifier
      example: "tkc_s1t2u3v4w5x6"
      pattern: "^tkc_[a-z0-9]{12}$"

    OfferingId:
      type: string
      description: Offering identifier
      example: "off_y1z2a3b4c5d6"
      pattern: "^off_[a-z0-9]{12}$"

    SubscriptionId:
      type: string
      description: Subscription identifier
      example: "sub_e1f2g3h4i5j6"
      pattern: "^sub_[a-z0-9]{12}$"

    # ============================================================================
    # ACCOUNT TYPES
    # ============================================================================
    AccountType:
      type: string
      enum:
        - INDIVIDUAL
        - ENTITY
        - ADMIN
        - SERVICE
      description: |
        Account classification:
        - INDIVIDUAL: Natural person
        - ENTITY: Legal entity/organization
        - ADMIN: Platform administrator
        - SERVICE: Service account for API access

    AccountStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - SUSPENDED
        - PENDING_VERIFICATION
        - CLOSED
      description: Current status of an account

    ApiKeyStatus:
      type: string
      enum:
        - ACTIVE
        - REVOKED
        - EXPIRED
      description: API key lifecycle status

    OrgStatus:
      type: string
      enum:
        - ACTIVE
        - SUSPENDED
        - CLOSED
      description: Organization status

    # ============================================================================
    # PROJECT TYPES
    # ============================================================================
    ProjectType:
      type: string
      enum:
        - REAL_ESTATE
        - RENEWABLE_ENERGY
        - INFRASTRUCTURE
        - PRIVATE_EQUITY
        - VENTURE_CAPITAL
        - CREDIT
        - OTHER
      description: Project asset class or category

    ProjectStatus:
      type: string
      enum:
        - DRAFT
        - ACTIVE
        - CLOSED
      description: Project lifecycle status

    # ============================================================================
    # TOKEN TYPES
    # ============================================================================
    TokenStandard:
      type: string
      enum:
        - ERC20
        - ERC1400
        - ERC721
        - ERC1155
        - SPL_TOKEN
      description: Blockchain token standard

    Rights:
      type: object
      description: Token holder rights and entitlements
      properties:
        voting:
          type: boolean
          description: Voting rights on corporate actions
        dividends:
          type: boolean
          description: Dividend/distribution rights
        liquidation:
          type: boolean
          description: Liquidation preference rights
        information:
          type: boolean
          description: Information rights
        redemption:
          type: boolean
          description: Redemption rights

    Tranche:
      type: string
      enum:
        - SENIOR
        - MEZZANINE
        - JUNIOR
        - EQUITY
        - COMMON
        - PREFERRED
      description: Investment tranche or seniority level

    # ============================================================================
    # PAYMENT TYPES
    # ============================================================================
    PayDirection:
      type: string
      enum:
        - INBOUND
        - OUTBOUND
      description: Payment direction (into or out of the platform)

    PayStatus:
      type: string
      enum:
        - PENDING
        - PROCESSING
        - COMPLETED
        - FAILED
        - CANCELLED
        - REVERSED
      description: Payment processing status

    PayMethod:
      type: string
      enum:
        - BANK_WIRE
        - ACH
        - SEPA
        - CRYPTO
        - CARD
        - WALLET
      description: Payment method/channel

    # ============================================================================
    # GOVERNANCE TYPES
    # ============================================================================
    CorporateActionType:
      type: string
      enum:
        - DIVIDEND
        - SPLIT
        - REVERSE_SPLIT
        - MERGER
        - ACQUISITION
        - CONVERSION
        - BUYBACK
        - RIGHTS_ISSUE
      description: Type of corporate action

    OfferingStatus:
      type: string
      enum:
        - DRAFT
        - LIVE
        - PAUSED
        - CLOSED
      description: Offering lifecycle status

    SubscriptionStatus:
      type: string
      enum:
        - DRAFT
        - PENDING_PAYMENT
        - PAID
        - ALLOCATED
        - REFUNDED
        - CANCELLED
      description: Subscription processing status

    MilestoneStatus:
      type: string
      enum:
        - PENDING
        - IN_PROGRESS
        - COMPLETED
        - DELAYED
        - CANCELLED
      description: Project milestone status

    DistributionStatus:
      type: string
      enum:
        - SCHEDULED
        - PROCESSING
        - COMPLETED
        - CANCELLED
      description: Distribution processing status

    # ============================================================================
    # COMMON METADATA
    # ============================================================================
    Locale:
      type: string
      enum: [en, ar, fr]
      description: Supported locales

    Timestamp:
      type: string
      format: date-time
      description: RFC3339 timestamp in UTC (Zulu) unless explicitly stated otherwise
      example: "2025-10-22T10:30:00Z"

    NullableTimestamp:
      oneOf:
        - $ref: "#/components/schemas/Timestamp"
        - type: "null"
      description: Optional timestamp (RFC3339 in UTC or null)

    Currency:
      type: string
      description: ISO 4217 currency code
      example: "USD"
      pattern: "^[A-Z]{3}$"

    Amount:
      type: number
      format: double
      description: Monetary amount (use with Currency)
      example: 1000.50

    Percentage:
      type: number
      format: double
      minimum: 0
      maximum: 100
      description: Percentage value (0-100)
      example: 5.25