feat!: improve UploadResult ergonomics (#664)

Author: rvagg

AGENTS.md

@@ -123,7 +123,7 @@ Client ──store──> Primary SP (endorsed)
 
 ### Failure Handling
 
-`UploadResult` returns `copies[]` (successful) and `failures[]` (failed). Primary failure is fatal; secondary failures are reported but non-fatal. `StoreError` and `CommitError` (in `errors/storage.ts`) carry providerId and cause chain.
+`UploadResult` returns `complete` (boolean), `copies[]` (successful), and `failedAttempts[]` (intermediate failures). Check `complete` to determine overall success -- do not use `failedAttempts.length` as a failure signal. Primary store failure throws `StoreError`; all commits failing throws `CommitError`. Both carry providerId and cause chain.
 
 ## Session Keys
 
@@ -194,14 +194,15 @@ Ref: FRC-0069
 // Simple: auto-managed multi-copy upload
 const synapse = await Synapse.create({ privateKey, rpcUrl })
 const result = await synapse.storage.upload(data)
+// result.complete === true means all requested copies succeeded
 // result.copies = [{ providerId, dataSetId, pieceId, role: 'primary'|'secondary' }]
-// result.failures = [{ providerId, error, role }]
+// result.failedAttempts = [{ providerId, error, role }] (non-empty does NOT mean failure)
 
 // Download (SP-agnostic, tries all known providers)
 const bytes = await synapse.storage.download({ pieceCid })
 
 // Explicit contexts for fine-grained control
-const [primary, secondary] = await synapse.storage.createContexts({ count: 2 })
+const [primary, secondary] = await synapse.storage.createContexts({ copies: 2 })
 const stored = await primary.store(data)            // Upload, get PieceCID
 const extraData = await secondary.presignForCommit([{ pieceCid: stored.pieceCid }])
 await secondary.pull({                               // SP-to-SP transfer

docs/src/content/docs/developer-guides/storage/storage-context.mdx

@@ -69,7 +69,7 @@ await synapse.storage.createContext({
 
 // Multiple contexts for multi-copy
 const contexts = await synapse.storage.createContexts({
-  count: 3,                     // number of contexts (default: 2)
+  copies: 3,                   // number of contexts (default: 2)
   providerIds: [1n, 2n, 3n],   // specific providers (mutually exclusive with dataSetIds)
   dataSetIds: [10n, 20n, 30n], // specific data sets (mutually exclusive with providerIds)
 })
@@ -132,7 +132,7 @@ const abortController = new AbortController()
 const preCalculatedCid = null as unknown as PieceCID;
 // ---cut---
 const contexts = await synapse.storage.createContexts({
-  count: 2,
+  copies: 2,
 })
 const [primary, secondary] = contexts
 
@@ -166,7 +166,7 @@ import { privateKeyToAccount } from "viem/accounts"
 
 const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const [primary, secondary] = await synapse.storage.createContexts({
-      count: 2,
+      copies: 2,
   metadata: { source: "my-app" },
 })
 const pieceCid = null as unknown as PieceCID;
@@ -209,7 +209,7 @@ import { privateKeyToAccount } from "viem/accounts"
 import type { Hex } from "viem";
 const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source: "my-app" })
 const contexts = await synapse.storage.createContexts({
-      count: 2,
+      copies: 2,
   metadata: { source: "my-app" },
 })
 const [primary, secondary] = contexts
@@ -270,7 +270,7 @@ const files = [
 
 // Create contexts for 2 providers
 const [primary, secondary] = await synapse.storage.createContexts({
-  count: 2,
+  copies: 2,
   metadata: { source: "batch-upload" },
 })
 
@@ -575,7 +575,7 @@ const client = synapse.client;
 const walletAddress = client.account.address;
 
 const [primary, secondary] = await synapse.storage.createContexts({
-  count: 2,
+  copies: 2,
   metadata: { source: "my-app" },
 })
 const pieceCid = null as unknown as PieceCID;

docs/src/content/docs/developer-guides/storage/storage-operations.mdx

@@ -46,7 +46,7 @@ const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source:
 
 const data = new Uint8Array([1, 2, 3, 4, 5])
 
-const { pieceCid, size, copies, failures } = await synapse.storage.upload(data)
+const { pieceCid, size, complete, copies, failedAttempts } = await synapse.storage.upload(data)
 
 console.log("PieceCID:", pieceCid.toString())
 console.log("Size:", size, "bytes")
@@ -56,21 +56,23 @@ for (const copy of copies) {
   console.log(`  Provider ${copy.providerId}: role=${copy.role}, dataSet=${copy.dataSetId}`)
 }
 
-if (failures.length > 0) {
-  console.warn("Some copies failed:", failures)
+if (!complete) {
+  console.warn("Some copies failed:", failedAttempts)
 }
 ```
 
 :::caution[Always check the result]
-`upload()` returns a result as long as **at least one** copy commits on-chain. It only throws when zero copies succeed. You **must** inspect `copies` and `failures` to know whether all requested copies were stored — a successful return does not guarantee all copies succeeded.
+`upload()` returns a result as long as **at least one** copy commits on-chain. It only throws when zero copies succeed. You **must** check `complete` to know whether all requested copies were stored — a successful return does not guarantee all copies succeeded.
 :::
 
 The result contains:
 
+- **`complete`** — `true` when all requested copies were stored and committed on-chain. This is the primary field to check.
+- **`requestedCopies`** — the number of copies that were requested (default: 2)
 - **`pieceCid`** — content address of your data, used for downloads
 - **`size`** — size of the uploaded data in bytes
 - **`copies`** — array of successful copies, each with `providerId`, `dataSetId`, `pieceId`, `role` (`'primary'` or `'secondary'`), `retrievalUrl`, and `isNewDataSet`
-- **`failures`** — array of failed copy attempts (partial failures are returned, not thrown), each with `providerId`, `role`, `error`, and `explicit`
+- **`failedAttempts`** — providers that were tried but did not produce a copy. The SDK retries failed secondaries with alternate providers, so a non-empty array often just means a provider was swapped out. These are diagnostic, check `complete` for the actual outcome.
 
 #### Upload with Metadata
 
@@ -183,11 +185,11 @@ const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source:
 const data = new Uint8Array(256)
 
 // Store 3 copies for higher redundancy
-const result3 = await synapse.storage.upload(data, { count: 3 })
+const result3 = await synapse.storage.upload(data, { copies: 3 })
 console.log("3 copies:", result3.copies.length)
 
 // Store a single copy when redundancy isn't needed
-const result1 = await synapse.storage.upload(data, { count: 1 })
+const result1 = await synapse.storage.upload(data, { copies: 1 })
 console.log("1 copy:", result1.copies.length)
 ```
 
@@ -220,23 +222,16 @@ const synapse = Synapse.create({ account: privateKeyToAccount("0x..."), source:
 
 const data = new Uint8Array(256)
 
-const result = await synapse.storage.upload(data, { count: 2 })
+const result = await synapse.storage.upload(data, { copies: 2 })
 
-// Check: did we get all requested copies?
-if (result.copies.length < 2) {
-  console.warn(`Only ${result.copies.length}/2 copies succeeded`)
-  for (const failure of result.failures) {
-    console.warn(`  Provider ${failure.providerId} (${failure.role}): ${failure.error}`)
+// Check overall success: complete === true means all requested copies succeeded
+if (!result.complete) {
+  console.warn(`Only ${result.copies.length}/${result.requestedCopies} copies succeeded`)
+  for (const attempt of result.failedAttempts) {
+    console.warn(`  Provider ${attempt.providerId} (${attempt.role}): ${attempt.error}`)
   }
 }
 
-// Check: did the endorsed primary succeed?
-const primaryFailed = result.failures.find(f => f.role === "primary")
-if (primaryFailed) {
-  console.warn(`Endorsed provider failed: ${primaryFailed.error}`)
-  // Data is only on non-endorsed secondaries
-}
-
 // Every copy is committed and being paid for
 for (const copy of result.copies) {
   console.log(`Provider ${copy.providerId}, dataset ${copy.dataSetId}, piece ${copy.pieceId}`)

docs/src/content/docs/getting-started/index.mdx

@@ -104,12 +104,12 @@ async function main() {
   }
 
   // 3) Upload — stores 2 copies across independent providers for durability
-  const { pieceCid, size, copies, failures } = await synapse.storage.upload(file)
+  const { pieceCid, size, complete, copies, failedAttempts } = await synapse.storage.upload(file)
   console.log(`✅ Upload complete!`);
   console.log(`PieceCID: ${pieceCid}`);
   console.log(`Size: ${size} bytes`);
   console.log(`Stored on ${copies.length} providers`);
-  if (failures.length > 0) console.warn(`${failures.length} copy attempt(s) failed`);
+  if (!complete) console.warn(`${failedAttempts.length} copy attempt(s) failed`);
 
   // 4) Download
   const bytes = await synapse.storage.download({ pieceCid })
@@ -205,9 +205,9 @@ const file = new TextEncoder().encode(
     🌍 You need to make sure to meet the minimum size
     requirement of 127 bytes per upload.`
 );
-const { pieceCid, copies, failures } = await synapse.storage.upload(file);
+const { pieceCid, complete, copies, failedAttempts } = await synapse.storage.upload(file);
 console.log(`Stored on ${copies.length} providers`);
-if (failures.length > 0) console.warn(`${failures.length} copy attempt(s) failed`);
+if (!complete) console.warn(`${failedAttempts.length} copy attempt(s) failed`);
 
 // Download data from any provider that has it
 const downloadedData = await synapse.storage.download({ pieceCid });

packages/synapse-sdk/src/storage/context.ts

@@ -244,7 +244,7 @@ export class StorageContext {
 
     if (resolutions.length > 0) {
       // Explicit path — validate count matches deduped results
-      const count = options.count ?? resolutions.length
+      const count = options.copies ?? resolutions.length
       if (resolutions.length !== count) {
         throw createError(
           'StorageContext',
@@ -266,7 +266,7 @@ export class StorageContext {
       }
     } else {
       // Smart selection path (neither dataSetIds nor providerIds provided)
-      const count = options.count ?? 2
+      const count = options.copies ?? 2
       resolutions = await StorageContext.smartSelect({
         synapse: options.synapse,
         metadata: options.metadata ?? {},
@@ -944,6 +944,8 @@ export class StorageContext {
     return {
       pieceCid: storeResult.pieceCid,
       size: storeResult.size,
+      requestedCopies: 1,
+      complete: true,
       copies: [
         {
           providerId: this._provider.id,
@@ -954,7 +956,7 @@ export class StorageContext {
           isNewDataSet: commitResult.isNewDataSet,
         },
       ],
-      failures: [],
+      failedAttempts: [],
     }
   }