openapi: 3.0.3
info:
  title: Socialfy LinkedIn Prospector API
  version: "0.1.0"
  description: |
    Contrato API-first para campanha simples do LinkedIn Prospector.
    Preview e search-preview são dry-run. Envio real exige canary e aprovação explícita.
servers:
  - url: https://linkedin-api.socialfy.me
    description: Produção
security:
  - clientSecret: []
tags:
  - name: Simple Prospect
    description: Fluxo self-service de criação de campanha
  - name: Readiness
    description: Gates de segurança antes de ativação
components:
  securitySchemes:
    clientSecret:
      type: apiKey
      in: header
      name: X-Client-Secret
  schemas:
    SimpleProspectInput:
      type: object
      required: [location_id, who, where, signal, offer]
      properties:
        location_id: { type: string }
        who: { type: string, example: donos de agência }
        where: { type: string, example: Brasil }
        signal: { type: string, example: usam GoHighLevel }
        offer: { type: string, example: uma operação de prospecção pelo LinkedIn }
    ErrorResponse:
      type: object
      properties:
        ok: { type: boolean, example: false }
        code:
          type: string
          enum: [query_too_large, provider_rejected_query, no_client_config, unipile_session_disconnected, no_qualified_leads, lead_list_empty, duplicate_reused, live_send_blocked, cap_exhausted]
        user_message: { type: string }
        next_action: { type: string }
paths:
  /ui/prospect-simple/preview:
    post:
      tags: [Simple Prospect]
      summary: Gera preview de intenção, copy e search plan
      description: Não cria campanha, não cria lista e não envia outreach.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SimpleProspectInput' }
      responses:
        '200':
          description: Preview gerado
  /ui/prospect-simple/search-preview:
    post:
      tags: [Simple Prospect]
      summary: Testa busca LinkedIn/Unipile em dry-run
      description: Retorna leads de preview sem criar enrollment ou enviar ações externas.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SimpleProspectInput' }
      responses:
        '200': { description: Busca válida }
        '422': { description: Query inválida ou sem leads elegíveis }
  /ui/prospect-simple/create-campaign:
    post:
      tags: [Simple Prospect]
      summary: Cria campanha draft
      description: Cria campanha/lista/cadência em draft; não ativa live.
      responses:
        '200': { description: Campanha draft criada }
  /ui/prospect-simple/activate-canary:
    post:
      tags: [Simple Prospect]
      summary: Ativa canary seguro
      description: Endpoint com efeito operacional; exige readiness e aprovação explícita.
      responses:
        '200': { description: Canary criado ou enviado para revisão }
        '403': { description: Live send bloqueado }
  /ui/campaigns/{campaign_id}/readiness:
    get:
      tags: [Readiness]
      summary: Lê gates de prontidão da campanha
      parameters:
        - in: path
          name: campaign_id
          required: true
          schema: { type: string }
      responses:
        '200': { description: Readiness da campanha }