@tripley-kit/native

See also: USAGE.md for full cross-project integration instructions and the complete API list.

Unified TypeScript SDK for Tripley Native host capabilities. The SDK uses Tripley xRPC under the hood and can connect through a Tauri host bridge today or a WebSocket provider in browser/console mode.

import { createTauriTripleyNative, installTripleyNative } from '@tripley-kit/native';

const native = await createTauriTripleyNative();
installTripleyNative(native);

const info = await window.tripley.native.runtime.getInfo();
const displays = await window.tripley.native.display.listDisplays();

For high-frequency writes, keep a native file handle open instead of repeatedly calling appendFile:

const log = await native.fs.openFile('/logs/app.log', {
  write: true,
  append: true,
  create: true,
});

await log.write('started\n');
await log.flush();
await log.close();

Electron preload or main processes should load the packaged Node addon and inject it into the SDK:

import { createElectronTripleyNative, installTripleyNative } from '@tripley-kit/native';

const native = await createElectronTripleyNative({ addon: tripleyNativeAddon });
installTripleyNative(native);

Electron uses the browser-link window fallback unless real window and display adapters are injected from preload/main. BrowserWindow and screen access are host-owned:

const native = await createElectronTripleyNative({
  addon: tripleyNativeAddon,
  adapters: {
    window: window.tripleyElectronWindowAdapter,
    display: window.tripleyElectronDisplayAdapter,
  },
});

SQLite now supports callback transactions and raw result sets:

const result = await db.transaction(async (tx) => {
  await tx.run('insert into ledger(id, amount) values (?, ?)', [id, amount]);
  return tx.get('select balance from account where id = ?', [accountId]);
});

Standalone host daemons can be reached over WebSocket. Pass authToken when the host was started with --auth-token, and narrow requiredServices when the host binary only exposes selected services. In a normal browser, native.window.openWindow({ url }) uses a browser-link fallback: it calls window.open(url) and ignores native-only bounds, display, and always-on-top options so Vite/dev-server projects can run against tripley-native-hostd without a Tauri or Electron shell:

import { createWebSocketTripleyNative } from '@tripley-kit/native';

const native = createWebSocketTripleyNative({
  url: 'ws://127.0.0.1:39010',
  authToken: 'local-dev-token',
  requiredServices: ['fs'],
});

await native.connect();
await native.fs.exists('/logs/app.log');
await native.window.openWindow({ url: 'http://localhost:5173/report' });

Verify and Package

pnpm --filter @tripley-kit/native run verify

The package publishes the generated dist directory and this README. dist is built during prepublishOnly and is not required to be checked into the repository.

Related Packages

@tripley-kit/xfs-client provides the optional CEN/XFS device API, and @tripley-kit/xfs-control-client provides simulator control APIs for XFS automation tests. They are split from @tripley-kit/native because most native-capability consumers do not need the XFS surface area.