@weapp-vite/qr 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @weapp-vite/qr
 
-`@weapp-vite/qr` 提供二维码矩阵编码、Base64 PNG 解码与终端文本渲染能力。
+`@weapp-vite/qr` 提供二维码矩阵编码、图片解码、reader 适配、微信小程序码结构识别与终端文本渲染能力。
 
 ```ts
 import { decodeQrCodeFromBase64, renderTerminalQrCode } from '@weapp-vite/qr'
@@ -8,3 +8,111 @@ import { decodeQrCodeFromBase64, renderTerminalQrCode } from '@weapp-vite/qr'
 const content = await decodeQrCodeFromBase64(base64Png)
 process.stdout.write(renderTerminalQrCode(content, { small: true }))
 ```
+
+## API
+
+### 编码
+
+```ts
+import { createQrCodeMatrix } from '@weapp-vite/qr'
+
+const matrix = createQrCodeMatrix('https://vite.icebreaker.top/')
+```
+
+### 解码
+
+```ts
+import {
+  decodeQrCodeFromBase64,
+  decodeQrCodeFromBuffer,
+  decodeQrCodeFromFile,
+} from '@weapp-vite/qr'
+
+const fromBase64 = await decodeQrCodeFromBase64(base64Png)
+const fromBuffer = await decodeQrCodeFromBuffer(imageBuffer)
+const fromFile = await decodeQrCodeFromFile('./fixtures/qr.png')
+```
+
+### Reader 输入
+
+```ts
+import { decodeWithQrReader } from '@weapp-vite/qr'
+import sharp from 'sharp'
+
+const { data, info } = await sharp(imageBuffer)
+  .ensureAlpha()
+  .raw()
+  .toBuffer({ resolveWithObject: true })
+
+const result = await decodeWithQrReader({
+  width: info.width,
+  height: info.height,
+  data,
+})
+
+console.log(result.result)
+```
+
+### 小程序码结构识别
+
+```ts
+import { detectMiniProgramCodeFromFile } from '@weapp-vite/qr'
+
+const detected = await detectMiniProgramCodeFromFile('./fixtures/mini-program-code.jpg')
+
+if (detected) {
+  console.log(detected.kind)
+  console.log(detected.locatorPoints)
+  console.log(detected.badgeBounds)
+  console.log(detected.logoBounds)
+}
+```
+
+这里的结构识别目标是判断图片是否符合微信小程序码几何特征，并返回定位点、中心 logo 区和右下角徽标区域。
+它不是把小程序码直接解码成链接或页面路径。
+
+### 高层类型检测
+
+```ts
+import { detectCodeTypeFromFile } from '@weapp-vite/qr'
+
+const codeType = await detectCodeTypeFromFile('./fixtures/code.png')
+
+if (codeType === 'qr') {
+  console.log('standard qr')
+}
+else if (codeType === 'mini-program-code') {
+  console.log('wechat mini program code')
+}
+else {
+  console.log('unknown')
+}
+```
+
+### 终端渲染
+
+```ts
+import {
+  createQrCodeMatrix,
+  renderTerminalQrCode,
+  renderTerminalQrCodeFromMatrix,
+} from '@weapp-vite/qr'
+
+const compact = renderTerminalQrCode('weapp-vite', { small: true })
+
+const matrix = createQrCodeMatrix('weapp-vite')
+const rendered = renderTerminalQrCodeFromMatrix(matrix)
+```
+
+## 导出类型
+
+```ts
+import type {
+  MiniProgramCodeDetectionResult,
+  QRCodeMatrix,
+  QRCodeReaderInput,
+  QRCodeReaderResult,
+  QRCodeRenderOptions,
+  QRCodeType,
+} from '@weapp-vite/qr'
+```

package/dist/index.d.mts

@@ -1,6 +1,22 @@
+import { Buffer } from "node:buffer";
+
+//#region src/codeType.d.ts
+/** QRCodeType 的类型定义。 */
+type QRCodeType = 'qr' | 'mini-program-code' | 'unknown';
+/** detectCodeTypeFromBuffer 的方法封装。 */
+declare function detectCodeTypeFromBuffer(buffer: Buffer): Promise<"qr" | "mini-program-code" | "unknown">;
+/** detectCodeTypeFromBase64 的方法封装。 */
+declare function detectCodeTypeFromBase64(content: string): Promise<"qr" | "mini-program-code" | "unknown">;
+/** detectCodeTypeFromFile 的方法封装。 */
+declare function detectCodeTypeFromFile(filePath: string): Promise<"qr" | "mini-program-code" | "unknown">;
+//#endregion
 //#region src/decode.d.ts
+/** decodeQrCodeFromBuffer 的方法封装。 */
+declare function decodeQrCodeFromBuffer(buffer: Buffer): Promise<string>;
 /** decodeQrCodeFromBase64 的方法封装。 */
 declare function decodeQrCodeFromBase64(content: string): Promise<string>;
+/** decodeQrCodeFromFile 的方法封装。 */
+declare function decodeQrCodeFromFile(filePath: string): Promise<string>;
 //#endregion
 //#region src/types.d.ts
 /**
@@ -17,8 +33,114 @@ type QRCodeMatrix = boolean[][];
 /** createQrCodeMatrix 的方法封装。 */
 declare function createQrCodeMatrix(input: string): QRCodeMatrix;
 //#endregion
+//#region src/miniProgramCode.d.ts
+interface MiniProgramCodePoint {
+  x: number;
+  y: number;
+}
+interface MiniProgramCodeBounds {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+/** MiniProgramCodeDetectionResult 的类型定义。 */
+interface MiniProgramCodeDetectionResult {
+  kind: 'wechat-mini-program-code';
+  width: number;
+  height: number;
+  confidence: number;
+  locatorPoints: readonly [MiniProgramCodePoint, MiniProgramCodePoint, MiniProgramCodePoint];
+  badgeBounds?: MiniProgramCodeBounds;
+  logoBounds?: MiniProgramCodeBounds;
+}
+/** detectMiniProgramCodeFromBuffer 的方法封装。 */
+declare function detectMiniProgramCodeFromBuffer(buffer: Buffer): Promise<{
+  kind: "wechat-mini-program-code";
+  width: number;
+  height: number;
+  confidence: number;
+  locatorPoints: readonly [MiniProgramCodePoint, MiniProgramCodePoint, MiniProgramCodePoint];
+  badgeBounds: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  };
+  logoBounds: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  } | undefined;
+} | null>;
+/** detectMiniProgramCodeFromBase64 的方法封装。 */
+declare function detectMiniProgramCodeFromBase64(content: string): Promise<{
+  kind: "wechat-mini-program-code";
+  width: number;
+  height: number;
+  confidence: number;
+  locatorPoints: readonly [MiniProgramCodePoint, MiniProgramCodePoint, MiniProgramCodePoint];
+  badgeBounds: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  };
+  logoBounds: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  } | undefined;
+} | null>;
+/** detectMiniProgramCodeFromFile 的方法封装。 */
+declare function detectMiniProgramCodeFromFile(filePath: string): Promise<{
+  kind: "wechat-mini-program-code";
+  width: number;
+  height: number;
+  confidence: number;
+  locatorPoints: readonly [MiniProgramCodePoint, MiniProgramCodePoint, MiniProgramCodePoint];
+  badgeBounds: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  };
+  logoBounds: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  } | undefined;
+} | null>;
+//#endregion
+//#region src/reader/core/types.d.ts
+/** QRCodeReaderResult 的类型定义。 */
+interface QRCodeReaderResult {
+  result: string;
+}
+/** QRCodeReaderInput 的类型定义。 */
+interface QRCodeReaderInput {
+  width: number;
+  height: number;
+  data: Buffer;
+}
+/** QRCodeReaderInstance 的类型定义。 */
+interface QRCodeReaderInstance {
+  decode: (input: QRCodeReaderInput) => Promise<QRCodeReaderResult>;
+}
+/** QRCodeReaderConstructor 的类型定义。 */
+type QRCodeReaderConstructor = new () => QRCodeReaderInstance;
+//#endregion
+//#region src/reader/decode.d.ts
+/** decodeWithQrReader 的方法封装。 */
+declare function decodeWithQrReader(input: QRCodeReaderInput): Promise<QRCodeReaderResult>;
+//#endregion
 //#region src/render.d.ts
+/** renderTerminalQrCodeFromMatrix 的方法封装。 */
+declare function renderTerminalQrCodeFromMatrix(matrix: QRCodeMatrix, options?: QRCodeRenderOptions): string;
 /** renderTerminalQrCode 的方法封装。 */
 declare function renderTerminalQrCode(input: string, options?: QRCodeRenderOptions): string;
 //#endregion
-export { type QRCodeMatrix, type QRCodeRenderOptions, createQrCodeMatrix, decodeQrCodeFromBase64, renderTerminalQrCode };
+export { type MiniProgramCodeDetectionResult, type QRCodeMatrix, type QRCodeReaderConstructor, type QRCodeReaderInput, type QRCodeReaderInstance, type QRCodeReaderResult, type QRCodeRenderOptions, type QRCodeType, createQrCodeMatrix, decodeQrCodeFromBase64, decodeQrCodeFromBuffer, decodeQrCodeFromFile, decodeWithQrReader, detectCodeTypeFromBase64, detectCodeTypeFromBuffer, detectCodeTypeFromFile, detectMiniProgramCodeFromBase64, detectMiniProgramCodeFromBuffer, detectMiniProgramCodeFromFile, renderTerminalQrCode, renderTerminalQrCodeFromMatrix };