@scanhero/sdk

Official TypeScript/JavaScript SDK for the Scan Hero document conversion API.

Convert PDF, Word, Excel, PowerPoint, images, audio, email, and 20+ other formats to Markdown (or DOCX, CSV, EPUB, and more) with full type safety.

The client is generated automatically from the live OpenAPI spec (/openapi.json) using openapi-typescript-codegen.

Install

npm install @scanhero/sdk

Node.js 18+ required (uses native fetch).

Quick start

import { ScanHero } from "@scanhero/sdk";

const sh = new ScanHero({ apiKey: "sh_..." });

// List recent tasks
const tasks = await sh.tasks.listTasksV1TasksGet();

// Get profile and credit balance
const me = await sh.users.getMeV1UsersMeGet();
console.log(me.credits);

For file uploads and downloads, use the generated request types on sh.tasks, sh.jobs, and sh.convert. See the API reference for multipart field names and options.

Authentication

Generate an API key at scanheroai.com/settings/api-keys.

const sh = new ScanHero({ apiKey: "sh_your_key_here" });

Or from the environment:

const sh = ScanHero.fromEnv();
// reads SCANHERO_API_KEY

Custom base URL (e.g. local backend):

const sh = new ScanHero({
  apiKey: "sh_test",
  baseUrl: "http://127.0.0.1:8080",
});

Regenerating from the OpenAPI spec

When the API changes, regenerate the typed client from production or a local server:

cd sdk/typescript
npm install
npm run generate   # default: https://api.scanheroai.com/openapi.json
npm run build

Against a local FastAPI instance:

OPENAPI_URL=http://127.0.0.1:8080/openapi.json npm run generate

Generated sources land in src/generated/. The thin wrapper in src/index.ts adds API-key auth and re-exports all models and services.

API surface

The ScanHero client exposes namespaced services matching the REST API:

| Property | Endpoints | |----------|-----------| | tasks | Upload, list, adjust, download conversions | | jobs | Batch uploads (up to 50 files) | | webhooks | Register push notification URLs | | templates | Saved processing configurations | | users | Profile and credit balance | | convert | Direct format conversions (PDF→DjVu, etc.) | | feedback | Quality ratings and cashback | | health | Liveness probe |

All request/response types (e.g. TaskResponse, ProcessingOptions) are exported from the package root.

API reference

Full reference: scanheroai.com/docs
Interactive (OpenAPI): scanheroai.com/docs/reference

Related SDKs

| Language | Package | Source | |----------|---------|--------| | Python | pip install scanhero | sdk/python/ — handcrafted helpers | | TypeScript / JavaScript | npm install @scanhero/sdk | This package — generated from /openapi.json |

Both SDKs are documented together at scanheroai.com/docs#sdk.

License

MIT