avatarsniff 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,86 @@
+import { R as RgbaImage, D as DetectOptions, a as DefaultAvatarDetection, b as DecodeOptions, I as ImageFormat } from './types-BlZG8aqK.cjs';
+export { c as DETECTOR_NAMES, d as DetectorName, e as DetectorToggles } from './types-BlZG8aqK.cjs';
+
+/**
+ * Analyse raw image pixels and decide whether they look like a generic/default
+ * provider avatar. Pure: the same input always yields the same result.
+ * Framework- and runtime-agnostic - no DOM, no Node, no native dependency.
+ *
+ * Runs an independent structural detector per family (initials, solidColor,
+ * personIcon, identicon); the first to claim the image wins, and `matched`
+ * reports which. Disable families via `options.detect` (each defaults on). The
+ * heuristics key on *structure*, never on specific palette colours, so they
+ * keep working as providers add new ones.
+ */
+declare function analyzeImage(image: RgbaImage, options?: DetectOptions): DefaultAvatarDetection;
+
+/**
+ * Built-in, zero-dependency image decoding for PNG, JPEG, GIF, WEBP and SVG.
+ *
+ * Two layers, no npm or native dependencies:
+ *
+ *  1. **Native layer** - when the runtime provides `createImageBitmap` + a
+ *     canvas (`OffscreenCanvas` or a DOM `<canvas>`), every format is decoded
+ *     by the platform: browsers, web workers, Deno, Bun. SVG is rasterised via
+ *     an `<img>` element when a DOM is present.
+ *  2. **Pure-JS layer** - for plain Node (no canvas), PNG and GIF are decoded in
+ *     pure JS (PNG inflate uses the built-in `DecompressionStream`) and JPEG via
+ *     the bundled `jpeg-js` (a devDependency inlined into `dist`, so consumers
+ *     still install zero dependencies). WEBP and SVG aren't decoded here; they
+ *     return `null`, which callers treat as "not a default, keep it" - the right
+ *     outcome for a real photo/graphic.
+ *
+ * Inputs larger than `maxBytes` (default 10MB) are rejected before decoding.
+ */
+declare const DEFAULT_MAX_BYTES: number;
+declare function sniffFormat(bytes: Uint8Array): ImageFormat;
+/**
+ * Decode encoded image bytes (PNG, JPEG, GIF, WEBP, SVG) to RGBA pixels.
+ * Returns `null` when the format can't be decoded in the current runtime or the
+ * input exceeds `maxBytes`. Zero dependencies.
+ */
+declare function decodeImage(bytes: Uint8Array | ArrayBuffer, options?: DecodeOptions): Promise<RgbaImage | null>;
+
+type Decoder = (bytes: Uint8Array) => Promise<RgbaImage | null>;
+/**
+ * Register a decoder for a format. The opt-in `avatarsniff/webp` and
+ * `avatarsniff/svg` entry points call this on import, so importing them makes
+ * `decodeImage`/`sniff` handle that format in plain Node too. You
+ * can also register your own decoder for any format.
+ */
+declare function registerDecoder(format: ImageFormat, decoder: Decoder): void;
+
+/** Minimal structural shape of a canvas `ImageData` (RGBA pixels). */
+interface ImageDataLike {
+    data: Uint8ClampedArray | Uint8Array | number[];
+    width: number;
+    height: number;
+}
+/**
+ * Anything `sniff` accepts:
+ *  - encoded bytes (`Uint8Array` / `ArrayBuffer`) — decoded, then analysed;
+ *  - raw pixels (a canvas `ImageData` or any `RgbaImage`) — analysed directly;
+ *  - a URL string — fetched, then decoded and analysed;
+ *  - `null` / `undefined` — resolves to `null` (nothing to sniff).
+ */
+type SniffInput = Uint8Array | ArrayBuffer | ImageDataLike | RgbaImage | string | null | undefined;
+/**
+ * Detect whether an avatar is a generic provider default. The one entry point —
+ * it sniffs out what you passed and does the right thing:
+ *
+ * ```ts
+ * await sniff(bytes);                 // Uint8Array / ArrayBuffer
+ * await sniff(canvasImageData);       // browser <canvas> getImageData()
+ * await sniff(user.photoUrl);         // URL string (fetched for you)
+ * await sniff(bytes, { detect: { identicon: false } });
+ * ```
+ *
+ * Always async. Returns `null` only when there was nothing to sniff — a
+ * nullish input, or a URL that was missing or failed to fetch — so the caller
+ * can keep the existing image. Undecodable bytes resolve to a not-a-default
+ * verdict (a real photo we can't read is safely kept, not wrongly replaced).
+ */
+declare function sniff(input: string | null | undefined, options?: DetectOptions): Promise<DefaultAvatarDetection | null>;
+declare function sniff(input: Uint8Array | ArrayBuffer | ImageDataLike | RgbaImage, options?: DetectOptions): Promise<DefaultAvatarDetection>;
+
+export { DEFAULT_MAX_BYTES, DecodeOptions, type Decoder, DefaultAvatarDetection, DetectOptions, type ImageDataLike, ImageFormat, RgbaImage, type SniffInput, analyzeImage, decodeImage, registerDecoder, sniff, sniffFormat };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+import { R as RgbaImage, D as DetectOptions, a as DefaultAvatarDetection, b as DecodeOptions, I as ImageFormat } from './types-BlZG8aqK.js';
+export { c as DETECTOR_NAMES, d as DetectorName, e as DetectorToggles } from './types-BlZG8aqK.js';
+
+/**
+ * Analyse raw image pixels and decide whether they look like a generic/default
+ * provider avatar. Pure: the same input always yields the same result.
+ * Framework- and runtime-agnostic - no DOM, no Node, no native dependency.
+ *
+ * Runs an independent structural detector per family (initials, solidColor,
+ * personIcon, identicon); the first to claim the image wins, and `matched`
+ * reports which. Disable families via `options.detect` (each defaults on). The
+ * heuristics key on *structure*, never on specific palette colours, so they
+ * keep working as providers add new ones.
+ */
+declare function analyzeImage(image: RgbaImage, options?: DetectOptions): DefaultAvatarDetection;
+
+/**
+ * Built-in, zero-dependency image decoding for PNG, JPEG, GIF, WEBP and SVG.
+ *
+ * Two layers, no npm or native dependencies:
+ *
+ *  1. **Native layer** - when the runtime provides `createImageBitmap` + a
+ *     canvas (`OffscreenCanvas` or a DOM `<canvas>`), every format is decoded
+ *     by the platform: browsers, web workers, Deno, Bun. SVG is rasterised via
+ *     an `<img>` element when a DOM is present.
+ *  2. **Pure-JS layer** - for plain Node (no canvas), PNG and GIF are decoded in
+ *     pure JS (PNG inflate uses the built-in `DecompressionStream`) and JPEG via
+ *     the bundled `jpeg-js` (a devDependency inlined into `dist`, so consumers
+ *     still install zero dependencies). WEBP and SVG aren't decoded here; they
+ *     return `null`, which callers treat as "not a default, keep it" - the right
+ *     outcome for a real photo/graphic.
+ *
+ * Inputs larger than `maxBytes` (default 10MB) are rejected before decoding.
+ */
+declare const DEFAULT_MAX_BYTES: number;
+declare function sniffFormat(bytes: Uint8Array): ImageFormat;
+/**
+ * Decode encoded image bytes (PNG, JPEG, GIF, WEBP, SVG) to RGBA pixels.
+ * Returns `null` when the format can't be decoded in the current runtime or the
+ * input exceeds `maxBytes`. Zero dependencies.
+ */
+declare function decodeImage(bytes: Uint8Array | ArrayBuffer, options?: DecodeOptions): Promise<RgbaImage | null>;
+
+type Decoder = (bytes: Uint8Array) => Promise<RgbaImage | null>;
+/**
+ * Register a decoder for a format. The opt-in `avatarsniff/webp` and
+ * `avatarsniff/svg` entry points call this on import, so importing them makes
+ * `decodeImage`/`sniff` handle that format in plain Node too. You
+ * can also register your own decoder for any format.
+ */
+declare function registerDecoder(format: ImageFormat, decoder: Decoder): void;
+
+/** Minimal structural shape of a canvas `ImageData` (RGBA pixels). */
+interface ImageDataLike {
+    data: Uint8ClampedArray | Uint8Array | number[];
+    width: number;
+    height: number;
+}
+/**
+ * Anything `sniff` accepts:
+ *  - encoded bytes (`Uint8Array` / `ArrayBuffer`) — decoded, then analysed;
+ *  - raw pixels (a canvas `ImageData` or any `RgbaImage`) — analysed directly;
+ *  - a URL string — fetched, then decoded and analysed;
+ *  - `null` / `undefined` — resolves to `null` (nothing to sniff).
+ */
+type SniffInput = Uint8Array | ArrayBuffer | ImageDataLike | RgbaImage | string | null | undefined;
+/**
+ * Detect whether an avatar is a generic provider default. The one entry point —
+ * it sniffs out what you passed and does the right thing:
+ *
+ * ```ts
+ * await sniff(bytes);                 // Uint8Array / ArrayBuffer
+ * await sniff(canvasImageData);       // browser <canvas> getImageData()
+ * await sniff(user.photoUrl);         // URL string (fetched for you)
+ * await sniff(bytes, { detect: { identicon: false } });
+ * ```
+ *
+ * Always async. Returns `null` only when there was nothing to sniff — a
+ * nullish input, or a URL that was missing or failed to fetch — so the caller
+ * can keep the existing image. Undecodable bytes resolve to a not-a-default
+ * verdict (a real photo we can't read is safely kept, not wrongly replaced).
+ */
+declare function sniff(input: string | null | undefined, options?: DetectOptions): Promise<DefaultAvatarDetection | null>;
+declare function sniff(input: Uint8Array | ArrayBuffer | ImageDataLike | RgbaImage, options?: DetectOptions): Promise<DefaultAvatarDetection>;
+
+export { DEFAULT_MAX_BYTES, DecodeOptions, type Decoder, DefaultAvatarDetection, DetectOptions, type ImageDataLike, ImageFormat, RgbaImage, type SniffInput, analyzeImage, decodeImage, registerDecoder, sniff, sniffFormat };