openapi: 3.0.3
info:
  title: OnBoarding API - V1
  version: 1.1.0
  description: API for querying all aspects of the onboarding flow.
  contact:
    name: SharinApp Team
#    _Changelog_
#    - **1.1.0**
#      - Add `store` endpoints
#    - **1.0.0**
#      - Initial API version
#      - `tags` endpoint
servers:
  - url: https://api-staging.sharin.app
    description: Staging server (pre-production)
  - url: https://api.sharin.app
    description: Production server
  - url: http://api.sharinapp.local
    description: Local development server (used in tests)

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API Key required for all requests
  schemas:
    Tags:
      title: Tags
      type: object
      properties:
        code:
          type: string
          example: "7c86834f1819f8c0ec3c03ed16470a83"
        label:
          type: string
          description: Tag name
          example: "Home and Lifestyle"
        icon_uri:
          type: string
          format: uri
          example: https://cdn.sharinapp.com/assets/icon.svg
        act_as_catalogue:
          type: string
          enum: ['Y', 'N']
          required: false
          description: Whether the tag is also treated as a catalogue
          example: "N"
    ErrorResponse:
      $ref: './schemas/CommonSchemas.yaml#/ErrorResponse'

paths:
  /v1/onboarding/tags:
    get:
      tags: [Tags]
      summary: Retrieve the complete tag list
      description: Returns the full list of tags cat act as catalogue.
      operationId: 00getTags
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      responses:
        '200':
          description: Complete list of tags
          content:
            application/json:
              schema:
                type: object
                required:
                  - meta
                  - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tags'
                  meta:
                    allOf:
                      - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/onboarding/store/vibe-narrative:
    post:
      tags: [Store Initialization]
      summary: Generate a store draft prompt
      description: Generate a draft prompt to be submitted to the storeowner to be adapted before being sent to the AI model.
      operationId: 01generateStep
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      requestBody:
        description: Payload containing the tag IDs for narrative filtering
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tag_codes:
                  type: array
                  items:
                    type: string
                    example:
                      tag_codes:
                        - "318a2c4217f0f31ce0535f077da1d29a"
                        - "070d31624110c2fbd045e35010f69cdd"
              required:
                - tag_codes
      responses:
        '200':
          description: A descriptive narrative of the store
          content:
            application/json:
              schema:
                type: object
                required:
                  - meta
                  - data
                properties:
                  data:
                    type: array
                    items:
                      title: Narrative Prompt
                      type: object
                      properties:
                        prompt:
                          type: string
                          required: true
                          example: I would like to create a store and sell products in the category of...
                  meta:
                    allOf:
                      - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/onboarding/store/front-names:
    post:
      tags: [Store Initialization]
      summary: Generate store name options
      description: Returns a list of suggested store names based on the provided store description and banned names.
      operationId: 02generateStep
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      requestBody:
        description: Payload containing the store description prompt and a list of banned names to exclude.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                incoming_prompt:
                  type: string
                  description: Detailed description of the store to guide name generation.
                banned_names:
                  type: array
                  description: List of store names to exclude from suggestions.
                  items:
                    type: string
                  example:
                    - "Sync Style"
                    - "Nexus Living"
                    - "Evo Essence"
              required:
                - incoming_prompt
                - banned_names
      responses:
        '200':
          description: A list of suggested store names
          content:
            application/json:
              schema:
                type: object
                required:
                  - meta
                  - data
                properties:
                  data:
                    type: array
                    items:
                      type: string
                      example:
                        - "Eclat Collection"
                        - "Verve Living"
                        - "Stile Futura"
                    description: List of suggested store names
                  meta:
                    allOf:
                      - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/onboarding/store/header-image-and-description:
    post:
      tags: [Store Initialization]
      summary: Generate store header-image and the description
      description: Returns the temporary image path along with the description, both intended to be confirmed before being used as permanent front store elements.
      operationId: 03generateStep
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      requestBody:
        description: Payload containing the definitive store description prompt.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                incoming_prompt:
                  type: string
                  description: Detailed description of the store to guide name generation.
              required:
                - incoming_prompt
      responses:
        '200':
          description: Draft for store description and header image
          content:
            application/json:
              schema:
                type: object
                required:
                  - meta
                  - data
                properties:
                  data:
                    type: object
                    properties:
                      header_image:
                        type: string
                        format: uri
                        example: https://cdn.sharinapp.com/assets/header_image.jpg
                      description:
                        type: string
                        description: Short description of the store.
                  meta:
                    allOf:
                      - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/onboarding/store/create:
    post:
      tags: [Store Creation]
      summary: Create a new store
      description: |
        Creates a new store during the onboarding process and returns
        the unique identifier of the newly generated store.
      operationId: CreateStoreStep01
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: './schemas/CommonSchemas.yaml#/ServerParamHeader'
        - $ref: './schemas/CommonSchemas.yaml#/LangParamHeader'
      requestBody:
        description: |
          Payload containing the definitive store brand assets.
          Textual data and image references are required to initialize the store.
          The header image must already be stored on the API server.
          Image streaming support may be extended in future versions.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                store_name:
                  type: string
                  description: |
                    The public name of the store as it will be displayed
                    to end users.
                store_description:
                  type: string
                  description: |
                    A descriptive text representing the store identity,
                    mission, or value proposition.
                store_header_image:
                  type: string
                  description: |
                    Alias path of the store header image as provided.
                    This value may reference a server-side path or an
                    internal alias that will be resolved by the system.
                  example: "@runtime\abc123.jpg"
              required:
                - store_name
                - store_description
                - store_header_image
      responses:
        '200':
          description: Store successfully created
          content:
            application/json:
              schema:
                type: object
                required:
                  - meta
                  - data
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        description: |
                          Unique identifier of the newly created store.
                  meta:
                    allOf:
                      - $ref: './schemas/CommonSchemas.yaml#/MetaDefaultResponse'
        default:
          description: Request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'