ocr-extractor-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Johnathan Ritzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# ocr-extractor-api
+
+This package provides types and helpers for the public API of the
+[OCR Extractor](https://community.obsidian.md/plugins/ocr-extractor) Obsidian
+plugin. The API allows another plugin or script to run the user's configured OCR
+engine on an attachment and get the extracted text.
+
+## Installation
+
+```bash
+npm install ocr-extractor-api
+```
+
+## Quick start
+
+```ts
+import { getOcrExtractorApi, isOcrError } from "ocr-extractor-api";
+
+const api = getOcrExtractorApi(app);
+if (!api) {
+  // OCR Extractor isn't installed or enabled
+  return;
+}
+
+try {
+  const { text } = await api.extractText(file); // `file` is the attachment TFile
+  // `text` is the extracted text (or `""` if none was found)
+} catch (error) {
+  // Use `isOcrError`, not `instanceof`
+  if (isOcrError(error) && error.code === "unsupported-file") {
+    // The configured engine can't process this file type
+    return;
+  }
+  throw error; // an unexpected error
+}
+```
+
+## Documentation
+
+The full API documentation is available in the [API reference](./docs).
+
+## Versioning
+
+This package is versioned independently of the plugin, and its version is the API
+version. See the [changelog](./CHANGELOG.md) for changes.
+
+## License
+
+`ocr-extractor-api` is licensed under the [MIT License](./LICENSE).

package/dist/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Identifies which kind of {@link OcrError} occurred.
+ *
+ * - `"unsupported-file"`: the OCR engine can't process this file (e.g. an
+ *   unsupported file type)
+ * - `"extraction-failed"`: any other failure during extraction (network,
+ *   auth, etc.)
+ *
+ * @since 1.0.0
+ */
+export type OcrErrorCode = "unsupported-file" | "extraction-failed";
+/**
+ * The error thrown by {@link OcrExtractorApi.extractText} when extraction
+ * fails. Identify it with {@link isOcrError} (not `instanceof`, which won't
+ * work across the plugin and npm package boundary). The original error,
+ * if any, is included as `cause`.
+ *
+ * @since 1.0.0
+ */
+export interface OcrError extends Error {
+    readonly code: OcrErrorCode;
+    readonly cause?: unknown;
+}
+/**
+ * Checks whether a caught value is an {@link OcrError}.
+ *
+ * @param error - The caught error to check
+ * @returns `true` if `error` is an {@link OcrError}, `false` otherwise
+ * @since 1.0.0
+ * @example
+ * ```ts
+ * try {
+ *   await api.extractText(file);
+ * } catch (error) {
+ *   if (isOcrError(error) && error.code === "unsupported-file") return;
+ *   throw error;
+ * }
+ * ```
+ */
+export declare function isOcrError(error: unknown): error is OcrError;
+/**
+ * Used by the plugin to construct an {@link OcrError} with the given code and
+ * message.
+ *
+ * @param code - Which kind of error this is
+ * @param message - A human-readable message
+ * @param options - Optional settings
+ * @param options.cause - The underlying error, if any
+ * @returns The new {@link OcrError}
+ * @since 1.0.0
+ */
+export declare function ocrError(code: OcrErrorCode, message?: string, options?: {
+    cause?: unknown;
+}): OcrError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,WAAW,QAAS,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAM5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,QAAQ,CAGV"}

package/dist/errors.js

@@ -0,0 +1,37 @@
+/**
+ * Checks whether a caught value is an {@link OcrError}.
+ *
+ * @param error - The caught error to check
+ * @returns `true` if `error` is an {@link OcrError}, `false` otherwise
+ * @since 1.0.0
+ * @example
+ * ```ts
+ * try {
+ *   await api.extractText(file);
+ * } catch (error) {
+ *   if (isOcrError(error) && error.code === "unsupported-file") return;
+ *   throw error;
+ * }
+ * ```
+ */
+export function isOcrError(error) {
+    return (error instanceof Error &&
+        error.name === "OcrError" &&
+        typeof error.code === "string");
+}
+/**
+ * Used by the plugin to construct an {@link OcrError} with the given code and
+ * message.
+ *
+ * @param code - Which kind of error this is
+ * @param message - A human-readable message
+ * @param options - Optional settings
+ * @param options.cause - The underlying error, if any
+ * @returns The new {@link OcrError}
+ * @since 1.0.0
+ */
+export function ocrError(code, message, options) {
+    const error = new Error(message ?? code, options);
+    return Object.assign(error, { name: "OcrError", code });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,CACL,KAAK,YAAY,KAAK;QACtB,KAAK,CAAC,IAAI,KAAK,UAAU;QACzB,OAAQ,KAA2B,CAAC,IAAI,KAAK,QAAQ,CACtD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CACtB,IAAkB,EAClB,OAAgB,EAChB,OAA6B;IAE7B,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Public API for the OCR Extractor Obsidian plugin
+ *
+ * Access it with {@link getOcrExtractorApi}.
+ *
+ * @packageDocumentation
+ */
+import type { App, TFile } from "obsidian";
+export { type OcrError, type OcrErrorCode, isOcrError, ocrError, } from "./errors.js";
+/**
+ * The API version
+ *
+ * @since 1.0.0
+ */
+export declare const OCR_EXTRACTOR_API_VERSION = "1.0.0";
+/**
+ * The result of a successful extraction
+ *
+ * @since 1.0.0
+ */
+export interface OcrExtractionResult {
+    /** Extracted text (or `""` if the file was processed but contained no text) */
+    text: string;
+}
+/**
+ * The OCR Extractor plugin's public API, obtained via {@link getOcrExtractorApi}
+ *
+ * @since 1.0.0
+ */
+export interface OcrExtractorApi {
+    /**
+     * The API version (i.e. {@link OCR_EXTRACTOR_API_VERSION})
+     *
+     * @since 1.0.0
+     */
+    readonly version: string;
+    /**
+     * Run the user's configured OCR engine on an attachment and return the
+     * extracted text. Does not modify any note.
+     *
+     * @param file - The attachment's `TFile`
+     * @param options - Optional settings
+     * @param options.signal - An optional `AbortSignal` to cancel the extraction
+     * @returns An {@link OcrExtractionResult} with the extracted `text` (`""` if none found)
+     * @throws An {@link OcrError} with an error `code` ({@link OcrErrorCode}), or
+     *         an `AbortError` if canceled via `options.signal`
+     * @since 1.0.0
+     * @example
+     * ```ts
+     * const { text } = await api.extractText(file);
+     * ```
+     */
+    extractText(file: TFile, options?: {
+        signal?: AbortSignal;
+    }): Promise<OcrExtractionResult>;
+}
+/**
+ * Get the OCR Extractor API from the Obsidian `app`.
+ *
+ * @param app - The Obsidian app instance
+ * @returns The API, or `undefined` if the plugin isn't installed or enabled
+ * @since 1.0.0
+ * @example
+ * ```ts
+ * const api = getOcrExtractorApi(app);
+ * if (!api) return;
+ * ```
+ */
+export declare function getOcrExtractorApi(app: App): OcrExtractorApi | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,UAAU,EACV,QAAQ,GACT,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;CACd;AAOD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CACT,IAAI,EAAE,KAAK,EACX,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,GAAG,GAAG,eAAe,GAAG,SAAS,CAGxE"}

package/dist/index.js

@@ -0,0 +1,31 @@
+/**
+ * Public API for the OCR Extractor Obsidian plugin
+ *
+ * Access it with {@link getOcrExtractorApi}.
+ *
+ * @packageDocumentation
+ */
+export { isOcrError, ocrError, } from "./errors.js";
+/**
+ * The API version
+ *
+ * @since 1.0.0
+ */
+export const OCR_EXTRACTOR_API_VERSION = "1.0.0";
+/**
+ * Get the OCR Extractor API from the Obsidian `app`.
+ *
+ * @param app - The Obsidian app instance
+ * @returns The API, or `undefined` if the plugin isn't installed or enabled
+ * @since 1.0.0
+ * @example
+ * ```ts
+ * const api = getOcrExtractorApi(app);
+ * if (!api) return;
+ * ```
+ */
+export function getOcrExtractorApi(app) {
+    const plugins = app.plugins?.plugins;
+    return plugins?.["ocr-extractor"]?.api;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAGL,UAAU,EACV,QAAQ,GACT,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAoDjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAQ;IACzC,MAAM,OAAO,GAAI,GAAsB,CAAC,OAAO,EAAE,OAAO,CAAC;IACzD,OAAO,OAAO,EAAE,CAAC,eAAe,CAAC,EAAE,GAAG,CAAC;AACzC,CAAC"}

package/docs/README.md

@@ -0,0 +1,29 @@
+**ocr-extractor-api**
+
+***
+
+# ocr-extractor-api
+
+Public API for the OCR Extractor Obsidian plugin
+
+Access it with [getOcrExtractorApi](functions/getOcrExtractorApi.md).
+
+## Interfaces
+
+- [OcrError](interfaces/OcrError.md)
+- [OcrExtractionResult](interfaces/OcrExtractionResult.md)
+- [OcrExtractorApi](interfaces/OcrExtractorApi.md)
+
+## Type Aliases
+
+- [OcrErrorCode](type-aliases/OcrErrorCode.md)
+
+## Variables
+
+- [OCR\_EXTRACTOR\_API\_VERSION](variables/OCR_EXTRACTOR_API_VERSION.md)
+
+## Functions
+
+- [getOcrExtractorApi](functions/getOcrExtractorApi.md)
+- [isOcrError](functions/isOcrError.md)
+- [ocrError](functions/ocrError.md)

package/docs/functions/getOcrExtractorApi.md

@@ -0,0 +1,38 @@
+[**ocr-extractor-api**](../README.md)
+
+***
+
+[ocr-extractor-api](../README.md) / getOcrExtractorApi
+
+# Function: getOcrExtractorApi()
+
+> **getOcrExtractorApi**(`app`): [`OcrExtractorApi`](../interfaces/OcrExtractorApi.md) \| `undefined`
+
+Defined in: [index.ts:87](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/index.ts#L87)
+
+Get the OCR Extractor API from the Obsidian `app`.
+
+## Parameters
+
+### app
+
+`App`
+
+The Obsidian app instance
+
+## Returns
+
+[`OcrExtractorApi`](../interfaces/OcrExtractorApi.md) \| `undefined`
+
+The API, or `undefined` if the plugin isn't installed or enabled
+
+## Since
+
+1.0.0
+
+## Example
+
+```ts
+const api = getOcrExtractorApi(app);
+if (!api) return;
+```

package/docs/functions/isOcrError.md

@@ -0,0 +1,42 @@
+[**ocr-extractor-api**](../README.md)
+
+***
+
+[ocr-extractor-api](../README.md) / isOcrError
+
+# Function: isOcrError()
+
+> **isOcrError**(`error`): `error is OcrError`
+
+Defined in: [errors.ts:42](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/errors.ts#L42)
+
+Checks whether a caught value is an [OcrError](../interfaces/OcrError.md).
+
+## Parameters
+
+### error
+
+`unknown`
+
+The caught error to check
+
+## Returns
+
+`error is OcrError`
+
+`true` if `error` is an [OcrError](../interfaces/OcrError.md), `false` otherwise
+
+## Since
+
+1.0.0
+
+## Example
+
+```ts
+try {
+  await api.extractText(file);
+} catch (error) {
+  if (isOcrError(error) && error.code === "unsupported-file") return;
+  throw error;
+}
+```

package/docs/functions/ocrError.md

@@ -0,0 +1,48 @@
+[**ocr-extractor-api**](../README.md)
+
+***
+
+[ocr-extractor-api](../README.md) / ocrError
+
+# Function: ocrError()
+
+> **ocrError**(`code`, `message?`, `options?`): [`OcrError`](../interfaces/OcrError.md)
+
+Defined in: [errors.ts:61](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/errors.ts#L61)
+
+Used by the plugin to construct an [OcrError](../interfaces/OcrError.md) with the given code and
+message.
+
+## Parameters
+
+### code
+
+[`OcrErrorCode`](../type-aliases/OcrErrorCode.md)
+
+Which kind of error this is
+
+### message?
+
+`string`
+
+A human-readable message
+
+### options?
+
+Optional settings
+
+#### cause?
+
+`unknown`
+
+The underlying error, if any
+
+## Returns
+
+[`OcrError`](../interfaces/OcrError.md)
+
+The new [OcrError](../interfaces/OcrError.md)
+
+## Since
+
+1.0.0

package/docs/interfaces/OcrError.md

@@ -0,0 +1,42 @@
+[**ocr-extractor-api**](../README.md)
+
+***
+
+[ocr-extractor-api](../README.md) / OcrError
+
+# Interface: OcrError
+
+Defined in: [errors.ts:21](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/errors.ts#L21)
+
+The error thrown by [OcrExtractorApi.extractText](OcrExtractorApi.md#extracttext) when extraction
+fails. Identify it with [isOcrError](../functions/isOcrError.md) (not `instanceof`, which won't
+work across the plugin and npm package boundary). The original error,
+if any, is included as `cause`.
+
+## Since
+
+1.0.0
+
+## Extends
+
+- `Error`
+
+## Properties
+
+### cause?
+
+> `readonly` `optional` **cause?**: `unknown`
+
+Defined in: [errors.ts:23](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/errors.ts#L23)
+
+#### Overrides
+
+`Error.cause`
+
+***
+
+### code
+
+> `readonly` **code**: [`OcrErrorCode`](../type-aliases/OcrErrorCode.md)
+
+Defined in: [errors.ts:22](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/errors.ts#L22)

package/docs/interfaces/OcrExtractionResult.md

@@ -0,0 +1,25 @@
+[**ocr-extractor-api**](../README.md)
+
+***
+
+[ocr-extractor-api](../README.md) / OcrExtractionResult
+
+# Interface: OcrExtractionResult
+
+Defined in: [index.ts:30](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/index.ts#L30)
+
+The result of a successful extraction
+
+## Since
+
+1.0.0
+
+## Properties
+
+### text
+
+> **text**: `string`
+
+Defined in: [index.ts:32](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/index.ts#L32)
+
+Extracted text (or `""` if the file was processed but contained no text)

package/docs/interfaces/OcrExtractorApi.md

@@ -0,0 +1,79 @@
+[**ocr-extractor-api**](../README.md)
+
+***
+
+[ocr-extractor-api](../README.md) / OcrExtractorApi
+
+# Interface: OcrExtractorApi
+
+Defined in: [index.ts:45](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/index.ts#L45)
+
+The OCR Extractor plugin's public API, obtained via [getOcrExtractorApi](../functions/getOcrExtractorApi.md)
+
+## Since
+
+1.0.0
+
+## Properties
+
+### version
+
+> `readonly` **version**: `string`
+
+Defined in: [index.ts:51](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/index.ts#L51)
+
+The API version (i.e. [OCR\_EXTRACTOR\_API\_VERSION](../variables/OCR_EXTRACTOR_API_VERSION.md))
+
+#### Since
+
+1.0.0
+
+## Methods
+
+### extractText()
+
+> **extractText**(`file`, `options?`): `Promise`\<[`OcrExtractionResult`](OcrExtractionResult.md)\>
+
+Defined in: [index.ts:69](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/index.ts#L69)
+
+Run the user's configured OCR engine on an attachment and return the
+extracted text. Does not modify any note.
+
+#### Parameters
+
+##### file
+
+`TFile`
+
+The attachment's `TFile`
+
+##### options?
+
+Optional settings
+
+###### signal?
+
+`AbortSignal`
+
+An optional `AbortSignal` to cancel the extraction
+
+#### Returns
+
+`Promise`\<[`OcrExtractionResult`](OcrExtractionResult.md)\>
+
+An [OcrExtractionResult](OcrExtractionResult.md) with the extracted `text` (`""` if none found)
+
+#### Throws
+
+An [OcrError](OcrError.md) with an error `code` ([OcrErrorCode](../type-aliases/OcrErrorCode.md)), or
+        an `AbortError` if canceled via `options.signal`
+
+#### Since
+
+1.0.0
+
+#### Example
+
+```ts
+const { text } = await api.extractText(file);
+```

package/docs/type-aliases/OcrErrorCode.md

@@ -0,0 +1,22 @@
+[**ocr-extractor-api**](../README.md)
+
+***
+
+[ocr-extractor-api](../README.md) / OcrErrorCode
+
+# Type Alias: OcrErrorCode
+
+> **OcrErrorCode** = `"unsupported-file"` \| `"extraction-failed"`
+
+Defined in: [errors.ts:11](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/errors.ts#L11)
+
+Identifies which kind of [OcrError](../interfaces/OcrError.md) occurred.
+
+- `"unsupported-file"`: the OCR engine can't process this file (e.g. an
+  unsupported file type)
+- `"extraction-failed"`: any other failure during extraction (network,
+  auth, etc.)
+
+## Since
+
+1.0.0

package/docs/variables/OCR_EXTRACTOR_API_VERSION.md

@@ -0,0 +1,17 @@
+[**ocr-extractor-api**](../README.md)
+
+***
+
+[ocr-extractor-api](../README.md) / OCR\_EXTRACTOR\_API\_VERSION
+
+# Variable: OCR\_EXTRACTOR\_API\_VERSION
+
+> `const` **OCR\_EXTRACTOR\_API\_VERSION**: `"1.0.0"` = `"1.0.0"`
+
+Defined in: [index.ts:23](https://github.com/jritzi/ocr-extractor/blob/e7f98a2c103b20be831bfca50d478c0c3b12ddec/ocr-extractor-api/src/index.ts#L23)
+
+The API version
+
+## Since
+
+1.0.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ocr-extractor-api",
+  "version": "1.0.0",
+  "description": "Types and helpers for the OCR Extractor Obsidian plugin's public API",
+  "type": "module",
+  "license": "MIT",
+  "author": "Johnathan Ritzi",
+  "homepage": "https://community.obsidian.md/plugins/ocr-extractor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jritzi/ocr-extractor.git",
+    "directory": "ocr-extractor-api"
+  },
+  "bugs": {
+    "url": "https://github.com/jritzi/ocr-extractor/issues"
+  },
+  "keywords": [
+    "ocr-extractor",
+    "obsidian",
+    "types",
+    "ocr"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "obsidian": "*"
+  },
+  "devDependencies": {
+    "obsidian": "^1.12.3",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.12.0",
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "generate-docs": "typedoc",
+    "version": "node scripts/version-bump.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}

package/src/errors.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { isOcrError, ocrError } from "./errors.js";
+
+describe("errors.ts", () => {
+  describe("isOcrError", () => {
+    it("returns true for an error built by ocrError", () => {
+      expect(isOcrError(ocrError("unsupported-file"))).toBe(true);
+    });
+
+    it("returns true for a duck-typed error from another bundle", () => {
+      const fromOtherBundle = Object.assign(new Error(), {
+        name: "OcrError",
+        code: "extraction-failed",
+      });
+      expect(isOcrError(fromOtherBundle)).toBe(true);
+    });
+
+    it("returns false for anything other than a real OcrError", () => {
+      expect(isOcrError(new Error("error"))).toBe(false);
+      expect(isOcrError(Object.assign(new Error(), { name: "OcrError" }))).toBe(
+        false,
+      );
+      expect(isOcrError({ name: "OcrError", code: "extraction-failed" })).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("ocrError", () => {
+    it("returns an error with the OcrError name and a code", () => {
+      const error = ocrError("unsupported-file");
+      expect(error).toBeInstanceOf(Error);
+      expect(error.name).toBe("OcrError");
+      expect(error.code).toBe("unsupported-file");
+    });
+
+    it("includes a provided message and cause", () => {
+      const cause = new Error();
+      const error = ocrError("extraction-failed", "request failed", { cause });
+      expect(error.message).toBe("request failed");
+      expect(error.cause).toBe(cause);
+    });
+  });
+});

package/src/errors.ts

@@ -0,0 +1,68 @@
+/**
+ * Identifies which kind of {@link OcrError} occurred.
+ *
+ * - `"unsupported-file"`: the OCR engine can't process this file (e.g. an
+ *   unsupported file type)
+ * - `"extraction-failed"`: any other failure during extraction (network,
+ *   auth, etc.)
+ *
+ * @since 1.0.0
+ */
+export type OcrErrorCode = "unsupported-file" | "extraction-failed";
+
+/**
+ * The error thrown by {@link OcrExtractorApi.extractText} when extraction
+ * fails. Identify it with {@link isOcrError} (not `instanceof`, which won't
+ * work across the plugin and npm package boundary). The original error,
+ * if any, is included as `cause`.
+ *
+ * @since 1.0.0
+ */
+export interface OcrError extends Error {
+  readonly code: OcrErrorCode;
+  readonly cause?: unknown;
+}
+
+/**
+ * Checks whether a caught value is an {@link OcrError}.
+ *
+ * @param error - The caught error to check
+ * @returns `true` if `error` is an {@link OcrError}, `false` otherwise
+ * @since 1.0.0
+ * @example
+ * ```ts
+ * try {
+ *   await api.extractText(file);
+ * } catch (error) {
+ *   if (isOcrError(error) && error.code === "unsupported-file") return;
+ *   throw error;
+ * }
+ * ```
+ */
+export function isOcrError(error: unknown): error is OcrError {
+  return (
+    error instanceof Error &&
+    error.name === "OcrError" &&
+    typeof (error as Partial<OcrError>).code === "string"
+  );
+}
+
+/**
+ * Used by the plugin to construct an {@link OcrError} with the given code and
+ * message.
+ *
+ * @param code - Which kind of error this is
+ * @param message - A human-readable message
+ * @param options - Optional settings
+ * @param options.cause - The underlying error, if any
+ * @returns The new {@link OcrError}
+ * @since 1.0.0
+ */
+export function ocrError(
+  code: OcrErrorCode,
+  message?: string,
+  options?: { cause?: unknown },
+): OcrError {
+  const error = new Error(message ?? code, options);
+  return Object.assign(error, { name: "OcrError", code });
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Public API for the OCR Extractor Obsidian plugin
+ *
+ * Access it with {@link getOcrExtractorApi}.
+ *
+ * @packageDocumentation
+ */
+
+import type { App, TFile } from "obsidian";
+
+export {
+  type OcrError,
+  type OcrErrorCode,
+  isOcrError,
+  ocrError,
+} from "./errors.js";
+
+/**
+ * The API version
+ *
+ * @since 1.0.0
+ */
+export const OCR_EXTRACTOR_API_VERSION = "1.0.0";
+
+/**
+ * The result of a successful extraction
+ *
+ * @since 1.0.0
+ */
+export interface OcrExtractionResult {
+  /** Extracted text (or `""` if the file was processed but contained no text) */
+  text: string;
+}
+
+/** The Obsidian `App` with plugin registry (not present in public types) */
+type AppWithPlugins = App & {
+  plugins?: { plugins?: Record<string, { api?: OcrExtractorApi }> };
+};
+
+/**
+ * The OCR Extractor plugin's public API, obtained via {@link getOcrExtractorApi}
+ *
+ * @since 1.0.0
+ */
+export interface OcrExtractorApi {
+  /**
+   * The API version (i.e. {@link OCR_EXTRACTOR_API_VERSION})
+   *
+   * @since 1.0.0
+   */
+  readonly version: string;
+
+  /**
+   * Run the user's configured OCR engine on an attachment and return the
+   * extracted text. Does not modify any note.
+   *
+   * @param file - The attachment's `TFile`
+   * @param options - Optional settings
+   * @param options.signal - An optional `AbortSignal` to cancel the extraction
+   * @returns An {@link OcrExtractionResult} with the extracted `text` (`""` if none found)
+   * @throws An {@link OcrError} with an error `code` ({@link OcrErrorCode}), or
+   *         an `AbortError` if canceled via `options.signal`
+   * @since 1.0.0
+   * @example
+   * ```ts
+   * const { text } = await api.extractText(file);
+   * ```
+   */
+  extractText(
+    file: TFile,
+    options?: { signal?: AbortSignal },
+  ): Promise<OcrExtractionResult>;
+}
+
+/**
+ * Get the OCR Extractor API from the Obsidian `app`.
+ *
+ * @param app - The Obsidian app instance
+ * @returns The API, or `undefined` if the plugin isn't installed or enabled
+ * @since 1.0.0
+ * @example
+ * ```ts
+ * const api = getOcrExtractorApi(app);
+ * if (!api) return;
+ * ```
+ */
+export function getOcrExtractorApi(app: App): OcrExtractorApi | undefined {
+  const plugins = (app as AppWithPlugins).plugins?.plugins;
+  return plugins?.["ocr-extractor"]?.api;
+}