@volter/twin-runhuman 0.1.0

package/src/runhuman-validate.ts

@@ -0,0 +1,185 @@
+// Runhuman 1 request-body validation, transcribed from RH1's own boundary schemas
+// (volter-ai/runhuman packages/shared/src/contracts/job.schema.ts + tester-job.schema.ts, zod ^3)
+// and its Fastify validator compiler (packages/api/src/utils/zod-validator-compiler.ts):
+//
+//   - an absent body validates as `{}`;
+//   - every issue is reported, joined by "; ", each as "<path>: <message>" (path dot-joined);
+//   - the whole string is prefixed "Invalid request body: ";
+//   - Fastify stamps the error statusCode 400 / code FST_ERR_VALIDATION, and RH1's global error
+//     handler serialises it as `{ error, statusCode, code }`.
+//
+// Messages are zod v3's own: "Required", "Expected string, received number",
+// "Invalid enum value. Expected 'a' | 'b', received 'c'", and "Invalid input" for a
+// `z.custom` (RH1's `objectGuard`) that rejects.
+import type { RunhumanTwinResponse } from './runhuman-twin.ts';
+
+export type FieldKind =
+  | { kind: 'string' }
+  | { kind: 'number' }
+  | { kind: 'boolean' }
+  | { kind: 'enum'; values: readonly string[] }
+  | { kind: 'object' } // RH1 objectGuard: plain object, not an array
+  | { kind: 'array'; of: FieldKind }
+  | { kind: 'unknown' };
+
+export type FieldSpec = FieldKind & { required?: boolean; refine?: (value: unknown) => string | undefined };
+
+function zodType(value: unknown): string {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'number' && Number.isNaN(value)) return 'nan';
+  return typeof value;
+}
+
+function checkKind(value: unknown, kind: FieldKind, path: string, issues: string[]): void {
+  const at = (message: string) => issues.push(path ? `${path}: ${message}` : message);
+  switch (kind.kind) {
+    case 'unknown':
+      return;
+    case 'string':
+    case 'number':
+    case 'boolean':
+      if (typeof value !== kind.kind || (kind.kind === 'number' && Number.isNaN(value))) at(`Expected ${kind.kind}, received ${zodType(value)}`);
+      return;
+    case 'enum':
+      if (typeof value !== 'string') {
+        at(`Expected ${kind.values.map((v) => `'${v}'`).join(' | ')}, received ${zodType(value)}`);
+      } else if (!kind.values.includes(value)) {
+        at(`Invalid enum value. Expected ${kind.values.map((v) => `'${v}'`).join(' | ')}, received '${value}'`);
+      }
+      return;
+    case 'object':
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) at('Invalid input');
+      return;
+    case 'array':
+      if (!Array.isArray(value)) {
+        at(`Expected array, received ${zodType(value)}`);
+        return;
+      }
+      value.forEach((el, i) => checkKind(el, kind.of, path ? `${path}.${i}` : String(i), issues));
+      return;
+  }
+}
+
+/** Validate a parsed JSON body against a z.object-shaped field map (unknown keys are stripped, as
+ *  zod's default object does). Returns the 400 RH1 answers, or undefined when the body passes. */
+export function validateBody(body: unknown, fields: Record<string, FieldSpec>): RunhumanTwinResponse | undefined {
+  const input = body === undefined || body === null ? {} : body;
+  const issues: string[] = [];
+  if (typeof input !== 'object' || Array.isArray(input)) {
+    issues.push(`Expected object, received ${zodType(input)}`);
+  } else {
+    const record = input as Record<string, unknown>;
+    for (const [name, spec] of Object.entries(fields)) {
+      const value = record[name];
+      if (value === undefined) {
+        if (spec.required) issues.push(`${name}: Required`);
+        continue;
+      }
+      const before = issues.length;
+      checkKind(value, spec, name, issues);
+      if (issues.length === before && spec.refine) {
+        const message = spec.refine(value);
+        if (message) issues.push(`${name}: ${message}`);
+      }
+    }
+  }
+  if (issues.length === 0) return undefined;
+  const error = `Invalid request body: ${issues.join('; ')}`;
+  return { status: 400, body: { error, statusCode: 400, code: 'FST_ERR_VALIDATION' } };
+}
+
+/** A `z.custom` objectGuard over the whole body (RH1's PATCH /tester/jobs/:jobId schema). */
+export function validateObjectBody(body: unknown): RunhumanTwinResponse | undefined {
+  const input = body === undefined || body === null ? {} : body;
+  if (typeof input === 'object' && !Array.isArray(input)) return undefined;
+  return { status: 400, body: { error: 'Invalid request body: Invalid input', statusCode: 400, code: 'FST_ERR_VALIDATION' } };
+}
+
+const S = { kind: 'string' } as const;
+const N = { kind: 'number' } as const;
+const B = { kind: 'boolean' } as const;
+const O = { kind: 'object' } as const;
+const PREF = { kind: 'enum', values: ['inherit', 'always', 'never'] } as const;
+
+// packages/shared/src/job/device-class.types.ts, tester/tester.types.ts (TESTER_DEVICES,
+// TESTER_LANGUAGES, CLAIM_SOURCES).
+export const DEVICE_CLASSES = ['desktop', 'mobile', 'both'] as const;
+export const TESTER_DEVICES = ['ios', 'android', 'pc', 'mac'] as const;
+export const TESTER_LANGUAGES = ['english', 'spanish'] as const;
+export const CLAIM_SOURCES = ['tester-portal', 'mobile-app', 'slack', 'discord-activity'] as const;
+
+/** createTestJobRequestSchema (POST /api/jobs). */
+export const CREATE_JOB_FIELDS: Record<string, FieldSpec> = {
+  projectId: S,
+  organizationId: S,
+  url: S,
+  description: S,
+  template: S,
+  templateContent: S,
+  targetDurationMinutes: N,
+  maxExtensionMinutes: N,
+  outputSchema: O,
+  resultsTemplate: S,
+  deviceClass: { kind: 'enum', values: DEVICE_CLASSES },
+  screenSize: { kind: 'unknown' },
+  attachments: { kind: 'array', of: O },
+  metadata: {
+    kind: 'object',
+    refine: (value) => {
+      const captureMode = (value as Record<string, unknown>).captureMode;
+      return captureMode === undefined || captureMode === 'supplier' || captureMode === 'external'
+        ? undefined
+        : 'metadata.captureMode must be supplier or external';
+    },
+  },
+  additionalValidationInstructions: S,
+  githubRepos: { kind: 'array', of: S },
+  githubRepo: S,
+  autoCreateGithubIssuesRepo: S,
+  githubToken: S,
+  commitSha: S,
+  enableCodeContext: B,
+  prNumbers: { kind: 'array', of: N },
+  issueNumbers: { kind: 'array', of: N },
+  checkTestability: B,
+  requiredDevices: { kind: 'array', of: { kind: 'enum', values: TESTER_DEVICES } },
+  requiredLanguages: { kind: 'array', of: { kind: 'enum', values: TESTER_LANGUAGES } },
+  requireSocialVideos: B,
+  requireSideload: B,
+  requiresRunhumanApkInstall: B,
+  autoCreateGithubIssues: B,
+  autoCreateGithubFeedback: B,
+  autoCreateJiraFeedback: B,
+  autoCreateJiraIssues: B,
+  autoCreateLinearIssues: B,
+  enhancedVideo: B,
+  enhanceInstructions: B,
+  autoCreateOnlyTesterSurfaced: B,
+  reopenIssuesOnDuplicate: B,
+  commentOnDuplicate: B,
+  slackNotification: O,
+  emailOnCompletion: PREF,
+  inAppOnCompletion: PREF,
+  emailOnFailure: PREF,
+  inAppOnFailure: PREF,
+};
+
+/** claimJobRequestSchema (POST /api/jobs/:jobId/claim): `claimSource` is REQUIRED by the schema
+ *  even though the handler carries a default. */
+export const CLAIM_JOB_FIELDS: Record<string, FieldSpec> = {
+  claimSource: { kind: 'enum', values: CLAIM_SOURCES, required: true },
+};
+
+/** endJobRequestSchema (POST /api/tester/jobs/:jobId/end). */
+export const END_JOB_FIELDS: Record<string, FieldSpec> = {
+  action: { kind: 'enum', values: ['clear_and_release', 'clear_and_cancel', 'save_and_cancel', 'platform_issue'], required: true },
+  note: { kind: 'string', required: true },
+};
+
+/** processTestResultsBodySchema (POST /api/tester/jobs/:jobId/process-results). */
+export const PROCESS_RESULTS_FIELDS: Record<string, FieldSpec> = {
+  job: O,
+  prefillTemplate: S,
+  clientInfo: O,
+};