content-moderation-sdk 0.0.1 → 0.1.1

package/src/core.ts

@@ -0,0 +1,440 @@
+import {
+  ModerationAbortError,
+  ModerationAdapterError,
+  ModerationAdapterNotFoundError,
+  ModerationRouteError,
+  ModerationValidationError,
+} from "./errors.js";
+import type {
+  BoundModerationClient,
+  ModerationAdapter,
+  ModerationAdapterContext,
+  ModerationClient,
+  ModerationClientOptions,
+  ModerationFallbackConfig,
+  ModerationHookEvent,
+  ModerationHooks,
+  ModerationInput,
+  ModerationItem,
+  ModerationOptions,
+  ModerationProcessingMode,
+  ModerationResult,
+  ModerationRetryConfig,
+  ModerationSettledResult,
+  ModerationValidationResult,
+} from "./types.js";
+import {
+  assertModerationInput,
+  flattenConversation,
+  isAbortLike,
+  normalizeAdapterResult,
+  normalizeSdkError,
+  raceWithAbort,
+  sleepWithAbort,
+  throwIfAborted,
+  toAdapterError,
+} from "./utils.js";
+
+const defaultDelay = (attempt: number) => Math.min(100 * 2 ** (attempt - 1), 2_000);
+
+type AnyAdapter = ModerationAdapter<string, unknown, unknown>;
+
+type PreparedRoute = {
+  adapter: AnyAdapter;
+  input: ModerationInput;
+  mode: ModerationProcessingMode;
+};
+
+type ResolvedRoute = {
+  primary: string;
+  names: readonly string[];
+  fallback?: ModerationFallbackConfig<string>;
+};
+
+export function createModerationClient<const TAdapters extends readonly ModerationAdapter[]>(
+  options: ModerationClientOptions<TAdapters>,
+): ModerationClient<TAdapters> {
+  if (options.adapters.length === 0) {
+    throw new ModerationValidationError("createModerationClient requires at least one adapter.");
+  }
+
+  const adapters = new Map<string, AnyAdapter>();
+  for (const adapter of options.adapters) {
+    if (!adapter.name || typeof adapter.name !== "string") {
+      throw new ModerationValidationError("Every moderation adapter requires a name.");
+    }
+    if (adapters.has(adapter.name)) {
+      throw new ModerationValidationError(`Duplicate moderation adapter "${adapter.name}".`);
+    }
+    adapters.set(adapter.name, adapter);
+  }
+
+  const defaultAdapter = options.defaultAdapter ?? options.adapters[0]?.name;
+  if (!defaultAdapter) {
+    throw new ModerationValidationError("createModerationClient requires a default adapter.");
+  }
+  requireAdapter(adapters, defaultAdapter);
+  validateRetry(options.retry);
+  validateFallback(adapters, options.fallback);
+
+  const validate = async (
+    input: ModerationInput,
+    requestOptions?: ModerationOptions<string>,
+  ): Promise<ModerationValidationResult> => {
+    throwIfAborted(requestOptions?.signal);
+    validateRetry(requestOptions?.retry ?? options.retry);
+    const route = resolveRoute(defaultAdapter, options.fallback, requestOptions);
+    validateFallback(adapters, route.fallback);
+    const prepared = await prepareRoutes(adapters, route.names, input);
+
+    return {
+      adapter: route.primary,
+      routes: route.names.map((name) => ({
+        adapter: name,
+        mode: prepared.get(name)?.mode ?? "native",
+      })),
+    };
+  };
+
+  const moderate = async (
+    input: ModerationInput,
+    requestOptions?: ModerationOptions<string>,
+  ): Promise<ModerationResult> => {
+    throwIfAborted(requestOptions?.signal);
+    validateRetry(requestOptions?.retry ?? options.retry);
+    const route = resolveRoute(defaultAdapter, options.fallback, requestOptions);
+    validateFallback(adapters, route.fallback);
+    const prepared = await prepareRoutes(adapters, route.names, input);
+    const failures: ModerationAdapterError[] = [];
+
+    for (const [index, name] of route.names.entries()) {
+      const candidate = prepared.get(name);
+      if (!candidate) {
+        throw new ModerationValidationError(`Moderation route "${name}" was not prepared.`);
+      }
+
+      try {
+        return await attemptAdapter({
+          candidate,
+          originalInput: input,
+          requestOptions,
+          retry: requestOptions?.retry ?? options.retry,
+          hooks: options.hooks,
+        });
+      } catch (error) {
+        if (error instanceof ModerationAbortError || error instanceof ModerationValidationError) {
+          throw error;
+        }
+
+        const failure = unwrapAttemptFailure(name, error);
+        failures.push(failure.error);
+        await invokeHook(options.hooks?.onError, {
+          adapter: name,
+          input,
+          inputType: input.type,
+          mode: candidate.mode,
+          attempt: failure.attempt,
+          metadata: requestOptions?.metadata,
+          error: failure.error,
+        });
+
+        const nextAdapter = route.names[index + 1];
+        if (!nextAdapter) break;
+
+        const shouldFallback = route.fallback?.shouldFallback;
+        if (shouldFallback) {
+          let shouldContinue: boolean;
+          try {
+            shouldContinue = await shouldFallback(failure.error, nextAdapter);
+          } catch (predicateError) {
+            throw new ModerationValidationError(
+              "The moderation fallback predicate threw an error.",
+              predicateError,
+            );
+          }
+          if (!shouldContinue) break;
+        }
+      }
+    }
+
+    throw new ModerationRouteError(failures);
+  };
+
+  const moderateMany = async (
+    items: readonly ModerationItem<string>[],
+    requestOptions?: ModerationOptions<string>,
+  ): Promise<readonly ModerationSettledResult[]> => {
+    const results: ModerationSettledResult[] = [];
+
+    for (const [index, item] of items.entries()) {
+      try {
+        const result = await moderate(item.input, mergeOptions(requestOptions, item.options));
+        results.push({ ok: true, index, result });
+      } catch (error) {
+        results.push({ ok: false, index, error: normalizeSdkError(error) });
+      }
+    }
+
+    return results;
+  };
+
+  const client = {
+    adapters,
+    defaultAdapter,
+    validate,
+    moderate,
+    moderateMany,
+    adapter(name: string) {
+      return requireAdapter(adapters, name);
+    },
+    withAdapter(name: string) {
+      requireAdapter(adapters, name);
+      return {
+        validate(input: ModerationInput, boundOptions?: ModerationOptions<string>) {
+          return validate(input, { ...boundOptions, adapter: name });
+        },
+        moderate(input: ModerationInput, boundOptions?: ModerationOptions<string>) {
+          return moderate(input, { ...boundOptions, adapter: name });
+        },
+        moderateMany(
+          items: readonly ModerationItem<string>[],
+          boundOptions?: ModerationOptions<string>,
+        ) {
+          return moderateMany(items, { ...boundOptions, adapter: name });
+        },
+      } as BoundModerationClient<AnyAdapter>;
+    },
+  };
+
+  return client as unknown as ModerationClient<TAdapters>;
+}
+
+async function prepareRoutes(
+  adapters: ReadonlyMap<string, AnyAdapter>,
+  names: readonly string[],
+  input: ModerationInput,
+): Promise<ReadonlyMap<string, PreparedRoute>> {
+  assertModerationInput(input);
+  const prepared = new Map<string, PreparedRoute>();
+
+  for (const name of names) {
+    const adapter = requireAdapter(adapters, name);
+    const candidate = prepareInput(adapter, input);
+    try {
+      await adapter.validate?.(candidate.input, {
+        adapter: name,
+        inputType: input.type,
+        mode: candidate.mode,
+      });
+    } catch (error) {
+      if (error instanceof ModerationValidationError) throw error;
+      throw new ModerationValidationError(`Moderation adapter "${name}" validation failed.`, {
+        adapter: name,
+        cause: error,
+      });
+    }
+    prepared.set(name, { adapter, ...candidate });
+  }
+
+  return prepared;
+}
+
+function prepareInput(
+  adapter: AnyAdapter,
+  input: ModerationInput,
+): Pick<PreparedRoute, "input" | "mode"> {
+  if (input.type === "text") {
+    if (!adapter.capabilities.text) unsupportedInput(adapter.name, "text");
+    return { input, mode: "native" };
+  }
+
+  if (input.type === "image") {
+    if (!adapter.capabilities.image) unsupportedInput(adapter.name, "image");
+    return { input, mode: "native" };
+  }
+
+  if (adapter.capabilities.conversation === "unsupported") {
+    unsupportedInput(adapter.name, "conversation");
+  }
+  if (adapter.capabilities.conversation === "flattened") {
+    return {
+      input: { type: "text", text: flattenConversation(input) },
+      mode: "flattened",
+    };
+  }
+  return { input, mode: "native" };
+}
+
+function unsupportedInput(adapter: string, inputType: ModerationInput["type"]): never {
+  throw new ModerationValidationError(
+    `Moderation adapter "${adapter}" does not support ${inputType} input.`,
+    { adapter, inputType },
+  );
+}
+
+async function attemptAdapter(input: {
+  candidate: PreparedRoute;
+  originalInput: ModerationInput;
+  requestOptions?: ModerationOptions<string>;
+  retry?: ModerationRetryConfig;
+  hooks?: ModerationHooks;
+}): Promise<ModerationResult> {
+  const maxAttempts = input.retry?.maxAttempts ?? 1;
+  const shouldRetry =
+    input.retry?.shouldRetry ?? ((error: ModerationAdapterError) => error.retryable);
+  const delayFor = input.retry?.delay ?? defaultDelay;
+  const name = input.candidate.adapter.name;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const hookEvent: ModerationHookEvent = {
+      adapter: name,
+      input: input.originalInput,
+      inputType: input.originalInput.type,
+      mode: input.candidate.mode,
+      attempt,
+      metadata: input.requestOptions?.metadata,
+    };
+    await invokeHook(input.hooks?.beforeModerate, hookEvent);
+    throwIfAborted(input.requestOptions?.signal);
+
+    try {
+      const context: ModerationAdapterContext = {
+        adapter: name,
+        inputType: input.originalInput.type,
+        mode: input.candidate.mode,
+        attempt,
+        signal: input.requestOptions?.signal,
+        metadata: input.requestOptions?.metadata,
+      };
+      const operation = Promise.resolve(
+        input.candidate.adapter.moderate(input.candidate.input, context),
+      );
+      const adapterResult = await raceWithAbort(operation, input.requestOptions?.signal);
+      const normalized = normalizeAdapterResult(name, adapterResult);
+      const result: ModerationResult = {
+        ...normalized,
+        inputType: input.originalInput.type,
+        mode: input.candidate.mode,
+      };
+      await invokeHook(input.hooks?.afterModerate, { ...hookEvent, result });
+      return result;
+    } catch (error) {
+      if (isAbortLike(error)) {
+        throw error instanceof ModerationAbortError
+          ? error
+          : new ModerationAbortError(input.requestOptions?.signal?.reason ?? error);
+      }
+      if (error instanceof ModerationValidationError) throw error;
+
+      const normalized = toAdapterError(name, error);
+      if (attempt >= maxAttempts) {
+        throw new AdapterAttemptFailure(normalized, attempt);
+      }
+
+      let retry: boolean;
+      try {
+        retry = shouldRetry(normalized, attempt);
+      } catch (callbackError) {
+        throw new ModerationValidationError(
+          "The moderation retry shouldRetry callback threw an error.",
+          callbackError,
+        );
+      }
+      if (!retry) throw new AdapterAttemptFailure(normalized, attempt);
+
+      let delayMs: number;
+      try {
+        delayMs = delayFor(attempt, normalized);
+      } catch (callbackError) {
+        throw new ModerationValidationError(
+          "The moderation retry delay callback threw an error.",
+          callbackError,
+        );
+      }
+      if (!Number.isFinite(delayMs) || delayMs < 0) {
+        throw new ModerationValidationError(
+          "Moderation retry delay must be a non-negative number.",
+          {
+            attempt,
+            delayMs,
+          },
+        );
+      }
+      await invokeHook(input.hooks?.onRetry, {
+        ...hookEvent,
+        error: normalized,
+        nextAttempt: attempt + 1,
+        delayMs,
+      });
+      await sleepWithAbort(delayMs, input.requestOptions?.signal);
+    }
+  }
+
+  throw new ModerationValidationError("Moderation retry loop exited unexpectedly.");
+}
+
+class AdapterAttemptFailure {
+  constructor(
+    readonly error: ModerationAdapterError,
+    readonly attempt: number,
+  ) {}
+}
+
+function unwrapAttemptFailure(adapter: string, error: unknown): AdapterAttemptFailure {
+  if (error instanceof AdapterAttemptFailure) return error;
+  return new AdapterAttemptFailure(toAdapterError(adapter, error), 1);
+}
+
+function resolveRoute(
+  defaultAdapter: string,
+  clientFallback: ModerationFallbackConfig<string> | undefined,
+  requestOptions?: ModerationOptions<string>,
+): ResolvedRoute {
+  const primary = requestOptions?.adapter ?? defaultAdapter;
+  const fallback = requestOptions?.fallback ?? clientFallback;
+  const names = [primary, ...(fallback?.adapters ?? [])].filter(
+    (name, index, route) => route.indexOf(name) === index,
+  );
+  return { primary, names, fallback };
+}
+
+function validateFallback(
+  adapters: ReadonlyMap<string, AnyAdapter>,
+  fallback?: ModerationFallbackConfig<string>,
+): void {
+  for (const name of fallback?.adapters ?? []) requireAdapter(adapters, name);
+}
+
+function validateRetry(retry?: ModerationRetryConfig): void {
+  if (retry?.maxAttempts === undefined) return;
+  if (!Number.isInteger(retry.maxAttempts) || retry.maxAttempts < 1) {
+    throw new ModerationValidationError(
+      "Moderation retry maxAttempts must be an integer of at least 1.",
+    );
+  }
+}
+
+function requireAdapter(adapters: ReadonlyMap<string, AnyAdapter>, name: string): AnyAdapter {
+  const adapter = adapters.get(name);
+  if (!adapter) throw new ModerationAdapterNotFoundError(name);
+  return adapter;
+}
+
+function mergeOptions(
+  base?: ModerationOptions<string>,
+  item?: ModerationOptions<string>,
+): ModerationOptions<string> | undefined {
+  if (!base && !item) return undefined;
+  return { ...base, ...item };
+}
+
+async function invokeHook<T>(
+  hook: ((event: T) => unknown | Promise<unknown>) | undefined,
+  event: T,
+): Promise<void> {
+  try {
+    await hook?.(event);
+  } catch {
+    // Hooks are best-effort observers and must never alter moderation behavior.
+  }
+}

package/src/errors.ts

@@ -0,0 +1,109 @@
+export type ModerationErrorCode =
+  | "validation_error"
+  | "adapter_not_found"
+  | "adapter_error"
+  | "route_error"
+  | "aborted"
+  | "internal_error";
+
+export type ModerationSdkErrorOptions = {
+  code: ModerationErrorCode | (string & {});
+  adapter?: string;
+  status?: number;
+  retryable?: boolean;
+  details?: unknown;
+  cause?: unknown;
+};
+
+export class ModerationSdkError extends Error {
+  readonly code: ModerationSdkErrorOptions["code"];
+  readonly adapter?: string;
+  readonly status?: number;
+  readonly retryable: boolean;
+  readonly details?: unknown;
+
+  constructor(message: string, options: ModerationSdkErrorOptions) {
+    super(message, { cause: options.cause });
+    this.name = "ModerationSdkError";
+    this.code = options.code;
+    this.adapter = options.adapter;
+    this.status = options.status;
+    this.retryable = options.retryable ?? false;
+    this.details = options.details;
+  }
+
+  toJSON(): Readonly<Record<string, unknown>> {
+    return Object.fromEntries([
+      ...Object.entries(this),
+      ["name", this.name],
+      ["message", this.message],
+    ]);
+  }
+}
+
+export class ModerationValidationError extends ModerationSdkError {
+  constructor(message: string, details?: unknown) {
+    super(message, { code: "validation_error", details });
+    this.name = "ModerationValidationError";
+  }
+}
+
+export class ModerationAdapterNotFoundError extends ModerationSdkError {
+  constructor(adapter: string) {
+    super(`Moderation adapter "${adapter}" is not registered.`, {
+      code: "adapter_not_found",
+      adapter,
+    });
+    this.name = "ModerationAdapterNotFoundError";
+  }
+}
+
+export type ModerationAdapterErrorOptions = Omit<ModerationSdkErrorOptions, "code" | "adapter"> & {
+  adapter: string;
+  code?: string;
+};
+
+export class ModerationAdapterError extends ModerationSdkError {
+  declare readonly adapter: string;
+
+  constructor(message: string, options: ModerationAdapterErrorOptions) {
+    super(message, {
+      code: options.code ?? "adapter_error",
+      adapter: options.adapter,
+      status: options.status,
+      retryable: options.retryable,
+      details: options.details,
+      cause: options.cause,
+    });
+    this.name = "ModerationAdapterError";
+  }
+}
+
+export class ModerationRouteError extends ModerationSdkError {
+  readonly failures: readonly ModerationAdapterError[];
+
+  constructor(failures: readonly ModerationAdapterError[]) {
+    super("Every moderation adapter in the route failed.", {
+      code: "route_error",
+      retryable: failures.some((failure) => failure.retryable),
+      details: failures,
+      cause: failures.at(-1),
+    });
+    this.name = "ModerationRouteError";
+    this.failures = failures;
+  }
+}
+
+export class ModerationAbortError extends ModerationSdkError {
+  constructor(reason?: unknown) {
+    super("Moderation was aborted.", {
+      code: "aborted",
+      cause: reason,
+    });
+    this.name = "ModerationAbortError";
+  }
+}
+
+export function isRetryableModerationError(error: unknown): error is ModerationSdkError {
+  return error instanceof ModerationSdkError && error.retryable;
+}

package/src/http.ts

@@ -0,0 +1,94 @@
+import { ModerationAbortError, ModerationAdapterError } from "./errors.js";
+import { isAbortLike } from "./utils.js";
+
+export function isRetryableHttpStatus(status: number): boolean {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;
+}
+
+export async function requestJson<T>(input: {
+  adapter: string;
+  provider: string;
+  fetcher: typeof fetch;
+  url: string;
+  init: RequestInit;
+}): Promise<T> {
+  let response: Response;
+  try {
+    response = await input.fetcher(input.url, input.init);
+  } catch (error) {
+    if (input.init.signal?.aborted || isAbortLike(error)) {
+      throw new ModerationAbortError(input.init.signal?.reason ?? error);
+    }
+    throw new ModerationAdapterError(`${input.provider} request failed.`, {
+      adapter: input.adapter,
+      code: "network_error",
+      retryable: true,
+      cause: error,
+    });
+  }
+
+  let body: unknown;
+  try {
+    body = await readBody(response);
+  } catch (error) {
+    if (input.init.signal?.aborted || isAbortLike(error)) {
+      throw new ModerationAbortError(input.init.signal?.reason ?? error);
+    }
+    throw new ModerationAdapterError(`${input.provider} response could not be read.`, {
+      adapter: input.adapter,
+      code: "network_error",
+      status: response.status,
+      retryable: true,
+      cause: error,
+    });
+  }
+  if (!response.ok) {
+    throw new ModerationAdapterError(httpErrorMessage(input.provider, response.status, body), {
+      adapter: input.adapter,
+      code: "http_error",
+      status: response.status,
+      retryable: isRetryableHttpStatus(response.status),
+      details: body,
+    });
+  }
+
+  if (body === undefined || typeof body === "string") {
+    throw new ModerationAdapterError(`${input.provider} returned an invalid JSON response.`, {
+      adapter: input.adapter,
+      code: "invalid_response",
+      status: response.status,
+      details: body,
+    });
+  }
+
+  return body as T;
+}
+
+async function readBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function httpErrorMessage(provider: string, status: number, body: unknown): string {
+  const detail = errorMessage(body);
+  return detail
+    ? `${provider} request failed (${status}): ${detail}`
+    : `${provider} request failed (${status}).`;
+}
+
+function errorMessage(body: unknown): string | undefined {
+  if (!body || typeof body !== "object")
+    return typeof body === "string" ? body.slice(0, 300) : undefined;
+  const record = body as Record<string, unknown>;
+  if (typeof record.message === "string") return record.message.slice(0, 300);
+  if (record.error && typeof record.error === "object") {
+    const nested = record.error as Record<string, unknown>;
+    if (typeof nested.message === "string") return nested.message.slice(0, 300);
+  }
+  return undefined;
+}

package/src/index.ts

@@ -0,0 +1,43 @@
+export { createModerationClient } from "./core.js";
+export {
+  ModerationAbortError,
+  ModerationAdapterError,
+  ModerationAdapterNotFoundError,
+  ModerationRouteError,
+  ModerationSdkError,
+  ModerationValidationError,
+  isRetryableModerationError,
+} from "./errors.js";
+export type {
+  BoundModerationClient,
+  MaybePromise,
+  ModerationAdapter,
+  ModerationAdapterCapabilities,
+  ModerationAdapterContext,
+  ModerationAdapterResult,
+  ModerationAdapterValidationContext,
+  ModerationAfterEvent,
+  ModerationCategoryAssessment,
+  ModerationClient,
+  ModerationClientOptions,
+  ModerationConversationInput,
+  ModerationErrorEvent,
+  ModerationFallbackConfig,
+  ModerationHookEvent,
+  ModerationHooks,
+  ModerationImageInput,
+  ModerationImageSource,
+  ModerationInput,
+  ModerationInputType,
+  ModerationItem,
+  ModerationMessage,
+  ModerationMessageRole,
+  ModerationOptions,
+  ModerationProcessingMode,
+  ModerationResult,
+  ModerationRetryConfig,
+  ModerationSettledResult,
+  ModerationTextInput,
+  ModerationValidationResult,
+  ModerationValidationRoute,
+} from "./types.js";