Add public PieceCID/CommP helper and top-level API for uploads

[HavenCTO]

Context / Problem

When uploading via executeUpload, PDP upload requires a valid PieceCID. The current SDK surface doesn’t expose a public helper to derive PieceCID/CommP from a CAR.

In our Electron app, we’re generating a CAR client-side and using filecoin-pin’s Synapse-based flow. StorageContext doesn’t expose any piece/comm helpers, so we can’t supply pieceCid and the upload fails with Invalid PieceCID: undefined.

Upstream guidance (see filecoin-pin #278) discourages instantiating Synapse internals directly; we want a supported API instead of reaching into private classes.

Requested Changes

1. Provide a public helper (e.g., getPieceCidFromCar(carPath|Uint8Array) or similar) that: a. Accepts a CAR (path or bytes) b. Returns PieceCID (CommP) and padded piece size c. Is callable without instantiating internal classes
2. Surface this helper via the top-level filecoin-pin API (or Synapse SDK) so downstream apps can pass pieceCid into executeUpload.
3. Document expected inputs/outputs and any constraints (e.g., CAR must be UnixFS-wrapped, size limits).

Why This Matters

• Without a public PieceCID helper, downstream clients must vendor their own CommP computation or reach into SDK internals, which conflicts with the direction in backport: remove all custom class instantiation of synapse-sdk classes #278 to avoid custom instantiation.
• A supported API enables reliable uploads (PDP) across environments where Go/Rust commp tooling isn’t available.

Environment / Repro

Upstream project : https://github.com/Haven-hvn/haven-player
Related issue : filecoin-project/filecoin-pin-website#134

Client: Electron app using filecoin-pin (Synapse SDK) to build a CAR and call executeUpload.
Result: StorageContext uploadPiece failed: Invalid PieceCID: undefined because pieceCid can’t be produced from public APIs.

Suggested API Shape (example)

// synchronous or async
const { pieceCid, paddedPieceSize } = await getPieceCidFromCar({
  carPath: string // or carBytes: Uint8Array
});

Thanks for considering—happy to test a draft API and provide feedback.