openapi: 3.0.3
info:
  title: Kanzy API Documentation
  version: 1.0.0
  description: |
    Interface documentation for Kanzy modules and endpoints.

servers:
  - url: http://localhost:3011
    description: Local server

tags:
  - name: Auth
  - name: Profile
  - name: Settings
  - name: Category
  - name: Product
  - name: Announcement
  - name: Brand
  - name: Community
  - name: Job
  - name: Post
  - name: Review
  - name: Address
  - name: Notification
  - name: Tier
  - name: Tag

paths:

  /api/v1/login:
    post:
      tags: [Auth]
      security: [] 
      summary: Login user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [email_or_phone, password]
              properties:
                email_or_phone:
                  type: string
                password:
                  type: string
      responses:
        200:
          description: Success

  /api/v1/register:
    post:
      tags: [Auth]
      summary: Register a new user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                [first_name, last_name, username, email, country_code, phone_number, password, password_confirmation]
              properties:
                first_name:
                  type: string
                middle_name:
                  type: string
                last_name:
                  type: string
                username:
                  type: string
                email:
                  type: string
                  format: email
                country_code:
                  type: string
                  example: "+91"
                phone_number:
                  type: string
                password:
                  type: string
                password_confirmation:
                  type: string
      responses:
        201:
          description: Registered

  /api/v1/verify-email:
    post:
      tags: [Auth]
      summary: Verify user email/phone via OTP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [email_or_phone, otp, type]
              properties:
                email_or_phone:
                  type: string
                otp:
                  type: string
                type:
                  type: string
                  enum: [login, forgot_password, register_time]
                token:
                  type: string
                  description: Required only if available
      responses:
        200:
          description: Verification success

  /api/v1/resend-verification-email:
    post:
      tags: [Auth]
      summary: Re-send verification OTP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [type, email_or_phone]
              properties:
                type:
                  type: string
                  enum: [login, forgot_password, register_time]
                email_or_phone:
                  type: string
                token:
                  type: string
                  description: Optional JWT token when available (for some flows)
      responses:
        200:
          description: OTP sent

  /api/v1/forgot-password:
    post:
      tags: [Auth]
      summary: Forgot password - send OTP
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [email_or_phone]
              properties:
                email_or_phone:
                  type: string
      responses:
        200:
          description: Email/OTP sent

  /api/v1/reset-password:
    post:
      tags: [Auth]
      summary: Reset password with token
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [token, email_or_phone, reset_password]
              properties:
                token:
                  type: string
                email_or_phone:
                  type: string
                reset_password:
                  type: string
      responses:
        200:
          description: Password reset

  /api/v1/refresh-token:
    post:
      tags: [Auth]
      summary: Refresh authentication token
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [refreshToken]
              properties:
                refreshToken:
                  type: string
      responses:
        200:
          description: Token refreshed

  /api/v1/logout:
    post:
      tags: [Auth]
      summary: Log user out
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [email, password]  # You might only need token in header
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        200:
          description: Logout success

  /api/v1/social-login:
    post:
      tags: [Auth]
      summary: Social auth login/register
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [provider, socialId, first_name, email]
              properties:
                provider:
                  type: string
                  enum: [google, facebook, apple]
                socialId:
                  type: string
                first_name:
                  type: string
                email:
                  type: string
      responses:
        200:
          description: Login success

  /api/v1/translator:
    post:
      tags: [Auth]
      summary: Translator utility
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [text, sourceLang, targetLang]
              properties:
                text:
                  type: string
                sourceLang:
                  type: string
                targetLang:
                  type: string
      responses:
        200:
          description: Translation

  /api/v1/profile:
    get:
      tags: [Profile]
      summary: Get user profile
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Profile returned }
    post:
      tags: [Profile]
      summary: Update profile
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                [
                  first_name, last_name, username, email, country_code, phone_number,
                  address_line_1, city, state, country, postal_code
                ]
              properties:
                first_name: { type: string }
                middle_name: { type: string }
                last_name: { type: string }
                username: { type: string }
                email: { type: string }
                country_code: { type: string }
                phone_number: { type: string }
                address_line_1: { type: string }
                address_line_2: { type: string }
                city: { type: string }
                state: { type: string }
                country: { type: string }
                postal_code: { type: string }
                alternate_country_code: { type: string }
                alternate_address_contact_number: { type: string }
      responses:
        200: { description: Profile updated }
    delete:
      tags: [Profile]
      summary: Delete profile/account
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Deleted }

  /api/v1/profile/file:
    post:
      tags: [Profile]
      summary: Upload profile image
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [profile]
              properties:
                profile:
                  type: string
                  format: binary
      responses:
        200: { description: File uploaded }

  /api/v1/profile-password:
    post:
      tags: [Profile]
      summary: Update profile password
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [current_password, password, password_confirmation]
              properties:
                current_password:
                  type: string
                password:
                  type: string
                password_confirmation:
                  type: string
      responses:
        200: { description: Password updated }

  /api/v1/profile/account-settings:
    get:
      tags: [Profile]
      summary: Get account settings
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Settings }
    put:
      tags: [Profile]
      summary: Update account settings (2FA, notification prefs)
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                notification_settings:
                  type: object
                  properties:
                    recommendations: { type: boolean }
                    receive_updates_on_whatsapp: { type: boolean }
                    receive_updates_and_offers: { type: boolean }
                two_factor_authentication:
                  type: object
                  properties:
                    whatsapp: { type: boolean }
                    email: { type: boolean }
                    phone_number: { type: boolean }
                otp:
                  type: string
      responses:
        200: { description: Updated }

  /api/v1/profile/account-settings/resend-otp:
    put:
      tags: [Profile]
      summary: Resend 2FA OTP for account settings
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                two_factor_authentication:
                  type: object
                  properties:
                    whatsapp: { type: boolean }
                    email: { type: boolean }
                    phone_number: { type: boolean }
      responses:
        200: { description: OTP sent }

  /api/v1/profile/social-account/connect:
    post:
      tags: [Profile]
      summary: Connect a social account
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [provider, providerId]
              properties:
                provider: { type: string }
                providerId: { type: string }
      responses:
        200: { description: Connected }

  # World/Region APIs
  /api/v1/regions:
    get:
      tags: [Profile]
      summary: List available regions
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Success }
  /api/v1/subregions:
    get:
      tags: [Profile]
      summary: List available subregions
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Success }
  /api/v1/countries:
    get:
      tags: [Profile]
      summary: List countries
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Success }
  /api/v1/states:
    get:
      tags: [Profile]
      summary: List states
      security: [ { bearerAuth: [] } ]
      parameters:
        - in: query
          name: country_id
          schema:
            type: string
          required: false
      responses:
        200: { description: Success }
  /api/v1/cities:
    get:
      tags: [Profile]
      summary: List cities
      security: [ { bearerAuth: [] } ]
      parameters:
        - in: query
          name: state_id
          schema:
            type: string
          required: false
      responses:
        200: { description: Success }

  # Categories & Category-Type
  /api/v1/categories-type:
    get:
      tags: [Category]
      summary: List category types
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Success }
  /api/v1/category-type/{id_or_slug}:
    get:
      tags: [Category]
      summary: Show category type
      security: [ { bearerAuth: [] } ]
      parameters:
        - in: path
          name: id_or_slug
          schema: { type: string }
          required: true
      responses:
        200: { description: Details }
  /api/v1/categories:
    get:
      tags: [Category]
      summary: List categories
      security: [ { bearerAuth: [] } ]
      parameters:
        - in: query
          name: search
          schema:
            type: string
          required: false
      responses:
        200: { description: Success }
  /api/v1/category/{id_or_slug}:
    get:
      tags: [Category]
      summary: Show category details
      security: [ { bearerAuth: [] } ]
      parameters:
        - in: path
          name: id_or_slug
          schema: { type: string }
          required: true
      responses:
        200: { description: Details }

  # Brands
  /api/v1/brands:
    get:
      tags: [Brand]
      summary: List all brands
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Brands }
  /api/v1/brand/{id_or_slug}:
    get:
      tags: [Brand]
      summary: Show brand
      security: [ { bearerAuth: [] } ]
      parameters:
        - in: path
          name: id_or_slug
          schema: { type: string }
      responses:
        200: { description: OK }

  # Announcement
  /api/v1/announcements:
    get:
      tags: [Announcement]
      summary: List announcements
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Announcements }
  /api/v1/announcement/{id_or_slug}:
    get:
      tags: [Announcement]
      summary: Show announcement details
      security: [ { bearerAuth: [] } ]
      parameters:
        - in: path
          name: id_or_slug
          schema: { type: string }
          required: true
      responses:
        200: { description: Detail }

  # Request Product
  /api/v1/request/product/store:
    post:
      tags: [Product]
      summary: Request a new product
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [categories, title, description]
              properties:
                categories:
                  type: array
                  items: { type: string }
                title:
                  type: string
                description:
                  type: string
      responses:
        200: { description: Requested }

  # Addresses API Endpoints
  /api/v1/addresses:
    get:
      tags: [Address]
      summary: List user addresses
      security:
        - bearerAuth: []
      responses:
        200:
          description: Addresses

  /api/v1/address/store:
    post:
      tags: [Address]
      summary: Store new address
      security:
        - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - address_line_1
                - address_line_2
                - city
                - state
                - country
                - postal_code
                - alternate_country_code
                - alternate_address_contact_number
                - address_type
              properties:
                address_line_1:
                  type: string
                address_line_2:
                  type: string
                city:
                  type: string
                state:
                  type: string
                country:
                  type: string
                postal_code:
                  type: string
                alternate_country_code:
                  type: string
                alternate_address_contact_number:
                  type: string
                address_type:
                  type: string
                  enum: [shipping, billing]
      responses:
        200:
          description: Added

  /api/v1/address/{id}/show:
    get:
      tags: [Address]
      summary: Show address details
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Address ID
          required: true
          schema:
            type: string
      responses:
        200:
          description: Details

  /api/v1/address/{id}/edit:
    get:
      tags: [Address]
      summary: Edit address (fetch for editing)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Address ID
          required: true
          schema:
            type: string
      responses:
        200:
          description: Details

  /api/v1/address/{id}/update:
    post:
      tags: [Address]
      summary: Update address
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Address ID
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address_line_1:
                  type: string
                address_line_2:
                  type: string
                city:
                  type: string
                state:
                  type: string
                country:
                  type: string
                postal_code:
                  type: string
                alternate_country_code:
                  type: string
                alternate_address_contact_number:
                  type: string
                address_type:
                  type: string
                  enum: [shipping, billing]
      responses:
        200:
          description: Updated

  /api/v1/address/{id}/delete:
    delete:
      tags: [Address]
      summary: Delete address
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Address ID
          required: true
          schema:
            type: string
      responses:
        200:
          description: Deleted

  /api/v1/address/{id}/set-primary:
    get:
      tags: [Address]
      summary: Set specified address as primary address
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          description: Address ID to set as primary
          required: true
          schema:
            type: string
      responses:
        200:
          description: Successfully set primary address
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Primary address set successfully."
        400:
          description: Invalid ID or address not found
        401:
          description: Unauthorized
        500:
          description: Internal server error


        
  # Home APIs (examples)
  /api/v1/home/categories:
    get:
      tags: [Category]
      summary: Fetch home categories
      responses:
        200: { description: OK }
  /api/v1/home/sub-categories:
    get:
      tags: [Category]
      summary: Fetch home sub-categories
      responses:
        200: { description: OK }
  /api/v1/home/brands:
    get:
      tags: [Brand]
      summary: Fetch home brands
      responses:
        200: { description: OK }
  /api/v1/home/products:
    get:
      tags: [Product]
      summary: Fetch home products
      responses:
        200: { description: OK }
  /api/v1/home/products/view-more:
    get:
      tags: [Product]
      summary: Fetch paginated home products
      responses:
        200: { description: OK }
  /api/v1/home/communties:
    get:
      tags: [Community]
      summary: Fetch home communities
      responses:
        200: { description: OK }
  /api/v1/home/jobs:
    get:
      tags: [Job]
      summary: Fetch home jobs
      responses:
        200: { description: OK }
  /api/v1/home/services:
    get:
      tags: [Job]
      summary: Fetch home services
      responses:
        200: { description: OK }

  # Notification
  /api/v1/notifications:
    get:
      tags: [Notification]
      summary: List notifications
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Notifications }
  /api/v1/notification/{id}/view:
    get:
      tags: [Notification]
      summary: Show notification details
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Details }
  /api/v1/notification/{id}/mark-as-read:
    get:
      tags: [Notification]
      summary: Mark notification as read
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Marked as read }
  /api/v1/notifications/mark-as-read-all:
    get:
      tags: [Notification]
      summary: Mark all notifications as read
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: All read }
  /api/v1/notification/{id}/mark-as-unread:
    get:
      tags: [Notification]
      summary: Mark notification as unread
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Marked as unread }
  /api/v1/notification/{id}/delete:
    delete:
      tags: [Notification]
      summary: Delete notification
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Deleted }

  # Post and Form Builder
  /api/v1/posts:
    get:
      tags: [Post]
      summary: List all posts
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: form_type
          in: query
          schema:
            type: string
            enum: [product, job, service, community]
          required: false
      responses:
        200: { description: Posts }

  /api/v1/fetch-form-builder:
    get:
      tags: [Post]
      summary: Get post form builder fields
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: category
          in: query
          schema: { type: string }
      responses:
        200: { description: Fields }

  /api/v1/store/post/form-builder:
    post:
      tags: [Post]
      summary: Store post via dynamic form
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [form_type, whoseForm]
              properties:
                form_type:
                  type: string
                  enum: [product, job, service, community]
                whoseForm:
                  type: string
                # Other dynamic fields - use additionalProperties true for dynamic keys
              additionalProperties: true
          multipart/form-data:
            schema:
              type: object
              required: [form_type, whoseForm]
              properties:
                form_type:
                  type: string
                  enum: [product, job, service, community]
                whoseForm:
                  type: string
                # Additional fields could come by dynamic form
              additionalProperties: true
      responses:
        200: { description: Created }

  /api/v1/post/{id}/view:
    get:
      tags: [Post]
      summary: View single post
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: form_type
          in: query
          schema:
            type: string
            enum: [product, job, service, community]
      responses:
        200: { description: Detail }

  /api/v1/post/{id}/edit:
    get:
      tags: [Post]
      summary: Edit post (fetch for editing)
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: form_type
          in: query
          schema:
            type: string
            enum: [product, job, service, community]
      responses:
        200: { description: Details }

  /api/v1/post/{id}/update:
    post:
      tags: [Post]
      summary: Update post
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [form_type, whoseForm]
              properties:
                form_type:
                  type: string
                whoseForm:
                  type: string
              additionalProperties: true
      responses:
        200: { description: Updated }

  /api/v1/post/{id}/delete:
    post:
      tags: [Post]
      summary: Delete post
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
        - name: form_type
          in: query
          schema:
            type: string
      responses:
        200: { description: Deleted }

  # Recently Viewed
  /api/v1/recently-viewed:
    get:
      tags: [Product]
      summary: List recently viewed products
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: List }
    post:
      tags: [Product]
      summary: Store recently viewed product
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: string
      responses:
        200: { description: Stored }

  # Reviews
  /api/v1/reviews:
    get:
      tags: [Review]
      summary: List reviews
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Reviews }

  /api/v1/review/store:
    post:
      tags: [Review]
      summary: Create a new review
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [sellerId, productId, rating, description]
              properties:
                sellerId: { type: string }
                productId: { type: string }
                rating: { type: integer }
                description: { type: string }
                review_files:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        200: { description: Created }

  /api/v1/review/{id}/view:
    get:
      tags: [Review]
      summary: View review
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Detail }

  /api/v1/review/{id}/edit:
    get:
      tags: [Review]
      summary: Edit review (fetch for editing)
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Details }

  /api/v1/review/{id}/update:
    post:
      tags: [Review]
      summary: Update review
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                sellerId: { type: string }
                productId: { type: string }
                rating: { type: integer }
                description: { type: string }
                review_files:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        200: { description: Updated }

  /api/v1/review/{id}/delete:
    delete:
      tags: [Review]
      summary: Delete review
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Deleted }

  # Help Center
  /api/v1/help-center/store:
    post:
      tags: [Auth]
      summary: Store Help Center Ticket
      security: [ { bearerAuth: [] } ]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [mainReason, subReason, firstName, lastName, email, countryCode, contactNumber, description]
              properties:
                mainReason: { type: string }
                subReason: { type: string }
                firstName: { type: string }
                lastName: { type: string }
                email: { type: string }
                countryCode: { type: string }
                contactNumber: { type: string }
                description: { type: string }
      responses:
        200: { description: Submitted }

  # Tiers (Subscriptions)
  /api/v1/tiers:
    get:
      tags: [Tier]
      summary: List all tiers
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Tiers }
  /api/v1/tier/{id_or_slug}/view:
    get:
      tags: [Tier]
      summary: View specific tier
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id_or_slug
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Tier details }

  # Tags
  /api/v1/tags:
    get:
      tags: [Tag]
      summary: List all tags
      security: [ { bearerAuth: [] } ]
      responses:
        200: { description: Tags }
  /api/v1/tags/{id_or_slug}/view:
    get:
      tags: [Tag]
      summary: View tag
      security: [ { bearerAuth: [] } ]
      parameters:
        - name: id_or_slug
          in: path
          required: true
          schema: { type: string }
      responses:
        200: { description: Tag detail }

  # Settings
  /api/v1/settings:
    get:
     tags: [Settings]
     summary: List or fetch general settings
     # No security defined here -> public endpoint
     responses:
       200:
         description: List of settings or general settings fetched
         content:
           application/json:
             schema:
               type: object
  
  /api/v1/setting/{slug}:
    get:
     tags: [Settings]
     summary: Fetch a specific setting by slug
     parameters:
       - name: slug
         in: path
         description: The unique slug (identifier) for the setting
         required: true
         schema:
           type: string
     # No security defined here -> public endpoint
     responses:
       200:
         description: Setting details retrieved successfully
         content:
           application/json:
             schema:
               type: object
               properties:
                 key:
                   type: string
                   example: "contact-support-phone-number"
                 value:
                   type: string
                   example: "+1-800-123-4567"
       404:
         description: Setting not found
       401:
         description: Unauthorized



components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
