@dakkitor/api-contracts 1.4.0 → 1.5.0

package/dist/outreach/outreach-requests.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outreach-requests.contract.d.ts","sourceRoot":"","sources":["../../contracts/outreach/outreach-requests.contract.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,cAAc,6BAA6B,CAAC;AAI5C,2EAA2E;AAC3E,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEM,CAAC;AAElD,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC5C,OAAO,8BAA8B,CACtC,CAAC;AAEF,eAAO,MAAM,+BAA+B;;;;;;EAIM,CAAC;AAEnD,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC;AAEF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAIM,CAAC;AAEtD,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,kCAAkC,CAC1C,CAAC;AAEF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8FpC,CAAC"}

package/dist/outreach/outreach-requests.contract.js

@@ -0,0 +1,134 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outreachRequestsContract = exports.ListOutreachRequestsResponseSchema = exports.CreateOutreachRequestBodySchema = exports.OutreachRequestQueueItemSchema = void 0;
+/**
+ * Project: Internal Recruitment Platform API
+ * File: outreach-requests.contract.ts
+ *
+ * Description: Agents mark jobs for outreach; the rack works the queue.
+ *
+ * Two lanes share one router because ts-rest does not model auth: `create` and
+ * `cancel` are the agent's JWT, `list` / `start` / `complete` are the service
+ * key. The server enforces the split with different guards per controller — see
+ * outreach-requests.v2.controller.ts and outreach.v2.controller.ts.
+ */
+const core_1 = require("@ts-rest/core");
+const zod_1 = require("zod");
+const error_schemas_1 = require("../common/error-schemas");
+const outreach_schemas_1 = require("./outreach.schemas");
+const outreach_requests_schemas_1 = require("./outreach-requests.schemas");
+__exportStar(require("./outreach-requests.schemas"), exports);
+const c = (0, core_1.initContract)();
+/** A queue row plus enough of the job to label a campaign in Relay Lab. */
+exports.OutreachRequestQueueItemSchema = outreach_requests_schemas_1.OutreachRequestSchema.extend({
+    job: outreach_schemas_1.OutreachJobSchema,
+}).openapi({ title: 'OutreachRequestQueueItem' });
+exports.CreateOutreachRequestBodySchema = zod_1.z
+    .object({
+    jobId: zod_1.z.string().uuid().describe('Job to mark for outreach'),
+})
+    .openapi({ title: 'CreateOutreachRequestBody' });
+exports.ListOutreachRequestsResponseSchema = zod_1.z
+    .object({
+    items: zod_1.z.array(exports.OutreachRequestQueueItemSchema),
+})
+    .openapi({ title: 'ListOutreachRequestsResponse' });
+exports.outreachRequestsContract = c.router({
+    create: {
+        method: 'POST',
+        path: '/outreach/requests',
+        body: exports.CreateOutreachRequestBodySchema,
+        responses: {
+            // A second "Start outreach" click is NOT an error: the route returns
+            // the existing open request so the button can render its state. There
+            // is deliberately no 409 here.
+            200: outreach_requests_schemas_1.OutreachRequestSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Mark a job for outreach',
+        description: 'Idempotent per job: if an open (PENDING or RUNNING) request already ' +
+            'exists it is returned unchanged. Snapshots the eligible-candidate ' +
+            'count onto the row at creation. 404 when the job does not exist or ' +
+            'is not open (AVAILABLE with a free position).',
+        metadata: { tags: ['Outreach'] },
+    },
+    cancel: {
+        method: 'POST',
+        path: '/outreach/requests/:id/cancel',
+        pathParams: zod_1.z.object({ id: zod_1.z.string().uuid() }),
+        body: zod_1.z.object({}),
+        responses: {
+            200: outreach_requests_schemas_1.OutreachRequestSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Withdraw an outreach request',
+        description: 'Terminal. Frees the job for a new request. Cancelling an already ' +
+            'terminal request is a 200 no-op returning the row unchanged.',
+        metadata: { tags: ['Outreach'] },
+    },
+    list: {
+        method: 'GET',
+        path: '/outreach/requests',
+        query: zod_1.z.object({
+            status: outreach_requests_schemas_1.OutreachRequestStatusSchema.optional().describe('Narrow to one state. Default: PENDING and RUNNING.'),
+        }),
+        responses: {
+            200: exports.ListOutreachRequestsResponseSchema,
+        },
+        summary: 'The open outreach queue',
+        description: 'PENDING and RUNNING requests, oldest first, with job facts for ' +
+            'labelling. Service lane only — the service account still cannot ' +
+            'read jobs generally.',
+        metadata: { tags: ['Outreach'] },
+    },
+    start: {
+        method: 'POST',
+        path: '/outreach/requests/:id/start',
+        pathParams: zod_1.z.object({ id: zod_1.z.string().uuid() }),
+        body: zod_1.z.object({}),
+        responses: {
+            200: outreach_requests_schemas_1.OutreachRequestSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Mark a request as being worked',
+        description: 'PENDING -> RUNNING. Idempotent: starting a RUNNING request returns ' +
+            'it unchanged. Starting a terminal request is a 404.',
+        metadata: { tags: ['Outreach'] },
+    },
+    complete: {
+        method: 'POST',
+        path: '/outreach/requests/:id/complete',
+        pathParams: zod_1.z.object({ id: zod_1.z.string().uuid() }),
+        body: zod_1.z.object({}),
+        responses: {
+            200: outreach_requests_schemas_1.OutreachRequestSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Mark a request as drained or ended',
+        description: 'PENDING or RUNNING -> COMPLETED. Terminal; frees the job for a new ' +
+            'request. Completing an already COMPLETED request is a 200 no-op.',
+        metadata: { tags: ['Outreach'] },
+    },
+}, {
+    pathPrefix: '/v2',
+    commonResponses: {
+        400: error_schemas_1.ErrorResponseSchema,
+        401: error_schemas_1.ErrorResponseSchema,
+        403: error_schemas_1.ErrorResponseSchema,
+        500: error_schemas_1.ErrorResponseSchema,
+    },
+});

package/dist/outreach/outreach-requests.schemas.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/**
+ * `COMPLETED` and `CANCELLED` are terminal and free the job for a new
+ * request. The invariant that at most one PENDING-or-RUNNING request exists
+ * per job is a partial unique index in the database, not an application
+ * check — mirroring uq_candidate_contact_sessions_active_canonical, which is
+ * the real guarantee behind the claim path.
+ */
+export declare const OutreachRequestStatusSchema: z.ZodEnum<["PENDING", "RUNNING", "COMPLETED", "CANCELLED"]>;
+export type OutreachRequestStatus = z.infer<typeof OutreachRequestStatusSchema>;
+/**
+ * `eligibleAtRequest` is a POINT-IN-TIME snapshot taken when the request was
+ * raised, not a live figure. The pool changes on every send, and refreshing it
+ * would reintroduce the per-job counting cost this design avoids on the feed.
+ * The live number is whatever claim-next finds. Label it as a snapshot.
+ */
+export declare const OutreachRequestSchema: z.ZodObject<{
+    id: z.ZodString;
+    jobId: z.ZodString;
+    status: z.ZodEnum<["PENDING", "RUNNING", "COMPLETED", "CANCELLED"]>;
+    eligibleAtRequest: z.ZodNumber;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    contactedCount: z.ZodNumber;
+    createdAt: z.ZodString;
+    startedAt: z.ZodNullable<z.ZodString>;
+    completedAt: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    createdAt: string;
+    status: "PENDING" | "COMPLETED" | "CANCELLED" | "RUNNING";
+    jobId: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    requestedByName: string | null;
+    contactedCount: number;
+    eligibleAtRequest: number;
+}, {
+    id: string;
+    createdAt: string;
+    status: "PENDING" | "COMPLETED" | "CANCELLED" | "RUNNING";
+    jobId: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    requestedByName: string | null;
+    contactedCount: number;
+    eligibleAtRequest: number;
+}>;
+export type OutreachRequest = z.infer<typeof OutreachRequestSchema>;
+//# sourceMappingURL=outreach-requests.schemas.d.ts.map

package/dist/outreach/outreach-requests.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outreach-requests.schemas.d.ts","sourceRoot":"","sources":["../../contracts/outreach/outreach-requests.schemas.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,6DAEM,CAAC;AAE/C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBM,CAAC;AAEzC,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC"}

package/dist/outreach/outreach-requests.schemas.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutreachRequestSchema = exports.OutreachRequestStatusSchema = void 0;
+/**
+ * Project: Internal Recruitment Platform API
+ * File: outreach-requests.schemas.ts
+ *
+ * Description: The outreach REQUEST queue — an agent marks a job for outreach,
+ * the rack polls the queue and launches a campaign against it.
+ *
+ * Split out of outreach-requests.contract.ts so jobs-tab.contract.ts can import
+ * the status enum for its feed-card payload without importing a ts-rest router.
+ *
+ * Auth: two lanes. Creating and cancelling is a human agent's JWT; listing,
+ * starting and completing is the service account's Bearer key — the same key
+ * the claim routes already accept.
+ */
+const zod_openapi_1 = require("@anatine/zod-openapi");
+const zod_1 = require("zod");
+(0, zod_openapi_1.extendZodWithOpenApi)(zod_1.z);
+/**
+ * `COMPLETED` and `CANCELLED` are terminal and free the job for a new
+ * request. The invariant that at most one PENDING-or-RUNNING request exists
+ * per job is a partial unique index in the database, not an application
+ * check — mirroring uq_candidate_contact_sessions_active_canonical, which is
+ * the real guarantee behind the claim path.
+ */
+exports.OutreachRequestStatusSchema = zod_1.z
+    .enum(['PENDING', 'RUNNING', 'COMPLETED', 'CANCELLED'])
+    .openapi({ title: 'OutreachRequestStatus' });
+/**
+ * `eligibleAtRequest` is a POINT-IN-TIME snapshot taken when the request was
+ * raised, not a live figure. The pool changes on every send, and refreshing it
+ * would reintroduce the per-job counting cost this design avoids on the feed.
+ * The live number is whatever claim-next finds. Label it as a snapshot.
+ */
+exports.OutreachRequestSchema = zod_1.z
+    .object({
+    id: zod_1.z.string().uuid(),
+    jobId: zod_1.z.string().uuid(),
+    status: exports.OutreachRequestStatusSchema,
+    eligibleAtRequest: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .describe('Eligible candidates counted when the request was raised'),
+    requestedByName: zod_1.z
+        .string()
+        .nullable()
+        .describe('Agent who raised the request'),
+    contactedCount: zod_1.z
+        .number()
+        .int()
+        .min(0)
+        .describe('Sends confirmed against this job so far'),
+    createdAt: zod_1.z.string().datetime(),
+    startedAt: zod_1.z.string().datetime().nullable(),
+    completedAt: zod_1.z.string().datetime().nullable(),
+})
+    .openapi({ title: 'OutreachRequest' });