openapi.yaml

openapi: 3.0.0
info:
  title: DocuThinker API
  description: Comprehensive API documentation for the DocuThinker application.
  version: 1.1.0
  termsOfService: https://docuthinker-fullstack-app.vercel.app/terms-of-service
  contact:
    name: DocuThinker
    url: https://docuthinker-fullstack-app.vercel.app/
    email: hoangson091104@gmail.com
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://docuthinker-ai-app.onrender.com/
    description: Production server
  - url: http://localhost:3000
    description: Local server
paths:
  /register:
    post:
      summary: Register a new user
      operationId: registerUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
              required:
                - email
                - password
      responses:
        201:
          description: User successfully registered
        400:
          description: Invalid input
  /login:
    post:
      summary: Login an existing user
      operationId: loginUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
              required:
                - email
                - password
      responses:
        200:
          description: Login successful
        401:
          description: Unauthorized
  /upload:
    post:
      summary: Upload and summarize a document
      operationId: uploadDocument
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: Optional user ID to save the document to Firestore
                title:
                  type: string
                  description: Document title
                text:
                  type: string
                  description: Document plaintext content (required)
                html:
                  type: string
                  description: Optional display-ready HTML (preserves formatting)
                filePath:
                  type: string
                  description: Path to the original file in storage
                fileType:
                  type: string
                  description: File type (e.g., "pdf", "docx")
              required:
                - title
                - text
      responses:
        200:
          description: Document summarized successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  summary:
                    type: string
                  originalText:
                    type: string
                  originalHtml:
                    type: string
                  fileType:
                    type: string
                  fileUrl:
                    type: string
                    description: Signed short-lived URL to the stored file
        400:
          description: Missing title or text
        404:
          description: User not found (if userId provided)
        500:
          description: Failed to summarize document
  /document-upload-url:
    post:
      summary: Mint a signed upload URL for direct file uploads
      operationId: getDocumentUploadUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: User ID
                fileName:
                  type: string
                  description: Original file name (e.g., "document.pdf")
              required:
                - userId
                - fileName
      responses:
        200:
          description: Signed upload URL created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  path:
                    type: string
                    description: Storage path for the file
                  token:
                    type: string
                    description: Upload token
                  signedUrl:
                    type: string
                    description: One-time signed URL for direct browser upload
        500:
          description: Failed to create upload URL
  /document-file:
    post:
      summary: Store an uploaded document file
      operationId: uploadDocumentFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The document file (PDF, DOCX, etc.)
                userId:
                  type: string
                  description: Optional user ID
              required:
                - file
      responses:
        200:
          description: File stored successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  filePath:
                    type: string
                    description: Storage path of the file
                  fileType:
                    type: string
                    description: Detected file type (e.g., "pdf")
        400:
          description: No file uploaded
        500:
          description: Failed to store file
  /generate-key-ideas:
    post:
      summary: Generate key ideas from a document
      operationId: generateKeyIdeas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documentId:
                  type: string
              required:
                - documentId
      responses:
        200:
          description: Key ideas generated successfully
        404:
          description: Document not found
  /generate-discussion-points:
    post:
      summary: Generate discussion points for a document
      operationId: generateDiscussionPoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documentId:
                  type: string
              required:
                - documentId
      responses:
        200:
          description: Discussion points generated successfully
        404:
          description: Document not found
  /chat:
    post:
      summary: Chat with AI
      operationId: chatWithAI
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                message:
                  type: string
              required:
                - userId
                - message
      responses:
        200:
          description: Chat response from AI
        400:
          description: Invalid input
  /forgot-password:
    post:
      summary: Request password reset
      operationId: forgotPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
              required:
                - email
      responses:
        200:
          description: Password reset email sent
        404:
          description: Email not found
  /verify-email:
    post:
      summary: Verify user email
      operationId: verifyEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
              required:
                - token
      responses:
        200:
          description: Email verified successfully
        400:
          description: Invalid token
  /documents/{userId}:
    get:
      summary: Retrieve all documents for a user
      operationId: getAllDocuments
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Documents retrieved successfully
        404:
          description: User not found
    delete:
      summary: Delete all documents for a user
      operationId: deleteAllDocuments
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: All documents deleted successfully
        404:
          description: User not found
  /documents/{userId}/{docId}:
    get:
      summary: Retrieve a specific document by ID
      operationId: getDocumentById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: docId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Document retrieved successfully
        404:
          description: Document not found
    delete:
      summary: Delete a specific document
      operationId: deleteDocument
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: docId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Document deleted successfully
        404:
          description: Document not found
  /document-details/{userId}/{docId}:
    get:
      summary: Retrieve full document details
      operationId: getDocumentDetails
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: docId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Document details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  title:
                    type: string
                  originalText:
                    type: string
                  originalHtml:
                    type: string
                    description: Display-ready HTML version of the document
                  fileType:
                    type: string
                  fileUrl:
                    type: string
                    description: Signed short-lived URL to the stored file
                  summary:
                    type: string
        404:
          description: Document not found
  /update-email:
    post:
      summary: Update user email
      operationId: updateUserEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                newEmail:
                  type: string
              required:
                - userId
                - newEmail
      responses:
        200:
          description: Email updated successfully
        404:
          description: User not found
  /update-password:
    post:
      summary: Update user password
      operationId: updateUserPassword
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                newPassword:
                  type: string
              required:
                - userId
                - newPassword
      responses:
        200:
          description: Password updated successfully
        404:
          description: User not found
  /days-since-joined/{userId}:
    get:
      summary: Get days since user joined
      operationId: getDaysSinceJoined
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Days since user joined retrieved successfully
        404:
          description: User not found
  /document-count/{userId}:
    get:
      summary: Get document count for a user
      operationId: getDocumentCount
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Document count retrieved successfully
        404:
          description: User not found
  /users/{userId}:
    get:
      summary: Get user email
      operationId: getUserEmail
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: User email retrieved successfully
        404:
          description: User not found
  /update-document-title:
    post:
      summary: Update document title
      operationId: updateDocumentTitle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                docId:
                  type: string
                newTitle:
                  type: string
              required:
                - docId
                - newTitle
      responses:
        200:
          description: Document title updated successfully
        404:
          description: Document not found
  /user-joined-date/{userId}:
    get:
      summary: Get user joined date
      operationId: getUserJoinedDate
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: User joined date retrieved successfully
        404:
          description: User not found
  /update-theme:
    put:
      summary: Update user theme preferences
      operationId: updateTheme
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                theme:
                  type: string
              required:
                - userId
                - theme
      responses:
        200:
          description: Theme updated successfully
        404:
          description: User not found
  /social-media/{userId}:
    get:
      summary: Get user's social media links
      operationId: getSocialMedia
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Social media links retrieved successfully
        404:
          description: User not found
  /update-social-media:
    post:
      summary: Update user's social media links
      operationId: updateSocialMedia
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                socialMedia:
                  type: object
                  additionalProperties:
                    type: string
              required:
                - userId
                - socialMedia
      responses:
        200:
          description: Social media links updated successfully
        404:
          description: User not found
  /sentiment-analysis:
    post:
      summary: Perform sentiment analysis on text
      operationId: sentimentAnalysis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
              required:
                - text
      responses:
        200:
          description: Sentiment analysis completed successfully
        400:
          description: Invalid input
  /actionable-recommendations:
    post:
      summary: Generate actionable recommendations
      operationId: actionableRecommendations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documentId:
                  type: string
              required:
                - documentId
      responses:
        200:
          description: Recommendations generated successfully
        404:
          description: Document not found
  /summary-in-language:
    post:
      summary: Generate a summary in a specified language
      operationId: summaryInLanguage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documentId:
                  type: string
                language:
                  type: string
              required:
                - documentId
                - language
      responses:
        200:
          description: Summary generated successfully
        404:
          description: Document not found
  /bullet-summary:
    post:
      summary: Generate a bullet-point summary
      operationId: bulletSummary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documentId:
                  type: string
              required:
                - documentId
      responses:
        200:
          description: Bullet-point summary generated successfully
        404:
          description: Document not found
  /content-rewriting:
    post:
      summary: Rewrite content for better readability
      operationId: contentRewriting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                documentId:
                  type: string
                style:
                  type: string
              required:
                - documentId
                - style
      responses:
        200:
          description: Content rewritten successfully
        404:
          description: Document not found
  /search-documents/{userId}:
    get:
      summary: Search for documents by a user
      operationId: searchDocuments
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: searchTerm
          in: query
          required: true
          schema:
            type: string
          description: Search term to find in document titles or content
      responses:
        200:
          description: Search results retrieved successfully
        404:
          description: User or documents not found
  /process-audio:
    post:
      summary: Process an audio file
      operationId: processAudioFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                audioFile:
                  type: string
                  format: binary
              required:
                - userId
                - audioFile
      responses:
        200:
          description: Audio processed successfully
        400:
          description: Invalid input
  /refine-summary:
    post:
      summary: Refine a generated summary
      operationId: refineSummary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                summary:
                  type: string
                context:
                  type: string
              required:
                - summary
                - context
      responses:
        200:
          description: Summary refined successfully
        400:
          description: Invalid input
  /graphql:
    post:
      summary: GraphQL API endpoint
      operationId: graphqlQuery
      description: >
        Execute GraphQL queries and mutations. GraphiQL explorer available at
        the same endpoint for introspection and testing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: GraphQL query string
                variables:
                  type: object
                  description: Query variables
              required:
                - query
      responses:
        200:
          description: GraphQL response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                  errors:
                    type: array
                    items:
                      type: object
        400:
          description: Invalid GraphQL query
  /passkey/register/options:
    post:
      summary: Begin passkey registration
      description: Generate WebAuthn registration options (a challenge) for the signed-in user. Returns a flowId that must be echoed back on verify.
      operationId: getPasskeyRegistrationOptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
              required:
                - userId
      responses:
        200:
          description: Registration options generated
        404:
          description: User not found
  /passkey/register/verify:
    post:
      summary: Complete passkey registration
      description: Verify the authenticator attestation and store the new credential.
      operationId: verifyPasskeyRegistration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                flowId:
                  type: string
                name:
                  type: string
                response:
                  type: object
                  description: The RegistrationResponseJSON produced by the browser.
              required:
                - userId
                - flowId
                - response
      responses:
        201:
          description: Passkey registered successfully
        400:
          description: Verification failed or session expired
        409:
          description: Passkey already registered
  /passkey/authenticate/options:
    post:
      summary: Begin passkey authentication
      description: Generate WebAuthn authentication options. Provide an email to scope to that account's credentials, or omit it for a discoverable (usernameless) flow.
      operationId: getPasskeyAuthenticationOptions
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
      responses:
        200:
          description: Authentication options generated
  /passkey/authenticate/verify:
    post:
      summary: Complete passkey authentication
      description: Verify the authenticator assertion and, on success, return a Firebase custom token and userId (the same contract as /login).
      operationId: verifyPasskeyAuthentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                flowId:
                  type: string
                response:
                  type: object
                  description: The AuthenticationResponseJSON produced by the browser.
              required:
                - flowId
                - response
      responses:
        200:
          description: Authentication successful; returns customToken and userId
        401:
          description: Passkey not recognized or verification failed
  /passkeys/{userId}:
    get:
      summary: List a user's passkeys
      operationId: listPasskeys
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Passkeys retrieved successfully
  /passkeys/{userId}/{credentialId}:
    patch:
      summary: Rename a passkey
      operationId: renamePasskey
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
                - name
      responses:
        200:
          description: Passkey renamed
        404:
          description: Passkey not found
    delete:
      summary: Delete a passkey
      operationId: deletePasskey
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: credentialId
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: Passkey deleted
        404:
          description: Passkey not found
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        password:
          type: string
    Document:
      type: object
      properties:
        id:
          type: string
        userId:
          type: string
        title:
          type: string
        summary:
          type: string
        contentPath:
          type: string
          description: Path to the large text/HTML content in storage
        filePath:
          type: string
          description: Path to the original uploaded file
        fileType:
          type: string
          description: File type (e.g., pdf, docx)
        createdAt:
          type: string
          format: date-time
    DocumentSummary:
      type: object
      properties:
        summary:
          type: string
        originalText:
          type: string
        originalHtml:
          type: string
        fileType:
          type: string
        fileUrl:
          type: string
    Sentiment:
      type: object
      properties:
        sentiment:
          type: string
          enum:
            - positive
            - negative
            - neutral
        score:
          type: number
    SocialMedia:
      type: object
      description: Social media profile links
      additionalProperties:
        type: string
    SearchResult:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        summary:
          type: string
    UploadUrl:
      type: object
      properties:
        path:
          type: string
          description: Storage path for the file
        token:
          type: string
          description: Upload token
        signedUrl:
          type: string
          description: One-time signed URL for direct browser upload
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: integer
        details:
          type: string
    Passkey:
      type: object
      description: A registered WebAuthn passkey (public metadata only; the public key is never returned).
      properties:
        id:
          type: string
          description: The credential ID (base64url), used as the document key.
        name:
          type: string
        deviceType:
          type: string
          enum:
            - singleDevice
            - multiDevice
        backedUp:
          type: boolean
          description: Whether the credential is synced/backed up across the user's devices.
        transports:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
          nullable: true