@dakkitor/api-contracts 1.1.153 → 1.4.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"outreach.contract.d.ts","sourceRoot":"","sources":["../../contracts/outreach/outreach.contract.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,EAAG,EAAW,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;EAIM,CAAC;AAE/C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAYM,CAAC;AAEnD,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;EAoBM,CAAC;AAEjD,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iCAAiC;;;;;;;;;EAOM,CAAC;AAErD,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAC/C,OAAO,iCAAiC,CACzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B;;;;;;;;;;;;EAUM,CAAC;AAElD,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAC5C,OAAO,8BAA8B,CACtC,CAAC;AAEF,eAAO,MAAM,kCAAkC;;;;;;EAIM,CAAC;AAEtD,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAChD,OAAO,kCAAkC,CAC1C,CAAC;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsE5B,CAAC"}

package/dist/outreach/outreach.contract.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outreachContract = exports.ReleaseOutreachLeaseResponseSchema = exports.ReleaseOutreachLeaseBodySchema = exports.ConfirmOutreachSentResponseSchema = exports.ConfirmOutreachSentBodySchema = exports.ClaimNextOutreachResponseSchema = exports.ClaimNextOutreachBodySchema = exports.OUTREACH_LEASE_TTL_MINUTES = void 0;
+/**
+ * Project: Internal Recruitment Platform API
+ * File: outreach.contract.ts
+ *
+ * Description: The outreach claim contract — claim one candidate, confirm the
+ * send, or hand the candidate back unsent. Claiming one at a time (rather than
+ * exporting a list) means eligibility is evaluated at the moment of sending,
+ * reuses the existing one-active-reveal-per-worker lock so an automated send
+ * and a human agent contend for the same lock, and keeps one phone number in
+ * flight at a time.
+ *
+ * Auth: Bearer token in the `authorization` header, issued to a service
+ * account. Nothing in these routes' protection depends on the route being
+ * unknown — this package is published publicly.
+ */
+const core_1 = require("@ts-rest/core");
+const error_schemas_1 = require("../common/error-schemas");
+const zod_1 = require("zod");
+const outreach_schemas_1 = require("./outreach.schemas");
+const c = (0, core_1.initContract)();
+/**
+ * How long a lease is held before it lapses and the candidate returns to the
+ * pool. There is no renewal endpoint: a heartbeat is more machinery than this
+ * needs, and a send still running after this long has gone wrong.
+ *
+ * The value must comfortably exceed the send path — a contact save, a chat
+ * open, up to three bubbles with inter-bubble delays, and verification backoff
+ * — or an expired-then-reclaimed candidate is messaged twice by two handsets.
+ */
+exports.OUTREACH_LEASE_TTL_MINUTES = 15;
+/**
+ * Eligibility is server-side policy and takes NO parameters. The commute
+ * budget, the do-not-contact and cool-down suppressions, and the exclusion of
+ * booked or already-dispositioned candidates all live in the handler. No future
+ * revision should add a "max minutes" argument here.
+ */
+exports.ClaimNextOutreachBodySchema = zod_1.z
+    .object({
+    deviceId: outreach_schemas_1.OutreachDeviceIdSchema,
+})
+    .openapi({ title: 'ClaimNextOutreachBody' });
+/**
+ * An empty pool is not an error. Both outcomes are 200, discriminated on
+ * `status`, because the caller does opposite things in the two cases — wind
+ * the campaign down versus back off and retry — and must be able to tell them
+ * apart without parsing an error string. The discriminated union guarantees
+ * `lease`, `candidate` and `job` are inaccessible without first narrowing on
+ * `status` — it does not force a consumer to handle every branch.
+ */
+exports.ClaimNextOutreachResponseSchema = zod_1.z
+    .discriminatedUnion('status', [
+    zod_1.z.object({
+        status: zod_1.z.literal('CLAIMED'),
+        lease: outreach_schemas_1.OutreachLeaseSchema,
+        candidate: outreach_schemas_1.OutreachCandidateSchema,
+        job: outreach_schemas_1.OutreachJobSchema,
+    }),
+    zod_1.z.object({
+        status: zod_1.z.literal('POOL_EMPTY'),
+    }),
+])
+    .openapi({ title: 'ClaimNextOutreachResponse' });
+/**
+ * `variantKey` and `metadata` are recorded but otherwise unused today. They
+ * exist now so the later message-variant experiment needs no contract change
+ * to become measurable.
+ *
+ * `deliveryVerified` distinguishes a send whose bubble was seen in the
+ * WhatsApp UI from one that was tapped but never confirmed. Both count as
+ * contacted. The flag exists so the second kind can be excluded from analysis
+ * and reviewed by a human — NOT so it can be retried.
+ */
+exports.ConfirmOutreachSentBodySchema = zod_1.z
+    .object({
+    deviceId: outreach_schemas_1.OutreachDeviceIdSchema,
+    variantKey: zod_1.z
+        .string()
+        .min(1)
+        .max(100)
+        .describe('Which message variant was rendered'),
+    deliveryVerified: zod_1.z
+        .boolean()
+        .describe('True when the sent bubble was observed in the WhatsApp UI'),
+    sentAt: zod_1.z
+        .string()
+        .datetime()
+        .describe('ISO-8601 UTC instant the send was performed'),
+    metadata: zod_1.z
+        .record(zod_1.z.unknown())
+        .optional()
+        .describe('Free-form caller diagnostics. Recorded, never interpreted.'),
+})
+    .openapi({ title: 'ConfirmOutreachSentBody' });
+/**
+ * Confirming twice is a success, not a conflict, and confirming against an
+ * expired lease is recorded too — flagged via `lateConfirm`. The message really
+ * was sent; refusing to record it is how a worker gets messaged twice.
+ */
+exports.ConfirmOutreachSentResponseSchema = zod_1.z
+    .object({
+    recorded: zod_1.z.literal(true),
+    lateConfirm: zod_1.z
+        .boolean()
+        .describe('True when the lease had already expired at confirm time'),
+})
+    .openapi({ title: 'ConfirmOutreachSentResponse' });
+/**
+ * Hands a candidate back to the pool unsent. For failures BEFORE the send
+ * button is tapped — a contact save that failed, a chat that would not open, a
+ * compose step that errored. Never after a send.
+ */
+exports.ReleaseOutreachLeaseBodySchema = zod_1.z
+    .object({
+    deviceId: outreach_schemas_1.OutreachDeviceIdSchema,
+    reason: outreach_schemas_1.OutreachReleaseReasonSchema,
+    detail: zod_1.z
+        .string()
+        .max(500)
+        .optional()
+        .describe('Free-text elaboration, most useful alongside OTHER'),
+})
+    .openapi({ title: 'ReleaseOutreachLeaseBody' });
+exports.ReleaseOutreachLeaseResponseSchema = zod_1.z
+    .object({
+    released: zod_1.z.literal(true),
+})
+    .openapi({ title: 'ReleaseOutreachLeaseResponse' });
+exports.outreachContract = c.router({
+    claimNext: {
+        method: 'POST',
+        path: '/outreach/jobs/:jobId/claim-next',
+        pathParams: zod_1.z.object({
+            jobId: zod_1.z.string().uuid().describe('Job to claim a candidate for'),
+        }),
+        body: exports.ClaimNextOutreachBodySchema,
+        responses: {
+            // Exhaustion is a 200 with status POOL_EMPTY, never an error.
+            200: exports.ClaimNextOutreachResponseSchema,
+            // A genuine conflict: the candidate was locked by someone else between
+            // selection and insert. The caller backs off and re-claims.
+            409: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Claim the next eligible candidate for a job',
+        description: 'Idempotent per device: a device that already holds an active lease ' +
+            'gets that lease back rather than an error, so a request that times ' +
+            'out after the server created the lease is safe to retry. Eligibility ' +
+            'is server-side policy and takes no parameters.',
+        metadata: { tags: ['Outreach'] },
+    },
+    confirmSent: {
+        method: 'POST',
+        path: '/outreach/leases/:leaseId/sent',
+        pathParams: zod_1.z.object({
+            leaseId: zod_1.z.string().uuid().describe('Lease being confirmed'),
+        }),
+        body: exports.ConfirmOutreachSentBodySchema,
+        responses: {
+            200: exports.ConfirmOutreachSentResponseSchema,
+            // The lease was never issued, or has been swept.
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Confirm that a message was sent under a lease',
+        description: 'Idempotent: confirming twice succeeds. An expired lease is accepted ' +
+            'and recorded with lateConfirm=true — the message really was sent, ' +
+            'and refusing to record it is how a worker gets messaged twice.',
+        metadata: { tags: ['Outreach'] },
+    },
+    release: {
+        method: 'POST',
+        path: '/outreach/leases/:leaseId/release',
+        pathParams: zod_1.z.object({
+            leaseId: zod_1.z.string().uuid().describe('Lease being released'),
+        }),
+        body: exports.ReleaseOutreachLeaseBodySchema,
+        responses: {
+            200: exports.ReleaseOutreachLeaseResponseSchema,
+            404: error_schemas_1.ErrorResponseSchema,
+        },
+        summary: 'Return a claimed candidate to the pool unsent',
+        description: 'For failures before the send button is tapped. Never after a send — ' +
+            'a tapped send is confirmed, not released.',
+        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.schemas.d.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+/**
+ * Which lane the claimed candidate lives in. `subjectId` is scoped by this:
+ * an OWNED subject is a `workers` row, a CURATED subject is a
+ * `curated_workers` row.
+ *
+ * `subjectKind` does NOT determine `canonicalKind`: an OWNED subject backed
+ * by a linked `curated_workers` row resolves to canonicalKind
+ * `CURATED_WORKER`, not `WORKER`. The pair `(canonicalKind, canonicalId)` —
+ * never `canonicalId` alone — is the canonical identity that spans both
+ * lanes.
+ */
+export declare const OutreachSubjectKindSchema: z.ZodEnum<["OWNED", "CURATED"]>;
+export type OutreachSubjectKind = z.infer<typeof OutreachSubjectKindSchema>;
+/**
+ * The table `canonicalId` is a row id in: `WORKER` for `workers`,
+ * `CURATED_WORKER` for `curated_workers`. This is NOT derivable from
+ * `subjectKind` (see the note on that schema) — it must travel alongside
+ * `canonicalId` rather than be inferred from it, because the pair is what
+ * every ledger table keys canonical identity on.
+ */
+export declare const OutreachCanonicalKindSchema: z.ZodEnum<["WORKER", "CURATED_WORKER"]>;
+export type OutreachCanonicalKind = z.infer<typeof OutreachCanonicalKindSchema>;
+/**
+ * The mode the returned `commuteMinutes` was MEASURED against, after the
+ * server-side fallback is applied — a candidate with no saved transportation
+ * method comes back as PUBLIC_TRANSPORT, never null.
+ *
+ * Only two values exist because proximity measures exactly two things:
+ * drive minutes and transit minutes. This is not the worker's saved
+ * transportation method (OWN_CAR / OWN_VAN / MOTORCYCLE / …) — reporting
+ * OWN_VAN would imply a measurement that does not exist. The consumer renders
+ * from this field and never re-derives it.
+ */
+export declare const OutreachTransportModeSchema: z.ZodEnum<["DRIVE", "PUBLIC_TRANSPORT"]>;
+export type OutreachTransportMode = z.infer<typeof OutreachTransportModeSchema>;
+/**
+ * An opaque correlation key for the handset that produced an outcome. This API
+ * never parses it, never validates it against a registry, and stores no device
+ * table — the caller owns what a device is. The bounds exist only to keep a
+ * runaway value out of the database.
+ */
+export declare const OutreachDeviceIdSchema: z.ZodString;
+export type OutreachDeviceId = z.infer<typeof OutreachDeviceIdSchema>;
+/**
+ * Why a lease was handed back unsent. Only for failures BEFORE the send button
+ * is tapped; a tapped send is confirmed, never released.
+ */
+export declare const OutreachReleaseReasonSchema: z.ZodEnum<["CONTACT_SAVE_FAILED", "CHAT_OPEN_FAILED", "COMPOSE_FAILED", "OTHER"]>;
+export type OutreachReleaseReason = z.infer<typeof OutreachReleaseReasonSchema>;
+export declare const OutreachLeaseSchema: z.ZodObject<{
+    leaseId: z.ZodString;
+    expiresAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    leaseId: string;
+    expiresAt: string;
+}, {
+    leaseId: string;
+    expiresAt: string;
+}>;
+export type OutreachLease = z.infer<typeof OutreachLeaseSchema>;
+export declare const OutreachCandidateSchema: z.ZodObject<{
+    subjectKind: z.ZodEnum<["OWNED", "CURATED"]>;
+    subjectId: z.ZodString;
+    canonicalKind: z.ZodEnum<["WORKER", "CURATED_WORKER"]>;
+    canonicalId: z.ZodString;
+    name: z.ZodString;
+    phoneNumber: z.ZodString;
+    commuteMinutes: z.ZodNumber;
+    transportMode: z.ZodEnum<["DRIVE", "PUBLIC_TRANSPORT"]>;
+}, "strip", z.ZodTypeAny, {
+    subjectKind: "OWNED" | "CURATED";
+    subjectId: string;
+    canonicalKind: "WORKER" | "CURATED_WORKER";
+    canonicalId: string;
+    name: string;
+    phoneNumber: string;
+    commuteMinutes: number;
+    transportMode: "DRIVE" | "PUBLIC_TRANSPORT";
+}, {
+    subjectKind: "OWNED" | "CURATED";
+    subjectId: string;
+    canonicalKind: "WORKER" | "CURATED_WORKER";
+    canonicalId: string;
+    name: string;
+    phoneNumber: string;
+    commuteMinutes: number;
+    transportMode: "DRIVE" | "PUBLIC_TRANSPORT";
+}>;
+export type OutreachCandidate = z.infer<typeof OutreachCandidateSchema>;
+/**
+ * Enough of the job to compose a message. Everything but the title is nullable
+ * because real jobs routinely lack pay or trade text, and a missing field must
+ * not make a candidate unclaimable.
+ */
+export declare const OutreachJobSchema: z.ZodObject<{
+    title: z.ZodString;
+    trade: z.ZodNullable<z.ZodString>;
+    payText: z.ZodNullable<z.ZodString>;
+    locationText: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    trade: string | null;
+    payText: string | null;
+    locationText: string | null;
+}, {
+    title: string;
+    trade: string | null;
+    payText: string | null;
+    locationText: string | null;
+}>;
+export type OutreachJob = z.infer<typeof OutreachJobSchema>;
+//# sourceMappingURL=outreach.schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"outreach.schemas.d.ts","sourceRoot":"","sources":["../../contracts/outreach/outreach.schemas.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,iCAEM,CAAC;AAE7C,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,yCAEM,CAAC;AAE/C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,0CAEM,CAAC;AAE/C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,aAIkC,CAAC;AAEtE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,2BAA2B,mFAEM,CAAC;AAE/C,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,mBAAmB;;;;;;;;;EAQM,CAAC;AAEvC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCM,CAAC;AAE3C,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAOM,CAAC;AAErC,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/outreach/outreach.schemas.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutreachJobSchema = exports.OutreachCandidateSchema = exports.OutreachLeaseSchema = exports.OutreachReleaseReasonSchema = exports.OutreachDeviceIdSchema = exports.OutreachTransportModeSchema = exports.OutreachCanonicalKindSchema = exports.OutreachSubjectKindSchema = void 0;
+/**
+ * Project: Internal Recruitment Platform API
+ * File: outreach.schemas.ts
+ *
+ * Description: Primitive shapes for the outreach claim contract — the wire
+ * format between this API and Relay Lab, which drives owned Android handsets
+ * through the real WhatsApp UI.
+ *
+ * Auth: these routes use the platform's existing scheme, a Bearer token in the
+ * `authorization` header, issued to a service account. The header is not
+ * declared in the contract (no route in this package declares headers); it is
+ * documented here so an external consumer knows what to send.
+ *
+ * This module deliberately defines its own shapes rather than importing from
+ * `workers`, `jobs` or `curated-worker-leads`: those contracts are densely
+ * cross-linked, and a consumer outside this monorepo should not have to compile
+ * the booking, crew and qualification graph to claim a candidate.
+ */
+const zod_openapi_1 = require("@anatine/zod-openapi");
+const zod_1 = require("zod");
+(0, zod_openapi_1.extendZodWithOpenApi)(zod_1.z);
+/**
+ * Which lane the claimed candidate lives in. `subjectId` is scoped by this:
+ * an OWNED subject is a `workers` row, a CURATED subject is a
+ * `curated_workers` row.
+ *
+ * `subjectKind` does NOT determine `canonicalKind`: an OWNED subject backed
+ * by a linked `curated_workers` row resolves to canonicalKind
+ * `CURATED_WORKER`, not `WORKER`. The pair `(canonicalKind, canonicalId)` —
+ * never `canonicalId` alone — is the canonical identity that spans both
+ * lanes.
+ */
+exports.OutreachSubjectKindSchema = zod_1.z
+    .enum(['OWNED', 'CURATED'])
+    .openapi({ title: 'OutreachSubjectKind' });
+/**
+ * The table `canonicalId` is a row id in: `WORKER` for `workers`,
+ * `CURATED_WORKER` for `curated_workers`. This is NOT derivable from
+ * `subjectKind` (see the note on that schema) — it must travel alongside
+ * `canonicalId` rather than be inferred from it, because the pair is what
+ * every ledger table keys canonical identity on.
+ */
+exports.OutreachCanonicalKindSchema = zod_1.z
+    .enum(['WORKER', 'CURATED_WORKER'])
+    .openapi({ title: 'OutreachCanonicalKind' });
+/**
+ * The mode the returned `commuteMinutes` was MEASURED against, after the
+ * server-side fallback is applied — a candidate with no saved transportation
+ * method comes back as PUBLIC_TRANSPORT, never null.
+ *
+ * Only two values exist because proximity measures exactly two things:
+ * drive minutes and transit minutes. This is not the worker's saved
+ * transportation method (OWN_CAR / OWN_VAN / MOTORCYCLE / …) — reporting
+ * OWN_VAN would imply a measurement that does not exist. The consumer renders
+ * from this field and never re-derives it.
+ */
+exports.OutreachTransportModeSchema = zod_1.z
+    .enum(['DRIVE', 'PUBLIC_TRANSPORT'])
+    .openapi({ title: 'OutreachTransportMode' });
+/**
+ * An opaque correlation key for the handset that produced an outcome. This API
+ * never parses it, never validates it against a registry, and stores no device
+ * table — the caller owns what a device is. The bounds exist only to keep a
+ * runaway value out of the database.
+ */
+exports.OutreachDeviceIdSchema = zod_1.z
+    .string()
+    .min(1)
+    .max(200)
+    .describe('Opaque, caller-owned handset identifier. Never parsed.');
+/**
+ * Why a lease was handed back unsent. Only for failures BEFORE the send button
+ * is tapped; a tapped send is confirmed, never released.
+ */
+exports.OutreachReleaseReasonSchema = zod_1.z
+    .enum(['CONTACT_SAVE_FAILED', 'CHAT_OPEN_FAILED', 'COMPOSE_FAILED', 'OTHER'])
+    .openapi({ title: 'OutreachReleaseReason' });
+exports.OutreachLeaseSchema = zod_1.z
+    .object({
+    leaseId: zod_1.z.string().uuid().describe('Lease identifier'),
+    expiresAt: zod_1.z
+        .string()
+        .datetime()
+        .describe('ISO-8601 UTC instant the lease lapses'),
+})
+    .openapi({ title: 'OutreachLease' });
+exports.OutreachCandidateSchema = zod_1.z
+    .object({
+    subjectKind: exports.OutreachSubjectKindSchema,
+    subjectId: zod_1.z
+        .string()
+        .uuid()
+        .describe('Row id within the lane named by subjectKind'),
+    canonicalKind: exports.OutreachCanonicalKindSchema,
+    canonicalId: zod_1.z
+        .string()
+        .uuid()
+        .describe('Canonical worker row id. Not derivable from subjectKind: the pair ' +
+        '(canonicalKind, canonicalId) — not canonicalId alone — is the ' +
+        'canonical identity that spans the owned and curated lanes.'),
+    name: zod_1.z.string().min(1).describe('Display name'),
+    phoneNumber: zod_1.z
+        .string()
+        .min(1)
+        .describe('E.164 phone number. Not re-validated on the way out: a real number ' +
+        'that a validator dislikes must still be sendable.'),
+    commuteMinutes: zod_1.z
+        .number()
+        .nonnegative()
+        .describe('Door-to-door minutes for transportMode. Not necessarily a whole ' +
+        'number: the source proximity columns are floats. Never null: ' +
+        'eligibility is strict on unknown travel times, so a claimed ' +
+        'candidate always has one.'),
+    transportMode: exports.OutreachTransportModeSchema,
+})
+    .openapi({ title: 'OutreachCandidate' });
+/**
+ * Enough of the job to compose a message. Everything but the title is nullable
+ * because real jobs routinely lack pay or trade text, and a missing field must
+ * not make a candidate unclaimable.
+ */
+exports.OutreachJobSchema = zod_1.z
+    .object({
+    title: zod_1.z.string().min(1).describe('Job title'),
+    trade: zod_1.z.string().nullable().describe('Trade label, if known'),
+    payText: zod_1.z.string().nullable().describe('Pay as displayed, if known'),
+    locationText: zod_1.z.string().nullable().describe('Location as displayed'),
+})
+    .openapi({ title: 'OutreachJob' });