feat: migrate callback API to onProgress with typed responses

[SgtPooki]

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

Lines 185 to 189 in 300ecd5

	progressCallbacks?: {
	onProviderSelected?: (provider: any) => void
	onDataSetCreationStarted?: (transaction: any) => void
	onDataSetResolved?: (info: { dataSetId: number; isExisting: boolean }) => void
	}

Instead of surfacing the granularity of callbacks that exist in synapse-sdk, we should allow consumers to pass an onProgress handler that receives an event for any of the callbacks. Similar to what we have in checkUploadReadiness:

/**
 * Options for evaluating whether an upload can proceed.
 */
export type UploadReadinessProgressEvent =
  | { type: 'checking-balances' }
  | { type: 'checking-allowances' }
  | { type: 'configuring-allowances' }
  | { type: 'allowances-configured'; transactionHash?: string }
  | { type: 'validating-capacity' }

export interface UploadReadinessOptions {
  /** Initialized Synapse instance. */
  synapse: Synapse
  /** Size of the CAR file (bytes). */
  fileSize: number
  /**
   * Automatically configure allowances when they are missing.
   * Defaults to `true` to match current CLI/action behaviour.
   */
  autoConfigureAllowances?: boolean
  /** Optional callback for progress updates. */
  onProgress?: (event: UploadReadinessProgressEvent) => void
}

what do you think @rvagg ?

[rvagg]

Yes, but also I think maybe we should backport this style to Synapse. When we combine CreateDataSet and AddPieces then we're going to get into trouble with the existing callbacks. Background here: FilOzone/synapse-sdk#264 (comment)

We could certainly experiment here and backport later. Or, since we want multi-party upload in Synapse to work well we might get there first.

[BigLep]

2025-10-30 maintainer conversation: this will be a major version breaking change and thus should make it in for v1.