alt-images-ai 1.0.0

package/README.md

@@ -0,0 +1,186 @@
+# alt-images-ai
+
+[![npm version](https://img.shields.io/npm/v/alt-images-ai)](https://www.npmjs.com/package/alt-images-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+Generate accessible alt text for images using AI. Supports **OpenAI** (GPT-4o) and **Google Gemini**.
+
+Zero runtime dependencies — uses only Node.js built-in modules. Full TypeScript support.
+
+## Features
+
+- **Multiple AI providers** — OpenAI and Google Gemini out of the box
+- **Flexible image input** — URLs, local files, base64 data URIs, or Buffers
+- **HTML processing** — Automatically scan and add `alt` attributes to `<img>` tags
+- **Batch processing** — Generate alt text for multiple images in parallel
+- **Multi-language** — Generate descriptions in any language
+- **Configurable** — Custom prompts, max length, model selection
+- **TypeScript** — Full type definitions included
+- **Lightweight** — Zero runtime dependencies
+
+## Installation
+
+```bash
+npm install alt-images-ai
+```
+
+## Quick Start
+
+```typescript
+import { AltImageClient } from "alt-images-ai";
+
+const client = new AltImageClient({
+  provider: "openai", // or "gemini"
+  apiKey: "your-api-key",
+});
+
+const alt = await client.generateAlt("https://example.com/photo.jpg");
+console.log(alt);
+// "Golden retriever running across a sunlit meadow"
+```
+
+## Usage
+
+### Create a Client
+
+```typescript
+import { AltImageClient } from "alt-images-ai";
+
+const client = new AltImageClient({
+  provider: "openai",    // "openai" | "gemini"
+  apiKey: "sk-...",
+  language: "es",         // optional — default: "en"
+  maxLength: 125,         // optional — max characters for alt text
+  model: "gpt-4o",       // optional — override default model
+  customPrompt: "...",    // optional — fully custom AI prompt
+});
+```
+
+### Generate Alt Text for a Single Image
+
+```typescript
+// From a URL
+const alt = await client.generateAlt("https://example.com/photo.jpg");
+
+// From a local file
+const alt = await client.generateAlt("./images/hero.png");
+
+// From a Buffer
+import fs from "fs";
+const buffer = fs.readFileSync("photo.jpg");
+const alt = await client.generateAlt(buffer);
+
+// With per-call overrides
+const alt = await client.generateAlt("photo.jpg", {
+  language: "fr",
+  maxLength: 100,
+});
+```
+
+### Batch Processing
+
+Process multiple images in parallel. Failed images are collected in the `errors` array without stopping the rest.
+
+```typescript
+const { results, errors } = await client.generateAltBatch([
+  "https://example.com/img1.jpg",
+  "https://example.com/img2.jpg",
+  "./local-image.png",
+]);
+
+for (const { src, alt } of results) {
+  console.log(`${src} → ${alt}`);
+}
+
+for (const { src, error } of errors) {
+  console.error(`${src} failed: ${error.message}`);
+}
+```
+
+### Process HTML
+
+Scan an HTML string, find `<img>` tags missing alt text, and automatically generate it:
+
+```typescript
+const html = `
+  <div>
+    <img src="hero.jpg">
+    <img src="team.jpg" alt="">
+    <img src="logo.png" alt="Company logo">
+  </div>
+`;
+
+const result = await client.processHTML(html);
+// hero.jpg  → gets AI-generated alt
+// team.jpg  → gets AI-generated alt (empty alt counts as missing)
+// logo.png  → left unchanged (already has alt text)
+```
+
+#### HTML Processing Options
+
+```typescript
+const result = await client.processHTML(html, {
+  onlyMissing: true,        // only process images without alt (default: true)
+  overrideExisting: false,   // replace existing alt values (default: false)
+  language: "es",            // override language for this call
+});
+```
+
+### One-liner
+
+Generate alt text without creating a client first:
+
+```typescript
+import { generateAlt } from "alt-images-ai";
+
+const alt = await generateAlt("photo.jpg", {
+  provider: "openai",
+  apiKey: "sk-...",
+});
+```
+
+## Providers
+
+| Provider | Default Model    | Documentation                                                  |
+| -------- | ---------------- | -------------------------------------------------------------- |
+| `openai` | `gpt-4o-mini`   | [OpenAI Vision](https://platform.openai.com/docs/guides/vision) |
+| `gemini` | `gemini-2.0-flash` | [Google Gemini](https://ai.google.dev/docs)                  |
+
+## API Reference
+
+### `new AltImageClient(options)`
+
+| Option         | Type                     | Required | Default          | Description                        |
+| -------------- | ------------------------ | -------- | ---------------- | ---------------------------------- |
+| `provider`     | `"openai" \| "gemini"`   | Yes      | —                | AI provider to use                 |
+| `apiKey`       | `string`                 | Yes      | —                | API key for the provider           |
+| `model`        | `string`                 | No       | Provider default | Override the default model         |
+| `language`     | `string`                 | No       | `"en"`           | Language for generated alt text    |
+| `maxLength`    | `number`                 | No       | —                | Maximum character length           |
+| `customPrompt` | `string`                 | No       | —                | Fully custom prompt for the AI     |
+
+### `client.generateAlt(image, options?): Promise<string>`
+
+Generate alt text for a single image. Accepts a URL, file path, data URI, or Buffer.
+
+### `client.generateAltBatch(images, options?): Promise<BatchResult>`
+
+Generate alt text for multiple images in parallel. Returns `{ results, errors }`.
+
+### `client.processHTML(html, options?): Promise<string>`
+
+Parse HTML, find `<img>` tags, and add AI-generated alt attributes. Returns the modified HTML string.
+
+### `generateAlt(image, options): Promise<string>`
+
+Standalone function that creates a client internally — useful for one-off calls.
+
+## Requirements
+
+- Node.js >= 18
+- An API key from [OpenAI](https://platform.openai.com/api-keys) or [Google AI Studio](https://aistudio.google.com/apikey)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { AltImageClientOptions, BatchResult, GenerateAltOptions, ProcessHTMLOptions } from "./types";
+export declare class AltImageClient {
+    private provider;
+    private language;
+    private maxLength;
+    private customPrompt;
+    constructor(options: AltImageClientOptions);
+    /**
+     * Generate alt text for a single image.
+     *
+     * @param image - URL, file path, data URI, or Buffer
+     * @param options - Override default language, maxLength, or prompt
+     * @returns The generated alt text string
+     */
+    generateAlt(image: string | Buffer, options?: GenerateAltOptions): Promise<string>;
+    /**
+     * Generate alt text for multiple images in parallel.
+     *
+     * @param images - Array of URLs, file paths, data URIs, or Buffers
+     * @param options - Override default language, maxLength, or prompt
+     * @returns Object with results array and errors array
+     */
+    generateAltBatch(images: (string | Buffer)[], options?: GenerateAltOptions): Promise<BatchResult>;
+    /**
+     * Process an HTML string: find <img> tags and generate alt text for them.
+     *
+     * @param html - HTML string to process
+     * @param options - Configure which images to process and generation options
+     * @returns The HTML string with alt attributes added/updated
+     */
+    processHTML(html: string, options?: ProcessHTMLOptions): Promise<string>;
+    private buildPrompt;
+}

package/dist/client.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AltImageClient = void 0;
+const openai_1 = require("./providers/openai");
+const gemini_1 = require("./providers/gemini");
+const image_1 = require("./utils/image");
+const html_1 = require("./utils/html");
+class AltImageClient {
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new Error("apiKey is required");
+        }
+        this.language = options.language ?? "en";
+        this.maxLength = options.maxLength;
+        this.customPrompt = options.customPrompt;
+        switch (options.provider) {
+            case "openai":
+                this.provider = new openai_1.OpenAIProvider(options.apiKey, options.model);
+                break;
+            case "gemini":
+                this.provider = new gemini_1.GeminiProvider(options.apiKey, options.model);
+                break;
+            default:
+                throw new Error(`Unsupported provider: ${options.provider}. Use "openai" or "gemini".`);
+        }
+    }
+    /**
+     * Generate alt text for a single image.
+     *
+     * @param image - URL, file path, data URI, or Buffer
+     * @param options - Override default language, maxLength, or prompt
+     * @returns The generated alt text string
+     */
+    async generateAlt(image, options) {
+        const { base64, mimeType } = await (0, image_1.resolveImage)(image);
+        const prompt = this.buildPrompt(options);
+        let alt = await this.provider.generateAlt(base64, mimeType, prompt);
+        const maxLen = options?.maxLength ?? this.maxLength;
+        if (maxLen && alt.length > maxLen) {
+            alt = alt.substring(0, maxLen - 3).trimEnd() + "...";
+        }
+        return alt;
+    }
+    /**
+     * Generate alt text for multiple images in parallel.
+     *
+     * @param images - Array of URLs, file paths, data URIs, or Buffers
+     * @param options - Override default language, maxLength, or prompt
+     * @returns Object with results array and errors array
+     */
+    async generateAltBatch(images, options) {
+        const results = [];
+        const errors = [];
+        const promises = images.map(async (image) => {
+            const src = Buffer.isBuffer(image) ? "[Buffer]" : image;
+            try {
+                const alt = await this.generateAlt(image, options);
+                results.push({ alt, src });
+            }
+            catch (err) {
+                errors.push({
+                    src,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            }
+        });
+        await Promise.all(promises);
+        return { results, errors };
+    }
+    /**
+     * Process an HTML string: find <img> tags and generate alt text for them.
+     *
+     * @param html - HTML string to process
+     * @param options - Configure which images to process and generation options
+     * @returns The HTML string with alt attributes added/updated
+     */
+    async processHTML(html, options) {
+        const onlyMissing = options?.onlyMissing ?? true;
+        const overrideExisting = options?.overrideExisting ?? false;
+        const imgTags = (0, html_1.extractImgTags)(html);
+        let result = html;
+        for (const tag of imgTags) {
+            const shouldProcess = !tag.hasAlt || (overrideExisting && !onlyMissing) || (tag.hasAlt && tag.alt === "");
+            if (!shouldProcess && onlyMissing)
+                continue;
+            if (tag.hasAlt && !overrideExisting && tag.alt !== "")
+                continue;
+            try {
+                const alt = await this.generateAlt(tag.src, options);
+                result = (0, html_1.setImgAlt)(result, tag, alt);
+            }
+            catch {
+                // Skip images that fail — keep existing HTML intact
+            }
+        }
+        return result;
+    }
+    buildPrompt(options) {
+        const custom = options?.customPrompt ?? this.customPrompt;
+        if (custom)
+            return custom;
+        const lang = options?.language ?? this.language;
+        const maxLen = options?.maxLength ?? this.maxLength;
+        let prompt = "Generate a concise, descriptive alt text for this image. " +
+            "The alt text should be useful for screen readers and accessibility. " +
+            "Describe the key visual content without starting with 'Image of' or 'Picture of'. " +
+            "Return ONLY the alt text, no quotes, no explanation.";
+        if (lang !== "en") {
+            prompt += ` Write the alt text in ${lang}.`;
+        }
+        if (maxLen) {
+            prompt += ` Keep it under ${maxLen} characters.`;
+        }
+        return prompt;
+    }
+}
+exports.AltImageClient = AltImageClient;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { AltImageClient } from "./client";
+export type { Provider, ImageInput, AltImageClientOptions, GenerateAltOptions, ProcessHTMLOptions, AltResult, BatchResult, BatchError, AIProvider, } from "./types";
+/**
+ * Convenience function: create a client and generate alt text in one call.
+ */
+export declare function generateAlt(image: string | Buffer, options: {
+    provider: "openai" | "gemini";
+    apiKey: string;
+    model?: string;
+    language?: string;
+    maxLength?: number;
+    customPrompt?: string;
+}): Promise<string>;

package/dist/index.js

@@ -0,0 +1,47 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AltImageClient = void 0;
+exports.generateAlt = generateAlt;
+var client_1 = require("./client");
+Object.defineProperty(exports, "AltImageClient", { enumerable: true, get: function () { return client_1.AltImageClient; } });
+/**
+ * Convenience function: create a client and generate alt text in one call.
+ */
+async function generateAlt(image, options) {
+    const { AltImageClient: Client } = await Promise.resolve().then(() => __importStar(require("./client")));
+    const client = new Client(options);
+    return client.generateAlt(image, options);
+}

package/dist/providers/gemini.d.ts

@@ -0,0 +1,8 @@
+import type { AIProvider } from "../types";
+export declare class GeminiProvider implements AIProvider {
+    private apiKey;
+    private model;
+    constructor(apiKey: string, model?: string);
+    generateAlt(imageBase64: string, mimeType: string, prompt: string): Promise<string>;
+    private request;
+}

package/dist/providers/gemini.js

@@ -0,0 +1,95 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiProvider = void 0;
+const https = __importStar(require("https"));
+class GeminiProvider {
+    constructor(apiKey, model) {
+        this.apiKey = apiKey;
+        this.model = model ?? "gemini-2.0-flash";
+    }
+    async generateAlt(imageBase64, mimeType, prompt) {
+        const body = JSON.stringify({
+            contents: [
+                {
+                    parts: [
+                        { text: prompt },
+                        {
+                            inline_data: {
+                                mime_type: mimeType,
+                                data: imageBase64,
+                            },
+                        },
+                    ],
+                },
+            ],
+            generationConfig: {
+                maxOutputTokens: 300,
+            },
+        });
+        const response = await this.request(body);
+        const data = JSON.parse(response);
+        if (data.error) {
+            throw new Error(`Gemini API error: ${data.error.message}`);
+        }
+        const text = data.candidates?.[0]?.content?.parts?.[0]?.text;
+        if (!text) {
+            throw new Error("Gemini returned an empty response");
+        }
+        return text.trim();
+    }
+    request(body) {
+        return new Promise((resolve, reject) => {
+            const req = https.request({
+                hostname: "generativelanguage.googleapis.com",
+                path: `/v1beta/models/${this.model}:generateContent?key=${this.apiKey}`,
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+            }, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk.toString();
+                });
+                res.on("end", () => resolve(data));
+            });
+            req.on("error", reject);
+            req.write(body);
+            req.end();
+        });
+    }
+}
+exports.GeminiProvider = GeminiProvider;

package/dist/providers/index.d.ts

@@ -0,0 +1,2 @@
+export { OpenAIProvider } from "./openai";
+export { GeminiProvider } from "./gemini";

package/dist/providers/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiProvider = exports.OpenAIProvider = void 0;
+var openai_1 = require("./openai");
+Object.defineProperty(exports, "OpenAIProvider", { enumerable: true, get: function () { return openai_1.OpenAIProvider; } });
+var gemini_1 = require("./gemini");
+Object.defineProperty(exports, "GeminiProvider", { enumerable: true, get: function () { return gemini_1.GeminiProvider; } });

package/dist/providers/openai.d.ts

@@ -0,0 +1,8 @@
+import type { AIProvider } from "../types";
+export declare class OpenAIProvider implements AIProvider {
+    private apiKey;
+    private model;
+    constructor(apiKey: string, model?: string);
+    generateAlt(imageBase64: string, mimeType: string, prompt: string): Promise<string>;
+    private request;
+}

package/dist/providers/openai.js

@@ -0,0 +1,96 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIProvider = void 0;
+const https = __importStar(require("https"));
+class OpenAIProvider {
+    constructor(apiKey, model) {
+        this.apiKey = apiKey;
+        this.model = model ?? "gpt-4o-mini";
+    }
+    async generateAlt(imageBase64, mimeType, prompt) {
+        const body = JSON.stringify({
+            model: this.model,
+            messages: [
+                {
+                    role: "user",
+                    content: [
+                        { type: "text", text: prompt },
+                        {
+                            type: "image_url",
+                            image_url: {
+                                url: `data:${mimeType};base64,${imageBase64}`,
+                            },
+                        },
+                    ],
+                },
+            ],
+            max_tokens: 300,
+        });
+        const response = await this.request(body);
+        const data = JSON.parse(response);
+        if (data.error) {
+            throw new Error(`OpenAI API error: ${data.error.message}`);
+        }
+        const text = data.choices?.[0]?.message?.content;
+        if (!text) {
+            throw new Error("OpenAI returned an empty response");
+        }
+        return text.trim();
+    }
+    request(body) {
+        return new Promise((resolve, reject) => {
+            const req = https.request({
+                hostname: "api.openai.com",
+                path: "/v1/chat/completions",
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.apiKey}`,
+                },
+            }, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk.toString();
+                });
+                res.on("end", () => resolve(data));
+            });
+            req.on("error", reject);
+            req.write(body);
+            req.end();
+        });
+    }
+}
+exports.OpenAIProvider = OpenAIProvider;

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+/** Supported AI providers */
+export type Provider = "openai" | "gemini";
+/** Image input: URL, local file path, or base64-encoded string */
+export type ImageInput = string | Buffer;
+/** Configuration for creating an AltImageClient */
+export interface AltImageClientOptions {
+    /** AI provider to use */
+    provider: Provider;
+    /** API key for the chosen provider */
+    apiKey: string;
+    /** Model to use (defaults to provider's recommended vision model) */
+    model?: string;
+    /** Language for the generated alt text (e.g. "en", "es", "fr") */
+    language?: string;
+    /** Maximum character length for the alt text */
+    maxLength?: number;
+    /** Custom prompt to guide the AI generation */
+    customPrompt?: string;
+}
+/** Options for a single generateAlt call (overrides client defaults) */
+export interface GenerateAltOptions {
+    /** Language for the generated alt text */
+    language?: string;
+    /** Maximum character length for the alt text */
+    maxLength?: number;
+    /** Custom prompt to guide the AI generation */
+    customPrompt?: string;
+}
+/** Options for HTML processing */
+export interface ProcessHTMLOptions extends GenerateAltOptions {
+    /** Only process <img> tags that are missing alt attributes (default: true) */
+    onlyMissing?: boolean;
+    /** Override existing alt attributes (default: false) */
+    overrideExisting?: boolean;
+}
+/** Result of a single alt text generation */
+export interface AltResult {
+    /** The generated alt text */
+    alt: string;
+    /** The image source that was processed */
+    src: string;
+}
+/** Result of a batch operation */
+export interface BatchResult {
+    /** Successfully generated results */
+    results: AltResult[];
+    /** Errors encountered during processing */
+    errors: BatchError[];
+}
+/** Error from a batch operation */
+export interface BatchError {
+    /** The image source that failed */
+    src: string;
+    /** The error that occurred */
+    error: Error;
+}
+/** Internal interface for AI provider implementations */
+export interface AIProvider {
+    /** Generate alt text for an image */
+    generateAlt(imageBase64: string, mimeType: string, prompt: string): Promise<string>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/html.d.ts

@@ -0,0 +1,18 @@
+export interface ImgTag {
+    /** Full match of the <img> tag */
+    fullMatch: string;
+    /** Value of the src attribute */
+    src: string;
+    /** Value of the alt attribute (undefined if missing) */
+    alt: string | undefined;
+    /** Whether the tag has an alt attribute at all */
+    hasAlt: boolean;
+}
+/**
+ * Extract all <img> tags from an HTML string.
+ */
+export declare function extractImgTags(html: string): ImgTag[];
+/**
+ * Replace an <img> tag's alt attribute in HTML, or add one if missing.
+ */
+export declare function setImgAlt(html: string, imgTag: ImgTag, altText: string): string;

package/dist/utils/html.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractImgTags = extractImgTags;
+exports.setImgAlt = setImgAlt;
+const IMG_REGEX = /<img\s[^>]*?>/gi;
+const SRC_REGEX = /src\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+))/i;
+const ALT_REGEX = /alt\s*=\s*(?:"([^"]*)"|'([^']*)')/i;
+/**
+ * Extract all <img> tags from an HTML string.
+ */
+function extractImgTags(html) {
+    const tags = [];
+    let match;
+    while ((match = IMG_REGEX.exec(html)) !== null) {
+        const fullMatch = match[0];
+        const srcMatch = SRC_REGEX.exec(fullMatch);
+        const altMatch = ALT_REGEX.exec(fullMatch);
+        const src = srcMatch
+            ? srcMatch[1] ?? srcMatch[2] ?? srcMatch[3] ?? ""
+            : "";
+        const hasAlt = altMatch !== null;
+        const alt = hasAlt
+            ? altMatch[1] ?? altMatch[2] ?? ""
+            : undefined;
+        if (src) {
+            tags.push({ fullMatch, src, alt, hasAlt });
+        }
+    }
+    return tags;
+}
+/**
+ * Replace an <img> tag's alt attribute in HTML, or add one if missing.
+ */
+function setImgAlt(html, imgTag, altText) {
+    const escaped = escapeAttrValue(altText);
+    let newTag;
+    if (imgTag.hasAlt) {
+        // Replace existing alt attribute
+        newTag = imgTag.fullMatch.replace(ALT_REGEX, `alt="${escaped}"`);
+    }
+    else {
+        // Add alt attribute after <img
+        newTag = imgTag.fullMatch.replace(/^<img/i, `<img alt="${escaped}"`);
+    }
+    return html.replace(imgTag.fullMatch, newTag);
+}
+function escapeAttrValue(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}

package/dist/utils/image.d.ts

@@ -0,0 +1,8 @@
+export interface ImageData {
+    base64: string;
+    mimeType: string;
+}
+/**
+ * Resolves an image input (URL, file path, base64, or Buffer) to base64 + mimeType.
+ */
+export declare function resolveImage(input: string | Buffer): Promise<ImageData>;

package/dist/utils/image.js

@@ -0,0 +1,137 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveImage = resolveImage;
+const fs = __importStar(require("fs"));
+const https = __importStar(require("https"));
+const http = __importStar(require("http"));
+const path = __importStar(require("path"));
+const MIME_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".svg": "image/svg+xml",
+};
+/**
+ * Resolves an image input (URL, file path, base64, or Buffer) to base64 + mimeType.
+ */
+async function resolveImage(input) {
+    if (Buffer.isBuffer(input)) {
+        return {
+            base64: input.toString("base64"),
+            mimeType: detectMimeFromBuffer(input),
+        };
+    }
+    // Base64 data URI
+    if (input.startsWith("data:")) {
+        const match = input.match(/^data:(image\/[^;]+);base64,(.+)$/);
+        if (!match) {
+            throw new Error("Invalid data URI format");
+        }
+        return { base64: match[2], mimeType: match[1] };
+    }
+    // URL
+    if (input.startsWith("http://") || input.startsWith("https://")) {
+        return downloadImage(input);
+    }
+    // File path
+    return readImageFile(input);
+}
+function readImageFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`File not found: ${filePath}`);
+    }
+    const buffer = fs.readFileSync(filePath);
+    const ext = path.extname(filePath).toLowerCase();
+    const mimeType = MIME_TYPES[ext] ?? detectMimeFromBuffer(buffer);
+    return {
+        base64: buffer.toString("base64"),
+        mimeType,
+    };
+}
+function downloadImage(url) {
+    const client = url.startsWith("https://") ? https : http;
+    return new Promise((resolve, reject) => {
+        client.get(url, (res) => {
+            if (res.statusCode &&
+                res.statusCode >= 300 &&
+                res.statusCode < 400 &&
+                res.headers.location) {
+                downloadImage(res.headers.location).then(resolve, reject);
+                return;
+            }
+            if (res.statusCode && res.statusCode >= 400) {
+                reject(new Error(`Failed to download image: HTTP ${res.statusCode}`));
+                return;
+            }
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                const buffer = Buffer.concat(chunks);
+                const contentType = res.headers["content-type"] ?? "";
+                const mimeType = contentType.startsWith("image/")
+                    ? contentType.split(";")[0]
+                    : detectMimeFromBuffer(buffer);
+                resolve({
+                    base64: buffer.toString("base64"),
+                    mimeType,
+                });
+            });
+            res.on("error", reject);
+        }).on("error", reject);
+    });
+}
+function detectMimeFromBuffer(buffer) {
+    if (buffer[0] === 0xff && buffer[1] === 0xd8)
+        return "image/jpeg";
+    if (buffer[0] === 0x89 &&
+        buffer[1] === 0x50 &&
+        buffer[2] === 0x4e &&
+        buffer[3] === 0x47)
+        return "image/png";
+    if (buffer[0] === 0x47 &&
+        buffer[1] === 0x49 &&
+        buffer[2] === 0x46)
+        return "image/gif";
+    if (buffer[0] === 0x52 &&
+        buffer[1] === 0x49 &&
+        buffer[2] === 0x46 &&
+        buffer[3] === 0x46)
+        return "image/webp";
+    return "image/jpeg"; // fallback
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { resolveImage } from "./image";
+export type { ImageData } from "./image";
+export { extractImgTags, setImgAlt } from "./html";
+export type { ImgTag } from "./html";

package/dist/utils/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setImgAlt = exports.extractImgTags = exports.resolveImage = void 0;
+var image_1 = require("./image");
+Object.defineProperty(exports, "resolveImage", { enumerable: true, get: function () { return image_1.resolveImage; } });
+var html_1 = require("./html");
+Object.defineProperty(exports, "extractImgTags", { enumerable: true, get: function () { return html_1.extractImgTags; } });
+Object.defineProperty(exports, "setImgAlt", { enumerable: true, get: function () { return html_1.setImgAlt; } });

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "alt-images-ai",
+  "version": "1.0.0",
+  "description": "Generate accessible alt text for images using AI (OpenAI, Google Gemini). Process single images, batch operations, or full HTML documents.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "alt-text",
+    "accessibility",
+    "a11y",
+    "images",
+    "ai",
+    "openai",
+    "gemini",
+    "gpt-4-vision",
+    "image-description",
+    "wcag",
+    "aria",
+    "html",
+    "seo"
+  ],
+  "author": "kreent",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kreent/alt-images-ai"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "typescript": "^5.4.0"
+  }
+}