chore: deprecate piece metadata getters

Signed-off-by: Jakub Sztandera <oss@kubuxu.com>

Author: Kubuxu

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

@@ -240,6 +240,9 @@ console.log(`Found ${pieces.length} pieces`);
 ### Getting Piece Metadata
 
 Access custom metadata attached to individual pieces:
+:::caution[Deprecated]
+Piece metadata getters are deprecated and will be removed from Synapse SDK packages. Read metadata from `PieceAdded` events or an indexer instead. Passing piece metadata when uploading or committing remains supported so providers can include it in those events.
+:::
 
 ```ts twoslash
 // @lib: esnext,dom

docs/src/content/docs/developer-guides/synapse-react.mdx

@@ -186,4 +186,8 @@ const StorageExample = () => {
 };
 ```
 
+:::caution[Deprecated]
+The `metadata` field returned for each piece by `useDataSets()` depends on deprecated FWSS piece metadata getters and will be removed. Read piece metadata from `PieceAdded` events or an indexer instead.
+:::
+
 Check out the [Synapse React Reference](/reference/filoz/synapse-react/toc/) for all available query and mutation hooks.

packages/synapse-core/src/pdp-verifier/get-pieces.ts

@@ -155,6 +155,8 @@ export namespace getPiecesWithMetadata {
  * fewer or no visible items. Treat `nextCursor` as opaque and use
  * {@link paginate} to traverse every page.
  *
+ * @deprecated FWSS piece metadata getters are being removed. Use {@link getPieces} and read metadata from `PieceAdded` events or an indexer instead.
+ *
  * @example Read the first page
  * ```ts
  * import { getPiecesWithMetadata } from '@filoz/synapse-core/pdp-verifier'

packages/synapse-core/src/warm-storage/get-all-piece-metadata.ts

@@ -37,6 +37,7 @@ export namespace getAllPieceMetadata {
 /**
  * Get all metadata for a piece formatted as a MetadataObject
  *
+ * @deprecated FWSS piece metadata getters are being removed. Read metadata from `PieceAdded` events or an indexer instead.
  * @param client - The client to use to get the piece metadata.
  * @param options - {@link getAllPieceMetadata.OptionsType}
  * @returns The metadata formatted as a MetadataObject {@link getAllPieceMetadata.OutputType}
@@ -90,6 +91,7 @@ export namespace getAllPieceMetadataCall {
  *
  * Use {@link parseAllPieceMetadata} to parse the output into a MetadataObject.
  *
+ * @deprecated FWSS piece metadata getters are being removed. Read metadata from `PieceAdded` events or an indexer instead.
  * @param options - {@link getAllPieceMetadataCall.OptionsType}
  * @returns The call to the getAllPieceMetadata function {@link getAllPieceMetadataCall.OutputType}
  * @throws Errors {@link getAllPieceMetadataCall.ErrorType}
@@ -132,6 +134,7 @@ export function getAllPieceMetadataCall(options: getAllPieceMetadataCall.Options
 /**
  * Parse the contract output into a MetadataObject
  *
+ * @deprecated The FWSS piece metadata getter is being removed. Read metadata from `PieceAdded` events or an indexer instead.
  * @param data - The contract output from the getAllPieceMetadata function {@link getAllPieceMetadata.ContractOutputType}
  * @returns The metadata formatted as a MetadataObject {@link getAllPieceMetadata.OutputType}
  */

packages/synapse-core/src/warm-storage/types.ts

@@ -56,6 +56,10 @@ export interface Piece {
   url: string
 }
 
+/**
+ * @deprecated FWSS piece metadata getters are being removed. Use {@link Piece} and read metadata from `PieceAdded` events or an indexer instead.
+ */
 export interface PieceWithMetadata extends Piece {
+  /** @deprecated Read metadata from `PieceAdded` events or an indexer instead. */
   metadata: MetadataObject
 }

packages/synapse-core/tsconfig.json

@@ -2,6 +2,7 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "./dist",
+    "removeComments": false,
     "types": ["mocha", "node"]
   },
   "include": ["src", "test"],

packages/synapse-sdk/src/warm-storage/service.ts

@@ -342,6 +342,7 @@ export class WarmStorageService {
   /**
    * Get all metadata for a piece in a data set
    *
+   * @deprecated FWSS piece metadata getters are being removed. Read metadata from `PieceAdded` events or an indexer instead.
    * @param options - Options for the piece
    * @param options.dataSetId - The data set ID
    * @param options.pieceId - The piece ID
@@ -354,6 +355,7 @@ export class WarmStorageService {
   /**
    * Get specific metadata key for a piece in a data set
    *
+   * @deprecated FWSS piece metadata getters are being removed. Read metadata from `PieceAdded` events or an indexer instead.
    * @param options - Options for the piece
    * @param options.dataSetId - The data set ID
    * @param options.pieceId - The piece ID

packages/synapse-sdk/tsconfig.json

@@ -2,6 +2,7 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "./dist",
+    "removeComments": false,
     "types": ["mocha", "node"]
   },
   "include": ["src/**/*", "package.json", "../synapse-core/src/utils/epoch.ts", "../synapse-core/test/epoch.test.ts"],