openapi: 3.0.3
info:
  title: Digital Business Card & Apple Wallet Platform API
  description: Versioned REST API powering mobile and external integrations for digital business card creation, template switching, QR codes, vCards, and Apple Wallet passes.
  version: 1.0.0
servers:
  - url: /api/v1
    description: Current Environment

paths:
  /register:
    post:
      summary: Register a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, email, password, password_confirmation]
              properties:
                name: { type: string, example: "Jane Doe" }
                email: { type: string, example: "jane@example.com" }
                phone: { type: string, example: "+15551234567" }
                password: { type: string, format: password, example: "Secret123!" }
                password_confirmation: { type: string, format: password, example: "Secret123!" }
      responses:
        '201':
          description: Registration successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  token: { type: string }

  /login:
    post:
      summary: Authenticate user and receive Sanctum bearer token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, example: "user@cards.test" }
                password: { type: string, example: "Password123!" }
                device_name: { type: string, example: "iPhone 15 Pro" }
      responses:
        '200':
          description: Token granted
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  user: { type: object }

  /logout:
    post:
      summary: Invalidate current API token
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Successfully logged out

  /me:
    get:
      summary: Get authenticated user details and card status
      security:
        - BearerAuth: []
      responses:
        '200':
          description: User profile and card state

  /card:
    get:
      summary: Retrieve authenticated user's digital business card
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Card details
        '404':
          description: No card found
    post:
      summary: Create user's single digital business card (Strict 1-card limit)
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [full_name]
              properties:
                full_name: { type: string }
                job_title: { type: string }
                company_name: { type: string }
                bio: { type: string }
                email: { type: string }
                phone: { type: string }
                whatsapp: { type: string }
                website: { type: string }
                address: { type: string }
                template_id: { type: integer }
                profile_photo: { type: string, format: binary }
                company_logo: { type: string, format: binary }
                is_published: { type: boolean }
      responses:
        '201':
          description: Card created
        '422':
          description: User already has a card or validation error
    put:
      summary: Update existing digital business card
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Card updated successfully

  /card/template:
    put:
      summary: Switch card presentation template without altering card content
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [template_id]
              properties:
                template_id: { type: integer, example: 2 }
      responses:
        '200':
          description: Template updated

  /card/qr-code:
    get:
      summary: Get card QR code SVG and public URL
      security:
        - BearerAuth: []
      responses:
        '200':
          description: QR code payload

  /card/vcard:
    get:
      summary: Download RFC 6350 contact .vcf file
      security:
        - BearerAuth: []
      responses:
        '200':
          description: vCard stream
          content:
            text/vcard:
              schema:
                type: string

  /card/wallet-pass:
    get:
      summary: Download Apple Wallet PassKit .pkpass file
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Binary .pkpass archive
          content:
            application/vnd.apple.pkpass:
              schema:
                type: string
                format: binary

  /templates:
    get:
      summary: List all active card templates
      responses:
        '200':
          description: List of templates

  /templates/{id}:
    get:
      summary: Get template details by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Template details

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Sanctum