@vouchington/utils 0.7.3 → 0.7.5

package/README.md

@@ -18,6 +18,11 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
 
 ## Subpaths
 
+- `ai-moderation`: moderation input building, flagged-category and prompt-injection checks that
+  return violations; the caller makes the provider call.
+- `bedrock-embeddings` and `bedrock-embedding-batches`: Nova `InvokeModel` input builders, response
+  parsing and dense-vector validation, and batch JSONL record and result codecs with opaque record
+  ids; the caller owns the AWS client.
 - `cache-tags`: canonical printable-ASCII wire encoding, one-segment URL decoding, validation,
   and escape-boundary truncation. Applications own family names, route recognition, and purge policy.
   Single-tag validation rejects spaces and comma separators; raw commas are percent-encoded.
@@ -31,6 +36,10 @@ import { createScopeCatalog } from '@vouchington/utils/scopes'
   request/acknowledge round trip with an injected message type and acceptance check, and a named
   Web Lock wrapper. Request actions, expected state transitions, and the bind/clear/reconcile
   sequence stay in the application.
+- `service-worker-activation`: `waitForActiveServiceWorker(registration, options)` resolves when
+  the registration has an active worker. An installing or waiting worker is preferred over
+  `serviceWorker.ready`. `timeoutMs` bounds the wait; omit it to wait without a deadline. The
+  caller supplies the timeout and may inject `serviceWorker` (default `navigator.serviceWorker`).
 - `json-ld`: schema.org JSON-LD builders (organization, website, navigation, collection, thing,
   comparison, item list, breadcrumb, profile) and script-safe serialization. Callers inject the
   absolute-URL resolver and site name; product schemas such as posts stay in the application.

package/dist/ai-moderation.d.mts

@@ -0,0 +1,34 @@
+/** The text or image parts a moderation endpoint accepts. */
+export type ModerationInputPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+    };
+};
+/** The fields of a moderation result this module reads. */
+export type ModerationResultLike = {
+    flagged: boolean;
+    categories: Record<string, boolean>;
+};
+export type MessageSafetyViolation = {
+    code: 'PROMPT_INJECTION';
+} | {
+    code: 'MODERATION_VIOLATION';
+    categories: string[];
+};
+/** Text first, then images, in the order given. */
+export declare function buildModerationInput(texts: readonly string[], imageUrls?: readonly string[]): ModerationInputPart[];
+/** Names of the categories a result flagged. */
+export declare function getFlaggedCategories(result: ModerationResultLike): string[];
+/**
+ * A violation naming every category flagged by any result, else null. Results line up with the
+ * request's inputs, so a later flagged input is never masked by a clean earlier one.
+ */
+export declare function checkModerationResults(results: readonly ModerationResultLike[]): MessageSafetyViolation | null;
+/** Common instruction-override and chat-template markers. Callers may pass their own list. */
+export declare const DEFAULT_PROMPT_INJECTION_PATTERNS: readonly RegExp[];
+/** A `PROMPT_INJECTION` violation when any pattern matches the message, else null. */
+export declare function checkPromptInjection(message: string, patterns?: readonly RegExp[]): MessageSafetyViolation | null;

package/dist/ai-moderation.mjs

@@ -0,0 +1,54 @@
+/** Text first, then images, in the order given. */
+export function buildModerationInput(texts, imageUrls = []) {
+    return [
+        ...texts.map((text) => ({ type: 'text', text })),
+        ...imageUrls.map((url) => ({ type: 'image_url', image_url: { url } })),
+    ];
+}
+/** Names of the categories a result flagged. */
+export function getFlaggedCategories(result) {
+    return Object.entries(result.categories).flatMap(([category, flagged]) => flagged ? [category] : []);
+}
+/**
+ * A violation naming every category flagged by any result, else null. Results line up with the
+ * request's inputs, so a later flagged input is never masked by a clean earlier one.
+ */
+export function checkModerationResults(results) {
+    const flagged = results.filter((result) => result.flagged);
+    if (flagged.length === 0)
+        return null;
+    const categories = [...new Set(flagged.flatMap(getFlaggedCategories))];
+    return { code: 'MODERATION_VIOLATION', categories };
+}
+/** Common instruction-override and chat-template markers. Callers may pass their own list. */
+export const DEFAULT_PROMPT_INJECTION_PATTERNS = [
+    /ignore\s+(all\s+)?(previous|prior|earlier)\s+(instructions?|prompts?|rules?)/i,
+    /disregard\s+(all\s+)?(previous|prior|earlier)\s+(instructions?|prompts?|rules?)/i,
+    /forget\s+(all\s+)?(previous|prior|earlier)\s+(instructions?|prompts?|rules?)/i,
+    // A chat-template style role prefix at the start of a line, not "operating system: Linux".
+    /(?:^|\n)\s*system\s*:/i,
+    /<\|im_start\|>/i,
+    /<\|im_end\|>/i,
+    /\[INST\]/i,
+    /\[\/INST\]/i,
+    /<system>/i,
+    /<\/system>/i,
+    // Require "now" to avoid benign phrases like "you are a great help"
+    /you\s+are\s+now\s+(a|an)\s+/i,
+    // A heading-style "new instructions:" at the start of a line, not "new instructions for the cake".
+    /(?:^|\n)\s*new\s+instructions?\s*:/i,
+    /override\s+(previous|prior|all)\s+(instructions?|rules?)/i,
+];
+/** A `PROMPT_INJECTION` violation when any pattern matches the message, else null. */
+export function checkPromptInjection(message, patterns = DEFAULT_PROMPT_INJECTION_PATTERNS) {
+    const matched = patterns.some((pattern) => {
+        // Global and sticky patterns are stateful; test from the start, then leave the caller's regex
+        // as it was found.
+        const previous = pattern.lastIndex;
+        pattern.lastIndex = 0;
+        const result = pattern.test(message);
+        pattern.lastIndex = previous;
+        return result;
+    });
+    return matched ? { code: 'PROMPT_INJECTION' } : null;
+}

package/dist/bedrock-embedding-batches.d.mts

@@ -0,0 +1,53 @@
+import { type EmbeddingOptions } from './bedrock-embeddings.mts';
+/**
+ * Nova accepts inline media up to 25 MB after Base64 encoding; 18,000,000 raw bytes encode to
+ * 24,000,000, leaving room for framing; callers that enforce a smaller
+ * decoded bound (e.g. after converting images) pass it as `maxImageBytes`.
+ */
+export declare const DEFAULT_MAX_IMAGE_EMBEDDING_BYTES = 18000000;
+export type BatchSizeOptions = EmbeddingOptions & {
+    /** Decoded image bytes bound used to budget the worst-case record. */
+    maxImageBytes?: number;
+    /**
+     * Longest `recordId` in UTF-16 code units (default 128). Budgeted at JSON's worst case of six
+     * bytes per unit, since escapes can expand the encoded line.
+     */
+    maxRecordIdLength?: number;
+};
+/** One JSONL line of a batch input file. `recordId` is opaque and comes back on the result line. */
+export declare function createEmbeddingRecordLine(recordId: string, modelInput: Record<string, unknown>): string;
+export declare function createEmbeddingTextRecordLine(record: {
+    recordId: string;
+    content: string;
+}, options?: EmbeddingOptions): string;
+export declare function createEmbeddingImageRecordLine(record: {
+    recordId: string;
+    format: 'jpeg' | 'png' | 'webp' | 'gif';
+    bytes: string;
+}, options?: EmbeddingOptions): string;
+/** Lower bound on a batch file for `records` images: worst-case payload plus actual framing. */
+export declare function minimumImageBatchSizeMB(records: number, options?: BatchSizeOptions): number;
+/** Same for text; JSON control-character escapes cost up to six bytes per UTF-16 code unit. */
+export declare function minimumTextBatchSizeMB(records: number, options?: BatchSizeOptions): number;
+/** One line of a batch output file. */
+export type BatchResultLine = {
+    recordId: string;
+    error?: unknown;
+    modelOutput?: {
+        embedding?: number[];
+        embeddings?: Array<{
+            embedding: number[];
+        } | number[]>;
+        inputTokenCount?: number;
+    };
+};
+export type BatchEmbeddingResult = {
+    recordId: string;
+    embedding: number[];
+    inputTokenCount: number | null;
+};
+/**
+ * The vector of a result line, or null for errored lines and lines without one. Decoding the
+ * opaque `recordId` and validating the vector's dimension stay with the application.
+ */
+export declare function parseBatchResult(line: BatchResultLine): BatchEmbeddingResult | null;

package/dist/bedrock-embedding-batches.mjs

@@ -0,0 +1,51 @@
+import { buildEmbeddingModelInput, extractEmbedding, NOVA_EMBEDDING_DEFAULTS, } from './bedrock-embeddings.mjs';
+/**
+ * Nova accepts inline media up to 25 MB after Base64 encoding; 18,000,000 raw bytes encode to
+ * 24,000,000, leaving room for framing; callers that enforce a smaller
+ * decoded bound (e.g. after converting images) pass it as `maxImageBytes`.
+ */
+export const DEFAULT_MAX_IMAGE_EMBEDDING_BYTES = 18_000_000;
+const DEFAULT_MAX_RECORD_ID_LENGTH = 128;
+/** A control character JSON-escapes to six bytes (`\u0001`), the worst case per code unit. */
+const WORST_CASE_ID_UNIT = '\u0001';
+/** One JSONL line of a batch input file. `recordId` is opaque and comes back on the result line. */
+export function createEmbeddingRecordLine(recordId, modelInput) {
+    return JSON.stringify({ recordId, modelInput });
+}
+export function createEmbeddingTextRecordLine(record, options = {}) {
+    return createEmbeddingRecordLine(record.recordId, buildEmbeddingModelInput({ text: record.content }, options));
+}
+export function createEmbeddingImageRecordLine(record, options = {}) {
+    return createEmbeddingRecordLine(record.recordId, buildEmbeddingModelInput({ image: { format: record.format, bytes: record.bytes } }, options));
+}
+function framingBytes(line) {
+    return Buffer.byteLength(line) + 1;
+}
+/** Lower bound on a batch file for `records` images: worst-case payload plus actual framing. */
+export function minimumImageBatchSizeMB(records, options = {}) {
+    const recordId = WORST_CASE_ID_UNIT.repeat(options.maxRecordIdLength ?? DEFAULT_MAX_RECORD_ID_LENGTH);
+    const framing = framingBytes(createEmbeddingImageRecordLine({ recordId, format: 'jpeg', bytes: '' }, options));
+    const maxBytes = options.maxImageBytes ?? DEFAULT_MAX_IMAGE_EMBEDDING_BYTES;
+    return (records * (Math.ceil(maxBytes / 3) * 4 + framing)) / 1024 / 1024;
+}
+/** Same for text; JSON control-character escapes cost up to six bytes per UTF-16 code unit. */
+export function minimumTextBatchSizeMB(records, options = {}) {
+    const recordId = WORST_CASE_ID_UNIT.repeat(options.maxRecordIdLength ?? DEFAULT_MAX_RECORD_ID_LENGTH);
+    const maxTextLength = options.maxTextLength ?? NOVA_EMBEDDING_DEFAULTS.maxTextLength;
+    const framing = framingBytes(createEmbeddingTextRecordLine({ recordId, content: '' }, options));
+    return (records * (maxTextLength * 6 + framing)) / 1024 / 1024;
+}
+/**
+ * The vector of a result line, or null for errored lines and lines without one. Decoding the
+ * opaque `recordId` and validating the vector's dimension stay with the application.
+ */
+export function parseBatchResult(line) {
+    const embedding = line.error ? undefined : extractEmbedding(line.modelOutput);
+    if (!embedding)
+        return null;
+    return {
+        recordId: line.recordId,
+        embedding,
+        inputTokenCount: line.modelOutput?.inputTokenCount ?? null,
+    };
+}

package/dist/bedrock-embeddings.d.mts

@@ -0,0 +1,62 @@
+/** Defaults for Amazon Nova multimodal embeddings; every field can be overridden. */
+export declare const NOVA_EMBEDDING_DEFAULTS: {
+    readonly modelId: 'amazon.nova-2-multimodal-embeddings-v1:0';
+    readonly dimension: 1024;
+    /** Nova's inline `text.value` cap (UTF-16 code units). */
+    readonly maxTextLength: 8192;
+    /** Nova documents no input token count; this approximate estimate is for analytics only. */
+    readonly charactersPerToken: 4;
+};
+export type EmbeddingOptions = {
+    modelId?: string;
+    dimension?: number;
+    maxTextLength?: number;
+    /** `embeddingPurpose`: `GENERIC_INDEX` (default) for stored content, a retrieval purpose for queries. */
+    purpose?: string;
+    /** Nova image `detailLevel` (e.g. `STANDARD_IMAGE` or `DOCUMENT_IMAGE`); omitted by default. */
+    imageDetailLevel?: string;
+};
+/** The `InvokeModel` input; the app wraps it in its own command and client. */
+export type InvokeEmbeddingInput = {
+    modelId: string;
+    contentType: 'application/json';
+    accept: 'application/json';
+    body: string;
+};
+type EmbeddingEntry = {
+    embedding: number[];
+} | number[];
+type EmbeddingResponseBody = {
+    embedding?: number[];
+    embeddings?: EmbeddingEntry[];
+};
+export declare class InvalidEmbeddingError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Slices to the limit. When the cut falls inside a word, drops a trailing high surrogate and backs
+ * up to the last whitespace so the word is not cut; a cut that already ends a word is kept. Falls
+ * back to the hard slice when the head has no whitespace.
+ */
+export declare function truncateEmbeddingText(text: string, maxLength?: number): string;
+export declare function estimateEmbeddingTokens(text: string, charactersPerToken?: number): number;
+/** The model input for one text or image, shared by the single and batch record formats. */
+export declare function buildEmbeddingModelInput(content: {
+    text: string;
+} | {
+    image: {
+        format: 'jpeg' | 'png' | 'webp' | 'gif';
+        bytes: string;
+    };
+}, options?: EmbeddingOptions): Record<string, unknown>;
+export declare function buildInvokeEmbeddingInput(text: string, options?: EmbeddingOptions): InvokeEmbeddingInput;
+/** The first embedding of a response or batch `modelOutput`, in either documented shape. */
+export declare function extractEmbedding(body: EmbeddingResponseBody | undefined): number[] | undefined;
+/**
+ * Parses an `InvokeModel` response body into a dense vector of `dimension` finite numbers; throws
+ * `InvalidEmbeddingError` when the body is empty or holds no valid vector.
+ */
+export declare function parseEmbeddingResponseBody(body: Uint8Array | undefined, dimension?: number): number[];
+/** Narrows to a finite-number vector of exactly `dimension` entries or throws. */
+export declare function requireDenseEmbedding(value: unknown, dimension?: number): number[];
+export {};

package/dist/bedrock-embeddings.mjs

@@ -0,0 +1,106 @@
+/** Defaults for Amazon Nova multimodal embeddings; every field can be overridden. */
+export const NOVA_EMBEDDING_DEFAULTS = {
+    modelId: 'amazon.nova-2-multimodal-embeddings-v1:0',
+    dimension: 1024,
+    /** Nova's inline `text.value` cap (UTF-16 code units). */
+    maxTextLength: 8_192,
+    /** Nova documents no input token count; this approximate estimate is for analytics only. */
+    charactersPerToken: 4,
+};
+export class InvalidEmbeddingError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'InvalidEmbeddingError';
+    }
+}
+/**
+ * Slices to the limit. When the cut falls inside a word, drops a trailing high surrogate and backs
+ * up to the last whitespace so the word is not cut; a cut that already ends a word is kept. Falls
+ * back to the hard slice when the head has no whitespace.
+ */
+export function truncateEmbeddingText(text, maxLength = NOVA_EMBEDDING_DEFAULTS.maxTextLength) {
+    if (text.length <= maxLength)
+        return text;
+    let sliced = text.slice(0, maxLength);
+    if (/\s/.test(text.charAt(maxLength)))
+        return sliced;
+    const last = sliced.charCodeAt(sliced.length - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        sliced = sliced.slice(0, -1);
+    const lastWhitespace = sliced.search(/\s\S*$/);
+    return lastWhitespace > 0 ? sliced.slice(0, lastWhitespace) : sliced;
+}
+export function estimateEmbeddingTokens(text, charactersPerToken = NOVA_EMBEDDING_DEFAULTS.charactersPerToken) {
+    return Math.ceil(text.length / charactersPerToken);
+}
+/** The model input for one text or image, shared by the single and batch record formats. */
+export function buildEmbeddingModelInput(content, options = {}) {
+    const dimension = options.dimension ?? NOVA_EMBEDDING_DEFAULTS.dimension;
+    const common = {
+        embeddingPurpose: options.purpose ?? 'GENERIC_INDEX',
+        embeddingDimension: dimension,
+    };
+    return {
+        taskType: 'SINGLE_EMBEDDING',
+        singleEmbeddingParams: 'text' in content
+            ? {
+                ...common,
+                text: {
+                    truncationMode: 'END',
+                    value: truncateEmbeddingText(content.text, options.maxTextLength),
+                },
+            }
+            : {
+                ...common,
+                image: {
+                    format: content.image.format,
+                    source: { bytes: content.image.bytes },
+                    ...(options.imageDetailLevel ? { detailLevel: options.imageDetailLevel } : {}),
+                },
+            },
+    };
+}
+export function buildInvokeEmbeddingInput(text, options = {}) {
+    return {
+        modelId: options.modelId ?? NOVA_EMBEDDING_DEFAULTS.modelId,
+        contentType: 'application/json',
+        accept: 'application/json',
+        body: JSON.stringify(buildEmbeddingModelInput({ text }, options)),
+    };
+}
+/** The first embedding of a response or batch `modelOutput`, in either documented shape. */
+export function extractEmbedding(body) {
+    if (body?.embedding)
+        return body.embedding;
+    const first = body?.embeddings?.[0];
+    return Array.isArray(first) ? first : first?.embedding;
+}
+/**
+ * Parses an `InvokeModel` response body into a dense vector of `dimension` finite numbers; throws
+ * `InvalidEmbeddingError` when the body is empty or holds no valid vector.
+ */
+export function parseEmbeddingResponseBody(body, dimension = NOVA_EMBEDDING_DEFAULTS.dimension) {
+    if (!body)
+        throw new InvalidEmbeddingError('Bedrock embedding response body is empty');
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(body));
+    }
+    catch (err) {
+        throw new InvalidEmbeddingError('Bedrock embedding response is not valid JSON', { cause: err });
+    }
+    const embedding = extractEmbedding(parsed);
+    if (!embedding) {
+        throw new InvalidEmbeddingError('Bedrock embedding response did not include an embedding');
+    }
+    return requireDenseEmbedding(embedding, dimension);
+}
+/** Narrows to a finite-number vector of exactly `dimension` entries or throws. */
+export function requireDenseEmbedding(value, dimension = NOVA_EMBEDDING_DEFAULTS.dimension) {
+    if (!Array.isArray(value) ||
+        value.length !== dimension ||
+        value.some((element) => typeof element !== 'number' || !Number.isFinite(element))) {
+        throw new InvalidEmbeddingError('Bedrock embedding is not a dense vector');
+    }
+    return value;
+}

package/dist/service-worker-activation.d.mts

@@ -0,0 +1,26 @@
+export declare class ServiceWorkerActivationTimeoutError extends Error {
+    constructor();
+}
+export interface WaitForActiveServiceWorkerOptions {
+    timeoutMs?: number;
+    /** Defaults to navigator.serviceWorker; injectable for tests. */
+    serviceWorker?: ServiceWorkerContainer;
+}
+declare global {
+    interface ServiceWorker extends EventTarget {
+        readonly state: 'parsed' | 'installing' | 'installed' | 'activating' | 'activated' | 'redundant';
+    }
+    interface ServiceWorkerRegistration {
+        readonly active: ServiceWorker | null;
+        readonly installing: ServiceWorker | null;
+        readonly waiting: ServiceWorker | null;
+    }
+    interface ServiceWorkerContainer {
+        readonly ready: Promise<ServiceWorkerRegistration>;
+    }
+    interface Navigator {
+        readonly serviceWorker: ServiceWorkerContainer;
+    }
+}
+/** Resolves when `registration` has an active worker. Pass `timeoutMs` to bound the wait. */
+export declare function waitForActiveServiceWorker(registration: ServiceWorkerRegistration, options?: WaitForActiveServiceWorkerOptions): Promise<ServiceWorkerRegistration>;

package/dist/service-worker-activation.mjs

@@ -0,0 +1,50 @@
+export class ServiceWorkerActivationTimeoutError extends Error {
+    constructor() {
+        super('Timed out waiting for the service worker to activate.');
+        this.name = 'ServiceWorkerActivationTimeoutError';
+    }
+}
+/** Resolves when `registration` has an active worker. Pass `timeoutMs` to bound the wait. */
+export function waitForActiveServiceWorker(registration, options = {}) {
+    const replacement = registration.installing ?? registration.waiting;
+    if (!replacement) {
+        if (registration.active)
+            return Promise.resolve(registration);
+        const container = options.serviceWorker ?? navigator.serviceWorker;
+        return waitWithOptionalTimeout(container.ready, options.timeoutMs);
+    }
+    if (replacement.state === 'activated')
+        return Promise.resolve(registration);
+    return waitForReplacement(registration, replacement, options.timeoutMs);
+}
+function waitForReplacement(registration, worker, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const timeout = timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => finish(() => reject(new ServiceWorkerActivationTimeoutError())), timeoutMs);
+        function finish(settle) {
+            worker.removeEventListener('statechange', onStateChange);
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            settle();
+        }
+        function onStateChange() {
+            if (worker.state === 'activated')
+                finish(() => resolve(registration));
+            else if (worker.state === 'redundant') {
+                finish(() => reject(new Error('Service worker replacement became redundant.')));
+            }
+        }
+        worker.addEventListener('statechange', onStateChange);
+        onStateChange();
+    });
+}
+function waitWithOptionalTimeout(ready, timeoutMs) {
+    if (timeoutMs === undefined)
+        return ready;
+    let timeout;
+    const timedOut = new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new ServiceWorkerActivationTimeoutError()), timeoutMs);
+    });
+    return Promise.race([ready, timedOut]).finally(() => clearTimeout(timeout));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/utils",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "Dependency-free runtime utilities for Vouchington-style applications.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/utils#readme",
   "bugs": {
@@ -20,6 +20,21 @@
   ],
   "type": "module",
   "exports": {
+    "./ai-moderation": {
+      "types": "./dist/ai-moderation.d.mts",
+      "import": "./dist/ai-moderation.mjs",
+      "default": "./dist/ai-moderation.mjs"
+    },
+    "./bedrock-embedding-batches": {
+      "types": "./dist/bedrock-embedding-batches.d.mts",
+      "import": "./dist/bedrock-embedding-batches.mjs",
+      "default": "./dist/bedrock-embedding-batches.mjs"
+    },
+    "./bedrock-embeddings": {
+      "types": "./dist/bedrock-embeddings.d.mts",
+      "import": "./dist/bedrock-embeddings.mjs",
+      "default": "./dist/bedrock-embeddings.mjs"
+    },
     "./api-errors": {
       "types": "./dist/api-errors.d.mts",
       "import": "./dist/api-errors.mjs",
@@ -50,6 +65,11 @@
       "import": "./dist/web-push-binding.mjs",
       "default": "./dist/web-push-binding.mjs"
     },
+    "./service-worker-activation": {
+      "types": "./dist/service-worker-activation.d.mts",
+      "import": "./dist/service-worker-activation.mjs",
+      "default": "./dist/service-worker-activation.mjs"
+    },
     "./json-ld": {
       "types": "./dist/json-ld.d.mts",
       "import": "./dist/json-ld.mjs",