@tripley-kit/xfs-control-client

TypeScript client for the Tripley.XFS simulator control plane. Use this package in automated tests and local simulator tooling to prepare device state, inject media, complete pending commands, or inspect simulator state through tripley-native-hostd.

This package is not the CEN/XFS device API. Production app code should use @tripley-kit/xfs-client for XFS commands and events. Test code can use this package next to @tripley-kit/xfs-client to drive the simulator.

Install

pnpm add @tripley-kit/xfs-control-client

Host setup

Start a tripley-native-hostd binary compiled with the service-xfs-control feature. If the app under test also calls XFS through the same host daemon, expose both services:

tripley-native-hostd --transport websocket --addr 127.0.0.1:39010 --services xfs,xfs-control --xfs-control-simulator-ws-url ws://127.0.0.1:39001

The default simulator control URL is ws://127.0.0.1:39001. Pass authToken to the client when the host daemon was started with --auth-token.

Connect

import { createWebSocketXfsControlClient } from '@tripley-kit/xfs-control-client';

const control = createWebSocketXfsControlClient({
  url: 'ws://127.0.0.1:39010',
  authToken: process.env.TRIPLEY_NATIVE_HOST_TOKEN,
});

await control.connect();

The high-level factory resolves these simulator control instances: RuntimeControl, IdcControl, PinControl, CdmControl, CimControl, BcrControl, PtrControl, SiuControl, and TtuControl. The generated clients are also exported if a test wants to resolve a single service manually.

IDC card injection example

Create or update a simulator card, then insert it while the IDC simulator has a pending card read command from the app under test.

import { IdcCardType, createWebSocketXfsControlClient } from '@tripley-kit/xfs-control-client';

const control = createWebSocketXfsControlClient({ url: 'ws://127.0.0.1:39010' });
await control.connect();

await control.idc.upsertCard({
  card: {
    id: 'visa-test-01',
    label: 'Visa Test 01',
    cardType: IdcCardType.Magstripe,
    track2: '4761739001010010=25122010000000000000',
  },
});

const services = await control.runtime.listLogicalServices({});
const idcService = services.services.find((service) => service.className === 'IDC');
if (!idcService) {
  throw new Error('No IDC logical service is configured in the simulator.');
}

const result = await control.idc.insertCardByLogicalService({
  logicalName: idcService.logicalName,
  cardId: 'visa-test-01',
});
if (result.hresult !== 0) {
  throw new Error(`insertCardByLogicalService failed: 0x${result.hresult.toString(16)}`);
}

For a full end-to-end test, start the XFS operation with @tripley-kit/xfs-client first, wait until the simulator has an active or pending IDC command, then call insertCardByLogicalService. Use runtime.listActiveCommands, runtime.listPendingCommands, and runtime.drainLogicalServiceEvents when a test needs to coordinate command completion or inspect simulator events.

Package relationship

• @tripley-kit/native: base Tripley Native capability SDK.
• @tripley-kit/xfs-client: CEN/XFS device API exposed by tripley-native-hostd.
• @tripley-kit/xfs-control-client: simulator control API for automation and test setup.

Run package verification with:

pnpm --filter @tripley-kit/xfs-control-client run verify