Figma Report Library Usage

arazzo: 1.0.1
info:
  title: Figma Report Library Usage
  summary: Open a library file, then pull its component or style usage analytics.
  description: >-
    A library-health flow that quantifies how widely a published library is
    adopted. The workflow opens the library file to confirm access and capture
    its metadata, then retrieves the library analytics usage data grouped by
    component or by file so adoption across teams and files can be reported.
    The file lookup comes from the Figma REST description while the analytics
    query comes from the dedicated analytics description, so both are
    referenced as distinct source descriptions. 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
  x-realizes-capability-ids:
  - BC-4200.30
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-4200.30
      capability_name: Software Design Management
      spec: figma-files-api-openapi.yml
      confidence: 0.7
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: filesApi
  url: ../openapi/figma-files-api-openapi.yml
  type: openapi
- name: libraryAnalyticsApi
  url: ../openapi/figma-library-analytics-api-openapi.yml
  type: openapi
workflows:
- workflowId: report-library-usage
  summary: Open a library file and report its usage analytics.
  description: >-
    Retrieves a library file and then pulls its usage analytics grouped by the
    requested dimension.
  inputs:
    type: object
    required:
    - fileKey
    - groupBy
    properties:
      fileKey:
        type: string
        description: The file key of the published library to report on.
      groupBy:
        type: string
        description: The dimension to group usage data by (component or file).
      order:
        type: string
        description: Sort order of the returned rows (asc or desc).
  steps:
  - stepId: getFile
    description: >-
      Open the library file to confirm it is accessible before pulling its
      usage analytics.
    operationId: getFile
    parameters:
    - name: file_key
      in: path
      value: $inputs.fileKey
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      fileName: $response.body#/name
  - stepId: getUsage
    description: >-
      Retrieve the library analytics usage data grouped by the requested
      dimension.
    operationId: getLibraryAnalyticsUsages
    parameters:
    - name: file_key
      in: path
      value: $inputs.fileKey
    - name: group_by
      in: query
      value: $inputs.groupBy
    - name: order
      in: query
      value: $inputs.order
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      components: $response.body#/components
      files: $response.body#/files
      nextPage: $response.body#/nextPage
      cursor: $response.body#/cursor
  outputs:
    fileName: $steps.getFile.outputs.fileName
    components: $steps.getUsage.outputs.components
    files: $steps.getUsage.outputs.files