Meta Refresh Audience Cohort

arazzo: 1.0.1
info:
  title: Meta Refresh Audience Cohort
  summary: Resolve the caller, add a new cohort to an audience, then remove stale members.
  description: >-
    Refreshes a custom audience cohort in one pass. It resolves the caller via
    /me for an audit trail, adds the new cohort's hashed payload to the custom
    audience, and then removes stale members from the same audience. The remove
    edge is declared without a request body in the spec, so stale members are
    dissociated by audience id. Every step inlines its request so the flow can
    be read and executed without opening the underlying OpenAPI description.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-400.60
  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-400.60
      capability_name: Digital Marketing Management
      spec: meta-custom-audiences-api-openapi.yml
      confidence: 0.75
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: customAudiencesApi
  url: ../openapi/meta-custom-audiences-api-openapi.yml
  type: openapi
- name: usersApi
  url: ../openapi/meta-users-api-openapi.yml
  type: openapi
workflows:
- workflowId: refresh-audience-cohort
  summary: Resolve the caller, add a new cohort, then remove stale audience members.
  description: >-
    Reads /me for context, adds the supplied hashed cohort payload to the custom
    audience, then removes stale members from the same audience.
  inputs:
    type: object
    required:
    - accessToken
    - customAudienceId
    - addPayload
    properties:
      accessToken:
        type: string
        description: A Meta Graph API user access token with ads permissions.
      customAudienceId:
        type: string
        description: The custom audience to refresh.
      addPayload:
        type: object
        description: Hashed payload for the new cohort to add (e.g. EMAIL_SHA256 data).
  steps:
  - stepId: resolveCaller
    description: >-
      Resolve the authenticated caller's id for an audit trail.
    operationId: getMe
    parameters:
    - name: access_token
      in: query
      value: $inputs.accessToken
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      callerId: $response.body#/id
  - stepId: addCohort
    description: >-
      Add the new cohort's hashed payload to the custom audience.
    operationId: addUsersToCustomAudience
    parameters:
    - name: custom-audience-id
      in: path
      value: $inputs.customAudienceId
    - name: access_token
      in: query
      value: $inputs.accessToken
    requestBody:
      contentType: application/json
      payload:
        payload: $inputs.addPayload
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      addSucceeded: $response.body#/success
  - stepId: removeStale
    description: >-
      Remove stale members from the same custom audience. The remove edge is
      declared without a request body in the spec.
    operationId: removeUsersFromCustomAudience
    parameters:
    - name: custom-audience-id
      in: path
      value: $inputs.customAudienceId
    - name: access_token
      in: query
      value: $inputs.accessToken
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      removed: $response.body#/success
  outputs:
    callerId: $steps.resolveCaller.outputs.callerId
    addSucceeded: $steps.addCohort.outputs.addSucceeded
    removed: $steps.removeStale.outputs.removed