plugin-document-parser 1.0.1

package/src/server/services/external-ocr-client.ts

@@ -0,0 +1,233 @@
+import axios, { AxiosRequestConfig } from 'axios';
+import FormData from 'form-data';
+import type { AttachmentLike } from './internal-parser-registry';
+
+// ─── Provider config types ─────────────────────────────────────────────────────
+
+export type OcrAuthType = 'bearer' | 'api-key-header' | 'basic' | 'custom-headers' | 'none';
+export type OcrRequestFormat = 'multipart' | 'json-base64' | 'url';
+
+export type OcrProviderConfig = {
+  apiEndpoint: string;
+  authType: OcrAuthType;
+  apiKey?: string;
+  authConfig?: {
+    headerName?: string;       // for api-key-header
+    username?: string;         // for basic auth
+    password?: string;         // for basic auth
+    customHeaders?: Record<string, string>; // for custom-headers
+  };
+  requestFormat: OcrRequestFormat;
+  requestConfig?: {
+    // multipart
+    fileFieldName?: string;
+    filenameFieldName?: string;
+    mimetypeFieldName?: string;
+    extraFields?: Record<string, string>;
+    // json-base64
+    base64FieldPath?: string;
+    filenameFieldPath?: string;
+    mimetypeFieldPath?: string;
+    extraBody?: Record<string, any>;
+    // url
+    urlFieldPath?: string;
+  };
+  responseTextPath?: string;
+  timeout?: number;
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Set a value at a dot-path inside an object, creating intermediate objects */
+function setByPath(obj: Record<string, any>, dotPath: string, value: any): void {
+  const parts = dotPath.split('.');
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (current[parts[i]] == null || typeof current[parts[i]] !== 'object') {
+      current[parts[i]] = {};
+    }
+    current = current[parts[i]];
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+/** Get a value from an object via dot-path. Supports simple array index: "pages.0.text" */
+function getByPath(obj: any, dotPath: string): any {
+  if (!obj || !dotPath) return undefined;
+  const parts = dotPath.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current == null) return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+/** Build Authorization / custom headers based on authType */
+function buildAuthHeaders(config: OcrProviderConfig): Record<string, string> {
+  const { authType, apiKey, authConfig = {} } = config;
+  const headers: Record<string, string> = {};
+
+  switch (authType) {
+    case 'bearer':
+      if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+      break;
+    case 'api-key-header': {
+      const headerName = authConfig.headerName || 'X-Api-Key';
+      if (apiKey) headers[headerName] = apiKey;
+      break;
+    }
+    case 'basic': {
+      const { username = '', password = '' } = authConfig;
+      const encoded = Buffer.from(`${username}:${password}`).toString('base64');
+      headers['Authorization'] = `Basic ${encoded}`;
+      break;
+    }
+    case 'custom-headers':
+      Object.assign(headers, authConfig.customHeaders ?? {});
+      break;
+    case 'none':
+    default:
+      break;
+  }
+
+  return headers;
+}
+
+// ─── Main client ──────────────────────────────────────────────────────────────
+
+export type ExternalOcrCallOptions = {
+  /** Raw file bytes */
+  fileBuffer: Buffer;
+  /** Original filename */
+  filename: string;
+  /** MIME type */
+  mimetype: string;
+  /** Download URL (used when requestFormat = 'url') */
+  fileUrl?: string;
+};
+
+/**
+ * Call an external OCR/document-parse API and return the extracted text.
+ *
+ * Supports three request formats:
+ *  - `multipart`   → multipart/form-data (most common for file upload APIs)
+ *  - `json-base64` → JSON body with base64-encoded file
+ *  - `url`         → JSON body with file download URL (provider fetches the file itself)
+ *
+ * Auth methods: bearer, api-key-header, basic, custom-headers, none.
+ */
+export async function callExternalOcr(
+  providerConfig: OcrProviderConfig,
+  options: ExternalOcrCallOptions,
+): Promise<string> {
+  const {
+    apiEndpoint,
+    requestFormat = 'multipart',
+    requestConfig = {},
+    responseTextPath = 'text',
+    timeout = 60000,
+  } = providerConfig;
+
+  const authHeaders = buildAuthHeaders(providerConfig);
+  let axiosConfig: AxiosRequestConfig = {
+    timeout,
+    headers: { ...authHeaders },
+  };
+  let body: any;
+
+  if (requestFormat === 'multipart') {
+    const form = new FormData();
+    const fileFieldName = requestConfig.fileFieldName || 'file';
+
+    form.append(fileFieldName, options.fileBuffer, {
+      filename: options.filename,
+      contentType: options.mimetype,
+    });
+
+    if (requestConfig.filenameFieldName) {
+      form.append(requestConfig.filenameFieldName, options.filename);
+    }
+    if (requestConfig.mimetypeFieldName) {
+      form.append(requestConfig.mimetypeFieldName, options.mimetype);
+    }
+    for (const [k, v] of Object.entries(requestConfig.extraFields ?? {})) {
+      form.append(k, v);
+    }
+
+    body = form;
+    axiosConfig.headers = {
+      ...axiosConfig.headers,
+      ...form.getHeaders(),
+    };
+  } else if (requestFormat === 'json-base64') {
+    const base64 = options.fileBuffer.toString('base64');
+    const jsonBody: Record<string, any> = { ...(requestConfig.extraBody ?? {}) };
+
+    setByPath(jsonBody, requestConfig.base64FieldPath || 'file', base64);
+    if (requestConfig.filenameFieldPath) {
+      setByPath(jsonBody, requestConfig.filenameFieldPath, options.filename);
+    }
+    if (requestConfig.mimetypeFieldPath) {
+      setByPath(jsonBody, requestConfig.mimetypeFieldPath, options.mimetype);
+    }
+
+    body = jsonBody;
+    axiosConfig.headers = {
+      ...axiosConfig.headers,
+      'Content-Type': 'application/json',
+    };
+  } else if (requestFormat === 'url') {
+    if (!options.fileUrl) {
+      throw new Error('[DocumentParser] requestFormat=url but no fileUrl was provided');
+    }
+    const jsonBody: Record<string, any> = { ...(requestConfig.extraBody ?? {}) };
+    setByPath(jsonBody, requestConfig.urlFieldPath || 'url', options.fileUrl);
+
+    body = jsonBody;
+    axiosConfig.headers = {
+      ...axiosConfig.headers,
+      'Content-Type': 'application/json',
+    };
+  } else {
+    throw new Error(`[DocumentParser] Unknown requestFormat: ${requestFormat}`);
+  }
+
+  const response = await axios.post(apiEndpoint, body, axiosConfig);
+  const responseData = response.data;
+
+  const text = getByPath(responseData, responseTextPath);
+  if (typeof text !== 'string') {
+    throw new Error(
+      `[DocumentParser] Could not extract text from response at path "${responseTextPath}". ` +
+        `Response: ${JSON.stringify(responseData).slice(0, 300)}`,
+    );
+  }
+
+  return text;
+}
+
+/**
+ * Lightweight connectivity test — sends a GET (or HEAD) to the provider endpoint
+ * to check reachability and auth. Used by the "Test Connection" button.
+ */
+export async function testOcrProviderConnection(
+  providerConfig: Pick<OcrProviderConfig, 'apiEndpoint' | 'authType' | 'apiKey' | 'authConfig' | 'timeout'>,
+): Promise<{ ok: boolean; status?: number; message?: string }> {
+  try {
+    const authHeaders = buildAuthHeaders(providerConfig as OcrProviderConfig);
+    const response = await axios.get(providerConfig.apiEndpoint, {
+      headers: authHeaders,
+      timeout: providerConfig.timeout ?? 10000,
+      // Don't throw on 4xx so we can return the status to the UI
+      validateStatus: () => true,
+    });
+    return {
+      ok: response.status < 500,
+      status: response.status,
+      message: response.status < 500 ? undefined : `Server error: ${response.status}`,
+    };
+  } catch (err: any) {
+    return { ok: false, message: err?.message ?? String(err) };
+  }
+}

package/src/server/services/internal-parser-registry.ts

@@ -0,0 +1,126 @@
+import { Context } from '@nocobase/actions';
+
+// ─── Public contract ──────────────────────────────────────────────────────────
+
+export type InternalParseResult = {
+  /** Extracted plain text content */
+  text: string;
+  /** True when this handler actually processed the file (not skipped/unsupported) */
+  handled: boolean;
+};
+
+/**
+ * Contract every internal parser handler must satisfy.
+ *
+ * Other plugins register handlers via:
+ *   plugin.internalParserRegistry.register(myHandler)
+ *
+ * Handlers are tried in registration order.  The first one that returns
+ * `handled: true` wins; the rest are skipped.  This lets specialised handlers
+ * (e.g. a dedicated Excel parser plugin) take priority over the generic
+ * fallback handler.
+ */
+export interface InternalParserHandler {
+  /** Unique name used for logging / debugging */
+  name: string;
+
+  /**
+   * Return true if this handler CAN process the given attachment.
+   * Called before `parse()` to avoid unnecessary work.
+   */
+  supports(attachment: AttachmentLike): boolean;
+
+  /**
+   * Parse the attachment and return extracted text.
+   * Throw if parsing fails — the registry will either propagate the error
+   * or let the router fall back to default, depending on settings.
+   */
+  parse(attachment: AttachmentLike, ctx: Context): Promise<InternalParseResult>;
+}
+
+/** Minimal shape of an attachment object passed through the system */
+export type AttachmentLike = {
+  id?: string | number;
+  filename?: string;
+  name?: string;
+  mimetype?: string;
+  extname?: string;
+  url?: string;
+  storageId?: number;
+  size?: number;
+  meta?: Record<string, any>;
+  [key: string]: any;
+};
+
+// ─── Registry ─────────────────────────────────────────────────────────────────
+
+/**
+ * Central registry for internal document parser handlers.
+ *
+ * Handlers are called in the order they were registered.
+ * The first handler that declares `supports() = true` processes the file.
+ *
+ * Usage (from another plugin):
+ *
+ *   const docParser = this.pm.get(PluginDocumentParserServer);
+ *   docParser.internalParserRegistry.register({
+ *     name: 'my-excel-parser',
+ *     supports: (att) => att.mimetype === 'application/vnd.openxmlformats...',
+ *     async parse(att, ctx) {
+ *       const text = await myExcelToText(att);
+ *       return { text, handled: true };
+ *     },
+ *   });
+ */
+export class InternalParserRegistry {
+  private handlers: InternalParserHandler[] = [];
+
+  /**
+   * Register a new handler.
+   * Pass `{ prepend: true }` to insert at the front so it takes priority
+   * over previously registered handlers (useful for specialised format plugins).
+   */
+  register(handler: InternalParserHandler, options?: { prepend?: boolean }): void {
+    if (this.handlers.find((h) => h.name === handler.name)) {
+      throw new Error(`[DocumentParser] Handler "${handler.name}" is already registered.`);
+    }
+    if (options?.prepend) {
+      this.handlers.unshift(handler);
+    } else {
+      this.handlers.push(handler);
+    }
+  }
+
+  /** Remove a previously registered handler by name */
+  unregister(name: string): void {
+    this.handlers = this.handlers.filter((h) => h.name !== name);
+  }
+
+  /** Return a copy of the current handler list (for introspection / tests) */
+  list(): ReadonlyArray<InternalParserHandler> {
+    return [...this.handlers];
+  }
+
+  /**
+   * Try handlers in order; return the result of the first one that
+   * `supports` and successfully `parse`s the attachment.
+   *
+   * Returns `{ text: '', handled: false }` when no handler supports the file.
+   */
+  async parse(attachment: AttachmentLike, ctx: Context): Promise<InternalParseResult> {
+    for (const handler of this.handlers) {
+      if (!handler.supports(attachment)) {
+        continue;
+      }
+      const result = await handler.parse(attachment, ctx);
+      if (result.handled) {
+        return result;
+      }
+    }
+    return { text: '', handled: false };
+  }
+
+  get size(): number {
+    return this.handlers.length;
+  }
+}