Expose real byte-level progress in uploadToSynapse callbacks

[HavenCTO]

Context / Problem

When calling uploadToSynapse, the progress reporting is limited to high-level milestone events (e.g., onUploadComplete, onPieceAdded). While the underlying synapse-core SDK provides real-time, byte-level upload progress via an onProgress callback, this information is not exposed or passed through by filecoin-pin. This prevents consumers from implementing accurate progress bars during the data transfer phase, as bytesUploaded remains unknown until the upload finishes.

Current Implementation

filecoin-pin/src/core/upload/synapse.ts

Line 93 in f15bba4

onProgress?.({ type: 'onUploadComplete', data: { pieceCid } })

filecoin-pin/src/core/upload/synapse.ts currently only maps lifecycle callbacks:

const uploadCallbacks: UploadCallbacks = {
  onUploadComplete: (pieceCid) => { ... },
  onPieceAdded: (txHash) => { ... },
  onPieceConfirmed: (pieceIds) => { ... },
  // onProgress: ??? // ✗ NOT PASSED!
};

The SDK's onProgress(bytesUploaded) callback is completely ignored, leaving a gap in telemetry during the actual network transfer.

The SDK Provides Real Progress

https://github.com/FilOzone/synapse-sdk/blob/4be67a838c5b602608b3ac33f9702c1343f87e09/packages/synapse-core/src/sp.ts#L523
File: synapse-sdk/packages/synapse-core/src/sp.ts (line ~520)
The lowest layer already tracks real progress:

let bytesUploaded = 0
const trackingStream = new TransformStream<Uint8Array, Uint8Array>({
  transform(chunk, controller) {
    bytesUploaded += chunk.length
    if (options.onProgress) {
      options.onProgress(bytesUploaded) // Real bytes uploaded!
    }
    controller.enqueue(chunk)
  },
})

File: synapse-sdk/packages/synapse-sdk/src/types.ts
The UploadCallbacks interface supports this:

export interface UploadCallbacks {
  /** Called periodically during upload with bytes uploaded so far */
  onProgress?: (bytesUploaded: number) => void
  onUploadComplete?: (pieceCid: PieceCID) => void
  // ...
}

Requested Changes

Update uploadToSynapse to accept and forward the onProgress callback from the underlying SDK.

1. Update Callback Interface: Extend the options or callbacks argument in uploadToSynapse to accept a progress handler.
2. Forward to SDK: Ensure the onProgress callback is passed to UploadCallbacks when calling the SDK, so it receives the bytesUploaded updates.

Suggested Implementation:

// In uploadToSynapse(), add:
const uploadCallbacks: UploadCallbacks = {
  onProgress: (bytesUploaded) => {
    // Expose real progress to caller
    onProgress?.({ type: 'onProgress', data: { bytesUploaded } })
  },
  onUploadComplete: (pieceCid) => { ... },
  // ...
};

Why This Matters

Without access to onProgress, integrations cannot accurately report transfer status to users. Progress bars either jump from 0% to 100% upon completion or rely on synthetic phase markers (e.g., "uploading..."), which degrades the user experience for file uploads.

Environment / Repro

• Client: Integration using filecoin-pin to track upload progress.
• Scenario: Uploading a CAR file (100MiB).
• Current Behavior: onUploadComplete fires only at the end. No intermediate events are received.
• Desired Behavior: Receive periodic updates with bytesUploaded during the transfer to render a smooth progress bar.

Thanks for considering—happy to test a callback implementation and provide feedback.

[BigLep]

Thanks @HavenCTO - the usecase make sense to me.

@SgtPooki @rvagg : any feedback on the API is welcome so we can make sure this is ready for someone to pick up.

[SgtPooki]

it should be super simple for someone to add this, and I'm all for adding it. Just haven't been able to focus on filecoin-pin for a while.

Maybe we can create a more explicit name since we use onProgress for generic stuff in filecoinPin: `onBytesProgress" or "onBytesUploaded"

[rvagg]

Same comment from me as #325 (comment)

[rvagg]

just please wait until FilOzone/synapse-sdk#593 is finally merged and released