@juspay/neurolink 10.10.12 → 10.11.0

package/dist/processors/config/fileExtensions.js

@@ -2,31 +2,32 @@
  * File Extension Constants
  * Centralized file extension definitions organized by category for file processing
  *
+ * The media/document/data/archive categories are derived from
+ * {@link FILE_TYPE_REGISTRY} rather than typed out here — they used to be a
+ * second hand-maintained list that drifted from both the registry-equivalent
+ * MIME map and the detector, so formats appeared "supported" in one place and
+ * were invisible in another. Source-code and text categories, which carry no
+ * modality, are still enumerated below.
+ *
  * @module processors/config/fileTypes
  */
+import { extensionsForModality } from "./fileTypeRegistry.js";
 // =============================================================================
 // IMAGE FILE EXTENSIONS
 // =============================================================================
 /**
- * Image file extensions supported by the platform
+ * Image file extensions supported by the platform.
+ * Includes `.svg`, which is processed as sanitized markup rather than raster.
  */
-export const IMAGE_EXTENSIONS = [
-    ".jpg",
-    ".jpeg",
-    ".png",
-    ".gif",
-    ".webp",
-    ".svg",
-    ".bmp",
-    ".tiff",
-    ".tif",
-    ".avif",
-    ".heic",
-    ".heif",
-    ".ico",
-];
+export const IMAGE_EXTENSIONS = extensionsForModality("image");
 /**
- * AI vision-supported image extensions (subset that works with AI models)
+ * Image extensions every vision-capable provider accepts as-is.
+ *
+ * Deliberately NOT derived from the registry: this is the intersection of what
+ * OpenAI, Anthropic, Google and Bedrock all accept, not the set NeuroLink can
+ * identify. Anything else the registry knows about (BMP, TIFF, AVIF, ICO,
+ * HEIC/HEIF) is transcoded to PNG before dispatch — see
+ * `adapters/imageFormatSupport.ts`.
  */
 export const AI_VISION_EXTENSIONS = [
     ".jpg",
@@ -41,19 +42,7 @@ export const AI_VISION_EXTENSIONS = [
 /**
  * Document file extensions for office documents and PDFs
  */
-export const DOCUMENT_EXTENSIONS = [
-    ".pdf",
-    ".docx",
-    ".doc",
-    ".xlsx",
-    ".xls",
-    ".pptx",
-    ".ppt",
-    ".odt",
-    ".ods",
-    ".odp",
-    ".rtf",
-];
+export const DOCUMENT_EXTENSIONS = extensionsForModality("document");
 /**
  * PDF document extensions
  */
@@ -98,14 +87,17 @@ export const CSV_EXTENSIONS = [".csv"];
  */
 export const YAML_EXTENSIONS = [".yaml", ".yml"];
 /**
- * All data format extensions combined
+ * All data format extensions combined.
+ *
+ * The tabular formats (.csv/.tsv) come from the registry; .json/.xml/.yaml are
+ * text formats with no modality of their own and stay listed here.
  */
 export const DATA_EXTENSIONS = [
     ".json",
     ".xml",
-    ".csv",
     ".yaml",
     ".yml",
+    ...extensionsForModality("data"),
 ];
 // =============================================================================
 // TEXT FILE EXTENSIONS
@@ -346,49 +338,18 @@ export const CONFIG_EXTENSIONS = [
 /**
  * Archive and compressed file extensions
  */
-export const ARCHIVE_EXTENSIONS = [
-    ".zip",
-    ".tar",
-    ".gz",
-    ".tgz",
-    ".tar.gz",
-    ".tar.bz2",
-    ".bz2",
-    ".rar",
-    ".7z",
-    ".xz",
-];
+export const ARCHIVE_EXTENSIONS = extensionsForModality("archive");
 // =============================================================================
 // MULTIMEDIA FILE EXTENSIONS
 // =============================================================================
 /**
  * Video file extensions
  */
-export const VIDEO_EXTENSIONS = [
-    ".mp4",
-    ".avi",
-    ".mov",
-    ".mkv",
-    ".webm",
-    ".flv",
-    ".wmv",
-    ".m4v",
-    ".mpg",
-    ".mpeg",
-];
+export const VIDEO_EXTENSIONS = extensionsForModality("video");
 /**
  * Audio file extensions
  */
-export const AUDIO_EXTENSIONS = [
-    ".mp3",
-    ".wav",
-    ".aac",
-    ".flac",
-    ".ogg",
-    ".m4a",
-    ".wma",
-    ".opus",
-];
+export const AUDIO_EXTENSIONS = extensionsForModality("audio");
 // =============================================================================
 // DESIGN FILE EXTENSIONS
 // =============================================================================

package/dist/processors/config/fileTypeRegistry.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Canonical file-format registry — the single source of truth for
+ * extension ↔ MIME ↔ FileType ↔ modality.
+ *
+ * ## Why this exists
+ *
+ * The same knowledge used to live in five hand-maintained tables that had no
+ * way of agreeing with each other:
+ *
+ *   1. `EXTENSION_MIME_MAP`                      (config/mimeConstants.ts)
+ *   2. the `*_EXTENSIONS` category arrays        (config/fileExtensions.ts)
+ *   3. `ExtensionStrategy.typeMap` + `.mimeMap`  (utils/fileDetector.ts)
+ *   4. `EXTENSION_TYPE_MAP`                      (utils/messageBuilder.ts)
+ *   5. each processor's `supportedExtensions` / `supportedMimeTypes`
+ *
+ * They drifted, and the drift was not cosmetic — a format that a processor
+ * declared it supported was routinely invisible to the detector standing in
+ * front of it, so the file never reached the processor at all. Measured on real
+ * ffmpeg-generated media before this registry existed:
+ *
+ *   .aiff .m2ts .mts .vob .3g2 .3gp   → "unknown"  (downgraded to metadata text)
+ *   .mpg .mpeg                        → "csv"      (binary parsed as a spreadsheet)
+ *   .ts                               → "text"     (MPEG-TS inlined as source code)
+ *
+ * Deriving all five consumers from one table makes that class of drift
+ * structurally impossible rather than merely fixed once.
+ *
+ * ## Invariants
+ *
+ * - `extensions[0]` is canonical for the format; the rest are accepted aliases.
+ * - `mimeTypes[0]` is canonical; the rest are aliases seen in the wild
+ *   (`audio/x-wav`, `image/x-icon`, vendor prefixes, …).
+ * - Every extension and every MIME type appears in exactly one entry. The
+ *   `assertRegistryIsUnambiguous()` check below is executed at module load, so
+ *   a duplicate is a startup failure rather than a silent last-write-wins.
+ * - `fileType` is the *routing* type the detector emits (what processor to
+ *   use); `modality` is the *category* a human means. They deliberately differ:
+ *   an .odt is `fileType: "docx"` (the Word processor handles it) but
+ *   `modality: "document"`, and .svg is `fileType: "svg"` (sanitised as markup,
+ *   never sent to a vision API) but `modality: "image"`.
+ *
+ * @module processors/config/fileTypeRegistry
+ */
+import type { FileFormatEntry, FileModality, FileType } from "../../types/index.js";
+/**
+ * Every file format NeuroLink can identify, grouped by modality.
+ *
+ * Adding a format here is all that is required — the extension map, the MIME
+ * map, the detector's lookup tables, the category arrays and the media
+ * processors' supported-format lists are all derived from this array.
+ */
+export declare const FILE_TYPE_REGISTRY: readonly FileFormatEntry[];
+/**
+ * Extensions that must NOT be treated as belonging to their registry entry's
+ * modality when only a filename is available.
+ *
+ * Derived from {@link EXTENSION_OVERRIDES}: `extensionsForModality("video")`
+ * feeds both `VIDEO_EXTENSIONS` and `VideoProcessor`'s supported list, and
+ * `BaseFileProcessor.isFileSupported` accepts a file when the *extension*
+ * matches even if the supplied mimetype says otherwise. Leaving `.ts` in that
+ * list made `isVideoFile("text/plain", "app.ts")` return true.
+ */
+/**
+ * Extension → MIME for the overridden extensions only.
+ *
+ * Exported so `EXTENSION_MIME_MAP` can apply the override as its FINAL layer.
+ * That map is built by spreading the registry over the text map, so without
+ * this the registry's `.ts → video/mp2t` won again and `getMimeTypeForExtension`
+ * disagreed with `mimeTypeForExtension` about the very same file.
+ */
+export declare const EXTENSION_MIME_OVERRIDES: Readonly<Record<string, string>>;
+/**
+ * Normalize an extension to the registry's key form: lowercased, with a leading
+ * dot. Accepts `"png"`, `".PNG"`, `"image.png"` and `"/tmp/a.png"` alike.
+ *
+ * Compound extensions (`.tar.gz`) are matched before the single-segment form so
+ * a `.tar.gz` resolves to the gzip entry rather than to `.gz` by accident —
+ * they happen to agree today, but the lookup should not depend on that.
+ */
+export declare function normalizeExtension(raw: string): string;
+/** Look up the registry entry for a file extension, or undefined. */
+export declare function lookupByExtension(ext: string): FileFormatEntry | undefined;
+/**
+ * Look up the registry entry for a MIME type, or undefined. Any `;charset=…`
+ * parameter is stripped, matching how Content-Type headers arrive.
+ */
+export declare function lookupByMimeType(mime: string): FileFormatEntry | undefined;
+/**
+ * Routing {@link FileType} for an extension, honouring {@link EXTENSION_OVERRIDES}.
+ * Returns undefined when the extension is not in the registry.
+ */
+export declare function fileTypeForExtension(ext: string): FileType | undefined;
+/** Canonical MIME type for an extension, or undefined when unknown. */
+export declare function mimeTypeForExtension(ext: string): string | undefined;
+/** Canonical extension (with leading dot) for a MIME type, or undefined. */
+export declare function extensionForMimeType(mime: string): string | undefined;
+/** Every extension registered for a modality, in registry order. */
+export declare function extensionsForModality(modality: FileModality): readonly string[];
+/** Every MIME type registered for a modality, in registry order. */
+export declare function mimeTypesForModality(modality: FileModality): readonly string[];
+/**
+ * True when the extension belongs to the given modality. Uses the entry's
+ * modality, not its routing `fileType`, so `.svg` counts as an image and `.odt`
+ * counts as a document.
+ */
+export declare function isModalityExtension(ext: string, modality: FileModality): boolean;