Class ReceiveTransfer

A file transfer in the receiving direction.

Created when a remote offer arrives (see FileTransferEvent.IncomingOffer). The application inspects ReceiveTransfer.metadata and then calls ReceiveTransfer.accept with a StorageSink — or ReceiveTransfer.reject to decline. Once accepted, framed chunks arriving on the data channel(s) are decoded, deduplicated, hashed (when checksums are enabled), and written to the sink at their byte offset. When the sender signals it is done and every chunk has been received, the digest is verified, the sink is closed, and the resulting SinkResult is exposed via ReceiveTransfer.result.

Example

manager.on('incoming-offer', (transfer) => {
    console.log(`incoming ${transfer.fileName} (${transfer.metadata.size} bytes)`)
    transfer.accept(new MemorySink())
    transfer.on('complete', () => {
        const blob = transfer.result?.blob
    })
})

Hierarchy (View Summary)

Transfer
- ReceiveTransfer

Index

Constructors

constructor

new ReceiveTransfer(params: ReceiveTransferParams): ReceiveTransfer
Parameters
- params: ReceiveTransferParams
  Offer-derived parameters; see ReceiveTransferParams. The transfer starts in TransferState.Offered, awaiting ReceiveTransfer.accept.
Returns ReceiveTransfer
Overrides Transfer.constructor
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:73

Properties

`Protected`_state

_state: TransferState = TransferState.Idle

Current lifecycle state.

`Protected`_transferredBytes

_transferredBytes: number = 0

Bytes transferred so far.

`Protected`_transferredChunks

_transferredChunks: number = 0

Chunks transferred so far.

`Protected` `Readonly`chunkSize

chunkSize: number

Payload bytes per chunk.

`Readonly`direction

direction: "receive" = TransferDirection.Receive

Always TransferDirection.Receive.

`Readonly`id

id: string

Unique identifier shared by both peers for this transfer.

`Readonly`metadata

metadata: FileMetadata

Name, MIME type, and size of the file being transferred.

`Readonly`peerId

peerId: string

Identifier of the remote peer participating in this transfer.

`Protected` `Readonly`totalChunks

totalChunks: number

Total number of chunks the file is divided into.

Accessors

fileName

get fileName(): string
Convenience accessor for the offered file name (equivalent to metadata.name).

Returns string
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:130

isTerminal

get isTerminal(): boolean
true once the transfer has reached a terminal state (completed, failed, or cancelled).

Returns boolean
Inherited from Transfer.isTerminal
- Defined in packages/sdk/src/filetransfer/Transfer.ts:107

result

get result(): SinkResult | null
The sink's finalized output (blob, byte array, and/or path), or null until the transfer reaches TransferState.Completed.

Returns SinkResult | null
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:138

state

get state(): TransferState
The current lifecycle state of the transfer.

Returns TransferState
Inherited from Transfer.state
- Defined in packages/sdk/src/filetransfer/Transfer.ts:102

Methods

`Protected`_notifyRemoteFailure

_notifyRemoteFailure(error: FileTransferError): void
Hook invoked by Transfer.fail when a local failure must be signalled to the remote peer. Overridden by the concrete subclasses to send a cancel over the control channel; a no-op by default.
Parameters
- error: FileTransferError
Returns void
Overrides Transfer._notifyRemoteFailure
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:86

`Protected`_onTerminal

_onTerminal(): void
Hook invoked once when the transfer first reaches a terminal state (completed/failed/cancelled). Subclasses override it to release resources — close per-transfer data channels, drain any suspended workers, clear timers.

Returns void
Overrides Transfer._onTerminal
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:113

accept

accept(sink: StorageSink): void
Accepts the offer and begins receiving into sink.

Opens the sink, transitions the transfer to active, and sends an accept control message (including any chunks already buffered, to support resume). If the transfer is not in TransferState.Offered, or the sink fails to open, the transfer fails instead.
Parameters
- sink: StorageSink
  Destination the received bytes are written to (for example MemorySink).
Returns void
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:151

attachChannel

attachChannel(channel: RTCDataChannel): void
Binds an inbound binary data channel to this transfer and starts consuming framed chunks from it. Called by FileTransferManager as the sender's parallel channels open; may be invoked multiple times (once per parallel channel).
Parameters
- channel: RTCDataChannel
  The data channel carrying framed chunk payloads for this transfer.
Returns void
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:198

cancel

cancel(reason?: string): void
Cancels the transfer, notifying the sender and aborting the sink. No-op if already terminal.
Parameters
- Optionalreason: string
  Optional reason; when provided, surfaced via TransferEvent.Error.
Returns void
Overrides Transfer.cancel
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:253

emit

emit<K extends keyof TransferEvents>(
event: K,
...args: TransferEvents[K],
): boolean
Synchronously invokes every listener registered for event, in registration order.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name to emit.
- ...args: TransferEvents[K]
  The argument tuple to pass to each listener, matching Events[event].
Returns boolean
true if at least one listener was invoked, false if there were none.

Remarks
The listener list is snapshotted before dispatch, so mutations made by handlers take effect only on subsequent emissions. Listeners are isolated: if one throws, the remaining listeners still run and the error is surfaced via console.error rather than swallowed silently (consistent with LocalMessageBus).
Inherited from Transfer.emit
- Defined in packages/core/src/EventEmitter.ts:95

`Protected`emitProgress

emitProgress(): void
Emits a TransferEvent.Progress event with the current snapshot.

Returns void
Inherited from Transfer.emitProgress
- Defined in packages/sdk/src/filetransfer/Transfer.ts:136

`Protected`fail

fail(error: FileTransferError, notifyRemote?: boolean): FileTransferError
Transitions the transfer to TransferState.Failed and emits TransferEvent.Error. No-op if the transfer is already terminal.
Parameters
- error: FileTransferError
  The error describing the failure.
- notifyRemote: boolean = false
Returns FileTransferError
The same error, for convenient throw/return chaining.
Inherited from Transfer.fail
- Defined in packages/sdk/src/filetransfer/Transfer.ts:177

handleControl

handleControl(
    msg:
        | {
            checksum: boolean;
            chunkSize: number;
            mimeType: string;
            name: string;
            parallelChannels: number;
            size: number;
            totalChunks: number;
            transferId: string;
            type: "ft-offer";
            version?: number;
        }
        | { haveChunks?: number[]; transferId: string; type: "ft-accept" }
        | { reason?: string; transferId: string; type: "ft-reject" }
        | { haveChunks: number[]; transferId: string; type: "ft-resume-request" }
        | { digest?: string; transferId: string; type: "ft-sent" }
        | { transferId: string; type: "ft-complete" }
        | { transferId: string; type: "ft-checksum-mismatch" }
        | { reason?: string; transferId: string; type: "ft-cancel" }
        | { transferId: string; type: "ft-pause" }
        | { transferId: string; type: "ft-resume" },
): void
Processes an inbound control message from the sender. A sent message records the sender-computed digest and marks the stream complete (triggering finalization once all chunks have arrived); a cancel aborts the transfer. Routed here by FileTransferManager.
Parameters
- msg:
      | {
          checksum: boolean;
          chunkSize: number;
          mimeType: string;
          name: string;
          parallelChannels: number;
          size: number;
          totalChunks: number;
          transferId: string;
          type: "ft-offer";
          version?: number;
      }
      | { haveChunks?: number[]; transferId: string; type: "ft-accept" }
      | { reason?: string; transferId: string; type: "ft-reject" }
      | { haveChunks: number[]; transferId: string; type: "ft-resume-request" }
      | { digest?: string; transferId: string; type: "ft-sent" }
      | { transferId: string; type: "ft-complete" }
      | { transferId: string; type: "ft-checksum-mismatch" }
      | { reason?: string; transferId: string; type: "ft-cancel" }
      | { transferId: string; type: "ft-pause" }
      | { transferId: string; type: "ft-resume" }
  The decoded control message.
  - {
        checksum: boolean;
        chunkSize: number;
        mimeType: string;
        name: string;
        parallelChannels: number;
        size: number;
        totalChunks: number;
        transferId: string;
        type: "ft-offer";
        version?: number;
    }
    checksum: boolean
    chunkSize: number
    mimeType: string
    name: string
    parallelChannels: number
    size: number
    totalChunks: number
    transferId: string
    type: "ft-offer"
    Optionalversion?: number
    Protocol version of the sender; see FT_PROTOCOL_VERSION. Optional for back-compat.
  - { haveChunks?: number[]; transferId: string; type: "ft-accept" }
  - { reason?: string; transferId: string; type: "ft-reject" }
  - { haveChunks: number[]; transferId: string; type: "ft-resume-request" }
  - { digest?: string; transferId: string; type: "ft-sent" }
  - { transferId: string; type: "ft-complete" }
  - { transferId: string; type: "ft-checksum-mismatch" }
  - { reason?: string; transferId: string; type: "ft-cancel" }
  - { transferId: string; type: "ft-pause" }
  - { transferId: string; type: "ft-resume" }
Returns void
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:213

listenerCount

listenerCount<K extends keyof TransferEvents>(event: K): number
Returns the number of listeners currently registered for event.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name to count listeners for.
Returns number
The count of registered listeners (0 if none).
Inherited from Transfer.listenerCount
- Defined in packages/core/src/EventEmitter.ts:128

off

off<K extends keyof TransferEvents>(
event: K,
listener: (...args: TransferEvents[K]) => void,
): this
Removes a previously registered listener for event.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name the listener was registered for.
- listener: (...args: TransferEvents[K]) => void
  The exact function reference passed to on or once.
Returns this
This emitter, for chaining.

Remarks
If the listener is not currently registered, this is a no-op. Only the first matching registration is removed.
Inherited from Transfer.off
- Defined in packages/core/src/EventEmitter.ts:74

on

on<K extends keyof TransferEvents>(
event: K,
listener: (...args: TransferEvents[K]) => void,
): this
Registers a listener that is invoked every time event is emitted.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: TransferEvents[K]) => void
  Callback invoked with the event's argument tuple.
Returns this
This emitter, for chaining.
Inherited from Transfer.on
- Defined in packages/core/src/EventEmitter.ts:43

once

once<K extends keyof TransferEvents>(
event: K,
listener: (...args: TransferEvents[K]) => void,
): this
Registers a listener that is invoked at most once: it is removed automatically before being called the first time event is emitted.
Type Parameters
- K extends keyof TransferEvents
Parameters
- event: K
  The event name to listen for.
- listener: (...args: TransferEvents[K]) => void
  Callback invoked with the event's argument tuple on the next emission.
Returns this
This emitter, for chaining.

Remarks
Remove a pending one-time listener by passing the same function reference to off.
Inherited from Transfer.once
- Defined in packages/core/src/EventEmitter.ts:57

pause

pause(): void
Requests that the sender pause streaming and notifies it. No-op unless the transfer is TransferState.Active.

Returns void
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:230

progress

progress(): TransferProgress
Returns a point-in-time TransferProgress snapshot.

Returns TransferProgress
Current byte/chunk counts and completion ratio (ratio is 0 for zero-byte files).
Inherited from Transfer.progress
- Defined in packages/sdk/src/filetransfer/Transfer.ts:123

reject

reject(reason?: string): void
Declines the offer, notifying the sender. No-op unless the transfer is TransferState.Offered.
Parameters
- Optionalreason: string
  Optional human-readable reason relayed to the sender.
Returns void
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:185

removeAllListeners

removeAllListeners(event?: keyof TransferEvents): this
Removes listeners for a single event, or for all events.
Parameters
- Optionalevent: keyof TransferEvents
  The event name to clear; if omitted, listeners for every event are removed.
Returns this
This emitter, for chaining.
Inherited from Transfer.removeAllListeners
- Defined in packages/core/src/EventEmitter.ts:116

requestResume

requestResume(): void
Ask the sender to resume, reporting the chunks already received so only the missing ones are resent. Invoked by FileTransferManager when the sender re-announces an in-progress transfer after a reconnect. No-op if the transfer is terminal or has not yet been accepted.

Returns void
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:104

resume

resume(): void
Requests that the sender resume streaming and notifies it. No-op unless the transfer is TransferState.Paused.

Returns void
- Defined in packages/sdk/src/filetransfer/ReceiveTransfer.ts:241

`Protected`toTransferError

toTransferError(
    err: unknown,
    code: FileTransferErrorCode,
    message?: string,
): FileTransferError
Normalizes an unknown thrown value into a FileTransferError tagged with this transfer's id, passing through existing FileTransferErrors unchanged.
Parameters
- err: unknown
  The caught value.
- code: FileTransferErrorCode
  The FileTransferErrorCode to assign when wrapping.
- Optionalmessage: string
  Optional override message; otherwise derived from err.
Returns FileTransferError
A FileTransferError suitable for Transfer.fail.
Inherited from Transfer.toTransferError
- Defined in packages/sdk/src/filetransfer/Transfer.ts:205

`Protected`transitionTo

transitionTo(next: TransferState): boolean
Attempts a state transition, enforcing the legal-transition table.
Parameters
- next: TransferState
  The state to move to.
Returns boolean
true if the transition occurred (or was a no-op because already in next); false if the transfer is already terminal or the transition is illegal. Transitions to TransferState.Failed and TransferState.Cancelled are always permitted from any non-terminal state.
Inherited from Transfer.transitionTo
- Defined in packages/sdk/src/filetransfer/Transfer.ts:149

Class ReceiveTransfer

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns ReceiveTransfer

Properties

Protected_state

Protected_transferredBytes

Protected_transferredChunks

Protected ReadonlychunkSize

Readonlydirection

Readonlyid

Readonlymetadata

ReadonlypeerId

Protected ReadonlytotalChunks

Accessors

fileName

Returns string

isTerminal

Returns boolean

result

Returns SinkResult | null

state

Returns TransferState

Methods

Protected_notifyRemoteFailure

Parameters

Returns void

Protected_onTerminal

Returns void

accept

Parameters

Returns void

attachChannel

Parameters

Returns void

cancel

Parameters

Returns void

emit

Type Parameters

Parameters

Returns boolean

Remarks

ProtectedemitProgress

Returns void

Protectedfail

Parameters

Returns FileTransferError

handleControl

Parameters

checksum: boolean

chunkSize: number

mimeType: string

name: string

parallelChannels: number

size: number

totalChunks: number

transferId: string

type: "ft-offer"

Optionalversion?: number

Returns void

listenerCount

Type Parameters

Parameters

Returns number

off

Type Parameters

Parameters

Returns this

Remarks

on

Type Parameters

`Protected`_state

`Protected`_transferredBytes

`Protected`_transferredChunks

`Protected` `Readonly`chunkSize

`Readonly`direction

`Readonly`id

`Readonly`metadata

`Readonly`peerId

`Protected` `Readonly`totalChunks

`Protected`_notifyRemoteFailure

`Protected`_onTerminal

`Protected`emitProgress

`Protected`fail

`Optional`version?: number

`Protected`toTransferError

`Protected`transitionTo