arazzo: 1.0.1
info:
  title: Figma Browse Project File Comments
  summary: List files in a project, open the first file, and read its comments.
  description: >-
    A project review flow that walks from a project down to the conversation
    happening inside one of its files. The workflow lists the files in a
    project, opens the first returned file to confirm access and capture its
    metadata, and then reads the comment thread left on that file. Every step
    spells out its request inline so the flow can be read and executed without
    opening the underlying OpenAPI description. Authentication is carried by
    the Figma personal access token bearer credential declared on each
    operation's security requirement.
  version: 1.0.0
sourceDescriptions:
- name: figmaRestApi
  url: ../openapi/figma-rest-api-openapi.yml
  type: openapi
workflows:
- workflowId: browse-project-file-comments
  summary: Drill from a project into one of its files and read that file's comments.
  description: >-
    Lists project files, selects the first file, retrieves it, and reads the
    comments left on it.
  inputs:
    type: object
    required:
    - projectId
    properties:
      projectId:
        type: string
        description: The ID of the project to list files from.
      asMarkdown:
        type: boolean
        description: Return comment message content as Markdown instead of plain text.
  steps:
  - stepId: listProjectFiles
    description: >-
      List the files contained in the project so a target file can be selected.
    operationId: getProjectFiles
    parameters:
    - name: project_id
      in: path
      value: $inputs.projectId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      projectName: $response.body#/name
      firstFileKey: $response.body#/files/0/key
  - stepId: getFile
    description: >-
      Retrieve the first file from the project to confirm access and capture
      its current metadata.
    operationId: getFile
    parameters:
    - name: file_key
      in: path
      value: $steps.listProjectFiles.outputs.firstFileKey
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      fileName: $response.body#/name
      lastModified: $response.body#/lastModified
  - stepId: getComments
    description: >-
      Read the comment thread left on the selected file, most recent first.
    operationId: getComments
    parameters:
    - name: file_key
      in: path
      value: $steps.listProjectFiles.outputs.firstFileKey
    - name: as_md
      in: query
      value: $inputs.asMarkdown
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      comments: $response.body#/comments
  outputs:
    projectName: $steps.listProjectFiles.outputs.projectName
    fileName: $steps.getFile.outputs.fileName
    comments: $steps.getComments.outputs.comments