@crowdsource.you/core 1.2.0

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * `@crowdsource.you/core` — the TypeScript client for the CrowdSource moderation
+ * API.
+ *
+ * The smallest integration this package supports, in full:
+ *
+ * ```ts
+ * import { CrowdSource } from '@crowdsource.you/core';
+ *
+ * const crowdsource = new CrowdSource();
+ *
+ * await crowdsource.reports.create({
+ *   externalReportId: report.id,
+ *   reportedBy: { oxyUserId: session.sub },
+ *   subject: {
+ *     externalId: post.id,
+ *     type: 'social.post',
+ *     author: { oxyUserId: post.authorId },
+ *   },
+ *   content: post.text,
+ *   allegations: ['harassment.targeted_abuse'],
+ * });
+ * ```
+ *
+ * One environment variable (`CROWDSOURCE_SERVICE_KEY`) and the object being
+ * reported. The Case Envelope, its resource ids, its digests, its relations, its
+ * principal bindings, the identity binding proof, the policy version, the
+ * retention terms and the idempotency key are all composed from that — see
+ * `envelope.ts` for what each one is derived from and why it cannot be left to
+ * the caller.
+ *
+ * Types come from `@crowdsource.you/contracts`. This package re-exports none
+ * of them: an integrator imports the contract from the contract package, so a
+ * `Decision` or a `TaxonomyCode` has exactly one definition.
+ */
+
+export { CrowdSource, SERVICE_KEY_ENV_VAR, BASE_URL_ENV_VAR } from './client.js';
+export type { CrowdSourceOptions } from './client.js';
+
+export { formatServiceKey, parseServiceKey } from './credential.js';
+export type { ServiceCredential } from './credential.js';
+
+export {
+  COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS,
+  DEFAULT_BASE_URL,
+  DEFAULT_POLICY,
+  DEFAULT_RETENTION_DAYS,
+} from './defaults.js';
+
+export { canonicalJson, resourceDigest, sha256Digest } from './digest.js';
+export type { CanonicalValue } from './digest.js';
+
+/**
+ * `composeCaseEnvelope` is deliberately NOT exported.
+ *
+ * It is the one function in this package that takes an `applicationId`, and it
+ * takes it from `Reports`, which got it from the credential. Exporting it would
+ * put an `applicationId` parameter on the public surface — which is the thing
+ * Appendix F says must not exist, however carefully the doc comment above it
+ * were worded. The envelope a report produces is reachable by reading what
+ * `reports.create` sends, not by building one yourself.
+ */
+export { CrowdSourceReportInputError, defaultIdempotencyKey } from './envelope.js';
+export type {
+  AllegationInput,
+  ContextInput,
+  ContextRole,
+  PrincipalInput,
+  ReportInput,
+  ReportSubjectInput,
+  ResourceInput,
+} from './envelope.js';
+
+export {
+  CROWDSOURCE_API_ERROR_CODES,
+  CrowdSourceApiError,
+  CrowdSourceConfigurationError,
+  CrowdSourceError,
+  CrowdSourceTransportError,
+  isCrowdSourceApiError,
+  isCrowdSourceApiErrorCode,
+  isCrowdSourceError,
+} from './errors.js';
+export type { CrowdSourceApiErrorCode } from './errors.js';
+
+export { Reports } from './reports.js';
+export type { ReportReceipt, ReportRequestOptions } from './reports.js';
+
+export { Cases, Decisions } from './cases.js';
+export type { CaseView, ReadOptions } from './cases.js';
+
+
+export { CommunityNotes } from './communityNotes.js';
+export type { CommunityNoteReadOptions, CommunityNoteRequestOptions } from './communityNotes.js';
+
+export { WebhookEndpoints } from './webhookEndpoints.js';
+export type {
+  RegisterWebhookEndpointInput,
+  RotateSecretOptions,
+  RotatedWebhookSecret,
+  WebhookEndpoint,
+  WebhookEndpointRequestOptions,
+  WebhookSecret,
+} from './webhookEndpoints.js';
+
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS } from './transport.js';
+export type { FetchLike } from './transport.js';

package/src/outbox/client.ts

@@ -0,0 +1,75 @@
+import { CrowdSource } from '../index.js';
+import type { CrowdSourceConnectionConfig, ModerationLogger } from './types.js';
+
+/**
+ * The CrowdSource client, built once and only when configured.
+ *
+ * There is deliberately almost nothing here. The SDK already owns the base URL,
+ * the timeouts, the bounded per-attempt retries, the idempotency key and the
+ * error classification, and a wrapper that re-implemented any of them would be a
+ * second answer to a question that has one. What this adds is exactly two
+ * things: the client is absent until the integration is switched on, and it is
+ * built once rather than per delivery.
+ *
+ * `applicationId` appears nowhere — the client reads it off the service key, and
+ * there is no option, field or parameter through which one could be passed.
+ */
+export interface CrowdSourceClientProvider {
+  /**
+   * The client, or `undefined` when the integration is not configured.
+   *
+   * `undefined` rather than a throw: a disabled integration is the normal state
+   * of a local checkout and of every deployment before rollout, and a report
+   * filed there must still be stored. The delivery worker is what notices there
+   * is nowhere to send it.
+   *
+   * A MISCONFIGURED client — a malformed service key — is a different thing and
+   * is logged once at error level. Once, because the alternative is one line per
+   * delivery attempt per report, which buries the cause it is meant to reveal.
+   */
+  get(): CrowdSource | undefined;
+}
+
+export function createClientProvider(input: {
+  config: CrowdSourceConnectionConfig;
+  logger: ModerationLogger;
+}): CrowdSourceClientProvider {
+  let client: CrowdSource | null = null;
+  let configurationError: string | null = null;
+
+  return {
+    get(): CrowdSource | undefined {
+      if (!input.config.enabled) return undefined;
+      if (client) return client;
+      if (configurationError !== null) return undefined;
+
+      const serviceKey = input.config.serviceKey;
+      if (!serviceKey) {
+        configurationError = 'no CrowdSource service key is configured';
+        input.logger.error('[CrowdSource] enabled but not configured', {
+          reason: configurationError,
+        });
+        return undefined;
+      }
+
+      try {
+        client = new CrowdSource({
+          serviceKey,
+          ...(input.config.baseUrl === undefined ? {} : { baseUrl: input.config.baseUrl }),
+        });
+        input.logger.info('[CrowdSource] client ready', {
+          applicationId: client.applicationId,
+        });
+        return client;
+      } catch (error: unknown) {
+        // The SDK's configuration errors name which part of the key is wrong and
+        // never echo the secret, so the message is safe to log.
+        configurationError = error instanceof Error ? error.message : String(error);
+        input.logger.error('[CrowdSource] service key rejected', {
+          reason: configurationError,
+        });
+        return undefined;
+      }
+    },
+  };
+}

package/src/outbox/decision.ts

@@ -0,0 +1,209 @@
+import { DecisionSchema, type Decision } from '@crowdsource.you/contracts';
+import type { EnforcementExecutor } from './enforcement/executor.js';
+import { primaryAction } from './enforcement/planner.js';
+import { localStatusForDecision } from './reportStatus.js';
+import type { ModerationReportStore } from './store/types.js';
+import type {
+  EnforcementOutcome,
+  ModerationEnforcementConfig,
+  ModerationLogger,
+  ModerationOutboxEvent,
+  ModerationReportFields,
+  ReportDecisionExtraFields,
+} from './types.js';
+
+/**
+ * Applying a decision that has already been received and recorded.
+ *
+ * The webhook answered 2xx long before this runs. What is left is the part that
+ * touches several collections: write the decision onto every report that opened
+ * or joined the case, and enforce it once.
+ *
+ * "Once" is the invariant that shapes this file. A hundred reports about the
+ * same material produce ONE case and ONE consequence, so enforcement is keyed on
+ * the decision and not on the reports — the executor is called a single time no
+ * matter how many reports are updated, and its own unique index makes even that
+ * call safe to repeat.
+ */
+
+/** A failure that will not be fixed by trying again. */
+export class ModerationDecisionRejectedError extends Error {
+  /** Read by the outbox: `false` dead-letters instead of retrying. */
+  readonly retryable = false;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ModerationDecisionRejectedError';
+  }
+}
+
+/** A failure that a later attempt can still resolve. */
+export class ModerationDecisionDeferredError extends Error {
+  readonly retryable = true;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ModerationDecisionDeferredError';
+  }
+}
+
+export function createDecisionWorker<
+  TReport extends ModerationReportFields,
+  TAction extends string,
+  TTx,
+>(input: {
+  reports: ModerationReportStore<TReport, TTx>;
+  executor: EnforcementExecutor<TAction>;
+  enforcement: ModerationEnforcementConfig<TAction>;
+  logger: ModerationLogger;
+  reportDecisionExtraFields?: (decision: Decision) => ReportDecisionExtraFields;
+}): (event: ModerationOutboxEvent) => Promise<void> {
+  /**
+   * Write the decision onto one report.
+   *
+   * `decision.revision` is passed as the ceiling the store guards on, so it is
+   * the DATABASE that refuses a stale write rather than a read-then-write in
+   * this process. Deliveries can overlap — CrowdSource retries for 24 hours, and
+   * a correction can arrive while the decision it supersedes is still being
+   * applied — and an older revision landing last would otherwise overwrite the
+   * current answer with a stale one.
+   */
+  const applyToReport = async (
+    reportId: string,
+    decision: Decision,
+    enforced: { action: TAction; at: Date | null } | undefined,
+  ): Promise<boolean> =>
+    await input.reports.applyDecision(
+      reportId,
+      {
+        localStatus: localStatusForDecision(decision.status),
+        decisionId: decision.id,
+        decisionRevision: decision.revision,
+        decisionOutcome: decision.outcome,
+        decisionStatus: decision.status,
+        decidedAt: new Date(decision.publishedAt),
+        /**
+         * `enforcedAction` is what the application DECIDED to do; `enforcedAt`
+         * is when an effect actually landed. They are written separately because
+         * they are different claims, and conflating them puts a timestamp on
+         * something that never happened — which is the normal case in `observe`
+         * mode, and the permanent case for an application with no sanction
+         * primitive. An audit row that says "enforced at 14:02" for an effect
+         * nobody carried out is not explainable, and every effect being
+         * explainable is the invariant.
+         */
+        ...(enforced === undefined
+          ? {}
+          : {
+              enforcedAction: enforced.action,
+              ...(enforced.at === null ? {} : { enforcedAt: enforced.at }),
+            }),
+        ...(input.reportDecisionExtraFields === undefined
+          ? {}
+          : { extra: input.reportDecisionExtraFields(decision) }),
+      },
+      decision.revision,
+    );
+
+  return async (event) => {
+    const caseId = event.payload.caseId;
+    if (caseId === undefined) {
+      throw new ModerationDecisionRejectedError(
+        'A decision.apply event carried no caseId.',
+      );
+    }
+
+    /**
+     * Parsed HERE rather than at the webhook.
+     *
+     * The receiver's job was to prove the bytes came from CrowdSource and to
+     * record them; refusing an unrecognised shape at the door would put a real
+     * decision back on a retry schedule until it expired. Parsing at the point
+     * of use means an event this deployment cannot yet read waits in the outbox
+     * until it can.
+     */
+    const parsed = DecisionSchema.safeParse(event.payload.decision);
+    if (!parsed.success) {
+      throw new ModerationDecisionRejectedError(
+        `The decision for case ${caseId} does not match the published contract: ${parsed.error.issues
+          .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+          .join('; ')}`,
+      );
+    }
+    const decision = parsed.data;
+
+    const reports = await input.reports.findByCaseId(caseId);
+
+    if (reports.length === 0) {
+      /**
+       * Retryable, and the race is real rather than theoretical: CrowdSource can
+       * decide a case and deliver the webhook while the response that carried
+       * the case id back to this deployment is still being written, or while a
+       * delivery is being retried. Backing off is correct; dead-lettering would
+       * throw the decision away.
+       */
+      throw new ModerationDecisionDeferredError(
+        `No local report is linked to case ${caseId} yet.`,
+      );
+    }
+
+    /**
+     * One subject per case. The dedup key includes the subject's external id, so
+     * every report merged into a case is about the same object — the first
+     * report names it.
+     */
+    const [first] = reports;
+    const outcomes = await input.executor.apply({
+      decision,
+      caseId,
+      subject: { type: first.reportedType, id: first.reportedId },
+    });
+
+    /**
+     * The EFFECTIVE action, not the planned one. `apply` is the only place that
+     * knows a planned action could not apply to this particular object, and
+     * `recordedAs` is how it says so — see `EnforcementEffect`.
+     */
+    const effectiveAction = (outcome: EnforcementOutcome<TAction>): TAction =>
+      outcome.recordedAs ?? outcome.action;
+
+    const enforcedAction = primaryAction(
+      outcomes.map(effectiveAction),
+      input.enforcement.precedence ?? input.enforcement.actions,
+    );
+    /**
+     * The timestamp belongs to the outcome of THIS action, not to the plan. An
+     * action that was claimed and recorded — observe mode, a mode that does not
+     * apply it, or an application with nothing to apply — leaves `enforcedAt`
+     * unset while `enforcedAction` still says what was decided.
+     */
+    const enforced =
+      enforcedAction === undefined
+        ? undefined
+        : {
+            action: enforcedAction,
+            at: outcomes.some(
+              (outcome) =>
+                effectiveAction(outcome) === enforcedAction &&
+                outcome.result === 'applied',
+            )
+              ? new Date()
+              : null,
+          };
+
+    let updated = 0;
+    for (const report of reports) {
+      if (await applyToReport(report.id, decision, enforced)) updated += 1;
+    }
+
+    input.logger.info('[CrowdSource] decision applied', {
+      caseId,
+      decisionId: decision.id,
+      revision: decision.revision,
+      outcome: decision.outcome,
+      reportsMatched: reports.length,
+      reportsUpdated: updated,
+      actions: outcomes.map((outcome) => `${outcome.action}:${outcome.result}`).join(','),
+    });
+  };
+}

package/src/outbox/delivery.ts

@@ -0,0 +1,163 @@
+import type { CrowdSourceClientProvider } from './client.js';
+import { buildModerationReportInput, type SubjectRegistry } from './evidence.js';
+import type { ModerationReportStore } from './store/types.js';
+import type {
+  ModerationLogger,
+  ModerationMetrics,
+  ModerationOutboxEvent,
+  ModerationReportFields,
+  ModerationTaxonomy,
+} from './types.js';
+
+/**
+ * Delivering a stored report to CrowdSource.
+ *
+ * Everything hard about this is already handled elsewhere and the shape of this
+ * file is what is left over: the SDK owns the envelope, the idempotency key, the
+ * timeouts, the per-attempt retries and the classification of failures; the
+ * outbox owns durability, backoff and dead-lettering. What remains is to
+ * describe the material, hand it over, and write down what came back.
+ *
+ * The failures are as important as the success:
+ *
+ * - **Nowhere to send it.** The integration is not configured. The event stays
+ *   pending, untouched, and delivers when it is — a delay, never a loss.
+ * - **The object is gone.** Deleted between the report and its delivery. There
+ *   is nothing to review, so the report closes locally instead of retrying for
+ *   days.
+ * - **The type has no provider.** Unreachable by design — such a report never
+ *   gets a delivery event — so an event that reaches it is a defect and is
+ *   dead-lettered rather than retried or filed as a state.
+ * - **Anything else** is the SDK's `retryable` to answer, and the outbox obeys
+ *   it.
+ */
+
+/** Thrown when there is nowhere to deliver to yet. Always retryable. */
+export class CrowdSourceUnavailableError extends Error {
+  readonly retryable = true;
+
+  constructor() {
+    super('The CrowdSource integration is not configured in this deployment.');
+    this.name = 'CrowdSourceUnavailableError';
+  }
+}
+
+/**
+ * A delivery event that cannot become deliverable.
+ *
+ * `retryable: false` is the field the outbox reads to dead-letter instead of
+ * backing off — the same contract every error from `@crowdsource.you/core` answers.
+ */
+export class ModerationDeliveryRejectedError extends Error {
+  readonly retryable = false;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ModerationDeliveryRejectedError';
+  }
+}
+
+export function createDeliveryWorker<TReport extends ModerationReportFields, TTx>(input: {
+  reports: ModerationReportStore<TReport, TTx>;
+  registry: SubjectRegistry;
+  taxonomy: ModerationTaxonomy;
+  client: CrowdSourceClientProvider;
+  logger: ModerationLogger;
+  metrics?: ModerationMetrics;
+}): (event: ModerationOutboxEvent) => Promise<void> {
+  const count = (result: string): void => {
+    input.metrics?.incrementCounter('crowdsource_report_delivery_total', 1, { result });
+  };
+
+  return async (event) => {
+    const reportId = event.payload.reportId;
+    if (reportId === undefined) {
+      throw new ModerationDeliveryRejectedError(
+        'A report.submit event carried no reportId.',
+      );
+    }
+
+    const report = await input.reports.findById(reportId);
+    if (!report) {
+      /**
+       * The report is gone but its delivery event survived. Nothing to deliver
+       * and nothing to fix, so the event completes — retrying would keep looking
+       * for a row that no longer exists.
+       */
+      input.logger.warn('[CrowdSource] delivery event has no report', { reportId });
+      return;
+    }
+
+    const crowdsource = input.client.get();
+    if (!crowdsource) throw new CrowdSourceUnavailableError();
+
+    /**
+     * A `ModerationSubjectUnsupportedError` from here is NOT caught. It carries
+     * `retryable: false`, so the outbox dead-letters the event and the
+     * reconciliation sweep counts it — which is the right channel for a defect
+     * that needs a human. Catching it and writing a local state would put the
+     * report somewhere nothing alerts on.
+     */
+    const described = await buildModerationReportInput({
+      report: {
+        id: reportId,
+        reportedType: report.reportedType,
+        reportedId: report.reportedId,
+        reporter: report.reporter,
+        categories: report.categories,
+        ...(report.details === undefined ? {} : { details: report.details }),
+        createdAt: report.createdAt,
+      },
+      registry: input.registry,
+      taxonomy: input.taxonomy,
+    });
+
+    if (described === null) {
+      // Nothing left to review, so the report is closed with the reason rather
+      // than retried against material that is gone.
+      await input.reports.close(
+        reportId,
+        'The reported content no longer exists, so there is nothing to review.',
+      );
+      count('content_unavailable');
+      return;
+    }
+
+    let receipt: Awaited<ReturnType<typeof crowdsource.reports.create>>;
+    try {
+      receipt = await crowdsource.reports.create(described.reportInput);
+    } catch (error: unknown) {
+      /**
+       * The failure is visible on the report itself, not only in the outbox row.
+       * `delivery_failed` is what a reporter's receipt and the reconciliation
+       * sweep both read; leaving the report at `queued` while the outbox quietly
+       * backed off would hide the problem in a collection nobody looks at.
+       * Written before rethrowing so the outbox still applies its own backoff or
+       * dead-letters the event.
+       */
+      await input.reports.markDeliveryFailed(
+        reportId,
+        // Bounded here rather than by a column width, so both dialects agree: a
+        // Mongoose validator throws on overflow and Postgres errors 22001.
+        (error instanceof Error ? error.message : String(error)).slice(0, 2_000),
+      );
+      count('failed');
+      throw error;
+    }
+
+    await input.reports.markSubmitted(reportId, {
+      crowdSourceReportId: receipt.reportId,
+      crowdSourceCaseId: receipt.caseId,
+      crowdSourceMerged: receipt.merged,
+      contentSnapshotHash: described.snapshotHash,
+      submittedAt: new Date(),
+    });
+
+    count(receipt.merged ? 'merged' : 'delivered');
+    input.logger.info('[CrowdSource] report delivered', {
+      reportId,
+      caseId: receipt.caseId,
+      merged: receipt.merged,
+    });
+  };
+}