API Evangelist enhancements for Hustle Public API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for Hustle Public API
  version: 1.0.0
extends: openapi/_original/hustle-openapi-original.json
actions:
- target: $.info
  update:
    x-apievangelist-rating: 3
    x-apievangelist-notes: >-
      OAuth2 client-credentials, cursor pagination, HMAC-signed webhooks, and a
      shared error envelope are well modeled. Gaps: no components.securitySchemes
      block (auth is only in prose), no operationIds, and errors are custom JSON
      rather than RFC 9457 problem+json.
- target: $
  update:
    x-apievangelist-recommendations:
    - Declare components.securitySchemes with an oauth2 clientCredentials flow and apply it via a top-level security[] requirement.
    - Add unique operationIds to every operation to make the spec generation- and agent-friendly.
    - Adopt application/problem+json (RFC 9457) for the ErrorResponse envelope.
    - Publish an enumerated scope catalog for the returned token `scope`.
    - Declare a 429 response and RateLimit-*/Retry-After response headers so the documented 25 req/s ceiling is machine-readable.
    - Enumerate MessageStatus.status terminal values and MessageStatus.errorCode codes instead of deferring to unpublished "messaging webhooks docs".
    - Publish a Thread resource (or drop threadId), which is currently emitted but not resolvable through the Public API.
    - Serve an RFC 8414 /.well-known/oauth-authorization-server document so the token endpoint is discoverable without reading prose docs.
- target: $.info
  update:
    x-agent-ready:
      idempotency: 'POST /leads upsert by (organizationId, phoneNumber)'
      pagination: cursor/limit -> items/cursor/hasMore
      webhooks: 'consentUpdate-v1, messageStatus-v1 (HMAC signed)'
      rate_limits: '25 req/s per account; no RateLimit-* headers, no 429 declared'
- target: $.paths['/messages/{id}'].get
  update:
    x-apievangelist-notes: >-
      Read-only delivery-status lookup. `status` is deliberately an open string
      (the carrier terminal set evolves) and `errorCode` is only present on
      failure — agents must treat the value space as unbounded and log
      unrecognized values rather than branching on a closed enum.