openapi: 3.2.0
info:
  title: Pypestream JavaScript SDK Event Handlers API
  description: "Client-side JavaScript SDK for embedding conversational AI chat interfaces into web applications.\n\n**Note:** This is a client-side SDK, not a REST API. This OpenAPI specification documents the SDK's \npublic methods and configurations for documentation purposes.\n\n## Getting Started\n\nInclude the SDK script in your HTML:\n```html\n<script src=\"https://your-pypestream-domain/config.js\"></script>\n```\n\nThen use the global `Pypestream` object to interact with the SDK.\n\n## Display Modes\n\n- **Window Mode**: Opens chat in a popup window\n- **Inline Mode**: Embeds chat directly in your webpage\n"
  version: 3.0.0
  contact:
    name: Pypestream Support
    url: https://support.pypestream.com
  license:
    name: Proprietary
    url: https://pypestream.com/terms
servers:
- url: https://api.pypestream.com/v3
  description: Production SDK API (Documentation Only)
security: []
tags:
- name: Event Handlers
  description: Register event callbacks
paths:
  /events/onShow:
    post:
      tags:
      - Event Handlers
      summary: Register onShow handler
      description: "Registers a callback for when the chat interface is shown.\n\n**JavaScript Usage:**\n```javascript\nPypestream.onShow(() => {\n  console.log('Chat opened');\n});\n```\n"
      operationId: onShow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventHandler'
      responses:
        '200':
          description: Handler registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventRegistrationResponse'
  /events/onHide:
    post:
      tags:
      - Event Handlers
      summary: Register onHide handler
      description: "Registers a callback for when the chat interface is hidden.\n\n**JavaScript Usage:**\n```javascript\nPypestream.onHide(() => {\n  console.log('Chat closed');\n});\n```\n"
      operationId: onHide
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventHandler'
      responses:
        '200':
          description: Handler registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventRegistrationResponse'
  /events/onChatEnd:
    post:
      tags:
      - Event Handlers
      summary: Register onChatEnd handler
      description: "Registers a callback for when a chat session ends.\n\n**JavaScript Usage:**\n```javascript\nPypestream.onChatEnd(() => {\n  console.log('Chat session ended');\n});\n```\n"
      operationId: onChatEnd
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventHandler'
      responses:
        '200':
          description: Handler registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventRegistrationResponse'
  /events/onChatRestart:
    post:
      tags:
      - Event Handlers
      summary: Register onChatRestart handler
      description: "Registers a callback for when a chat session is restarted.\n\n**JavaScript Usage:**\n```javascript\nPypestream.onChatRestart(() => {\n  console.log('Chat restarted');\n});\n```\n"
      operationId: onChatRestart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventHandler'
      responses:
        '200':
          description: Handler registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventRegistrationResponse'
  /events/onSetupComplete:
    post:
      tags:
      - Event Handlers
      summary: Register onSetupComplete handler
      description: "Registers a callback for when initial setup completes.\n\n**JavaScript Usage:**\n```javascript\nPypestream.onSetupComplete(() => {\n  console.log('Setup complete');\n});\n```\n"
      operationId: onSetupComplete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventHandler'
      responses:
        '200':
          description: Handler registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventRegistrationResponse'
  /events/onFirstMessage:
    post:
      tags:
      - Event Handlers
      summary: Register onFirstMessage handler
      description: "Registers a callback for when the first message is received.\n\n**JavaScript Usage:**\n```javascript\nPypestream.onFirstMessage(() => {\n  console.log('First message received');\n});\n```\n"
      operationId: onFirstMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventHandler'
      responses:
        '200':
          description: Handler registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventRegistrationResponse'
  /events/onMount:
    post:
      tags:
      - Event Handlers
      summary: Register onMount handler
      description: "Registers a callback for when the app iframe is mounted in the DOM.\n\n**JavaScript Usage:**\n```javascript\nPypestream.onMount(() => {\n  console.log('Iframe mounted');\n});\n```\n"
      operationId: onMount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventHandler'
      responses:
        '200':
          description: Handler registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventRegistrationResponse'
components:
  schemas:
    EventHandler:
      type: object
      required:
      - handler
      properties:
        handler:
          type: string
          description: JavaScript function name or reference
          example: myHandlerFunction
    EventRegistrationResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        eventType:
          type: string
          example: onShow
        message:
          type: string
          example: Event handler registered successfully
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key for accessing Pypestream services (if applicable).

        Note: The JavaScript SDK does not require API keys for client-side usage.

        '
externalDocs:
  description: Full Pypestream Documentation
  url: https://docs.pypestream.com