{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/pipeshub/json-schema/pipeshub-job-status-schema.json",
  "title": "JobStatus",
  "description": "Complete status information for a crawling job",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/pipeshub-crawling-jobs-api-openapi.yml#/components/schemas/JobStatus",
  "type": "object",
  "properties": {
    "id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Unique job ID assigned by BullMQ"
    },
    "name": {
      "type": "string",
      "description": "Job name (format crawl-{connector}-{connectorId})"
    },
    "data": {
      "$ref": "#/$defs/CrawlingJobData"
    },
    "progress": {
      "description": "Job progress information (can be number 0-100 or object with percentage/current/total)",
      "oneOf": [
        {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Progress percentage (0-100)"
        },
        {
          "type": "object",
          "description": "Detailed progress object",
          "properties": {
            "percentage": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "current": {
              "type": "integer",
              "description": "Current items processed"
            },
            "total": {
              "type": "integer",
              "description": "Total items to process"
            }
          }
        }
      ]
    },
    "delay": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Delay in milliseconds before job starts (for delayed/scheduled jobs)"
    },
    "timestamp": {
      "type": "integer",
      "description": "Unix timestamp when job was created (milliseconds)"
    },
    "attemptsMade": {
      "type": "integer",
      "description": "Number of execution attempts made (increments on retry)"
    },
    "finishedOn": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Unix timestamp when job completed (null if not finished)"
    },
    "processedOn": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Unix timestamp when job started processing (null if not started)"
    },
    "failedReason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Error message if job failed"
    },
    "state": {
      "type": "string",
      "enum": [
        "waiting",
        "active",
        "completed",
        "failed",
        "delayed",
        "paused",
        "stuck"
      ],
      "description": "Current state of the job in the queue:<br>\n<ul>\n<li><b>waiting</b>: Queued and waiting to be processed</li>\n<li><b>active</b>: Currently being processed by a worker</li>\n<li><b>completed</b>: Successfully finished</li>\n<li><b>failed</b>: Failed after all retry attempts</li>\n<li><b>delayed</b>: Scheduled to run at a future time</li>\n<li><b>paused</b>: Manually paused by user</li>\n<li><b>stuck</b>: Job is stuck (worker crashed mid-processing)</li>\n</ul>\n"
    }
  },
  "required": [
    "name",
    "data",
    "timestamp",
    "attemptsMade",
    "state"
  ],
  "$defs": {
    "BaseScheduleConfig": {
      "type": "object",
      "description": "Base configuration fields common to all schedule types",
      "properties": {
        "scheduleType": {
          "$ref": "#/$defs/CrawlingScheduleType"
        },
        "isEnabled": {
          "type": "boolean",
          "default": true,
          "description": "Whether the schedule is active. Disabled schedules won't create new jobs."
        },
        "timezone": {
          "type": "string",
          "default": "UTC",
          "description": "IANA timezone identifier (e.g., \"America/New_York\", \"Europe/London\", \"Asia/Tokyo\")"
        }
      },
      "required": [
        "scheduleType"
      ]
    },
    "CrawlingJobData": {
      "type": "object",
      "description": "Data payload stored with each crawling job in the queue",
      "properties": {
        "connector": {
          "type": "string",
          "description": "Connector type identifier (e.g., \"drive\", \"onedrive\", \"slack\")"
        },
        "connectorId": {
          "type": "string",
          "description": "Unique identifier of the connector instance"
        },
        "scheduleConfig": {
          "$ref": "#/$defs/ScheduleConfig"
        },
        "orgId": {
          "type": "string",
          "description": "Organization ID that owns this crawling job"
        },
        "userId": {
          "type": "string",
          "description": "User ID who created/scheduled this job"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "When the job was created/scheduled"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true,
          "description": "Optional additional metadata for the job"
        }
      },
      "required": [
        "connector",
        "connectorId",
        "scheduleConfig",
        "orgId",
        "userId",
        "timestamp"
      ]
    },
    "CrawlingScheduleType": {
      "type": "string",
      "enum": [
        "hourly",
        "daily",
        "weekly",
        "monthly",
        "custom",
        "once",
        "interval"
      ],
      "description": "Type of crawling schedule that determines how often the connector data is synced.<br>\n<ul>\n<li><b>hourly</b>: Run at specified minute every X hours</li>\n<li><b>daily</b>: Run once per day at specified hour and minute</li>\n<li><b>weekly</b>: Run on specified days of the week at specified time</li>\n<li><b>monthly</b>: Run on specified day of month at specified time</li>\n<li><b>custom</b>: Use cron expression for complex schedules</li>\n<li><b>once</b>: Run once at a specific future datetime</li>\n<li><b>interval</b>: Repeat every N minutes regardless of clock time (BullMQ <code>every</code>-based)</li>\n</ul>\n"
    },
    "CustomScheduleConfig": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseScheduleConfig"
        },
        {
          "type": "object",
          "description": "Run crawling job using a custom cron expression for complex schedules",
          "properties": {
            "scheduleType": {
              "type": "string",
              "enum": [
                "custom"
              ]
            },
            "cronExpression": {
              "type": "string",
              "pattern": "^(\\S+\\s+){4}\\S+$",
              "description": "Standard 5-field cron expression: minute hour day-of-month month day-of-week.<br>\nExamples:<br>\n<ul>\n<li><code>0 2 * * *</code> - Every day at 2:00 AM</li>\n<li><code>30 */4 * * *</code> - Every 4 hours at minute 30</li>\n<li><code>0 9 * * 1-5</code> - Weekdays at 9:00 AM</li>\n<li><code>0 0 1,15 * *</code> - 1st and 15th of each month at midnight</li>\n</ul>\n"
            },
            "description": {
              "type": "string",
              "description": "Human-readable description of the cron schedule"
            }
          },
          "required": [
            "cronExpression"
          ]
        }
      ]
    },
    "DailyScheduleConfig": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseScheduleConfig"
        },
        {
          "type": "object",
          "description": "Run crawling job once per day at a specified time",
          "properties": {
            "scheduleType": {
              "type": "string",
              "enum": [
                "daily"
              ]
            },
            "hour": {
              "type": "integer",
              "minimum": 0,
              "maximum": 23,
              "description": "Hour of the day to run (0-23, 24-hour format)"
            },
            "minute": {
              "type": "integer",
              "minimum": 0,
              "maximum": 59,
              "description": "Minute of the hour to run (0-59)"
            }
          },
          "required": [
            "hour",
            "minute"
          ]
        }
      ]
    },
    "HourlyScheduleConfig": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseScheduleConfig"
        },
        {
          "type": "object",
          "description": "Run crawling job every X hours at a specified minute",
          "properties": {
            "scheduleType": {
              "type": "string",
              "enum": [
                "hourly"
              ]
            },
            "minute": {
              "type": "integer",
              "minimum": 0,
              "maximum": 59,
              "description": "Minute of the hour to run (0-59)"
            },
            "interval": {
              "type": "integer",
              "minimum": 1,
              "maximum": 24,
              "default": 1,
              "description": "Run every X hours (1 = every hour, 2 = every 2 hours, etc.)"
            }
          },
          "required": [
            "minute"
          ]
        }
      ]
    },
    "IntervalScheduleConfig": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseScheduleConfig"
        },
        {
          "type": "object",
          "description": "Repeat every N minutes using BullMQ's millisecond-based <code>every</code> repeat option.\nUnlike cron-based schedules this fires relative to the previous run, not at a fixed\nwall-clock time. Used by the connector sync scheduler when\n<code>selectedStrategy = SCHEDULED</code> with an <code>intervalMinutes</code> config.\n",
          "properties": {
            "scheduleType": {
              "type": "string",
              "enum": [
                "interval"
              ]
            },
            "intervalMinutes": {
              "type": "integer",
              "minimum": 1,
              "maximum": 525600,
              "description": "How often to repeat, in minutes. Maximum is 525 600 (one year).\nBullMQ stores this as <code>every: intervalMinutes * 60 * 1000</code> ms;\nthe <code>pattern</code> field will be <code>null</code> on repeatable-job\nlistings for this schedule type.\n"
            }
          },
          "required": [
            "intervalMinutes"
          ]
        }
      ]
    },
    "MonthlyScheduleConfig": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseScheduleConfig"
        },
        {
          "type": "object",
          "description": "Run crawling job on a specified day of each month",
          "properties": {
            "scheduleType": {
              "type": "string",
              "enum": [
                "monthly"
              ]
            },
            "dayOfMonth": {
              "type": "integer",
              "minimum": 1,
              "maximum": 31,
              "description": "Day of the month to run (1-31). If day doesn't exist in month, job runs on last day."
            },
            "hour": {
              "type": "integer",
              "minimum": 0,
              "maximum": 23,
              "description": "Hour of the day to run (0-23)"
            },
            "minute": {
              "type": "integer",
              "minimum": 0,
              "maximum": 59,
              "description": "Minute of the hour to run (0-59)"
            }
          },
          "required": [
            "dayOfMonth",
            "hour",
            "minute"
          ]
        }
      ]
    },
    "OnceScheduleConfig": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseScheduleConfig"
        },
        {
          "type": "object",
          "description": "Run crawling job once at a specific future datetime",
          "properties": {
            "scheduleType": {
              "type": "string",
              "enum": [
                "once"
              ]
            },
            "scheduledTime": {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 datetime when the job should run. Must be in the future."
            }
          },
          "required": [
            "scheduledTime"
          ]
        }
      ]
    },
    "ScheduleConfig": {
      "description": "Schedule configuration for crawling jobs. The structure varies based on <code>scheduleType</code>.<br><br>\n<b>Schedule Type Configurations:</b><br>\n<ul>\n<li><b>hourly:</b> <code>minute</code>, <code>interval</code> (optional)</li>\n<li><b>daily:</b> <code>hour</code>, <code>minute</code></li>\n<li><b>weekly:</b> <code>daysOfWeek</code>, <code>hour</code>, <code>minute</code></li>\n<li><b>monthly:</b> <code>dayOfMonth</code>, <code>hour</code>, <code>minute</code></li>\n<li><b>custom:</b> <code>cronExpression</code>, <code>description</code> (optional)</li>\n<li><b>once:</b> <code>scheduledTime</code></li>\n<li><b>interval:</b> <code>intervalMinutes</code> — repeats every N minutes (BullMQ <code>every</code>-based)</li>\n</ul>\n",
      "oneOf": [
        {
          "$ref": "#/$defs/HourlyScheduleConfig"
        },
        {
          "$ref": "#/$defs/DailyScheduleConfig"
        },
        {
          "$ref": "#/$defs/WeeklyScheduleConfig"
        },
        {
          "$ref": "#/$defs/MonthlyScheduleConfig"
        },
        {
          "$ref": "#/$defs/CustomScheduleConfig"
        },
        {
          "$ref": "#/$defs/OnceScheduleConfig"
        },
        {
          "$ref": "#/$defs/IntervalScheduleConfig"
        }
      ]
    },
    "WeeklyScheduleConfig": {
      "allOf": [
        {
          "$ref": "#/$defs/BaseScheduleConfig"
        },
        {
          "type": "object",
          "description": "Run crawling job on specified days of the week",
          "properties": {
            "scheduleType": {
              "type": "string",
              "enum": [
                "weekly"
              ]
            },
            "daysOfWeek": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 0,
                "maximum": 6
              },
              "minItems": 1,
              "description": "Days of the week to run (0=Sunday, 1=Monday, ..., 6=Saturday).<br>\nExample: [1, 3, 5] runs on Monday, Wednesday, Friday\n"
            },
            "hour": {
              "type": "integer",
              "minimum": 0,
              "maximum": 23,
              "description": "Hour of the day to run (0-23)"
            },
            "minute": {
              "type": "integer",
              "minimum": 0,
              "maximum": 59,
              "description": "Minute of the hour to run (0-59)"
            }
          },
          "required": [
            "daysOfWeek",
            "hour",
            "minute"
          ]
        }
      ]
    }
  }
}