openapi: 3.0.3
info:
  title: Netnaunse API
  version: 0.1.0
  description: Cloud communications platform API (SMS-first).
servers:
  - url: http://localhost:3000
    description: Local gateway
paths:
  /health:
    get:
      summary: Gateway health
      responses:
        "200":
          description: OK
  /v1/auth/register:
    post:
      summary: Register user, organization, and wallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
                firstName: { type: string }
                lastName: { type: string }
                organizationName: { type: string }
      responses:
        "201":
          description: Created
  /v1/auth/login:
    post:
      summary: Login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string }
                password: { type: string }
      responses:
        "200":
          description: JWT + user
  /v1/auth/me:
    get:
      summary: Current user
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: User profile
  /v1/sms/send:
    post:
      summary: Queue an SMS
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [to, message]
              properties:
                to: { type: string }
                message: { type: string }
                senderId: { type: string }
                language: { type: string, enum: [English, Unicode] }
                scheduledAt: { type: string, format: date-time }
      responses:
        "202":
          description: Queued
        "402":
          description: Insufficient balance
  /v1/sms:
    get:
      summary: List messages
      security: [{ bearerAuth: [] }]
      parameters:
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: limit
          schema: { type: integer, default: 20 }
      responses:
        "200":
          description: Message list
  /v1/sms/{id}:
    get:
      summary: Message status
      security: [{ bearerAuth: [] }]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Message
  /v1/dashboard/stats:
    get:
      summary: Dashboard stats
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Stats
  /v1/wallet:
    get:
      summary: Wallet balance
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Wallet
  /v1/wallet/transactions:
    get:
      summary: Wallet transactions
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Transactions
  /v1/wallet/top-up:
    post:
      summary: Credit wallet (manual/dev)
      security: [{ bearerAuth: [] }]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount: { type: number }
      responses:
        "200":
          description: Updated wallet
  /v1/kyc:
    get:
      summary: Get KYC submission
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: KYC or null
    post:
      summary: Submit KYC
      security: [{ bearerAuth: [] }]
      responses:
        "201":
          description: Submitted
  /v1/sender-ids:
    get:
      summary: List sender ID requests
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: List
    post:
      summary: Request sender ID
      security: [{ bearerAuth: [] }]
      responses:
        "201":
          description: Created
  /v1/contacts:
    get:
      summary: List contacts
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Contacts
    post:
      summary: Create contact
      security: [{ bearerAuth: [] }]
      responses:
        "201":
          description: Created
  /v1/templates:
    get:
      summary: List templates
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Templates
    post:
      summary: Create template
      security: [{ bearerAuth: [] }]
      responses:
        "201":
          description: Created
  /v1/campaigns:
    get:
      summary: List campaigns
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Campaigns
    post:
      summary: Create campaign (draft/scheduled)
      security: [{ bearerAuth: [] }]
      responses:
        "201":
          description: Created
  /v1/webhooks:
    get:
      summary: List webhook endpoints
      security: [{ bearerAuth: [] }]
      responses:
        "200":
          description: Endpoints
    post:
      summary: Register webhook
      security: [{ bearerAuth: [] }]
      responses:
        "201":
          description: Created (includes secret once)
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT from /v1/auth/login or API key nn_…