@dakkitor/api-contracts 1.1.154 → 1.5.0

package/dist/jobs/jobs.contract.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.jobsContractRouter = exports.SearchJobResponseSchema = exports.SearchJobResultSchema = exports.SearchJobQuerySchema = exports.FilterMapMarkersSchema = exports.PaginatedJobResponseSchema = exports.FilterJobSchema = exports.BatchDeleteJobResponseSchema = exports.BatchDeleteJobSchema = exports.BatchUpdateJobResponseSchema = exports.BatchUpdateJobSchema = exports.UpdateJobSchema = exports.CreateDraftJobSchema = exports.CreateJobSchema = exports.JobMapMarkersResponseSchema = exports.JobMapMarkerSchema = exports.JobSchema = exports.CreateJobQualificationSchema = exports.JobQualificationSchema = exports.CreatePaySchema = exports.PaySchema = exports.JobSortableFieldsSchema = exports.JobStatusSchema = void 0;
+exports.jobsContractRouter = exports.DuplicateJobConflictSchema = exports.SearchJobResponseSchema = exports.SearchJobResultSchema = exports.SearchJobQuerySchema = exports.FilterMapMarkersSchema = exports.PaginatedJobResponseSchema = exports.JobFeedResponseSchema = exports.JobFeedQuerySchema = exports.JOB_FEED_PAGE_SIZE = exports.FilterJobSchema = exports.BatchDeleteJobResponseSchema = exports.BatchDeleteJobSchema = exports.BatchUpdateJobResponseSchema = exports.BatchUpdateJobSchema = exports.UpdateJobSchema = exports.CreateJobSchema = exports.DemandBreakdownDetailResponseSchema = exports.DemandBreakdownDetailQuerySchema = exports.DemandUnitSchema = exports.DemandEpisodeSchema = exports.DemandBreakdownResponseSchema = exports.DemandBreakdownRowSchema = exports.DemandBreakdownFilterSchema = exports.DemandWindowSchema = exports.JobMapMarkersResponseSchema = exports.JobMapMarkerSchema = exports.PaginatedJobListResponseSchema = exports.FeedJobItemSchema = exports.JobListItemSchema = exports.JobSchema = exports.CreateJobQualificationSchema = exports.JobQualificationSchema = exports.CreatePaySchema = exports.PaySchema = exports.JobSortFieldMapping = exports.JobSortableFieldsSchema = exports.JobStartDateSchema = exports.CreationSourceSchema = exports.JobEventSchema = exports.JobCloseSourceSchema = exports.JobCloseReasonSchema = exports.JobEventTypeSchema = exports.JobStatusSchema = void 0;
 const zod_openapi_1 = require("@anatine/zod-openapi");
 const core_1 = require("@ts-rest/core");
 const zod_1 = require("zod");
@@ -9,13 +9,54 @@ const common_schemas_1 = require("../common/common-schemas");
 const error_schemas_1 = require("../common/error-schemas");
 const pagination_query_schema_1 = require("../common/pagination-query.schema");
 const pagination_schema_1 = require("../common/pagination.schema");
-const curated_workers_contract_1 = require("../curated-workers/curated-workers.contract");
+const summary_schemas_1 = require("../shared/summary-schemas");
 const users_contract_1 = require("../users/users.contract");
 (0, zod_openapi_1.extendZodWithOpenApi)(zod_1.z);
 /**
  * Job Status Enum
  */
-exports.JobStatusSchema = zod_1.z.enum(['AVAILABLE', 'NOT_AVAILABLE', 'DRAFT']);
+exports.JobStatusSchema = zod_1.z.enum(['AVAILABLE', 'NOT_AVAILABLE']);
+/**
+ * Job lifecycle event log (job_events table) — read-only history.
+ * Mirrors apps/api JobEvent entity + its enums.
+ */
+exports.JobEventTypeSchema = zod_1.z.enum([
+    'CREATED',
+    'STATUS_CHANGED',
+    'POSITIONS_CHANGED',
+]);
+exports.JobCloseReasonSchema = zod_1.z.enum([
+    'FILLED',
+    'PARTIALLY_FILLED',
+    'UNFILLED',
+]);
+exports.JobCloseSourceSchema = zod_1.z.enum([
+    'BOOKINGS',
+    'DECLARED',
+    'EXPIRED',
+    'START_DATE',
+]);
+exports.JobEventSchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    eventType: exports.JobEventTypeSchema,
+    fromStatus: exports.JobStatusSchema.nullable(),
+    toStatus: exports.JobStatusSchema.nullable(),
+    numberOfPositions: zod_1.z.number().int(),
+    previousNumberOfPositions: zod_1.z.number().int().nullable(),
+    filledPositions: zod_1.z.number().int().nullable(),
+    closeReason: exports.JobCloseReasonSchema.nullable(),
+    closeSource: exports.JobCloseSourceSchema.nullable(),
+    occurredAt: zod_1.z.union([zod_1.z.string().datetime(), zod_1.z.date()]),
+});
+/**
+ * Creation Source Enum
+ */
+exports.CreationSourceSchema = zod_1.z.enum(['MANUAL', 'BOT']);
+/** UK-local calendar date the job starts, e.g. '2026-07-14'. */
+exports.JobStartDateSchema = zod_1.z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'Expected YYYY-MM-DD')
+    .describe('Start date (UK-local calendar date)');
 /**
  * Job Sortable Fields Enum
  */
@@ -34,60 +75,71 @@ exports.JobSortableFieldsSchema = zod_1.z
     'receivedRate',
     'workHours',
     'qualificationsCount',
+    'creationSource',
     'createdAt',
     'updatedAt',
+    'startDate',
 ])
     .openapi({ title: 'JobSortableFields' });
+/** Maps sort field values to ability field paths on SortJobSchema. */
+exports.JobSortFieldMapping = {
+    description: 'description',
+    numberOfPositions: 'numberOfPositions',
+    status: 'status',
+    tradeId: 'tradeId',
+    collaborationCompany: 'collaboration.companyId',
+    collaborationClient: 'collaboration.clientId',
+    collaborationAgent: 'collaboration.userId',
+    distance: 'distance',
+    postcode: 'postcode',
+    payRate: 'payRate',
+    receivedRate: 'receivedRate',
+    workHours: 'workHours',
+    qualificationsCount: 'qualificationsCount',
+    creationSource: 'creationSource',
+    createdAt: 'createdAt',
+    updatedAt: 'updatedAt',
+    startDate: 'startDate',
+};
 /**
  * Pay Schema - Nested object for job payment details
  */
 exports.PaySchema = zod_1.z
     .object({
-    rateUnit: common_schemas_1.RateUnitSchema.describe('The unit for the pay rate'),
-    isNegotiable: zod_1.z
-        .boolean()
-        .default(false)
-        .describe('Whether the rate is negotiable'),
-    rate: zod_1.z.coerce
-        .number()
-        .min(1)
-        .nullable()
-        .optional()
-        .describe('The pay rate'),
+    rateUnit: common_schemas_1.RateUnitSchema.describe('Hourly or Daily'),
+    isNegotiable: zod_1.z.boolean().default(false).describe('Negotiable'),
+    rate: zod_1.z.coerce.number().min(1).nullable().optional().describe('e.g. 15.00'),
     rateMax: zod_1.z.coerce
         .number()
         .min(1)
         .nullable()
         .optional()
-        .describe('The maximum pay rate (for a range)'),
+        .describe('e.g. 20.00'),
     receivedRate: zod_1.z.coerce
         .number()
         .min(1)
         .nullable()
         .optional()
-        .describe('The received pay rate'),
+        .describe('e.g. 18.00'),
 })
     .openapi({ title: 'Pay' });
 exports.CreatePaySchema = zod_1.z
     .object({
-    rateUnit: common_schemas_1.RateUnitSchema.default('HOURLY').describe('The unit for the pay rate'),
-    isNegotiable: zod_1.z
-        .boolean()
-        .default(false)
-        .describe('Whether the rate is negotiable'),
-    rate: zod_1.z.number().min(1).nullable().optional().describe('The pay rate'),
+    rateUnit: common_schemas_1.RateUnitSchema.default('HOURLY').describe('Pay rate'),
+    isNegotiable: zod_1.z.boolean().default(false).describe('Negotiable'),
+    rate: zod_1.z.number().min(1).nullable().optional().describe('Pay rate'),
     rateMax: zod_1.z
         .number()
         .min(1)
         .optional()
         .nullable()
-        .describe('The maximum pay rate (for a range)'),
+        .describe('Maximum pay rate'),
     receivedRate: zod_1.z
         .number()
         .min(1)
         .nullable()
         .optional()
-        .describe('The received pay rate'),
+        .describe('Received rate'),
 })
     .superRefine((data, ctx) => {
     if (!data.isNegotiable) {
@@ -121,13 +173,13 @@ exports.CreatePaySchema = zod_1.z
 exports.JobQualificationSchema = zod_1.z
     .object({
     id: zod_1.z.string().uuid().describe('The ID of the job qualification'),
-    qualificationId: zod_1.z.string().uuid().describe('The ID of the qualification'),
+    qualificationId: zod_1.z.string().uuid().describe('Qualification'),
     qualificationTypeId: zod_1.z
         .string()
         .uuid()
         .optional()
         .nullable()
-        .describe('The ID of the qualification type'),
+        .describe('Qualification type'),
 })
     .openapi({ title: 'JobQualification' });
 exports.CreateJobQualificationSchema = zod_1.z
@@ -136,7 +188,7 @@ exports.CreateJobQualificationSchema = zod_1.z
     qualificationTypeId: zod_1.z
         .union([zod_1.z.string().uuid(), zod_1.z.null()])
         .optional()
-        .describe('The ID of the qualification type'),
+        .describe('Qualification type'),
 })
     .openapi({ title: 'CreateJobQualification' });
 /**
@@ -145,24 +197,18 @@ exports.CreateJobQualificationSchema = zod_1.z
 exports.JobSchema = zod_1.z
     .object({
     id: zod_1.z.string().uuid().describe('Job ID'),
-    description: zod_1.z.string().describe('Job Description'),
-    numberOfPositions: zod_1.z
-        .number()
-        .int()
-        .min(1)
-        .describe('Number of Positions Available'),
+    description: zod_1.z.string().describe('Description'),
+    numberOfPositions: zod_1.z.number().int().min(1).describe('Positions'),
     workHours: zod_1.z.coerce
         .number()
         .min(0.01)
         .max(60)
         .optional()
         .nullable()
-        .describe('Number of Work Hours'),
-    status: exports.JobStatusSchema.describe('Job Status'),
+        .describe('Work Hours'),
+    status: exports.JobStatusSchema.describe('Status'),
     pay: exports.PaySchema.describe('Payment Details'),
-    location: common_schemas_1.LocationDetailsSchema.optional()
-        .nullable()
-        .describe('Job Location'),
+    location: common_schemas_1.LocationDetailsSchema.optional().nullable().describe('Location'),
     tradeId: zod_1.z
         .string()
         .min(1, { message: 'Trade is required' })
@@ -172,10 +218,10 @@ exports.JobSchema = zod_1.z
         .array(exports.JobQualificationSchema)
         .optional()
         .default([])
-        .describe('Job Qualifications'),
-    currentCollaboration: collaborations_contract_1.CollaborationSchema.nullable()
+        .describe('Qualifications'),
+    collaboration: collaborations_contract_1.CollaborationSchema.nullable()
         .optional()
-        .describe('Current Collaboration'),
+        .describe('Collaboration'),
     createdAt: zod_1.z
         .union([zod_1.z.string().datetime(), zod_1.z.date()])
         .transform((val) => (val instanceof Date ? val.toISOString() : val))
@@ -193,6 +239,9 @@ exports.JobSchema = zod_1.z
     createdBy: users_contract_1.UserSchema.nullable()
         .optional()
         .describe('User who created the job'),
+    creationSource: exports.CreationSourceSchema.nullable()
+        .optional()
+        .describe('How the job was created (BOT or MANUAL)'),
     distanceKm: zod_1.z.number().nullable().optional().describe('Distance in KM'),
     filledPositions: zod_1.z
         .number()
@@ -200,8 +249,58 @@ exports.JobSchema = zod_1.z
         .min(0)
         .default(0)
         .describe('Number of filled positions in the current availability window (computed from qualifying bookings)'),
+    startDate: exports.JobStartDateSchema.nullable().describe('Start date'),
 })
     .openapi({ title: 'Job' });
+/**
+ * JobListItemSchema - Lightweight schema for job list views.
+ * Uses summary nested types instead of full entity schemas to reduce payload size.
+ * Key differences from JobSchema:
+ * - `location` uses LocationSummarySchema (4 fields) instead of LocationDetailsSchema (9 fields)
+ * - `collaboration` uses CollaborationSummarySchema instead of full CollaborationSchema
+ * - `createdBy` uses UserSummarySchema (shown as FA on jobs with no collaboration)
+ */
+exports.JobListItemSchema = zod_1.z
+    .object({
+    id: zod_1.z.string().uuid(),
+    description: zod_1.z.string(),
+    numberOfPositions: zod_1.z.coerce.number().int().min(1),
+    workHours: zod_1.z.coerce.number().nullable().optional(),
+    status: exports.JobStatusSchema,
+    pay: exports.PaySchema,
+    location: summary_schemas_1.LocationSummarySchema.nullable().optional(),
+    tradeId: zod_1.z.string().uuid(),
+    jobQualifications: zod_1.z.array(exports.JobQualificationSchema).nullable().optional(),
+    collaboration: summary_schemas_1.CollaborationSummarySchema.nullable().optional(),
+    createdAt: zod_1.z
+        .union([zod_1.z.string().datetime(), zod_1.z.date()])
+        .transform((val) => (val instanceof Date ? val.toISOString() : val)),
+    updatedAt: zod_1.z
+        .union([zod_1.z.string().datetime(), zod_1.z.date()])
+        .transform((val) => (val instanceof Date ? val.toISOString() : val)),
+    createdById: zod_1.z.string().uuid().nullable().optional(),
+    createdBy: summary_schemas_1.UserSummarySchema.nullable().optional(),
+    creationSource: exports.CreationSourceSchema.nullable().optional(),
+    distanceKm: zod_1.z.coerce.number().nullable().optional(),
+    filledPositions: zod_1.z.coerce.number().int().min(0).default(0),
+    startDate: exports.JobStartDateSchema.nullable().optional().describe('Start date'),
+})
+    .openapi({ title: 'JobListItem' });
+// FeedJobItem mirrors JobListItem (flat tradeId, JobQualificationSchema-shaped
+// jobQualifications) — names for trades/qualifications are resolved on the
+// client from the shared trades/qualifications context, not denormalized here.
+exports.FeedJobItemSchema = exports.JobListItemSchema.extend({
+    // Legacy/imported jobs may not have a trade. The jobs table deliberately
+    // permits this and the feed UI renders an explicit no-trade state.
+    tradeId: zod_1.z.string().uuid().nullable(),
+    availableSince: zod_1.z
+        .union([zod_1.z.string().datetime(), zod_1.z.date()])
+        .transform((val) => (val instanceof Date ? val.toISOString() : val))
+        .nullable(),
+}).openapi({ title: 'FeedJobItem' });
+exports.PaginatedJobListResponseSchema = (0, pagination_schema_1.createPaginatedResponseSchema)(exports.JobListItemSchema)
+    .describe('Jobs retrieved successfully')
+    .openapi({ title: 'JobListPaginatedResponse' });
 /**
  * Lightweight schema for map marker data.
  * Contains only the fields needed to place and identify markers on a map.
@@ -215,13 +314,23 @@ exports.JobMapMarkerSchema = zod_1.z
     latitude: zod_1.z.number().describe('Latitude coordinate'),
     longitude: zod_1.z.number().describe('Longitude coordinate'),
     postcode: zod_1.z.string().nullable().optional().describe('Postcode'),
-    numberOfPositions: zod_1.z.number().int().min(1).describe('Number of positions'),
+    numberOfPositions: zod_1.z.number().int().min(1).describe('Positions'),
     filledPositions: zod_1.z
         .number()
         .int()
         .min(0)
         .default(0)
         .describe('Filled positions count'),
+    createdAt: zod_1.z
+        .string()
+        .datetime()
+        .describe('Job creation timestamp (ISO) — used for demand-trend bucketing'),
+    clusterId: zod_1.z
+        .string()
+        .uuid()
+        .nullable()
+        .optional()
+        .describe("Id of this job's CONFIRMED duplicate cluster, or null. The Breakdown collapses markers sharing a clusterId into one demand unit."),
 })
     .openapi({ title: 'JobMapMarker' });
 exports.JobMapMarkersResponseSchema = zod_1.z
@@ -231,37 +340,129 @@ exports.JobMapMarkersResponseSchema = zod_1.z
     excludedCount: zod_1.z
         .number()
         .int()
-        .describe('Jobs excluded due to missing coordinates'),
+        .describe('Jobs beyond the 1000-marker render cap (all returned markers have coordinates)'),
 })
     .openapi({ title: 'JobMapMarkersResponse' });
 /**
- * Create Job Schema
+ * Demand/Supply breakdown (spec 2026-07-11-demand-supply-accuracy-design).
+ * A "demand unit" is a cluster-deduped availability episode island; see
+ * apps/api demand-breakdown.sql.ts for derivation.
  */
-exports.CreateJobSchema = zod_1.z
+exports.DemandWindowSchema = zod_1.z
     .object({
-    description: zod_1.z.string().min(10).describe('Job Description'),
-    location: common_schemas_1.CreateLocationSchema.optional()
-        .nullable()
-        .describe('Job Location'),
-    numberOfPositions: zod_1.z
+    from: zod_1.z.string().date().describe('Window start (inclusive, yyyy-MM-dd)'),
+    to: zod_1.z.string().date().describe('Window end (inclusive, yyyy-MM-dd)'),
+})
+    .refine((w) => w.from <= w.to, { message: 'window.from must be <= window.to' })
+    .refine((w) => (Date.parse(w.to) - Date.parse(w.from)) / 86400000 <= 366, { message: 'window must span at most 366 days' })
+    .openapi({ title: 'DemandWindow' });
+const demandBreakdownFilterShape = {
+    window: exports.DemandWindowSchema,
+    tradeId: zod_1.z.string().uuid().optional().nullable().describe('Filter by trade'),
+    companyId: zod_1.z.string().uuid().optional().nullable().describe('Search Company'),
+    clientId: zod_1.z.string().uuid().optional().nullable().describe('Search Client'),
+    userId: zod_1.z.string().uuid().optional().nullable().describe('Search First Agent'),
+    location: common_schemas_1.LocationFilterSchema.optional().nullable().describe('Filter by location'),
+    pay: common_schemas_1.PayRangeSchema.optional().nullable().describe('Filter by pay rate range'),
+    qualificationFilters: zod_1.z
+        .array(common_schemas_1.QualificationFilterSchema)
+        .optional()
+        .describe('Qualifications'),
+};
+exports.DemandBreakdownFilterSchema = zod_1.z
+    .object(demandBreakdownFilterShape)
+    .openapi({ title: 'DemandBreakdownFilter' });
+exports.DemandBreakdownRowSchema = zod_1.z
+    .object({
+    area: zod_1.z.string().describe('Postcode area (outward letters, e.g. "SW")'),
+    tradeId: zod_1.z.string().uuid(),
+    tradeName: zod_1.z.string(),
+    units: zod_1.z.number().int().describe('Demand units in window (cluster-deduped)'),
+    episodes: zod_1.z.number().int().describe('Raw episodes folded into those units'),
+    positionEpisodes: zod_1.z
         .number()
         .int()
-        .min(1)
-        .max(100)
-        .describe('Number of Positions'),
-    workHours: zod_1.z
+        .describe('Σ unit positions (post-collapse) — the flow numerator'),
+    filledInWindow: zod_1.z
         .number()
-        .min(0.01)
-        .max(60)
-        .default(8)
-        .describe('Number of Work Hours'),
-    pay: exports.CreatePaySchema.describe('Payment Details'),
+        .int()
+        .describe('Filled-status bookings created in window on scoped jobs'),
+    stockUnfilled: zod_1.z
+        .number()
+        .int()
+        .describe('Unfilled positions on currently-AVAILABLE jobs (deduped)'),
+    unitsFirstHalf: zod_1.z.number().int(),
+    unitsSecondHalf: zod_1.z.number().int(),
+    centroidLongitude: zod_1.z.number().nullable(),
+    centroidLatitude: zod_1.z.number().nullable(),
+})
+    .openapi({ title: 'DemandBreakdownRow' });
+exports.DemandBreakdownResponseSchema = zod_1.z
+    .object({
+    rows: zod_1.z.array(exports.DemandBreakdownRowSchema),
+    totals: zod_1.z.object({
+        units: zod_1.z.number().int(),
+        episodes: zod_1.z.number().int(),
+        positionEpisodes: zod_1.z.number().int(),
+        filledInWindow: zod_1.z.number().int(),
+        stockUnfilled: zod_1.z.number().int(),
+    }),
+    excludedNoLocation: zod_1.z
+        .number()
+        .int()
+        .describe('Scoped jobs skipped: missing/unparseable postcode'),
+    excludedNoTrade: zod_1.z.number().int().describe('Scoped jobs skipped: no trade'),
+})
+    .openapi({ title: 'DemandBreakdownResponse' });
+exports.DemandEpisodeSchema = zod_1.z
+    .object({
+    jobId: zod_1.z.string().uuid(),
+    occurredAt: zod_1.z.string().describe('Episode timestamp (ISO)'),
+    positions: zod_1.z.number().int(),
+    kind: zod_1.z.enum(['CREATED', 'REOPEN']),
+})
+    .openapi({ title: 'DemandEpisode' });
+exports.DemandUnitSchema = zod_1.z
+    .object({
+    unitStart: zod_1.z.string().describe('First episode timestamp (ISO)'),
+    positions: zod_1.z.number().int().describe('Max positions across merged episodes'),
+    clusterStatus: zod_1.z.enum(['CONFIRMED', 'PENDING', 'NONE']),
+    episodes: zod_1.z.array(exports.DemandEpisodeSchema),
+    jobs: zod_1.z.array(zod_1.z.object({
+        jobId: zod_1.z.string().uuid(),
+        status: exports.JobStatusSchema,
+        positions: zod_1.z.number().int(),
+    })),
+    filledInWindow: zod_1.z.number().int(),
+    stockUnfilled: zod_1.z.number().int(),
+})
+    .openapi({ title: 'DemandUnit' });
+exports.DemandBreakdownDetailQuerySchema = zod_1.z
+    .object({
+    ...demandBreakdownFilterShape,
+    area: zod_1.z.string().min(1).describe('Postcode area key, e.g. "SW"'),
+    tradeId: zod_1.z.string().uuid().describe('Trade (required here)'),
+})
+    .openapi({ title: 'DemandBreakdownDetailQuery' });
+exports.DemandBreakdownDetailResponseSchema = zod_1.z
+    .object({ units: zod_1.z.array(exports.DemandUnitSchema) })
+    .openapi({ title: 'DemandBreakdownDetailResponse' });
+/**
+ * Create Job Schema
+ */
+exports.CreateJobSchema = zod_1.z
+    .object({
+    description: zod_1.z.string().min(10).describe('Description'),
+    location: common_schemas_1.CreateLocationSchema.optional().nullable().describe('Location'),
     tradeId: zod_1.z
         .string()
         .min(1, { message: 'Trade is required' })
         .pipe(zod_1.z.string().uuid())
         .describe('Trade'),
-    currentCollaboration: zod_1.z
+    numberOfPositions: zod_1.z.number().int().min(1).max(100).describe('Positions'),
+    workHours: zod_1.z.number().min(0.01).max(60).default(8).describe('Work Hours'),
+    pay: exports.CreatePaySchema.describe('Payment Details'),
+    collaboration: zod_1.z
         .object({
         id: zod_1.z
             .string()
@@ -271,85 +472,51 @@ exports.CreateJobSchema = zod_1.z
     })
         .optional()
         .nullable()
-        .describe('Current Collaboration'),
+        .describe('Collaboration'),
+    status: exports.JobStatusSchema.optional().describe('Status'),
     jobQualifications: zod_1.z
         .array(exports.CreateJobQualificationSchema)
         .optional()
-        .describe('Job Qualifications'),
-    status: exports.JobStatusSchema.optional().describe('Job Status'),
-})
-    .superRefine((data, ctx) => {
-    // If no collaboration is provided, status must be DRAFT (or will default to DRAFT)
-    const hasCollaboration = data.currentCollaboration && data.currentCollaboration.id;
-    if (!hasCollaboration) {
-        // If status is explicitly set to non-DRAFT, fail validation
-        if (data.status !== undefined && data.status !== 'DRAFT') {
-            ctx.addIssue({
-                code: zod_1.z.ZodIssueCode.custom,
-                message: 'A collaboration is required when creating a job with non-draft status.',
-                path: ['currentCollaboration'],
-            });
-        }
-    }
-})
-    .transform((data) => {
-    // If no collaboration, default status to DRAFT
-    const hasCollaboration = data.currentCollaboration && data.currentCollaboration.id;
-    return {
-        ...data,
-        status: hasCollaboration ? (data.status ?? 'AVAILABLE') : 'DRAFT',
-    };
+        .describe('Qualifications'),
+    acknowledgedDuplicateIds: zod_1.z
+        .array(zod_1.z.string().uuid())
+        .optional()
+        .describe('Ids of suspected-duplicate jobs the creator has reviewed and confirmed are NOT the same job. Presence (even empty) skips the duplicate probe and records rejected pairs against these ids.'),
+    startDate: exports.JobStartDateSchema.nullable().optional(),
 })
+    .transform((data) => ({
+    ...data,
+    status: data.status ?? 'AVAILABLE',
+}))
     .openapi({ title: 'CreateJob' });
 /**
- * Create Draft Job Schema - For bot-created jobs without collaboration
+ * Update Job Schema
  */
-exports.CreateDraftJobSchema = zod_1.z
+exports.UpdateJobSchema = zod_1.z
     .object({
-    description: zod_1.z.string().min(10).describe('Job Description'),
-    location: common_schemas_1.CreateLocationSchema.optional()
-        .nullable()
-        .describe('Job Location'),
-    numberOfPositions: zod_1.z
-        .number()
-        .int()
-        .min(1)
-        .max(100)
-        .describe('Number of Positions'),
-    workHours: zod_1.z
-        .number()
-        .min(0.01)
-        .max(60)
-        .default(8)
-        .describe('Number of Work Hours'),
-    pay: exports.CreatePaySchema.describe('Payment Details'),
+    description: zod_1.z.string().min(10).optional().describe('Description'),
+    location: common_schemas_1.CreateLocationSchema.optional().nullable().describe('Location'),
     tradeId: zod_1.z
         .string()
         .min(1, { message: 'Trade is required' })
         .pipe(zod_1.z.string().uuid())
-        .describe('Trade'),
-    jobQualifications: zod_1.z
-        .array(exports.CreateJobQualificationSchema)
         .optional()
-        .describe('Job Qualifications'),
-})
-    .openapi({ title: 'CreateDraftJob' });
-/**
- * Update Job Schema
- */
-exports.UpdateJobSchema = zod_1.z
-    .object({
-    description: zod_1.z.string().min(10).optional().describe('Job Description'),
-    location: common_schemas_1.CreateLocationSchema.optional()
-        .nullable()
-        .describe('Job Location'),
+        .describe('Trade'),
     numberOfPositions: zod_1.z
         .number()
         .int()
         .min(1)
         .max(100)
         .optional()
-        .describe('Number of Positions'),
+        .describe('Positions'),
+    positionsAreRemaining: zod_1.z
+        .boolean()
+        .optional()
+        .describe('When true, numberOfPositions is the count STILL NEEDED (remaining); the API sets total = currentFilled + numberOfPositions. Omitted/false = absolute total. Set by the bot on reposts; never by the web form.'),
+    declaredFilled: zod_1.z
+        .boolean()
+        .optional()
+        .describe('When closing a job (status -> NOT_AVAILABLE), marks it as DECLARED filled (sourced externally, e.g. a "filled" reply in the group) rather than the default BOOKINGS-derived close. Set by the bot on "filled" closes only; never by the web form or on cancellations.'),
     workHours: zod_1.z
         .number()
         .min(0.01)
@@ -357,13 +524,7 @@ exports.UpdateJobSchema = zod_1.z
         .optional()
         .describe('Number of Work Hours'),
     pay: exports.CreatePaySchema.optional().describe('Payment Details'),
-    tradeId: zod_1.z
-        .string()
-        .min(1, { message: 'Trade is required' })
-        .pipe(zod_1.z.string().uuid())
-        .optional()
-        .describe('Trade'),
-    currentCollaboration: zod_1.z
+    collaboration: zod_1.z
         .preprocess((val) => (val === '' ? null : val), zod_1.z
         .object({
         id: zod_1.z
@@ -385,32 +546,13 @@ exports.UpdateJobSchema = zod_1.z
         }
         return val;
     })
-        .describe('Current Collaboration'),
+        .describe('Collaboration'),
+    status: exports.JobStatusSchema.optional().describe('Job Status'),
     jobQualifications: zod_1.z
         .array(exports.CreateJobQualificationSchema)
         .optional()
         .describe('Job Qualifications'),
-    status: exports.JobStatusSchema.optional().describe('Job Status'),
-})
-    .superRefine((data, ctx) => {
-    // If status is being set to something other than DRAFT,
-    // and currentCollaboration is null or an empty object (form with no selection),
-    // then require a collaboration.
-    // Note: We check for null or missing id specifically, not `!data.currentCollaboration`,
-    // because undefined means the field wasn't provided in the request (PATCH),
-    // and the service layer will handle checking the existing job's collaboration.
-    const hasNoCollaboration = data.currentCollaboration === null ||
-        (data.currentCollaboration !== undefined &&
-            !data.currentCollaboration.id);
-    if (data.status !== undefined &&
-        data.status !== 'DRAFT' &&
-        hasNoCollaboration) {
-        ctx.addIssue({
-            code: zod_1.z.ZodIssueCode.custom,
-            message: 'A collaboration is required when setting status to a non-draft value.',
-            path: ['currentCollaboration'],
-        });
-    }
+    startDate: exports.JobStartDateSchema.nullable().optional(),
 })
     .openapi({ title: 'UpdateJob' });
 exports.BatchUpdateJobSchema = zod_1.z
@@ -446,40 +588,62 @@ exports.BatchDeleteJobResponseSchema = zod_1.z
  * Filter Job Schema
  */
 exports.FilterJobSchema = pagination_query_schema_1.PaginationQuerySchema.extend({
-    tradeId: zod_1.z.string().uuid().optional().nullable().describe('Filter by trade'),
-    qualificationFilters: zod_1.z
-        .array(curated_workers_contract_1.QualificationFilterSchema)
-        .optional()
-        .describe('Filter by qualifications'),
-    status: exports.JobStatusSchema.optional()
+    status: exports.JobStatusSchema.optional().nullable().describe('Status'),
+    creationSource: exports.CreationSourceSchema.optional()
         .nullable()
-        .describe('Filter by job status'),
+        .describe('Filter by creation source'),
+    tradeId: zod_1.z.string().uuid().optional().nullable().describe('Filter by trade'),
+    description: zod_1.z.string().optional().nullable().describe('Paste job post'),
+    companyId: zod_1.z.string().uuid().optional().nullable().describe('Search Company'),
+    clientId: zod_1.z.string().uuid().optional().nullable().describe('Search Client'),
     userId: zod_1.z
         .string()
         .uuid()
         .optional()
         .nullable()
         .describe('Search First Agent'),
-    clientId: zod_1.z.string().uuid().optional().nullable().describe('Search Client'),
-    companyId: zod_1.z.string().uuid().optional().nullable().describe('Search Company'),
     location: common_schemas_1.LocationFilterSchema.optional()
         .nullable()
         .describe('Filter by location'),
     pay: common_schemas_1.PayRangeSchema.optional()
         .nullable()
         .describe('Filter by pay rate range'),
-    sortBy: exports.JobSortableFieldsSchema.optional()
-        .nullable()
-        .describe('The field to sort the results by'),
-    sortOrder: common_schemas_1.SortOrderSchema.optional()
-        .nullable()
-        .describe('The order to sort the results by'),
+    qualificationFilters: zod_1.z
+        .array(common_schemas_1.QualificationFilterSchema)
+        .optional()
+        .describe('Qualifications'),
     createdAt: common_schemas_1.DateRangeSchema.optional()
         .nullable()
         .describe('Filter by created date range'),
     updatedAt: common_schemas_1.DateRangeSchema.optional()
         .nullable()
         .describe('Filter by updated date range'),
+    // Not a jobs column — the API resolves this to an EXISTS against
+    // outreach_requests. Defined inline rather than reusing workers.contract's
+    // BooleanFilterSchema: that would add a jobs -> workers contract import for a
+    // two-value enum, and its `unknown` member has no meaning here.
+    outreachRequested: zod_1.z
+        .enum(['only_with', 'only_without'])
+        .optional()
+        .nullable()
+        .describe('Marked for outreach'),
+    sort: (0, common_schemas_1.createSortArraySchema)(exports.JobSortableFieldsSchema),
+});
+exports.JOB_FEED_PAGE_SIZE = 300;
+exports.JobFeedQuerySchema = exports.FilterJobSchema.extend({
+    page: zod_1.z.coerce.number().int().min(1).default(1),
+    limit: zod_1.z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(exports.JOB_FEED_PAGE_SIZE)
+        .default(exports.JOB_FEED_PAGE_SIZE),
+});
+exports.JobFeedResponseSchema = zod_1.z.object({
+    items: exports.FeedJobItemSchema.array().max(exports.JOB_FEED_PAGE_SIZE),
+    page: zod_1.z.number().int().min(1),
+    limit: zod_1.z.number().int().min(1).max(exports.JOB_FEED_PAGE_SIZE),
+    hasMore: zod_1.z.boolean(),
 });
 exports.PaginatedJobResponseSchema = (0, pagination_schema_1.createPaginatedResponseSchema)(exports.JobSchema)
     .describe('Jobs retrieved successfully')
@@ -488,34 +652,32 @@ exports.PaginatedJobResponseSchema = (0, pagination_schema_1.createPaginatedResp
  * Filter schema for map markers — same filters as job list, but no pagination.
  */
 exports.FilterMapMarkersSchema = zod_1.z.object({
+    status: exports.JobStatusSchema.optional().nullable().describe('Status'),
     tradeId: zod_1.z.string().uuid().optional().nullable().describe('Filter by trade'),
-    status: exports.JobStatusSchema.optional()
-        .nullable()
-        .describe('Filter by job status'),
+    companyId: zod_1.z.string().uuid().optional().nullable().describe('Search Company'),
+    clientId: zod_1.z.string().uuid().optional().nullable().describe('Search Client'),
     userId: zod_1.z
         .string()
         .uuid()
         .optional()
         .nullable()
         .describe('Search First Agent'),
-    clientId: zod_1.z.string().uuid().optional().nullable().describe('Search Client'),
-    companyId: zod_1.z.string().uuid().optional().nullable().describe('Search Company'),
     location: common_schemas_1.LocationFilterSchema.optional()
         .nullable()
         .describe('Filter by location'),
     pay: common_schemas_1.PayRangeSchema.optional()
         .nullable()
         .describe('Filter by pay rate range'),
+    qualificationFilters: zod_1.z
+        .array(common_schemas_1.QualificationFilterSchema)
+        .optional()
+        .describe('Qualifications'),
     createdAt: common_schemas_1.DateRangeSchema.optional()
         .nullable()
         .describe('Filter by created date range'),
     updatedAt: common_schemas_1.DateRangeSchema.optional()
         .nullable()
         .describe('Filter by updated date range'),
-    qualificationFilters: zod_1.z
-        .array(curated_workers_contract_1.QualificationFilterSchema)
-        .optional()
-        .describe('Filter by qualifications'),
 });
 /**
  * Search Job Schema - For trigram-based duplicate detection
@@ -525,12 +687,15 @@ exports.SearchJobQuerySchema = zod_1.z
     description: zod_1.z
         .string()
         .min(10)
-        .describe('Job description to search for similar jobs'),
-    userId: zod_1.z
+        .describe('Description to search for similar jobs'),
+    userId: zod_1.z.string().uuid().optional().describe('Search First Agent'),
+    tradeId: zod_1.z.string().uuid().optional().describe('Trade'),
+    postcode: zod_1.z
         .string()
-        .uuid()
+        .min(1)
+        .max(8)
         .optional()
-        .describe('Filter by user who created the job'),
+        .describe('Postcode for structured fallback when trigram finds no matches'),
     threshold: zod_1.z.coerce
         .number()
         .min(0.1)
@@ -544,11 +709,28 @@ exports.SearchJobResultSchema = zod_1.z
     .object({
     similarity: zod_1.z.number().describe('Similarity score (0-1)'),
     job: exports.JobSchema.describe('The matching job'),
+    lastCloseSource: exports.JobCloseSourceSchema.nullable()
+        .optional()
+        .describe('closeSource of the last close event, when job is NOT_AVAILABLE'),
+    lastClosedAt: zod_1.z
+        .string()
+        .datetime()
+        .nullable()
+        .optional()
+        .describe('occurredAt of the last close event, when job is NOT_AVAILABLE'),
 })
     .openapi({ title: 'SearchJobResult' });
 exports.SearchJobResponseSchema = zod_1.z
     .array(exports.SearchJobResultSchema)
     .openapi({ title: 'SearchJobResponse' });
+exports.DuplicateJobConflictSchema = zod_1.z
+    .object({
+    code: zod_1.z.literal('DUPLICATE_JOB_SUSPECTED'),
+    candidates: zod_1.z
+        .array(exports.SearchJobResultSchema)
+        .describe('Existing open jobs that look like duplicates of the submission'),
+})
+    .openapi({ title: 'DuplicateJobConflict' });
 const c = (0, core_1.initContract)();
 exports.jobsContractRouter = c.router({
     create: {
@@ -556,28 +738,17 @@ exports.jobsContractRouter = c.router({
         path: '/v2/jobs',
         responses: {
             201: exports.JobSchema,
-            409: error_schemas_1.ErrorResponseSchema,
+            409: exports.DuplicateJobConflictSchema,
         },
         body: exports.CreateJobSchema,
         summary: 'Create a new job',
         metadata: { tags: ['Jobs'], openApi: { operationId: 'createJob' } },
     },
-    createDraft: {
-        method: 'POST',
-        path: '/v2/jobs/draft',
-        responses: {
-            201: exports.JobSchema,
-            409: error_schemas_1.ErrorResponseSchema,
-        },
-        body: exports.CreateDraftJobSchema,
-        summary: 'Create a draft job (without collaboration)',
-        metadata: { tags: ['Jobs'], openApi: { operationId: 'createDraftJob' } },
-    },
     findAll: {
         method: 'GET',
         path: '/v2/jobs',
         responses: {
-            200: exports.PaginatedJobResponseSchema,
+            200: exports.PaginatedJobListResponseSchema,
         },
         query: exports.FilterJobSchema,
         summary: 'Get all jobs',
@@ -606,6 +777,25 @@ exports.jobsContractRouter = c.router({
             openApi: { operationId: 'getJobMapMarkers' },
         },
     },
+    getDemandBreakdown: {
+        method: 'GET',
+        path: '/v2/jobs/demand-breakdown',
+        responses: { 200: exports.DemandBreakdownResponseSchema },
+        query: exports.DemandBreakdownFilterSchema,
+        summary: 'Area×trade demand rollup: units/flow, stock, trend halves, centroids',
+        metadata: { tags: ['Jobs'], openApi: { operationId: 'getDemandBreakdown' } },
+    },
+    getDemandBreakdownDetail: {
+        method: 'GET',
+        path: '/v2/jobs/demand-breakdown/detail',
+        responses: { 200: exports.DemandBreakdownDetailResponseSchema },
+        query: exports.DemandBreakdownDetailQuerySchema,
+        summary: 'Evidence drill-down: demand units with episodes for one area×trade',
+        metadata: {
+            tags: ['Jobs'],
+            openApi: { operationId: 'getDemandBreakdownDetail' },
+        },
+    },
     batchUpdate: {
         method: 'PATCH',
         path: '/v2/jobs/batch',
@@ -639,6 +829,16 @@ exports.jobsContractRouter = c.router({
             openApi: { operationId: 'batchDeleteJobs' },
         },
     },
+    feed: {
+        method: 'GET',
+        path: '/v2/jobs/feed',
+        query: exports.JobFeedQuerySchema,
+        responses: {
+            200: exports.JobFeedResponseSchema,
+        },
+        summary: 'Get a paginated live jobs feed; AVAILABLE jobs are retained and unavailable jobs expire after 30 minutes',
+        metadata: { tags: ['Jobs'], openApi: { operationId: 'getJobFeed' } },
+    },
     findOne: {
         method: 'GET',
         path: '/v2/jobs/:id',
@@ -652,6 +852,19 @@ exports.jobsContractRouter = c.router({
         summary: 'Get a job by ID',
         metadata: { tags: ['Jobs'], openApi: { operationId: 'findJobById' } },
     },
+    events: {
+        method: 'GET',
+        path: '/v2/jobs/:id/events',
+        responses: {
+            200: zod_1.z.object({ items: exports.JobEventSchema.array() }),
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        pathParams: zod_1.z.object({
+            id: zod_1.z.string().uuid().describe('Job ID'),
+        }),
+        summary: 'Get the lifecycle event history for a job (newest first)',
+        metadata: { tags: ['Jobs'], openApi: { operationId: 'getJobEvents' } },
+    },
     update: {
         method: 'PATCH',
         path: '/v2/jobs/:id',