openapi: 3.1.0
info:
  title: Kareet CRM Tools
  description: |
    OpenAPI for ChatGPT Custom GPT **Actions**.

    Agents never paste Anthropic/OpenAI API keys. Auth is a **Kareet workspace API token**
    (Settings → APIs & Webhooks → Create key) or OAuth when you connect Kareet.

    Same tools as the human command menu (score goal, score listing, create lead, upsert listing).
  version: 1.0.0
  contact:
    name: Kareet
    url: https://crm.kareet.com

servers:
  - url: https://crm.kareet.com
    description: Production Kareet CRM

security:
  - bearerAuth: []

paths:
  /s/kareet/score-goal:
    post:
      operationId: scoreGoal
      summary: Score goal progress
      description: |
        Computes progress % and status (ON_TRACK, AT_RISK, WON, MISSED) from target/current.
        Same rules as human command menu **Score goal progress**.
      tags: [Goals]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoalInput'
      responses:
        '200':
          description: Score result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalScoreResult'

  /s/kareet/suggest-goal-next:
    post:
      operationId: suggestGoalNext
      summary: Suggest next step for a goal
      description: One concrete next action for the agent (human can click the same tool).
      tags: [Goals]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoalInput'
      responses:
        '200':
          description: Next step
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalSuggestResult'

  /s/kareet/score-listing-ladder:
    post:
      operationId: scoreListingLadder
      summary: Score UAE listing portal ladder
      description: Sets Completeness/Verified ladder scoring for Bayut/PF-style listings.
      tags: [Listings]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListingLadderInput'
      responses:
        '200':
          description: Ladder score
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /s/kareet/upsert-listing:
    post:
      operationId: upsertListing
      summary: Create or update a listing
      description: Extension / AI capture of a UAE listing (AED, community, beds, raw copy).
      tags: [Listings]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertListingInput'
      responses:
        '200':
          description: Listing upserted
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /s/kareet/create-lead:
    post:
      operationId: createLead
      summary: Create a property lead
      description: Create a UAE RE lead (budget AED, areas, WhatsApp, intent).
      tags: [Leads]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLeadInput'
      responses:
        '200':
          description: Lead created
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /s/kareet/bulk-import-leads:
    post:
      operationId: bulkImportLeads
      summary: Import leads from CSV or rows
      description: |
        Paste spreadsheet CSV (header row) or JSON rows. Maps common headers
        (Name, Phone, Budget, Areas). Max 200 rows default.
      tags: [Import]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                csv:
                  type: string
                rows:
                  type: array
                  items:
                    type: object
                maxRows:
                  type: integer
      responses:
        '200':
          description: Import summary
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /s/kareet/bulk-import-listings:
    post:
      operationId: bulkImportListings
      summary: Import listings from CSV or rows
      tags: [Import]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                csv:
                  type: string
                rows:
                  type: array
                  items:
                    type: object
                maxRows:
                  type: integer
      responses:
        '200':
          description: Import summary
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /s/kareet/ingest-portal-lead:
    post:
      operationId: ingestPortalLead
      summary: Create lead from portal email parse
      description: Used by email-ingest service (Bayut/PF alerts without official API).
      tags: [Leads]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        '200':
          description: Lead created
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true

  /healthz:
    get:
      operationId: healthz
      summary: Health check
      security: []
      tags: [System]
      responses:
        '200':
          description: OK

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Kareet workspace API key from Settings → APIs & Webhooks.
        Header: `Authorization: Bearer <token>`

  schemas:
    GoalInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - DEALS_CLOSED
            - LISTINGS_LIVE
            - LEADS_CONTACTED
            - VIEWINGS_BOOKED
            - COMMISSION_AED
            - RESPONSE_SLA
            - CUSTOM
        status:
          type: string
        targetValue:
          type: string
          description: Numeric target e.g. "5"
        currentValue:
          type: string
          description: Progress so far e.g. "2"
        unit:
          type: string
          description: deals, listings, leads, AED…
        dueDate:
          type: string
          format: date-time
        name:
          type: string

    GoalScoreResult:
      type: object
      properties:
        progressPct:
          type: string
        status:
          type: string
        missing:
          type: array
          items:
            type: string
        summary:
          type: string

    GoalSuggestResult:
      type: object
      properties:
        nextStep:
          type: string
        rationale:
          type: string

    ListingLadderInput:
      type: object
      additionalProperties: true
      description: Listing fields used by the UAE portal ladder scorer

    UpsertListingInput:
      type: object
      properties:
        name:
          type: string
        community:
          type: string
        beds:
          type: string
        offering:
          type: string
          enum: [SALE, RENT]
        priceAed:
          type: string
        sourcePortal:
          type: string
        sourceUrl:
          type: string
        rawCopy:
          type: string
      required:
        - name

    CreateLeadInput:
      type: object
      properties:
        name:
          type: string
        phone:
          type: string
        intent:
          type: string
          enum: [BUY, RENT, SELL, UNKNOWN]
        budgetAed:
          type: string
        areas:
          type: string
        source:
          type: string
        nextAction:
          type: string
      required:
        - name
