@munchi_oy/pax-smart-terminal-printer-sdk

React Native bridge for the embedded printer on PAX smart terminals.

Scope

• Supported hardware: PAX A8900 series only.
• Supported capability: embedded printer only.
• External printers are not supported.
• Cash drawer support is not part of this package.
• Non-printer terminal integrations are out of scope.

Install

pnpm add @munchi_oy/pax-smart-terminal-printer-sdk

Android

Pax NeptuneLite resource files are bundled in resources/pax/neptune-lite-api/V4.26.00.

• JAR: resources/pax/neptune-lite-api/V4.26.00/android/libs/NeptuneLiteApi_V4.26.00_20260408.jar
• Native libraries: resources/pax/neptune-lite-api/V4.26.00/android/jniLibs

android/build.gradle is already wired to consume this bundle.

This package is intended for the embedded printer on PAX A8900 devices only. Only the Android runtime resources are published with the package. Neptune reference docs are kept out of the npm payload.

Usage

import {
  prepare,
  getDeviceInfo,
  getPrinterStatus,
  print,
  printText,
  cutPaper
} from "@munchi_oy/pax-smart-terminal-printer-sdk";

const device = await getDeviceInfo();
await prepare();
const status = await getPrinterStatus();
await print({
  commands: [
    { type: "align", align: "center" },
    { type: "text", text: "Hello Pax\n" }
  ]
});
await printText("Hello Pax");
await cutPaper();

Call prepare() before printing. initialize() is kept as an alias to prepare().

getDeviceInfo() returns normalized device identity data only. Readiness and printer availability checks belong to prepare().

Current status

What is wired end to end today:

• getDeviceInfo() returns normalized device identity data from the current platform.
• prepare() and initialize() are wired to the Android Neptune printer layer and resolve the embedded IPrinter handle.
• getPrinterStatus() is wired to Neptune printer.getStatus().
• print(job) is wired to Neptune init -> apply commands -> start().
• printText(text, options) is wired to Neptune init -> setAlignMode? -> printStr -> start().
• cutPaper() is wired to Neptune cutPaper(full).

What to expect on each platform:

• Android on supported PAX hardware: this package is intended to run for real.
• iOS: the package should still build into the app, but printing is not supported. getDeviceInfo() returns a safe fallback object. prepare() rejects with UnsupportedPlatform.

What is not implemented as a feature:

• no printer retry or automatic recovery
• no pause/resume queue flow
• no external printer support
• no cash drawer support
• no guarantee of cross-app printer ownership beyond what the embedded PAX runtime already does

Runtime behavior

• Call prepare() before print(), printText(), or cutPaper().
• If prepare() has not succeeded yet, JS throws NotPrepared before going down to native.
• print() and printText() are serialized in a native FIFO queue on a worker thread.
• The queue is inside the app process only. It prevents rapid taps or Promise.all() from colliding inside the same app.
• Printer errors such as out of paper, cover open, busy, permission, or whitelist failures reject the current call through the package error model. They are not retried automatically.

What You Control

The public controls currently exposed to the consumer are:

• prepare() / initialize()
• getDeviceInfo()
• getPrinterStatus()
• print(job)
• printText(text, options)
• cutPaper()

print(job) currently supports these command types:

• align
• text
• bitmap
• feed
• font
• fontScale
• gray
• spacing
• indent
• invert
• cut

printText(text, options) now maps all fields in PrintTextOptions into the native Neptune flow:

• align maps to printer alignment
• fontSize maps to the nearest supported Neptune font preset
• bold maps to a darker print gray level

If you need exact per-command styling, continue using print(job). printText is a convenience wrapper with a smaller style contract.

Verification level

This repo currently verifies:

• TypeScript unit tests
• package build
• native queue unit tests
• Android compile integration

This repo does not by itself prove that a given receipt has printed successfully on hardware. Real printer verification still needs a PAX device.

Development

Publish a local build to yalc:

pnpm yalc:publish

Publish the package with the repo publish flow:

pnpm publish:package

Create a versioned release:

pnpm release:patch
pnpm release:minor
pnpm release:major

pnpm publish:package builds before publishing. pnpm release:* bumps package.json, runs tests, builds, commits the release, and creates a v<version> tag by default.

CI

GitHub Actions runs the package validation flow on pushes, pull requests, and manual dispatch:

pnpm validate

This currently covers:

• pnpm test
• pnpm typecheck
• pnpm build

Real Neptune printer runtime validation still requires a PAX device or a self-hosted hardware runner.