rdhiq-cr

TypeScript/JavaScript client for the RDHIQ card reader local agent HTTP API. It targets dual ESM + CommonJS builds with matching type declarations.

The HTTP client uses the global fetch. Consumers can run on Node 18+, Bun, or other runtimes that provide fetch.

Install

npm install rdhiq-cr
# or
bun add rdhiq-cr

To use the repo directly before publish, link or depend on the git URL for this repository.

Quick start

By default the client talks to http://127.0.0.1:5078. Override with baseUrl if your agent listens elsewhere.

import { RdhiqClient, ApiError } from 'rdhiq-cr';

const client = new RdhiqClient({
  // baseUrl: 'http://127.0.0.1:5078', // default
});

// Health
await client.health.get();

// Session + read job
const { sessionId } = await client.sessions.open(null);
const { jobId } = await client.reads.create(sessionId, null);
const job = await client.reads.get(sessionId, jobId);
const text = await client.reads.getText(sessionId, jobId);

reads.getImage returns an ArrayBuffer (binary).

Non-success HTTP statuses throw ApiError with status and body (see below).

API overview

RdhiqClient exposes five namespaces:

| Property | Role | | ---------- | ----------------------------------------------------------- | | health | GET /health | | admin | Agent settings and logs under /api/v1/admin/* | | reader | Initialize reader, scanner info, notifications, latest read | | sessions | Open, get, release, heartbeat | | reads | Create read jobs, poll status, text, image, cancel |

For every method, path, and exported type, see the API reference or the guide.

Errors

Failed responses (response.ok === false) throw ApiError:

• status — HTTP status code
• body — parsed JSON if possible, otherwise plain text
• name — 'ApiError'

import { ApiError } from 'rdhiq-cr';

try {
  await client.health.get();
} catch (e) {
  if (e instanceof ApiError) {
    console.error(e.status, e.body);
  }
  throw e;
}

Exports

The package exports RdhiqClient, ApiError, RdhiqClientOptions, and request/response types (for example SessionOpenResponse, ReadJobResponse). See src/index.ts.

Documentation

Site source lives in docs/. Run bun run docs:dev to work on it locally. Markdown sources: guide, API.

Developing this package

Requirements: Bun 1.3+ for scripts in this repo.

bun install
bun test
bun run build

Scripts

| Script | What it does | | ---------------------- | ---------------------------------------------------------- | | bun run build | Clean dist/, then build ESM, CJS, and types in sequence | | bun run build:clean | Remove the dist/ directory | | bun run build:esm | Emit dist/index.mjs (+ source map) | | bun run build:cjs | Emit dist/index.cjs (+ source map) | | bun run build:types | Emit dist/index.d.mts and dist/index.d.cts via tsc | | bun test | Run the test suite | | bun run fmt | Format with oxfmt | | bun run lint | Lint and auto-fix with oxlint | | bun run docs:dev | Run the VitePress dev server | | bun run docs:build | Build the static docs site | | bun run docs:preview | Preview the built docs site | | bun run release | Run release-it |

Project layout

src/
  index.ts             Public exports
  client.ts            RdhiqClient
  http.ts              HttpClient (JSON + binary)
  error.ts             ApiError
  types.ts             API types
  resources/
    admin.ts
    health.ts
    reader.ts
    reads.ts
    sessions.ts
test/
  index.test.ts
tsconfig.json
tsconfig.build.json
docs/                  VitePress site

Build output

bun run build writes dist/index.{mjs,cjs} plus index.d.mts / index.d.cts. Publishing uses "files": ["dist"] and conditional exports with nested types for ESM and CJS.

Git hooks

husky runs:

• pre-commit: lint-staged (see .lintstagedrc.json)
• commit-msg: commitlint using @commitlint/config-conventional