openapi: 3.0.3
info:
  title: Repzo API - Bulk Export
  version: 1.0.0
  description: |
    Exports large datasets to **Excel** or **Parquet**. Starting an export
    (`POST /bulk-export`) creates a job for one of ~50 supported entity types
    (`clients`, `products`, `contracts`, `reps`, ...) selected via the `type`
    query parameter; the job runs the aggregation, writes the file to media
    storage, and records a `status` and a download `link`. `GET /bulk-export`
    lists the export jobs (see also `bulk-export-report`).

    **Who calls it.** Back-office admins — the `creator` audit stamp is always
    an admin, set server-side from the session token.

    **Multi-tenancy & lifecycle.** Jobs are scoped by `company_namespace[]`
    (injected from session — never sent in the body). A job moves through
    `processing` then `success` / `fail`; on success, `link` (and the `media`
    storage id) point at the generated file.

    **Unsupported operations.** Only find (list jobs) and create (start a job)
    are available. `GET /bulk-export/{id}`, `update`, `patch`, and `remove` are
    rejected with `400`.
servers:
  - url: https://sv.api.repzo.me
security:
  - ApiKeyAuth: []
  - JwtAuth: []
paths:
  /bulk-export:
    get:
      summary: List bulk-export jobs
      operationId: findBulkExports
      parameters:
        - in: query
          name: _id
          description: Filter by job `_id`. Pass once or as `?_id[]=...` for multiple.
          schema:
            oneOf:
              - type: string
              - type: array
                items: { type: string }
        - in: query
          name: type
          description: Filter by exported entity type.
          schema:
            $ref: "#/components/schemas/BulkExportType"
        - in: query
          name: status
          description: Filter by job status.
          schema:
            type: string
            enum: [processing, success, fail]
        - in: query
          name: export_type
          description: Filter by output format.
          schema:
            type: string
            enum: [excel, parquet]
        - in: query
          name: export
          description: When truthy, schedule the export as an emailed job instead of returning it inline.
          schema: { type: boolean }
        - in: query
          name: from_updatedAt
          description: Cursor — jobs updated on or after this Unix timestamp (ms).
          schema: { type: number }
        - in: query
          name: to_updatedAt
          description: Cursor — jobs updated on or before this Unix timestamp (ms).
          schema: { type: number }
        - in: query
          name: per_page
          schema: { type: integer, minimum: 1, maximum: 50000 }
          example: 20
        - in: query
          name: page
          schema: { type: integer, minimum: 1 }
          example: 1
      responses:
        "200":
          description: A paginated list of export jobs.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkExportFindResult"
    post:
      summary: Start a bulk export
      operationId: createBulkExport
      parameters:
        - in: query
          name: type
          required: true
          description: Entity type to export. Sent as a query parameter, not in the body.
          schema:
            $ref: "#/components/schemas/BulkExportType"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkExportCreateBody"
      responses:
        "201":
          description: The created export job — `status` reflects progress and `link` is populated when the file is ready.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BulkExportSchema"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: |
        Server-issued API key. Also accepted via the `x-api-key` header or the
        `?apiKey=` query parameter as fallbacks.
    JwtAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Raw JWT in the `Authorization` header — **no `Bearer ` prefix**. Obtained
        from `POST /authenticate` (admin login).
  schemas:
    BulkExportType:
      type: string
      description: One of the supported export entity types.
      enum:
        - clients
        - products
        - variants
        - categories
        - subCategories
        - availabilityMsl
        - availabilityMslWithProducts
        - reps
        - mslWithVariants
        - jobCategories
        - jobs
        - tags
        - routes
        - routesWithClients
        - plans
        - planWithRules
        - targetRulesWithClients
        - rulesWithRoutes
        - targetRulesWithReps
        - adjustAccount
        - rules
        - warehouses
        - productGroups
        - priceListItems
        - measureunit
        - measureunitFamily
        - lineTarget
        - clientLineClassification
        - retailExecutionPresets
        - promotions
        - customListItems
        - assets
        - assetUnits
        - speciality
        - clientLocation
        - reminders
        - admins
        - companyGroup
        - company
        - variantBatch
        - banksList
        - clientUblInfo
        - supplier
        - contractInstallment
        - targetRule
        - contracts
        - assetPartTypes
        - assetParts
        - clientUblInfo_JO
        - clientUblInfo_SA
        - nameSpaceFreshnessWindowCodes
    BulkExportCreateBody:
      type: object
      description: |
        Export options. `type` is sent as a query parameter (not in the body).
        The `creator` audit stamp and `company_namespace` are normally injected
        from session and can be omitted — both are optional here for
        integration / cross-namespace callers.
      properties:
        export_type:
          type: string
          enum: [excel, parquet]
          default: excel
        columns:
          type: object
          additionalProperties: true
          description: Map of column paths to include / label in the generated file.
        name:
          type: string
          description: Optional label for the export job.
        creator:
          $ref: "#/components/schemas/BulkExportCreator"
        company_namespace:
          type: array
          items: { type: string }
          description: Tenant key — normally injected from session; optional, for cross-namespace callers.
    BulkExportCreator:
      type: object
      description: Audit stamp of the admin who started the job. Set server-side from the session token — never sent by the client.
      properties:
        _id: { type: string }
        type: { type: string, enum: [admin] }
        name: { type: string }
        admin: { type: string }
    BulkExportSchema:
      type: object
      description: A bulk-export job document as stored.
      properties:
        _id: { type: string }
        creator:
          $ref: "#/components/schemas/BulkExportCreator"
        type:
          $ref: "#/components/schemas/BulkExportType"
        status:
          type: string
          enum: [processing, success, fail]
        messages:
          type: array
          items: { type: object }
        _errors:
          type: array
          items: { type: object }
        start_time: { type: integer, format: int64 }
        end_time: { type: integer, format: int64 }
        bucket_name: { type: string }
        region: { type: string }
        key: { type: string }
        link: { type: string, description: Download URL of the generated file. }
        media:
          type: array
          items: { type: string }
          description: "Media-storage `_id`(s) of the generated file (ref `media-storage`)."
        teams:
          type: array
          items: { type: string }
        export_type:
          type: string
          enum: [excel, parquet]
        row_count: { type: number }
        company_namespace:
          type: array
          items: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    BulkExportFindResult:
      type: object
      description: Paginated list of export jobs.
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/BulkExportSchema"
        total_result: { type: number }
        current_count: { type: number }
        total_pages: { type: number }
        current_page: { type: number }
        per_page: { type: number }
        first_page_url: { type: string }
        last_page_url: { type: string }
        next_page_url: { type: string, nullable: true }
        prev_page_url: { type: string, nullable: true }
        path: { type: string }