Send files directly between devices over the internet - no cloud storage, no size limits.
@altersend/domain
State management for AlterSend's P2P file transfer flow. Translates worklet events into a typed Zustand store and exposes commands the UI calls directly.
Used by both the mobile and desktop apps so they share one source of truth for transfer state.
Install
npm install @altersend/domain
Peer dependencies (you must install these in your app):
npm install react zustand
Quick start
At app entry — once, before any component mounts:
import { bindTransferApi } from '@altersend/domain'
import { mobileApi } from './api' // your platform's TransferApi implementation
bindTransferApi(mobileApi, {
onError: (context, err) => Sentry.captureException(err, { tags: { context } })
})
In a component:
import { useTransferStore, joinSession, clearSession } from '@altersend/domain'
function ReceiveButton() {
const role = useTransferStore((s) => s.role)
const peerCount = useTransferStore((s) => s.peerCount)
if (role === 'receiver') {
return <button onClick={clearSession}>End session</button>
}
return <button onClick={() => joinSession('topic-key')}>Join</button>
}
Architecture
worklet events ──► bindTransferApi ──► reducer ──► store
│
▼
useTransferStore
▲
UI ────────────► commands ──► dispatchToTransferStore
│
└──► worker RPC (worklet)
- store holds
TransferSessionState— one source of truth. - reducer is a pure
(state, action) → statefunction. No side effects. - commands are imperative functions UI calls. They dispatch state changes and proxy worker RPCs.
- binding is the worklet adapter — installs event subscriptions, wires
bindTransferApi. - effects are module-level subscribers (peer watchdog, background reconnect).
Public API
Setup
bindTransferApi(api, options?)— wire the platformTransferApiinto the store.TransferApi— the interface mobile/desktop implement.BindTransferApiOptions—{ onError?: (context, error) => void }.
State
useTransferStore(selector)— React hook.transferStore— module-level store (use.getState()/.subscribe()).dispatchToTransferStore(action)— dispatch aTransferAction.TransferSessionState,TransferAction,TransferRole— types.
Commands
joinSession(topic)/startSendSession()/clearSession()shareFiles(files)/downloadFiles(files)addSelectedFiles(files)/removeSelectedFile(path)/continueShare(files)/clearSenderFlow()
Remembered devices (pairing)
hostPairingSession()/joinPairingSession(topic)— pair via QR / coderequestPair(transferId, peerKey)/rememberVote(input)— pair a connected peerinviteDevice(input)/respondToInvite(input)— code-free invites to remembered devicesloadPeers()/forgetPeer(pubkey)— list / remove remembered devicesusePairingSession(options)— React hook driving the pairing & devices UI
Effects (mobile-only setup)
startPeerWatchdog()— firespeer_unreachableafter a connection grace period.startBackgroundReconnectEffect()— marksreconnectingwhen the app backgrounds mid-receive.setAppActive(active)— drive fromAppState(mobile). Desktop ignores it.
Receive-specific helpers
getOfferKey,getDownloadTotals,createSingleDownloadRequest,createDirectoryDownloadRequests,applyDownloadRouted.getReceivePageCopy,getReceiveStep,isSessionOverStep— receive-page view-model helpers.
Send-specific helpers
getSendStep,getSendPageCopy,getStatusLabel,getStatusTone,getProgressState,normalizeSelectedFiles.
Generic utilities
formatFileSize,getParentDir,shortenHomePath.
Error handling
bindTransferApi accepts an optional onError callback. It receives every error that bubbles out of a command catch block or the boot RPC, with a stable context string identifying the call site:
bindTransferApi(api, {
onError: (context, error) => {
Sentry.captureException(error, { tags: { context } })
}
})
Without onError, errors fall back to console.error. The store still receives the corresponding set_error / join_failed / boot_failed action either way — so the UI's error banner keeps working regardless of the integration.
License
Apache-2.0