@crowdsource.you/core 1.2.0

package/dist/webhookEndpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhookEndpoints.js","sourceRoot":"","sources":["../src/webhookEndpoints.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "@crowdsource.you/core",
+  "version": "1.2.0",
+  "description": "The CrowdSource integration: the API client at the root, and the Express webhook receiver, the transactional outbox and the test sandbox behind subpaths",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/express/index.d.ts",
+      "import": "./dist/esm/express/index.js",
+      "require": "./dist/express/index.js",
+      "default": "./dist/express/index.js"
+    },
+    "./outbox": {
+      "types": "./dist/outbox/index.d.ts",
+      "import": "./dist/esm/outbox/index.js",
+      "require": "./dist/outbox/index.js",
+      "default": "./dist/outbox/index.js"
+    },
+    "./outbox/postgres": {
+      "types": "./dist/outbox/postgres/index.d.ts",
+      "import": "./dist/esm/outbox/postgres/index.js",
+      "require": "./dist/outbox/postgres/index.js",
+      "default": "./dist/outbox/postgres/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/esm/testing/index.js",
+      "require": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "express": ["./dist/express/index.d.ts"],
+      "outbox": ["./dist/outbox/index.d.ts"],
+      "outbox/postgres": ["./dist/outbox/postgres/index.d.ts"],
+      "testing": ["./dist/testing/index.d.ts"]
+    }
+  },
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.esm.json && bun ../../scripts/write-esm-marker.mjs",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "db:generate": "drizzle-kit generate",
+    "lint": "tsc --noEmit --noUnusedLocals --noUnusedParameters && tsc -p tsconfig.test.json",
+    "test": "bun run test:unit && bun run test:express && bun run test:testing && bun run test:outbox && bun run test:invariants && bun run test:table-type",
+    "test:unit": "node ../../node_modules/vitest/vitest.mjs run",
+    "test:express": "node ../../node_modules/vitest/vitest.mjs run -c vitest.express.config.ts",
+    "test:outbox": "node ../../node_modules/vitest/vitest.mjs run -c vitest.outbox.config.ts",
+    "test:testing": "node ../../node_modules/vitest/vitest.mjs run -c vitest.testing.config.ts",
+    "test:invariants": "bun ./scripts/test-invariants.mjs",
+    "test:table-type": "bun ./scripts/test-report-table-type.mjs",
+    "test:watch": "node ../../node_modules/vitest/vitest.mjs",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "crowdsource",
+    "moderation",
+    "sdk",
+    "outbox",
+    "webhooks",
+    "express",
+    "postgresql"
+  ],
+  "author": "OxyHQ",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OxyHQ/CrowdSource",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/OxyHQ/CrowdSource/tree/main/packages/core#readme",
+  "bugs": "https://github.com/OxyHQ/CrowdSource/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@crowdsource.you/contracts": "1.1.0",
+    "@oxy.so/db": "^1.0.0",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.9.5",
+    "drizzle-kit": "^0.31.10",
+    "drizzle-orm": "^0.45.2",
+    "express": "^5.2.1",
+    "postgres": "^3.4.9",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "!src/**/__tests__/**"
+  ],
+  "peerDependencies": {
+    "@crowdsource.you/contracts": "^1.1.0",
+    "@oxy.so/db": "^1.0.0",
+    "drizzle-orm": "^0.45.2",
+    "express": ">=4.18.0 <6",
+    "postgres": "^3.4.9"
+  },
+  "peerDependenciesMeta": {
+    "@oxy.so/db": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
+    }
+  }
+}

package/src/cases.ts

@@ -0,0 +1,119 @@
+/**
+ * `GET /v1/cases/{id}` and `GET /v1/decisions/{id}` (§10.2).
+ *
+ * Both are look-ups by an id CrowdSource gave the application. There is no case
+ * search and there will not be one: "nobody chooses the case they review" is an
+ * invariant, and a list endpoint on the application API would be the first step
+ * towards a queue somebody browses.
+ *
+ * `decisions.get` is written against the route §10.2 defines. **The backend does
+ * not serve it yet** — nothing publishes decisions, because sortition, review
+ * and consensus are not built — so it answers 404 today. It is here because a
+ * client of a documented endpoint is not a stub, and because the webhook path
+ * (`case.decided`) is how an application learns about a decision anyway; this is
+ * the read-back for one it already has an id for.
+ */
+
+import { DecisionSchema, type Decision, type TaxonomyCode } from '@crowdsource.you/contracts';
+import { z } from 'zod';
+
+import { CrowdSourceTransportError } from './errors.js';
+import type { Transport } from './transport.js';
+
+/**
+ * The projection §10.2 returns for a case.
+ *
+ * Deliberately not the case document. Priority score, review pool and reporter
+ * fingerprints never leave the service — an application that could read its own
+ * cases' priority could learn which signals move it.
+ */
+export interface CaseView {
+  readonly caseId: string;
+  readonly status: string;
+  readonly subject: { readonly externalId: string; readonly type: string };
+  readonly policy: { readonly policySetId: string; readonly version: string };
+  readonly taxonomyVersion: string;
+  readonly allegationCodes: readonly (TaxonomyCode | (string & {}))[];
+  /** How many reports merged into this case. §7.3: many reports, one case. */
+  readonly reportCount: number;
+  readonly sensitivityClass: string;
+  readonly currentRevision: number;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+const CaseViewSchema = z.looseObject({
+  caseId: z.string(),
+  status: z.string(),
+  subject: z.looseObject({ externalId: z.string(), type: z.string() }),
+  policy: z.looseObject({ policySetId: z.string(), version: z.string() }),
+  taxonomyVersion: z.string(),
+  allegationCodes: z.array(z.string()),
+  reportCount: z.number(),
+  sensitivityClass: z.string(),
+  currentRevision: z.number(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export interface ReadOptions {
+  readonly signal?: AbortSignal;
+}
+
+export class Cases {
+  private readonly transport: Transport;
+
+  constructor(transport: Transport) {
+    this.transport = transport;
+  }
+
+  async get(caseId: string, options: ReadOptions = {}): Promise<CaseView> {
+    const response = await this.transport.request<unknown>({
+      method: 'GET',
+      path: `/v1/cases/${encodeURIComponent(caseId)}`,
+      signal: options.signal,
+    });
+
+    const parsed = CaseViewSchema.safeParse(response);
+    if (!parsed.success) {
+      throw new CrowdSourceTransportError(
+        'CrowdSource answered with a case this client does not recognise.',
+        { retryable: false, cause: parsed.error },
+      );
+    }
+    return parsed.data;
+  }
+}
+
+export class Decisions {
+  private readonly transport: Transport;
+
+  constructor(transport: Transport) {
+    this.transport = transport;
+  }
+
+  /**
+   * Reads one immutable revision of a decision.
+   *
+   * A published revision is never edited (Appendix F); a later revision
+   * supersedes it and carries `supersedesDecisionId`. So a decision read twice
+   * is byte-identical, and an application that cached one never needs to
+   * invalidate it — it needs to notice a `decision.corrected` webhook.
+   */
+  async get(decisionId: string, options: ReadOptions = {}): Promise<Decision> {
+    const response = await this.transport.request<unknown>({
+      method: 'GET',
+      path: `/v1/decisions/${encodeURIComponent(decisionId)}`,
+      signal: options.signal,
+    });
+
+    const parsed = DecisionSchema.safeParse(response);
+    if (!parsed.success) {
+      throw new CrowdSourceTransportError(
+        'CrowdSource answered with a decision this client does not recognise.',
+        { retryable: false, cause: parsed.error },
+      );
+    }
+    return parsed.data;
+  }
+}

package/src/client.ts

@@ -0,0 +1,202 @@
+/**
+ * The client.
+ *
+ * The whole design target is the length of the smallest integration:
+ *
+ *     const crowdsource = new CrowdSource();
+ *     await crowdsource.reports.create({ ... });
+ *
+ * Everything else has a default that is correct for the overwhelming majority of
+ * integrators and a way to override it for the rest. The service key comes from
+ * the environment, the base URL is the one deployment CrowdSource has, and the
+ * envelope, the policy version, the digests, the principal refs and the
+ * idempotency key are all composed rather than configured.
+ *
+ * This client is SERVER-SIDE ONLY. A service credential is the tenant's identity
+ * for its whole moderation stream; shipping one to a browser or a mobile bundle
+ * hands every user of the application the ability to file reports as the
+ * application, read its cases and exhaust its quota. The package depends on
+ * `node:crypto` and does not build for a browser, which is the intended
+ * outcome rather than a limitation to work around.
+ */
+
+import { Cases, Decisions } from './cases.js';
+import { CommunityNotes } from './communityNotes.js';
+import { parseServiceKey, type ServiceCredential } from './credential.js';
+import { DEFAULT_BASE_URL } from './defaults.js';
+import { CrowdSourceConfigurationError } from './errors.js';
+import { Reports } from './reports.js';
+import {
+  DEFAULT_MAX_ATTEMPTS,
+  DEFAULT_TIMEOUT_MS,
+  Transport,
+  type FetchLike,
+} from './transport.js';
+import { WebhookEndpoints } from './webhookEndpoints.js';
+
+/** The environment variable a zero-configuration integration reads. */
+export const SERVICE_KEY_ENV_VAR = 'CROWDSOURCE_SERVICE_KEY';
+
+/** Overrides the service host. Set only when pointing at a local backend. */
+export const BASE_URL_ENV_VAR = 'CROWDSOURCE_BASE_URL';
+
+export interface CrowdSourceOptions {
+  /**
+   * The service key CrowdSource issued, as one opaque string. Defaults to
+   * `process.env.CROWDSOURCE_SERVICE_KEY`.
+   *
+   * There is no `applicationId` option here or anywhere else. The application a
+   * report belongs to is read off this credential — see `credential.ts`.
+   */
+  readonly serviceKey?: string;
+  /**
+   * A first-party Oxy service authenticating with NO CrowdSource credential.
+   *
+   * Return a current Oxy service token; it is asked for once per request
+   * attempt, so returning a cached token and refreshing it when it expires is
+   * the expected shape (`oxyServices.getServiceToken()` does exactly that).
+   *
+   * With this set, `serviceKey` is neither needed nor read. CrowdSource resolves
+   * the tenant from the Oxy application the token names, so nothing here has to
+   * be issued, stored or rotated by a person. Third parties keep the service
+   * key: they run where Oxy cannot vouch for them.
+   */
+  readonly oxyToken?: () => string | Promise<string>;
+  readonly baseUrl?: string;
+  /** Per-attempt deadline. Default 10s. */
+  readonly timeoutMs?: number;
+  /** Attempts per call including the first, for retryable failures. Default 3. */
+  readonly maxAttempts?: number;
+  /**
+   * Marks reports as coming from the application's own pre-production (§5.1
+   * `source.environment`). CrowdSource has one deployment; this is a property of
+   * the report, not a different host to talk to.
+   *
+   * Every report from a sandbox client must carry `submittedAt`, because the
+   * environment travels inside `source` and `source` cannot be composed without
+   * one — see `ReportInput.submittedAt` for why inventing that timestamp would
+   * turn every retry into a 409.
+   */
+  readonly sandbox?: boolean;
+  /** Injected for tests and for the in-process sandbox. Defaults to global `fetch`. */
+  readonly fetch?: FetchLike;
+}
+
+export class CrowdSource {
+  /**
+   * The application this client acts as.
+   *
+   * Read off the credential when there is one. With an Oxy token there is
+   * nothing to read it off — the mapping lives in CrowdSource — so it resolves
+   * on first use from `GET /v1/applications/me` and is remembered.
+   */
+  readonly applicationId: string | Promise<string>;
+
+  readonly reports: Reports;
+  readonly cases: Cases;
+  readonly decisions: Decisions;
+  /** Where decisions get delivered, and the secret that signs them (§10.2). */
+  readonly webhookEndpoints: WebhookEndpoints;
+  /** Community notes: write, withdraw, draw to rate, rate, and the reads. */
+  readonly communityNotes: CommunityNotes;
+
+  constructor(options: CrowdSourceOptions = {}) {
+    /**
+     * Two ways to be an application, and exactly one of them is configured.
+     *
+     * The Oxy path is checked first so that a deployment which has BOTH — during
+     * the migration off shared secrets — uses the identity it can prove rather
+     * than the secret it still happens to hold. Removing the key is then the
+     * cleanup, not the cutover.
+     */
+    const credential: ServiceCredential | null = options.oxyToken
+      ? null
+      : parseServiceKey(options.serviceKey ?? process.env[SERVICE_KEY_ENV_VAR] ?? '');
+
+    const baseUrl = normalisedBaseUrl(
+      options.baseUrl ?? process.env[BASE_URL_ENV_VAR] ?? DEFAULT_BASE_URL,
+    );
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+      throw new CrowdSourceConfigurationError(
+        'This runtime has no global fetch. Pass one as the `fetch` option.',
+      );
+    }
+
+    const oxyToken = options.oxyToken;
+    const transport = new Transport({
+      baseUrl,
+      bearerToken: credential ? () => credential.bearerToken : () => oxyToken!(),
+      timeoutMs,
+      maxAttempts: options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+      fetch: fetchImpl,
+    });
+
+    this.applicationId = credential ? credential.applicationId : lazyApplicationId(transport);
+    this.reports = new Reports({
+      transport,
+      applicationId: this.applicationId,
+      environment: options.sandbox === true ? 'sandbox' : 'production',
+    });
+    this.cases = new Cases(transport);
+    this.decisions = new Decisions(transport);
+    this.webhookEndpoints = new WebhookEndpoints(transport);
+    this.communityNotes = new CommunityNotes(transport);
+  }
+}
+
+
+/**
+ * Asks CrowdSource which application this client is, once.
+ *
+ * Only the Oxy-token path needs this: a service key carries the id inside it.
+ * The promise is created at construction and awaited wherever the id is used,
+ * so the lookup happens at most once per client and never blocks a caller that
+ * does not need it (community notes never do; a report does, because its
+ * envelope names the application and the server refuses one that disagrees).
+ *
+ * A failure is not swallowed into a placeholder id. An envelope carrying the
+ * wrong application is refused by the server anyway, and a client that invented
+ * one would turn a clear "we could not identify you" into a confusing 403 on
+ * every report.
+ */
+function lazyApplicationId(transport: Transport): Promise<string> {
+  let pending: Promise<string> | null = null;
+  const resolve = () => (pending ??= askApplicationId(transport));
+  // A thenable rather than a promise: nothing is requested until somebody
+  // awaits it, so a client that only reads community notes — which never name
+  // an application — makes no identity call at all. Awaiting it twice still
+  // makes one.
+  return { then: (onFulfilled, onRejected) => resolve().then(onFulfilled, onRejected) } as Promise<string>;
+}
+
+function askApplicationId(transport: Transport): Promise<string> {
+  return transport
+    .request<{ applicationId?: unknown }>({ method: 'GET', path: '/v1/applications/me' })
+    .then((body) => {
+      const applicationId = body?.applicationId;
+      if (typeof applicationId !== 'string' || applicationId.length === 0) {
+        throw new CrowdSourceConfigurationError(
+          'CrowdSource did not name the application this token belongs to.',
+        );
+      }
+      return applicationId;
+    });
+}
+
+function normalisedBaseUrl(value: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new CrowdSourceConfigurationError(`'${value}' is not a usable CrowdSource base URL.`);
+  }
+  if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost') {
+    throw new CrowdSourceConfigurationError(
+      'A CrowdSource base URL must be https. A service credential sent in clear is a credential you have to rotate.',
+    );
+  }
+  // Trailing slashes are stripped so `${baseUrl}/v1/reports` never doubles up.
+  return parsed.origin + parsed.pathname.replace(/\/+$/, '');
+}

package/src/communityNotes.ts

@@ -0,0 +1,194 @@
+import {
+  CommunityNoteAssignmentBatchSchema,
+  CommunityNoteListSchema,
+  CommunityNoteRatedListSchema,
+  CommunityNoteRatingSchema,
+  CommunityNoteSchema,
+  ShownCommunityNotesSchema,
+  type CommunityNote,
+  type CommunityNoteAssignment,
+  type CommunityNoteAssignmentRequest,
+  type CommunityNoteRatedList,
+  type CommunityNoteRating,
+  type CommunityNoteRatingSubmission,
+  type CommunityNoteSubmission,
+} from '@crowdsource.you/contracts';
+import type { z } from 'zod';
+
+import { sha256Digest } from './digest.js';
+import { CrowdSourceTransportError } from './errors.js';
+import type { Transport } from './transport.js';
+
+/**
+ * Community notes (`docs/architecture/community-notes.md`): reader-written context
+ * under the application's subjects, shown once raters of different viewpoints
+ * agree it is helpful.
+ *
+ * The application acts for its users, naming each by its own opaque principal id.
+ * Every write is retry-safe with no key from the caller where one can be derived
+ * from what the write IS — one note per writer per subject, one rating per rater
+ * per note — and the derived keys hash the principal ids, so an application's
+ * user ids never travel in a header a proxy might log. Drawing notes to rate has
+ * no such identity (two draws for one rater are two different requests), so that
+ * one method takes the key from the caller.
+ */
+
+export interface CommunityNoteRequestOptions {
+  readonly idempotencyKey?: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface CommunityNoteReadOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** A stable, header-safe digest of the parts that identify a write. */
+function digestOf(...parts: readonly string[]): string {
+  return sha256Digest(JSON.stringify(parts)).replace('sha256:', '');
+}
+
+export class CommunityNotes {
+  private readonly transport: Transport;
+
+  constructor(transport: Transport) {
+    this.transport = transport;
+  }
+
+  /** Writes a note. A retry of the same writer's note on the same subject returns it. */
+  async write(submission: CommunityNoteSubmission, options: CommunityNoteRequestOptions = {}): Promise<CommunityNote> {
+    return this.parse(
+      CommunityNoteSchema,
+      await this.transport.request<unknown>({
+        method: 'POST',
+        path: '/v1/community-notes',
+        body: submission,
+        idempotencyKey:
+          options.idempotencyKey ??
+          `community-note.${digestOf(submission.externalSubjectId, submission.authorPrincipalId)}`,
+        signal: options.signal,
+      }),
+      'a community note',
+    );
+  }
+
+  /** Withdraws a note. Only its writer may; anyone else's note answers 404. */
+  async withdraw(
+    noteId: string,
+    authorPrincipalId: string,
+    options: CommunityNoteRequestOptions = {},
+  ): Promise<CommunityNote> {
+    return this.parse(
+      CommunityNoteSchema,
+      await this.transport.request<unknown>({
+        method: 'POST',
+        path: `/v1/community-notes/${encodeURIComponent(noteId)}/withdraw`,
+        body: { authorPrincipalId },
+        idempotencyKey: options.idempotencyKey ?? `community-note-withdrawal.${digestOf(noteId)}`,
+        signal: options.signal,
+      }),
+      'a community note',
+    );
+  }
+
+  /**
+   * Draws notes for one rater to rate — the ONLY way to be allowed to rate one.
+   *
+   * `idempotencyKey` is required: a retry with the same key returns the same
+   * batch, and a new key is a new draw.
+   */
+  async drawToRate(
+    request: CommunityNoteAssignmentRequest,
+    options: CommunityNoteRequestOptions & { readonly idempotencyKey: string },
+  ): Promise<CommunityNoteAssignment[]> {
+    const batch = this.parse(
+      CommunityNoteAssignmentBatchSchema,
+      await this.transport.request<unknown>({
+        method: 'POST',
+        path: '/v1/community-notes/assignments',
+        body: request,
+        idempotencyKey: options.idempotencyKey,
+        signal: options.signal,
+      }),
+      'a batch of community note assignments',
+    );
+    return batch.assignments;
+  }
+
+  /** Rates a note assigned to the rater. Final: a second rating is refused. */
+  async rate(
+    noteId: string,
+    submission: CommunityNoteRatingSubmission,
+    options: CommunityNoteRequestOptions = {},
+  ): Promise<CommunityNoteRating> {
+    return this.parse(
+      CommunityNoteRatingSchema,
+      await this.transport.request<unknown>({
+        method: 'POST',
+        path: `/v1/community-notes/${encodeURIComponent(noteId)}/ratings`,
+        body: submission,
+        idempotencyKey:
+          options.idempotencyKey ?? `community-note-rating.${digestOf(noteId, submission.raterPrincipalId)}`,
+        signal: options.signal,
+      }),
+      'a community note rating',
+    );
+  }
+
+  /** The shown note, if any, for each of up to 50 subjects. */
+  async shown(externalSubjectIds: readonly string[], options: CommunityNoteReadOptions = {}): Promise<CommunityNote[]> {
+    const subjects = [...new Set(externalSubjectIds)];
+    if (subjects.length === 0) return [];
+    const response = this.parse(
+      ShownCommunityNotesSchema,
+      await this.transport.request<unknown>({
+        method: 'GET',
+        path: `/v1/community-notes/shown?subjects=${subjects.map(encodeURIComponent).join(',')}`,
+        signal: options.signal,
+      }),
+      'a shown community notes lookup',
+    );
+    return response.notes;
+  }
+
+  /** A writer's own notes, newest first. */
+  async writtenBy(authorPrincipalId: string, options: CommunityNoteReadOptions = {}): Promise<CommunityNote[]> {
+    const response = this.parse(
+      CommunityNoteListSchema,
+      await this.transport.request<unknown>({
+        method: 'GET',
+        path: `/v1/community-notes/principals/${encodeURIComponent(authorPrincipalId)}/notes`,
+        signal: options.signal,
+      }),
+      'a list of community notes',
+    );
+    return response.notes;
+  }
+
+  /** A rater's own ratings, each with the note it rated, newest first. */
+  async ratedBy(
+    raterPrincipalId: string,
+    options: CommunityNoteReadOptions = {},
+  ): Promise<CommunityNoteRatedList['ratings']> {
+    const response = this.parse(
+      CommunityNoteRatedListSchema,
+      await this.transport.request<unknown>({
+        method: 'GET',
+        path: `/v1/community-notes/principals/${encodeURIComponent(raterPrincipalId)}/ratings`,
+        signal: options.signal,
+      }),
+      'a list of community note ratings',
+    );
+    return response.ratings;
+  }
+
+  private parse<S extends z.ZodType>(schema: S, response: unknown, what: string): z.infer<S> {
+    const parsed = schema.safeParse(response);
+    if (!parsed.success) {
+      throw new CrowdSourceTransportError(`CrowdSource answered with ${what} this client does not recognise.`, {
+        retryable: false,
+        cause: parsed.error,
+      });
+    }
+    return parsed.data;
+  }
+}