openapi: 3.0.0
info:
  title: Workorder Portal Link API
  description: API for managing workorder portal links
  version: 1.0.0
servers:
  - url: https://api.repzo.me/v1
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Workorder Portal Link
    description: Workorder portal link management operations
paths:
  /workorder-portal-link:
    get:
      tags:
        - Workorder Portal Link
      summary: Get all workorder portal links
      description: Retrieve a list of all workorder portal links with optional filtering and pagination
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: sort
          in: query
          description: Sort field
          required: false
          schema:
            type: string
        - name: company_namespace
          in: query
          description: Company namespace for filtering
          required: false
          schema:
            type: array
            items:
              type: string
        - name: workorder
          in: query
          description: Filter by workorder ID
          required: false
          schema:
            type: string
        - name: is_active
          in: query
          description: Filter by active status
          required: false
          schema:
            type: boolean
        - name: link_type
          in: query
          description: Filter by link type
          required: false
          schema:
            type: string
            enum: ["public", "private", "secure"]
        - name: _id
          in: query
          description: Filter by ID
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/WorkorderPortalLink"
                  paging:
                    $ref: "#/components/schemas/PagingInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags:
        - Workorder Portal Link
      summary: Create a new workorder portal link
      description: Create a new workorder portal link
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkorderPortalLinkRequest"
      responses:
        "201":
          description: Workorder portal link created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/WorkorderPortalLink"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /workorder-portal-link/{id}:
    get:
      tags:
        - Workorder Portal Link
      summary: Get workorder portal link by ID
      description: Retrieve a specific workorder portal link by its ID
      parameters:
        - name: id
          in: path
          required: true
          description: Workorder portal link ID
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/WorkorderPortalLink"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    patch:
      tags:
        - Workorder Portal Link
      summary: Update workorder portal link
      description: Update an existing workorder portal link
      parameters:
        - name: id
          in: path
          required: true
          description: Workorder portal link ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkorderPortalLinkRequest"
      responses:
        "200":
          description: Workorder portal link updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/WorkorderPortalLink"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
        - Workorder Portal Link
      summary: Delete workorder portal link
      description: Delete a workorder portal link by ID
      parameters:
        - name: id
          in: path
          required: true
          description: Workorder portal link ID
          schema:
            type: string
      responses:
        "200":
          description: Workorder portal link deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /workorder-portal-link/{id}/regenerate:
    post:
      tags:
        - Workorder Portal Link
      summary: Regenerate portal link
      description: Regenerate the portal link URL and access token
      parameters:
        - name: id
          in: path
          required: true
          description: Workorder portal link ID
          schema:
            type: string
      responses:
        "200":
          description: Portal link regenerated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/WorkorderPortalLink"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /workorder-portal-link/{id}/activate:
    post:
      tags:
        - Workorder Portal Link
      summary: Activate portal link
      description: Activate a workorder portal link
      parameters:
        - name: id
          in: path
          required: true
          description: Workorder portal link ID
          schema:
            type: string
      responses:
        "200":
          description: Portal link activated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/WorkorderPortalLink"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /workorder-portal-link/{id}/deactivate:
    post:
      tags:
        - Workorder Portal Link
      summary: Deactivate portal link
      description: Deactivate a workorder portal link
      parameters:
        - name: id
          in: path
          required: true
          description: Workorder portal link ID
          schema:
            type: string
      responses:
        "200":
          description: Portal link deactivated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/WorkorderPortalLink"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: "Use format: Bearer {api_key}"
  schemas:
    WorkorderPortalLink:
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier
          example: "507f1f77bcf86cd799439011"
        workorder:
          type: string
          description: Workorder ID reference
          example: "507f1f77bcf86cd799439012"
        link_token:
          type: string
          description: Unique token for the portal link
          example: "wpl_abc123def456"
        full_url:
          type: string
          description: Complete portal link URL
          example: "https://portal.repzo.me/workorder/wpl_abc123def456"
        link_type:
          type: string
          description: Type of portal link
          enum: ["public", "private", "secure"]
          example: "private"
        permissions:
          type: object
          properties:
            can_view_details:
              type: boolean
              description: Can view workorder details
              default: true
            can_add_comments:
              type: boolean
              description: Can add comments
              default: true
            can_upload_files:
              type: boolean
              description: Can upload files
              default: false
            can_view_history:
              type: boolean
              description: Can view workorder history
              default: true
            can_approve_reject:
              type: boolean
              description: Can approve or reject workorder
              default: false
        access_restrictions:
          type: object
          properties:
            allowed_ips:
              type: array
              items:
                type: string
              description: Allowed IP addresses (if restricted)
            max_uses:
              type: integer
              description: Maximum number of uses
            password_protected:
              type: boolean
              description: Whether password protection is enabled
              default: false
            require_email_verification:
              type: boolean
              description: Whether email verification is required
              default: false
        expiry_date:
          type: string
          format: date-time
          description: When the portal link expires
        is_active:
          type: boolean
          description: Whether the portal link is active
          example: true
        usage_stats:
          type: object
          properties:
            total_views:
              type: integer
              description: Total number of views
              example: 15
            unique_visitors:
              type: integer
              description: Number of unique visitors
              example: 3
            last_accessed:
              type: string
              format: date-time
              description: Last access timestamp
            access_log:
              type: array
              items:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                  ip_address:
                    type: string
                  user_agent:
                    type: string
                  action:
                    type: string
              description: Access log entries
        notification_settings:
          type: object
          properties:
            notify_on_access:
              type: boolean
              description: Send notification when link is accessed
              default: false
            notify_on_comment:
              type: boolean
              description: Send notification when comment is added
              default: true
            notify_on_file_upload:
              type: boolean
              description: Send notification when file is uploaded
              default: true
            notification_recipients:
              type: array
              items:
                type: string
              description: Email addresses to notify
        custom_branding:
          type: object
          properties:
            logo_url:
              type: string
              description: Custom logo URL
            brand_color:
              type: string
              description: Brand color hex code
              example: "#FF5733"
            custom_domain:
              type: string
              description: Custom domain for the portal link
            footer_text:
              type: string
              description: Custom footer text
        metadata:
          type: object
          properties:
            created_by:
              type: string
              description: User who created the link
            purpose:
              type: string
              description: Purpose of the portal link
            tags:
              type: array
              items:
                type: string
              description: Tags for organization
        company_namespace:
          type: array
          items:
            type: string
          description: Company namespace
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        modifiedAt:
          type: string
          format: date-time
          description: Last modification timestamp
        SVClient:
          type: integer
          description: Client version
        __v:
          type: integer
          description: Document version
      required:
        - workorder
        - link_token
        - link_type
    CreateWorkorderPortalLinkRequest:
      type: object
      properties:
        workorder:
          type: string
          description: Workorder ID reference
          example: "507f1f77bcf86cd799439012"
        link_type:
          type: string
          description: Type of portal link
          enum: ["public", "private", "secure"]
          default: "private"
        permissions:
          type: object
          properties:
            can_view_details:
              type: boolean
              default: true
            can_add_comments:
              type: boolean
              default: true
            can_upload_files:
              type: boolean
              default: false
            can_view_history:
              type: boolean
              default: true
            can_approve_reject:
              type: boolean
              default: false
        access_restrictions:
          type: object
          properties:
            allowed_ips:
              type: array
              items:
                type: string
            max_uses:
              type: integer
            password_protected:
              type: boolean
              default: false
            require_email_verification:
              type: boolean
              default: false
        expiry_date:
          type: string
          format: date-time
          description: When the portal link expires
        notification_settings:
          type: object
          properties:
            notify_on_access:
              type: boolean
              default: false
            notify_on_comment:
              type: boolean
              default: true
            notify_on_file_upload:
              type: boolean
              default: true
            notification_recipients:
              type: array
              items:
                type: string
        custom_branding:
          type: object
          properties:
            logo_url:
              type: string
            brand_color:
              type: string
            custom_domain:
              type: string
            footer_text:
              type: string
        metadata:
          type: object
          properties:
            purpose:
              type: string
            tags:
              type: array
              items:
                type: string
        is_active:
          type: boolean
          description: Whether the portal link is active
          default: true
        company_namespace:
          type: array
          items:
            type: string
          description: Company namespace
      required:
        - workorder
    UpdateWorkorderPortalLinkRequest:
      type: object
      properties:
        link_type:
          type: string
          description: Type of portal link
          enum: ["public", "private", "secure"]
        permissions:
          type: object
          properties:
            can_view_details:
              type: boolean
            can_add_comments:
              type: boolean
            can_upload_files:
              type: boolean
            can_view_history:
              type: boolean
            can_approve_reject:
              type: boolean
        access_restrictions:
          type: object
          properties:
            allowed_ips:
              type: array
              items:
                type: string
            max_uses:
              type: integer
            password_protected:
              type: boolean
            require_email_verification:
              type: boolean
        expiry_date:
          type: string
          format: date-time
          description: When the portal link expires
        is_active:
          type: boolean
          description: Whether the portal link is active
        notification_settings:
          type: object
          properties:
            notify_on_access:
              type: boolean
            notify_on_comment:
              type: boolean
            notify_on_file_upload:
              type: boolean
            notification_recipients:
              type: array
              items:
                type: string
        custom_branding:
          type: object
          properties:
            logo_url:
              type: string
            brand_color:
              type: string
            custom_domain:
              type: string
            footer_text:
              type: string
        metadata:
          type: object
          properties:
            purpose:
              type: string
            tags:
              type: array
              items:
                type: string
        company_namespace:
          type: array
          items:
            type: string
          description: Company namespace
    PagingInfo:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
        page:
          type: integer
          description: Current page number
        per_page:
          type: integer
          description: Items per page
        pages:
          type: integer
          description: Total number of pages
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Invalid request parameters"
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Authentication required"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Insufficient permissions"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Resource not found"
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Validation failed"
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Internal server error"