flair-printer
v0.0.18
Published
This plugin allows printing receipts via USB (ESCPOS)
Readme
flair-printer
This plugin allows printing receipts via USB (ESCPOS)
Install
npm install flair-printer
npx cap syncAPI
getPrinters()scanUsbPrinters()listSystemPrinters()probePrinter(...)setPrinter(...)removePrinter(...)testPrint(...)printReceipt(...)warmUp(...)executeTapAndPay(...)provideConnectionToken(...)addListener('connectionTokenNeeded', ...)setServerUrl(...)getServerUrl()clearServerUrl()openEnvPicker()getKioskMode()setKioskMode(...)releaseDeviceOwner()worldlineInfo()worldlineCharge(...)worldlineRefund(...)worldlineCommit(...)worldlineRollback(...)worldlineCancel(...)worldlineTest(...)worldlinePending()worldlineBalance(...)- Interfaces
- Type Aliases
getPrinters()
getPrinters() => Promise<{ printers: Printer[]; }>Returns: Promise<{ printers: Printer[]; }>
scanUsbPrinters()
scanUsbPrinters() => Promise<{ printers: USBPrinter[]; }>libusb / USB-host discovery. On Windows this only finds printers that have been
switched to a WinUSB driver — use listSystemPrinters() there instead.
Returns: Promise<{ printers: USBPrinter[]; }>
listSystemPrinters()
listSystemPrinters() => Promise<SystemPrintersResult>The OS print queues available for type: 'WINDOWS' printers.
Resolves { supported: false, printers: [] } on platforms without a spooler.
Returns: Promise<SystemPrintersResult>
probePrinter(...)
probePrinter(options: { type?: PrinterType; connectionInfo?: string; }) => Promise<ProbeResult>Check that a network printer answers before its config is saved.
Only NETWORK / TCP printers can be probed.
| Param | Type |
| ------------- | ---------------------------------------------------------------------------------------- |
| options | { type?: PrinterType; connectionInfo?: string; } |
Returns: Promise<ProbeResult>
setPrinter(...)
setPrinter({ printer }: { printer: Printer; }) => Promise<PrinterResult>| Param | Type |
| --------- | --------------------------------------------------------- |
| __0 | { printer: Printer; } |
Returns: Promise<PrinterResult>
removePrinter(...)
removePrinter({ printerId }: { printerId: string; }) => Promise<PrinterResult>| Param | Type |
| --------- | ----------------------------------- |
| __0 | { printerId: string; } |
Returns: Promise<PrinterResult>
testPrint(...)
testPrint({ printerId }: { printerId: string; }) => Promise<PrinterResult>Print a short diagnostic receipt to verify a printer config.
| Param | Type |
| --------- | ----------------------------------- |
| __0 | { printerId: string; } |
Returns: Promise<PrinterResult>
printReceipt(...)
printReceipt({ printerId, data, }: { printerId: string; data: { raw: number[]; logo?: string; }; }) => Promise<PrinterResult>| Param | Type |
| --------- | ---------------------------------------------------------------------------- |
| __0 | { printerId: string; data: { raw: number[]; logo?: string; }; } |
Returns: Promise<PrinterResult>
warmUp(...)
warmUp(options?: { simulated?: boolean | undefined; } | undefined) => Promise<void>Prime the Stripe Terminal SDK in the background so the first payment is fast. Call this on app/device page load with the connectionTokenNeeded listener already set up. Fire-and-forget — resolves immediately while warmup runs in the background.
| Param | Type |
| ------------- | ------------------------------------- |
| options | { simulated?: boolean; } |
executeTapAndPay(...)
executeTapAndPay(options: TapAndPayOptions) => Promise<TapAndPayResult>| Param | Type |
| ------------- | ------------------------------------------------------------- |
| options | TapAndPayOptions |
Returns: Promise<TapAndPayResult>
provideConnectionToken(...)
provideConnectionToken(options: { token: string; }) => Promise<void>Supply a fresh connection token to the Stripe Terminal SDK.
Call this in response to the fetchConnectionToken event (re-auth / reconnect scenarios).
| Param | Type |
| ------------- | ------------------------------- |
| options | { token: string; } |
addListener('connectionTokenNeeded', ...)
addListener(eventName: 'connectionTokenNeeded', listenerFunc: () => void) => Promise<PluginListenerHandle>Fired by the native plugin every time the Stripe Terminal SDK needs a fresh connection token (on init, discovery, connect, and any SDK reconnect). Fetch a new token from your backend and call provideConnectionToken().
| Param | Type |
| ------------------ | ------------------------------------ |
| eventName | 'connectionTokenNeeded' |
| listenerFunc | () => void |
Returns: Promise<PluginListenerHandle>
setServerUrl(...)
setServerUrl(options: { url: string; }) => Promise<void>Persist a new server URL and immediately navigate the WebView to it.
| Param | Type |
| ------------- | ----------------------------- |
| options | { url: string; } |
getServerUrl()
getServerUrl() => Promise<{ url: string | null; }>Return the currently-saved server URL, or null if none is stored (falls back to build-time default).
Returns: Promise<{ url: string | null; }>
clearServerUrl()
clearServerUrl() => Promise<void>Clear the saved server URL and open the env picker so the user can choose a new one.
openEnvPicker()
openEnvPicker() => Promise<void>Load the environment-switcher page (launcher.html) over the current WebView.
getKioskMode()
getKioskMode() => Promise<KioskModeState>The stored kiosk choice and whether it is in effect. Resolves
{ supported: false, ... } on web instead of rejecting.
Returns: Promise<KioskModeState>
setKioskMode(...)
setKioskMode(options: { enabled: boolean; }) => Promise<KioskModeState>Store the kiosk choice and apply it right away where the platform allows. Whatever can't be applied now is applied on the next start. Resolves the resulting state.
| Param | Type |
| ------------- | ---------------------------------- |
| options | { enabled: boolean; } |
Returns: Promise<KioskModeState>
releaseDeviceOwner()
releaseDeviceOwner() => Promise<KioskModeState>Android only: give up device-owner status. A device-owner app cannot be uninstalled, and adb cannot remove the owner either, so without this only a factory reset releases the device. Refused while kiosk mode is enabled.
Returns: Promise<KioskModeState>
worldlineInfo()
worldlineInfo() => Promise<WorldlineInfo>Whether this bridge drives Worldline terminals. Resolves { supported: false } where it
doesn't instead of rejecting - check it rather than whether the method exists.
Returns: Promise<WorldlineInfo>
worldlineCharge(...)
worldlineCharge(options: WorldlineChargeOptions) => Promise<WorldlineChargeResult>Charges the terminal and waits for the guest. A success is held open on the terminal: call worldlineCommit once the payment is booked, worldlineRollback if it could not be. Uncommitted, the terminal reverses it by itself after 60 s.
| Param | Type |
| ------------- | ------------------------------------------------------------------------- |
| options | WorldlineChargeOptions |
Returns: Promise<WorldlineChargeResult>
worldlineRefund(...)
worldlineRefund(options: WorldlineRefundOptions) => Promise<WorldlineChargeResult>Pays an earlier charge back on the terminal. Held open like a charge: worldlineCommit once the refund is booked, worldlineRollback if it could not be. Not on bridges built before 0.0.18.
| Param | Type |
| ------------- | ------------------------------------------------------------------------- |
| options | WorldlineRefundOptions |
Returns: Promise<WorldlineChargeResult>
worldlineCommit(...)
worldlineCommit(options: { requestId: string; }) => Promise<WorldlineResult>| Param | Type |
| ------------- | ----------------------------------- |
| options | { requestId: string; } |
Returns: Promise<WorldlineResult>
worldlineRollback(...)
worldlineRollback(options: { requestId: string; }) => Promise<WorldlineResult>| Param | Type |
| ------------- | ----------------------------------- |
| options | { requestId: string; } |
Returns: Promise<WorldlineResult>
worldlineCancel(...)
worldlineCancel(options: { terminal: WorldlineTerminalConfig; }) => Promise<WorldlineResult>Aborts a charge still waiting for the guest. Best effort.
| Param | Type |
| ------------- | ------------------------------------------------------------------------------------------ |
| options | { terminal: WorldlineTerminalConfig; } |
Returns: Promise<WorldlineResult>
worldlineTest(...)
worldlineTest(options: { terminal: WorldlineTerminalConfig; posId?: string; unattended?: boolean; }) => Promise<WorldlineResult & { terminalId?: string; }>Connects and logs in, answering the terminal id.
| Param | Type |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| options | { terminal: WorldlineTerminalConfig; posId?: string; unattended?: boolean; } |
Returns: Promise<WorldlineResult & { terminalId?: string; }>
worldlinePending()
worldlinePending() => Promise<{ charges: WorldlinePendingCharge[]; }>Approved charges not yet committed or rolled back. A page that loads asks this and settles them, so a reload between booking and commit doesn't leave a booked payment reversed.
Returns: Promise<{ charges: WorldlinePendingCharge[]; }>
worldlineBalance(...)
worldlineBalance(options: WorldlineBalanceOptions) => Promise<WorldlineBalanceResult>The terminal's daily closing (TIM deactivate > balance): sends the period's transactions to the acquirers. Refused while a payment runs or is held open. After it, a charge can no longer be reversed, only credited. Not on bridges built before 0.0.18.
| Param | Type |
| ------------- | --------------------------------------------------------------------------- |
| options | WorldlineBalanceOptions |
Returns: Promise<WorldlineBalanceResult>
Interfaces
Printer
| Prop | Type | Description |
| -------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | |
| name | string | |
| type | PrinterType | |
| connectionInfo | string | Address of the printer, interpreted per type: - NETWORK / TCP — host or host:port (port defaults to 9100) - USB — vendorIdxproductId, e.g. 5380x156 - WINDOWS — the print queue name; queueName is preferred but this is accepted |
| queueName | string | Windows print queue name, exactly as returned by listSystemPrinters(). |
| lineWidth | number | |
USBPrinter
| Prop | Type |
| --------------- | ------------------- |
| vendorId | string |
| productId | string |
SystemPrintersResult
| Prop | Type | Description |
| --------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| supported | boolean | False wherever the platform has no print spooler (Android, web). Check this rather than testing whether the method exists — Capacitor defines every declared method on every platform, so typeof plugin.listSystemPrinters is always 'function' and cannot be used for feature detection. |
| printers | SystemPrinter[] | |
| error | string | |
SystemPrinter
An OS print queue, as reported by the host platform.
| Prop | Type | Description |
| ----------------- | -------------------- | ----------------------------------------------------------------------- |
| name | string | Queue name to store as queueName — this is what the spooler resolves. |
| displayName | string | Human-readable name for the picker; falls back to name. |
| description | string | |
| status | number | |
| isDefault | boolean | |
ProbeResult
| Prop | Type | Description |
| --------------- | -------------------- | ------------------------------------------ |
| reachable | boolean | |
| target | string | The host:port that was actually dialled. |
| latencyMs | number | |
| error | string | |
PrinterResult
| Prop | Type |
| ------------- | -------------------- |
| success | boolean |
| message | string |
TapAndPayResult
| Prop | Type | Description |
| --------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status | 'error' | 'succeeded' | 'requires_capture' | 'canceled' | succeeded — payment done (auto-capture PI) requires_capture — collected, call POST /capture on your backend with paymentIntentId canceled — user pressed Cancel on the overlay error — something failed, check errorMessage |
| paymentIntentId | string | PaymentIntent ID — present for succeeded / requires_capture / canceled |
| errorMessage | string | |
| errorCode | string | |
TapAndPayOptions
| Prop | Type | Description |
| ------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| paymentIntentClientSecret | string | Client secret of a PaymentIntent created on your backend (payment_method_types: ['card_present']) |
| locationId | string | Stripe Terminal location ID belonging to the connected account |
| merchantDisplayName | string | Business name shown on the native payment overlay |
| simulated | boolean | Use simulated reader — for testing only, no real card needed. Defaults to false. |
PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |
KioskModeState
Kiosk mode keeps guests inside the app. The bridge stores the choice natively, so it survives restarts and is applied again on every launch.
- Desktop: a fullscreen, always-on-top window that cannot be closed, which also starts with Windows. Applied immediately. The Windows key and Ctrl+Alt+Del are the operating system's, so a fully locked kiosk still needs Assigned Access or Shell Launcher.
- Android: Lock Task Mode plus hidden system bars. A device-owner app (see
deviceOwner) is locked without asking. Otherwise Android falls back to screen pinning: the user confirms a prompt and can leave by holding Back + Overview.
| Prop | Type | Description |
| --------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| supported | boolean | False where the platform cannot do it (web, or a native build that predates it). |
| enabled | boolean | The stored choice — what the device starts in. |
| active | boolean | Whether kiosk mode is in effect right now. |
| lockMode | 'locked' | 'pinned' | 'none' | Android only. locked = Lock Task Mode (device owner), pinned = screen pinning, none = neither. |
| deviceOwner | boolean | Android only: the app is the device owner, so Lock Task Mode needs no confirmation. |
| pending | boolean | Android only: Android is showing the screen-pinning prompt and waiting for the user to confirm. |
| restartRequired | boolean | The choice is stored but could not be applied now. It is applied on the next app start. |
| message | string | Why it could not be applied, when it could not. |
WorldlineInfo
| Prop | Type | Description |
| ---------------- | -------------------- | ----------------------------------------------------------------------------------------------- |
| supported | boolean | False wherever the bridge can't drive Worldline terminals (Android, web, an older desktop app). |
| apiVersion | string | TIM SDK version, when supported. |
| message | string | |
WorldlineChargeResult
| Prop | Type | Description |
| ----------------- | --------------------------------------------------------------------- | -------------------------------------------------------------- |
| transaction | WorldlineTransaction | Set on success. The charge is not final until worldlineCommit. |
WorldlineTransaction
| Prop | Type | Description |
| ------------------ | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| reference | string | Acquirer reference (acqTransRef), else the terminal's own. |
| authCode | string | |
| brand | string | Card brand as the terminal names it (VISA, Mastercard, TWINT, …). |
| maskedPan | string | As masked by the terminal. |
| tid | string | Terminal id (TID). |
| acqId | string | |
| acqTransRef | string | |
| trmTransRef | string | |
| transSeq | string | The terminal's sequence number - what a reversal names the charge by. |
| transRef | string | |
| timeStamp | string | When the terminal carried it out, its local time as YYYY-MM-DDTHH:mm:ss. |
| refundMethod | WorldlineRefundMethod | Set on a refund: how the terminal paid the charge back. |
| receipts | { recipient: string; text: string; }[] | Slips the terminal produced, recipient = merchant / cardholder. |
WorldlineChargeOptions
| Prop | Type | Description |
| ---------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| requestId | string | Correlates the later commit / rollback with this charge (the device request id). |
| terminal | WorldlineTerminalConfig | |
| amount | number | Major units, e.g. 12.5. |
| currency | string | |
| posId | string | Identifies this register at the terminal. |
| unattended | boolean | Adds TIM's Unattended guide - required for self-checkout kiosks. |
WorldlineTerminalConfig
A Worldline terminal (TIM, the Swiss ep2 cash register interface), as the restaurant set it up.
transport: tcp = native TIM, default port 7784 (also the EFT simulator); websocket = the
terminal's WebSocket interface, default port 80.
| Prop | Type |
| --------------- | --------------------------------- |
| ip | string |
| port | number |
| transport | 'tcp' | 'websocket' |
WorldlineRefundOptions
| Prop | Type | Description |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| method | WorldlineRefundMethod | |
| original | Pick<
WorldlineTransaction,
'authCode' | 'acqId' | 'acqTransRef' | 'trmTransRef' | 'transSeq' | 'transRef' | 'timeStamp'
> | What the terminal reported for the charge being refunded. A reversal needs its transSeq, a credit its authCode; the other references are passed along where known. |
WorldlineResult
| Prop | Type | Description |
| ------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| success | boolean | |
| message | string | |
| code | string | TIM result code name on a failure (apiCancelEcr, declined, …). |
| final | boolean | worldlineCommit / worldlineRollback of a refund: the terminal held nothing open, because the refund was final once approved (the simulator does that for a reversal). A commit then succeeds; a rollback fails, since the money already went back. |
WorldlinePendingCharge
An approved charge the bridge still holds open - e.g. because the page reloaded before settling it.
| Prop | Type | Description |
| ----------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| requestId | string | |
| transaction | WorldlineTransaction | |
| remainingMs | number | How long the terminal still waits before it reverses the charge by itself. |
WorldlineBalanceResult
| Prop | Type | Description |
| ------------- | ------------------------------------------------------------- | --------------- |
| balance | WorldlineBalance | Set on success. |
WorldlineBalance
What the terminal reported for a daily closing (TIM balance).
| Prop | Type | Description |
| ---------------- | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| tid | string | Terminal id (TID). |
| seqCounter | number | The terminal's period sequence number. |
| counters | WorldlineBalanceCounter[] | |
| receipts | { recipient: string; text: string; }[] | The closing's slips as text, recipient = merchant (usually the only one). |
WorldlineBalanceCounter
One brand's transactions in a daily closing, amounts in major units per currency.
| Prop | Type |
| ------------ | ---------------------------------------------------------------------- |
| brand | string |
| acqId | string |
| count | number |
| totals | { currency?: string; count?: number; amount?: number; }[] |
WorldlineBalanceOptions
| Prop | Type | Description |
| ---------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| terminal | WorldlineTerminalConfig | |
| posId | string | Identifies this register at the terminal. |
| unattended | boolean | Adds TIM's Unattended guide - required for self-checkout kiosks. |
Type Aliases
PrinterType
How the bridge reaches the printer.
WINDOWS— a Windows print queue, addressed by name and fed raw ESC/POS through the spooler. Desktop only, and the preferred choice for a USB receipt printer on Windows: it needs no driver swap.NETWORK/TCP— raw ESC/POS over TCP, default port 9100. Desktop and Android.USB— direct USB. On Android this is the USB host API; on desktop it is libusb, which on Windows only works after the printer has been moved off its print driver onto WinUSB (Zadig). PreferWINDOWSthere.
HTTP was the old name for NETWORK — it was never HTTP. It has been removed, and
the bridges no longer accept it: a printer still stored as HTTP is rejected with
"Unsupported printer type" and has to be re-saved as NETWORK.
'USB' | 'NETWORK' | 'TCP' | 'WINDOWS'
WorldlineRefundMethod
reversal voids the charge without the card, but only until the terminal's daily closing.
credit pays the amount back to a card the guest presents, on any later day.
'reversal' | 'credit'
Pick
From T, pick a set of properties whose keys are in the union K
{ [P in K]: T[P]; }
