captcha-ocr 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 (2026-07-24)
+
+- Initial release of `captcha-ocr`.
+- 支持 Buffer、Uint8Array、Base64 和 Data URL 输入。
+- 提供可扩展的 Profile/Rule 识别规则。
+- 提供 ESM、CommonJS 和 TypeScript 类型声明。
+- 内置四则运算验证码识别规则。

package/README.md

@@ -0,0 +1,223 @@
+# captcha-ocr
+
+**English** | [中文](README.zh-CN.md)
+
+`captcha-ocr` is a TypeScript OCR package for image-based arithmetic captchas. It accepts image bytes or Base64 data, preprocesses difficult images, runs Tesseract OCR, and evaluates the recognized expression through a configurable profile and rule system.
+
+## Requirements
+
+- Node.js 20 or newer
+- A native runtime supported by [`sharp`](https://sharp.pixelplumbing.com/)
+
+The first OCR call may download the English Tesseract training data (`eng.traineddata`). Make sure the runtime can access the network during the first initialization, or provide the training data through your Tesseract setup.
+
+## Install
+
+```bash
+pnpm add captcha-ocr
+```
+
+The package includes ESM, CommonJS, and TypeScript declaration builds.
+
+## Quick start
+
+```ts
+import {
+  closeDefaultRecognizer,
+  recognizeCaptcha
+} from 'captcha-ocr';
+
+const result = await recognizeCaptcha(imageData);
+
+if (result.ok) {
+  console.log(result.expression); // 7*9
+  console.log(result.answer);     // 63
+} else {
+  console.error(result.error?.code, result.error?.message);
+}
+
+await closeDefaultRecognizer();
+```
+
+`imageData` can be any of the following:
+
+- `Buffer`
+- `Uint8Array`
+- A raw Base64 string
+- An image Data URL such as `data:image/png;base64,...`
+
+## Reuse a recognizer
+
+For server-side workloads, create one recognizer and reuse it for multiple images. This avoids initializing an OCR worker for every request.
+
+```ts
+import {
+  arithmeticProfile,
+  createRecognizer
+} from 'captcha-ocr';
+
+const recognizer = createRecognizer({
+  profile: arithmeticProfile
+});
+
+const first = await recognizer.recognize(firstImage);
+const second = await recognizer.recognize(secondImage);
+
+await recognizer.close();
+```
+
+Call `close()` when the recognizer is no longer needed so its worker resources can be released.
+
+## Recognition result
+
+```ts
+interface RecognitionResult<TAnswer> {
+  ok: boolean;
+  profileId: string;
+  ocrText: string;
+  normalizedText: string;
+  expression: string | null;
+  answer: TAnswer | null;
+  error: {
+    code: string;
+    message: string;
+  } | null;
+  ocrVariant: 'original' | 'threshold';
+  durationMs: number;
+  source: {
+    width: number | null;
+    height: number | null;
+    format: string | null;
+  };
+  preprocess: {
+    mode: 'original' | 'threshold';
+    scale: number;
+    threshold: number | null;
+  };
+  processedImage?: Buffer;
+}
+```
+
+The processed image is omitted by default. Enable it only when you need to inspect preprocessing results:
+
+```ts
+const result = await recognizer.recognize(imageData, {
+  includeProcessedImage: true
+});
+
+console.log(result.processedImage);
+```
+
+## Built-in arithmetic rule
+
+The default `arithmeticProfile` supports:
+
+- `+`
+- `-`
+- `*`
+- `/`
+
+Common OCR variants such as `x`, `X`, `×`, and `·` are normalized to `*`; `÷` is normalized to `/`. Expressions are evaluated with a fixed parser and do not use `eval`.
+
+You can import the arithmetic rule directly:
+
+```ts
+import {
+  arithmeticProfile,
+  createArithmeticRule
+} from 'captcha-ocr/rules/arithmetic';
+```
+
+## Custom profiles and rules
+
+The recognizer is not limited to arithmetic. A profile defines OCR options and preprocessing, while a rule normalizes, parses, and evaluates recognized text.
+
+```ts
+import {
+  createRecognizer,
+  type CaptchaProfile,
+  type CaptchaRule
+} from 'captcha-ocr';
+
+interface ParsedCode {
+  value: string;
+}
+
+const rule: CaptchaRule<ParsedCode, string> = {
+  id: 'fixed-code-v1',
+
+  normalize(text) {
+    return text.trim().toUpperCase();
+  },
+
+  parse(text) {
+    const normalized = this.normalize(text);
+
+    if (!/^[A-F0-9]{4}$/.test(normalized)) {
+      return {
+        ok: false,
+        normalized,
+        error: {
+          code: 'CODE_NOT_MATCHED',
+          message: 'The value is not a four-character hexadecimal code.'
+        }
+      };
+    }
+
+    return {
+      ok: true,
+      normalized,
+      expression: normalized,
+      parsed: {
+        value: normalized
+      }
+    };
+  },
+
+  evaluate(parsed) {
+    return parsed.value;
+  }
+};
+
+const profile: CaptchaProfile<ParsedCode, string> = {
+  id: 'fixed-code-v1',
+  ocr: {
+    language: 'eng',
+    whitelist: '0123456789ABCDEF',
+    pageSegMode: 7
+  },
+  rule
+};
+
+const recognizer = createRecognizer({ profile });
+const result = await recognizer.recognize(imageData);
+await recognizer.close();
+```
+
+This keeps the OCR pipeline reusable while allowing each captcha format to define its own parsing and evaluation behavior.
+
+## CommonJS
+
+```js
+const {
+  arithmeticProfile,
+  createRecognizer
+} = require('captcha-ocr');
+```
+
+## Error handling
+
+- OCR may succeed while the configured rule fails to parse the text. In that case, the result has `ok: false` and a structured `error`.
+- Invalid image input throws an `ImageInputError`.
+- OCR worker initialization, image decoding, and native dependency errors are thrown to the caller and should be handled according to the host application's needs.
+
+## Local demo
+
+The repository also contains a small Web UI and CLI for manual testing. They are development tools and are not included in the published package.
+
+```bash
+pnpm install
+pnpm start
+```
+
+Open <http://127.0.0.1:3000> after the server starts.

package/README.zh-CN.md

@@ -0,0 +1,223 @@
+# captcha-ocr
+
+[English](README.md) | **中文**
+
+`captcha-ocr` 是一个用于图形算术验证码识别的 TypeScript OCR 包。它支持图片数据和 Base64 输入，可以对复杂图片进行预处理，使用 Tesseract OCR 识别文本，并通过可配置的 Profile 和 Rule 系统解析、计算识别结果。
+
+## 环境要求
+
+- Node.js 20 或更高版本
+- [`sharp`](https://sharp.pixelplumbing.com/) 支持的原生运行环境
+
+首次调用 OCR 时，Tesseract 可能会下载英文训练数据（`eng.traineddata`）。请确保运行环境在首次初始化时可以访问网络，或者通过 Tesseract 配置提供训练数据。
+
+## 安装
+
+```bash
+pnpm add captcha-ocr
+```
+
+包内同时提供 ESM、CommonJS 和 TypeScript 类型声明。
+
+## 快速开始
+
+```ts
+import {
+  closeDefaultRecognizer,
+  recognizeCaptcha
+} from 'captcha-ocr';
+
+const result = await recognizeCaptcha(imageData);
+
+if (result.ok) {
+  console.log(result.expression); // 7*9
+  console.log(result.answer);     // 63
+} else {
+  console.error(result.error?.code, result.error?.message);
+}
+
+await closeDefaultRecognizer();
+```
+
+`imageData` 支持以下类型：
+
+- `Buffer`
+- `Uint8Array`
+- 纯 Base64 字符串
+- 图片 Data URL，例如 `data:image/png;base64,...`
+
+## 复用识别器
+
+服务端连续识别多张图片时，建议创建一个识别器并复用，避免为每个请求重复初始化 OCR Worker。
+
+```ts
+import {
+  arithmeticProfile,
+  createRecognizer
+} from 'captcha-ocr';
+
+const recognizer = createRecognizer({
+  profile: arithmeticProfile
+});
+
+const first = await recognizer.recognize(firstImage);
+const second = await recognizer.recognize(secondImage);
+
+await recognizer.close();
+```
+
+识别器不再使用时，请调用 `close()` 释放 Worker 资源。
+
+## 识别结果
+
+```ts
+interface RecognitionResult<TAnswer> {
+  ok: boolean;
+  profileId: string;
+  ocrText: string;
+  normalizedText: string;
+  expression: string | null;
+  answer: TAnswer | null;
+  error: {
+    code: string;
+    message: string;
+  } | null;
+  ocrVariant: 'original' | 'threshold';
+  durationMs: number;
+  source: {
+    width: number | null;
+    height: number | null;
+    format: string | null;
+  };
+  preprocess: {
+    mode: 'original' | 'threshold';
+    scale: number;
+    threshold: number | null;
+  };
+  processedImage?: Buffer;
+}
+```
+
+默认不会返回处理后的图片。调试预处理结果时，可以显式开启：
+
+```ts
+const result = await recognizer.recognize(imageData, {
+  includeProcessedImage: true
+});
+
+console.log(result.processedImage);
+```
+
+## 内置算术规则
+
+默认的 `arithmeticProfile` 支持：
+
+- `+`
+- `-`
+- `*`
+- `/`
+
+常见 OCR 变体会自动归一化：`x`、`X`、`×` 和 `·` 会转换为 `*`，`÷` 会转换为 `/`。表达式使用固定解析器计算，不会调用 `eval`。
+
+也可以单独导入算术规则：
+
+```ts
+import {
+  arithmeticProfile,
+  createArithmeticRule
+} from 'captcha-ocr/rules/arithmetic';
+```
+
+## 自定义 Profile 和 Rule
+
+识别器不限于算术验证码。Profile 定义 OCR 参数和预处理方式，Rule 负责对识别文本进行归一化、解析和计算。
+
+```ts
+import {
+  createRecognizer,
+  type CaptchaProfile,
+  type CaptchaRule
+} from 'captcha-ocr';
+
+interface ParsedCode {
+  value: string;
+}
+
+const rule: CaptchaRule<ParsedCode, string> = {
+  id: 'fixed-code-v1',
+
+  normalize(text) {
+    return text.trim().toUpperCase();
+  },
+
+  parse(text) {
+    const normalized = this.normalize(text);
+
+    if (!/^[A-F0-9]{4}$/.test(normalized)) {
+      return {
+        ok: false,
+        normalized,
+        error: {
+          code: 'CODE_NOT_MATCHED',
+          message: '无法识别为四位十六进制编码。'
+        }
+      };
+    }
+
+    return {
+      ok: true,
+      normalized,
+      expression: normalized,
+      parsed: {
+        value: normalized
+      }
+    };
+  },
+
+  evaluate(parsed) {
+    return parsed.value;
+  }
+};
+
+const profile: CaptchaProfile<ParsedCode, string> = {
+  id: 'fixed-code-v1',
+  ocr: {
+    language: 'eng',
+    whitelist: '0123456789ABCDEF',
+    pageSegMode: 7
+  },
+  rule
+};
+
+const recognizer = createRecognizer({ profile });
+const result = await recognizer.recognize(imageData);
+await recognizer.close();
+```
+
+这样可以复用统一的 OCR 流程，同时为不同验证码格式定义独立的解析和计算行为。
+
+## CommonJS
+
+```js
+const {
+  arithmeticProfile,
+  createRecognizer
+} = require('captcha-ocr');
+```
+
+## 错误处理
+
+- OCR 成功但规则无法解析文本时，结果会返回 `ok: false` 和结构化的 `error`。
+- 输入不是有效图片数据时，会抛出 `ImageInputError`。
+- OCR Worker 初始化、图片解码或原生依赖异常会抛出错误，调用方应根据业务需要处理。
+
+## 本地 Demo
+
+仓库还提供用于人工测试的 Web UI 和 CLI，它们属于开发工具，不会包含在发布包中。
+
+```bash
+pnpm install
+pnpm start
+```
+
+服务启动后打开 <http://127.0.0.1:3000>。

package/dist/arithmetic-CUs9apP8.d.cts

@@ -0,0 +1,113 @@
+type ImageInput = Buffer | Uint8Array | string;
+interface RecognitionError {
+    code: string;
+    message: string;
+}
+interface OcrLogEntry {
+    status: string;
+    progress?: number;
+    [key: string]: unknown;
+}
+interface OcrProfile {
+    language: string;
+    whitelist: string;
+    pageSegMode: number | string;
+    preserveInterwordSpaces?: boolean;
+}
+interface PreprocessProfile {
+    scale?: number;
+    thresholds?: number[];
+}
+interface RuleParseSuccess<TParsed> {
+    ok: true;
+    normalized: string;
+    expression: string;
+    parsed: TParsed;
+}
+interface RuleParseFailure {
+    ok: false;
+    normalized: string;
+    error: RecognitionError;
+}
+type RuleParseResult<TParsed> = RuleParseSuccess<TParsed> | RuleParseFailure;
+interface CaptchaRule<TParsed, TAnswer> {
+    id: string;
+    normalize(text: string): string;
+    parse(text: string): RuleParseResult<TParsed>;
+    evaluate(parsed: TParsed): TAnswer;
+}
+interface CaptchaProfile<TParsed, TAnswer> {
+    id: string;
+    ocr?: Partial<OcrProfile>;
+    preprocess?: PreprocessProfile;
+    rule: CaptchaRule<TParsed, TAnswer>;
+}
+interface RecognizeOptions {
+    thresholds?: number[];
+    scale?: number;
+    includeProcessedImage?: boolean;
+}
+interface ImageSource {
+    width: number | null;
+    height: number | null;
+    format: string | null;
+}
+interface PreprocessInfo {
+    mode: 'original' | 'threshold';
+    scale: number;
+    threshold: number | null;
+}
+interface RecognitionResult<TAnswer> {
+    ok: boolean;
+    profileId: string;
+    ocrText: string;
+    normalizedText: string;
+    expression: string | null;
+    answer: TAnswer | null;
+    error: RecognitionError | null;
+    ocrVariant: PreprocessInfo['mode'];
+    durationMs: number;
+    source: ImageSource;
+    preprocess: PreprocessInfo;
+    processedImage?: Buffer;
+}
+
+interface ArithmeticExpression {
+    left: number;
+    operator: string;
+    right: number;
+}
+interface ArithmeticOperator {
+    aliases?: string[];
+    evaluate(left: number, right: number): number;
+    validate?(left: number, right: number): RecognitionError | null;
+}
+declare const DEFAULT_OPERATORS: Record<string, ArithmeticOperator>;
+interface ArithmeticRuleOptions {
+    id?: string;
+    whitelist?: string;
+    operators?: Record<string, ArithmeticOperator>;
+}
+declare function createArithmeticRule(options?: ArithmeticRuleOptions): CaptchaRule<ArithmeticExpression, number>;
+declare const arithmeticRule: CaptchaRule<ArithmeticExpression, number>;
+interface LegacyExpressionSuccess {
+    ok: true;
+    normalized: string;
+    expression: string;
+    answer: number;
+    error: null;
+}
+interface LegacyExpressionFailure {
+    ok: false;
+    normalized: string;
+    expression: null;
+    answer: null;
+    error: RecognitionError;
+}
+type LegacyExpressionResult = LegacyExpressionSuccess | LegacyExpressionFailure;
+declare function normalizeOcrText(text: string): string;
+declare function parseExpression(text: string): LegacyExpressionResult;
+declare function calculate(left: number, operator: string, right: number): number;
+declare const arithmeticProfile: CaptchaProfile<ArithmeticExpression, number>;
+
+export { type ArithmeticExpression as A, type CaptchaProfile as C, DEFAULT_OPERATORS as D, type ImageInput as I, type LegacyExpressionFailure as L, type OcrLogEntry as O, type PreprocessInfo as P, type RecognizeOptions as R, type RecognitionResult as a, type ImageSource as b, type PreprocessProfile as c, type ArithmeticOperator as d, type ArithmeticRuleOptions as e, type CaptchaRule as f, type LegacyExpressionResult as g, type LegacyExpressionSuccess as h, type OcrProfile as i, type RecognitionError as j, type RuleParseFailure as k, type RuleParseResult as l, type RuleParseSuccess as m, arithmeticProfile as n, arithmeticRule as o, calculate as p, createArithmeticRule as q, normalizeOcrText as r, parseExpression as s };

package/dist/arithmetic-CUs9apP8.d.ts

@@ -0,0 +1,113 @@
+type ImageInput = Buffer | Uint8Array | string;
+interface RecognitionError {
+    code: string;
+    message: string;
+}
+interface OcrLogEntry {
+    status: string;
+    progress?: number;
+    [key: string]: unknown;
+}
+interface OcrProfile {
+    language: string;
+    whitelist: string;
+    pageSegMode: number | string;
+    preserveInterwordSpaces?: boolean;
+}
+interface PreprocessProfile {
+    scale?: number;
+    thresholds?: number[];
+}
+interface RuleParseSuccess<TParsed> {
+    ok: true;
+    normalized: string;
+    expression: string;
+    parsed: TParsed;
+}
+interface RuleParseFailure {
+    ok: false;
+    normalized: string;
+    error: RecognitionError;
+}
+type RuleParseResult<TParsed> = RuleParseSuccess<TParsed> | RuleParseFailure;
+interface CaptchaRule<TParsed, TAnswer> {
+    id: string;
+    normalize(text: string): string;
+    parse(text: string): RuleParseResult<TParsed>;
+    evaluate(parsed: TParsed): TAnswer;
+}
+interface CaptchaProfile<TParsed, TAnswer> {
+    id: string;
+    ocr?: Partial<OcrProfile>;
+    preprocess?: PreprocessProfile;
+    rule: CaptchaRule<TParsed, TAnswer>;
+}
+interface RecognizeOptions {
+    thresholds?: number[];
+    scale?: number;
+    includeProcessedImage?: boolean;
+}
+interface ImageSource {
+    width: number | null;
+    height: number | null;
+    format: string | null;
+}
+interface PreprocessInfo {
+    mode: 'original' | 'threshold';
+    scale: number;
+    threshold: number | null;
+}
+interface RecognitionResult<TAnswer> {
+    ok: boolean;
+    profileId: string;
+    ocrText: string;
+    normalizedText: string;
+    expression: string | null;
+    answer: TAnswer | null;
+    error: RecognitionError | null;
+    ocrVariant: PreprocessInfo['mode'];
+    durationMs: number;
+    source: ImageSource;
+    preprocess: PreprocessInfo;
+    processedImage?: Buffer;
+}
+
+interface ArithmeticExpression {
+    left: number;
+    operator: string;
+    right: number;
+}
+interface ArithmeticOperator {
+    aliases?: string[];
+    evaluate(left: number, right: number): number;
+    validate?(left: number, right: number): RecognitionError | null;
+}
+declare const DEFAULT_OPERATORS: Record<string, ArithmeticOperator>;
+interface ArithmeticRuleOptions {
+    id?: string;
+    whitelist?: string;
+    operators?: Record<string, ArithmeticOperator>;
+}
+declare function createArithmeticRule(options?: ArithmeticRuleOptions): CaptchaRule<ArithmeticExpression, number>;
+declare const arithmeticRule: CaptchaRule<ArithmeticExpression, number>;
+interface LegacyExpressionSuccess {
+    ok: true;
+    normalized: string;
+    expression: string;
+    answer: number;
+    error: null;
+}
+interface LegacyExpressionFailure {
+    ok: false;
+    normalized: string;
+    expression: null;
+    answer: null;
+    error: RecognitionError;
+}
+type LegacyExpressionResult = LegacyExpressionSuccess | LegacyExpressionFailure;
+declare function normalizeOcrText(text: string): string;
+declare function parseExpression(text: string): LegacyExpressionResult;
+declare function calculate(left: number, operator: string, right: number): number;
+declare const arithmeticProfile: CaptchaProfile<ArithmeticExpression, number>;
+
+export { type ArithmeticExpression as A, type CaptchaProfile as C, DEFAULT_OPERATORS as D, type ImageInput as I, type LegacyExpressionFailure as L, type OcrLogEntry as O, type PreprocessInfo as P, type RecognizeOptions as R, type RecognitionResult as a, type ImageSource as b, type PreprocessProfile as c, type ArithmeticOperator as d, type ArithmeticRuleOptions as e, type CaptchaRule as f, type LegacyExpressionResult as g, type LegacyExpressionSuccess as h, type OcrProfile as i, type RecognitionError as j, type RuleParseFailure as k, type RuleParseResult as l, type RuleParseSuccess as m, arithmeticProfile as n, arithmeticRule as o, calculate as p, createArithmeticRule as q, normalizeOcrText as r, parseExpression as s };