Publish a KW Worldwide listing

arazzo: 1.0.1
info:
  title: Publish a KW Worldwide listing
  summary: Resolve the KW controlled vocabularies, create a KWLS listing, then read it back to confirm it indexed.
  description: >-
    A native Arazzo workflow over the only anonymously published Keller
    Williams contract. Every operationId below exists verbatim in
    openapi/keller-williams-listings-search-openapi.json. All three steps
    require an approved DevHub application: an `api-key` header plus an
    `Authorization` header carrying Basic base64(API_KEY:API_SECRET).
    Run it against the sandbox server (https://sandbox.partners.api.kw.com/v2)
    first — the spec declares both servers.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-4960.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-4960.30
      capability_name: Listing Data & MLS Management
      spec: keller-williams-search-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: searchApi
  url: ../openapi/keller-williams-search-api-openapi.yml
  type: openapi
workflows:
- workflowId: publish-kww-listing
  summary: Look up the vocabularies, create a listing, and verify it.
  description: >-
    KW rejects a create whose numeric ids do not match its controlled
    vocabulary, so the lookup table is resolved first. There is no
    idempotency key on the create — the final read-back is how you
    confirm exactly one listing exists.
  inputs:
    type: object
    required:
    - authorization
    - apiKey
    - mlsId
    - mlsNumber
    - sourceSystemName
    - currentListPrice
    - listStatusId
    - listCategory
    - listCategoryId
    - propType
    - propTypeId
    - propSubtype
    - propSubtypeId
    properties:
      authorization:
        type: string
        description: "Basic base64Encode(API_KEY:API_SECRET)"
      apiKey:
        type: string
        description: The DevHub application API key, sent as the api-key header.
      mlsId:
        type: string
      mlsNumber:
        type: string
      sourceSystemName:
        type: string
      currentListPrice:
        type: number
      listStatusId:
        type: integer
      listCategory:
        type: string
      listCategoryId:
        type: integer
      propType:
        type: string
      propTypeId:
        type: integer
      propSubtype:
        type: string
      propSubtypeId:
        type: integer
      listDesc:
        type: string
        description: "Avoid special characters such as % — the provider documents that they break the listing."
  steps:
  - stepId: resolve-vocabularies
    description: >-
      Fetch the controlled vocabularies so every numeric id on the
      create body can be validated against KW's own tables.
    operationId: listings-read-by-table
    parameters:
    - name: Authorization
      in: header
      value: $inputs.authorization
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      lookupHits: $response.body#/hits/hits

  - stepId: create-listing
    description: Create the KWLS listing with the eleven required fields.
    operationId: listings-create
    dependsOn:
    - resolve-vocabularies
    parameters:
    - name: Authorization
      in: header
      value: $inputs.authorization
    requestBody:
      contentType: application/json
      payload:
        mls_id: $inputs.mlsId
        mls_number: $inputs.mlsNumber
        source_system_name: $inputs.sourceSystemName
        current_list_price: $inputs.currentListPrice
        list_status_id: $inputs.listStatusId
        list_category: $inputs.listCategory
        list_category_id: $inputs.listCategoryId
        prop_type: $inputs.propType
        prop_type_id: $inputs.propTypeId
        prop_subtype: $inputs.propSubtype
        prop_subtype_id: $inputs.propSubtypeId
        list_desc: $inputs.listDesc
    successCriteria:
    - condition: $statusCode == 201
    - condition: $response.body#/success == true
    outputs:
      listUuid: $response.body#/data/list_uuid
      listKey: $response.body#/data/list_key
      kwlsStatus: $response.body#/data/kwls_status

  - stepId: verify-listing
    description: >-
      Read the listing back by its KW composite key. Indexing is
      asynchronous, so allow a few seconds before this step.
    operationId: listings-read
    dependsOn:
    - create-listing
    parameters:
    - name: Authorization
      in: header
      value: $inputs.authorization
    - name: limit
      in: query
      value: 1
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      total: $response.body#/hits/total/value
      firstHit: $response.body#/hits/hits

  outputs:
    listUuid: $steps.create-listing.outputs.listUuid
    listKey: $steps.create-listing.outputs.listKey
    kwlsStatus: $steps.create-listing.outputs.kwlsStatus
    verifiedTotal: $steps.verify-listing.outputs.total