content-moderation-sdk 0.0.1 → 0.1.1

package/src/utils.ts

@@ -0,0 +1,281 @@
+import {
+  ModerationAbortError,
+  ModerationAdapterError,
+  ModerationSdkError,
+  ModerationValidationError,
+} from "./errors.js";
+import type {
+  ModerationAdapterResult,
+  ModerationImageSource,
+  ModerationInput,
+  ModerationMessageRole,
+} from "./types.js";
+
+const MESSAGE_ROLES = new Set<ModerationMessageRole>(["system", "user", "assistant", "tool"]);
+const BASE64_PATTERN = /^(?:[A-Za-z\d+/]{4})*(?:[A-Za-z\d+/]{2}==|[A-Za-z\d+/]{3}=)?$/;
+
+export function assertModerationInput(input: ModerationInput): void {
+  if (!input || typeof input !== "object") {
+    throw new ModerationValidationError("Moderation input must be an object.");
+  }
+
+  if (input.type === "text") {
+    if (typeof input.text !== "string" || input.text.trim().length === 0) {
+      throw new ModerationValidationError("Text moderation requires non-empty text.");
+    }
+    return;
+  }
+
+  if (input.type === "image") {
+    assertImageSource(input.source);
+    return;
+  }
+
+  if (input.type === "conversation") {
+    if (!Array.isArray(input.messages) || input.messages.length === 0) {
+      throw new ModerationValidationError("Conversation moderation requires at least one message.");
+    }
+
+    for (const [index, message] of input.messages.entries()) {
+      if (!message || typeof message !== "object" || !MESSAGE_ROLES.has(message.role)) {
+        throw new ModerationValidationError(
+          `Conversation message ${index} has an unsupported role.`,
+        );
+      }
+      if (typeof message.content !== "string" || message.content.trim().length === 0) {
+        throw new ModerationValidationError(
+          `Conversation message ${index} requires non-empty string content.`,
+        );
+      }
+    }
+    return;
+  }
+
+  throw new ModerationValidationError("Unsupported moderation input type.");
+}
+
+export function assertImageSource(source: ModerationImageSource): void {
+  if (!source || typeof source !== "object") {
+    throw new ModerationValidationError("Image moderation requires an image source.");
+  }
+
+  if (source.type === "url") {
+    let parsed: URL;
+    try {
+      parsed = new URL(source.url);
+    } catch {
+      throw new ModerationValidationError("Image URL must be a valid HTTP(S) URL.");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new ModerationValidationError("Image URL must use HTTP or HTTPS.");
+    }
+    return;
+  }
+
+  if (source.type === "base64") {
+    assertMediaType(source.mediaType);
+    if (typeof source.data !== "string") {
+      throw new ModerationValidationError("Image base64 data must be a string.");
+    }
+    const normalized = normalizeBase64(source.data);
+    if (normalized.length === 0 || !BASE64_PATTERN.test(normalized)) {
+      throw new ModerationValidationError("Image base64 data is invalid.");
+    }
+    return;
+  }
+
+  if (source.type === "bytes") {
+    assertMediaType(source.mediaType);
+    if (!isBinaryData(source.data) || binaryByteLength(source.data) === 0) {
+      throw new ModerationValidationError(
+        "Image bytes must be a non-empty Uint8Array, ArrayBuffer, or Blob.",
+      );
+    }
+    return;
+  }
+
+  throw new ModerationValidationError("Unsupported image source type.");
+}
+
+function assertMediaType(mediaType: string): void {
+  if (typeof mediaType !== "string" || !/^image\/[A-Za-z\d.+-]+$/i.test(mediaType)) {
+    throw new ModerationValidationError('Image mediaType must look like "image/png".');
+  }
+}
+
+function isBinaryData(value: unknown): value is Uint8Array | ArrayBuffer | Blob {
+  return value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof Blob;
+}
+
+export function flattenConversation(input: Extract<ModerationInput, { type: "conversation" }>) {
+  return JSON.stringify(input.messages);
+}
+
+export function normalizeHttpEndpoint(value: string, label: string): string {
+  let endpoint: URL;
+  try {
+    endpoint = new URL(value);
+  } catch {
+    throw new ModerationValidationError(`${label} must be a valid HTTP(S) URL.`);
+  }
+  if (endpoint.protocol !== "http:" && endpoint.protocol !== "https:") {
+    throw new ModerationValidationError(`${label} must use HTTP or HTTPS.`);
+  }
+  return endpoint.toString().replace(/\/+$/, "");
+}
+
+export function normalizeBase64(value: string): string {
+  return value.replace(/\s+/g, "");
+}
+
+export function base64ByteLength(value: string): number {
+  const normalized = normalizeBase64(value);
+  if (normalized.length === 0) return 0;
+  const padding = normalized.endsWith("==") ? 2 : normalized.endsWith("=") ? 1 : 0;
+  return (normalized.length * 3) / 4 - padding;
+}
+
+export function binaryByteLength(value: Uint8Array | ArrayBuffer | Blob): number {
+  if (value instanceof Blob) return value.size;
+  return value.byteLength;
+}
+
+export function imageSourceByteLength(source: ModerationImageSource): number | undefined {
+  if (source.type === "url") return undefined;
+  if (source.type === "base64") return base64ByteLength(source.data);
+  return binaryByteLength(source.data);
+}
+
+export async function imageSourceToBase64(source: Exclude<ModerationImageSource, { type: "url" }>) {
+  if (source.type === "base64") return normalizeBase64(source.data);
+
+  const bytes =
+    source.data instanceof Blob
+      ? new Uint8Array(await source.data.arrayBuffer())
+      : source.data instanceof ArrayBuffer
+        ? new Uint8Array(source.data)
+        : source.data;
+  return bytesToBase64(bytes);
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+export async function imageSourceToDataUrl(
+  source: Exclude<ModerationImageSource, { type: "url" }>,
+) {
+  return `data:${source.mediaType};base64,${await imageSourceToBase64(source)}`;
+}
+
+export function normalizeAdapterResult<Name extends string, Raw>(
+  adapter: Name,
+  value: ModerationAdapterResult<Name, Raw>,
+): ModerationAdapterResult<Name, Raw> {
+  if (!value || typeof value !== "object") {
+    throw new ModerationAdapterError("Adapter returned an invalid moderation result.", {
+      adapter,
+      code: "invalid_response",
+    });
+  }
+  if (typeof value.flagged !== "boolean") {
+    throw new ModerationAdapterError('Adapter result requires a boolean "flagged" field.', {
+      adapter,
+      code: "invalid_response",
+    });
+  }
+  if (!value.categories || typeof value.categories !== "object") {
+    throw new ModerationAdapterError('Adapter result requires a "categories" object.', {
+      adapter,
+      code: "invalid_response",
+    });
+  }
+
+  return { ...value, adapter };
+}
+
+export function toAdapterError(adapter: string, error: unknown): ModerationAdapterError {
+  if (error instanceof ModerationAdapterError) {
+    if (error.adapter === adapter) return error;
+    return new ModerationAdapterError(error.message, {
+      adapter,
+      code: error.code,
+      status: error.status,
+      retryable: error.retryable,
+      details: error.details,
+      cause: error,
+    });
+  }
+
+  if (error instanceof ModerationSdkError) {
+    return new ModerationAdapterError(error.message, {
+      adapter,
+      code: error.code,
+      status: error.status,
+      retryable: error.retryable,
+      details: error.details,
+      cause: error,
+    });
+  }
+
+  return new ModerationAdapterError(
+    error instanceof Error ? error.message : "Moderation adapter failed.",
+    { adapter, cause: error },
+  );
+}
+
+export function normalizeSdkError(error: unknown): ModerationSdkError {
+  if (error instanceof ModerationSdkError) return error;
+  return new ModerationSdkError(error instanceof Error ? error.message : "Moderation failed.", {
+    code: "internal_error",
+    cause: error,
+  });
+}
+
+export function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new ModerationAbortError(signal.reason);
+}
+
+export function isAbortLike(error: unknown): boolean {
+  return (
+    error instanceof ModerationAbortError ||
+    (error instanceof DOMException && error.name === "AbortError") ||
+    (error instanceof Error && error.name === "AbortError")
+  );
+}
+
+export async function raceWithAbort<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  throwIfAborted(signal);
+  if (!signal) return promise;
+
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => reject(new ModerationAbortError(signal.reason));
+    signal.addEventListener("abort", abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}
+
+export function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
+  throwIfAborted(signal);
+  if (ms <= 0) return Promise.resolve();
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(done, ms);
+    const abort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      reject(new ModerationAbortError(signal?.reason));
+    };
+
+    function done() {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }
+
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}