feat(retriever): add SubgraphRetriever

[silent-cipher]

This PR introduces the SubgraphRetriever, a new component that allows fetching piece information from a user-configured subgraph.

It can be chained with other retrievers, such as ChainRetriever and FilCDNRetriever, to create a flexible and powerful data discovery pipeline. This provides an alternative for users who rely on subgraphs for commp to provider mapping.

This also contains an SubgraphService that can be used independently -

import { SubgraphService } from '@filoz/synapse-sdk'

const subgraphUrl = 'https://api.thegraph.com/subgraphs/name/some/subgraph'
const subgraphService = new SubgraphService({ endpoint: subgraphUrl })

// Example: Query for active providers with custom filtering
const activeProviders = await subgraphService.queryProviders({
  where: {
    status: 'Approved',
  },
  orderBy: 'totalProofSets',
  orderDirection: 'desc',
  first: 10
})

console.log('Top 10 active providers by proof sets:', activeProviders)

[rvagg]

Looking good!

[rvagg]

Suggested change

	const hexCommP = toHex(commP.bytes)
	const commPParsed = asCommP(commP)
	if (commPParsed == null) {
	throw new Error(`Invalid CommP: ${commP}`)
	}
	const hexCommP = toHex(commPParsed.bytes)

[Copilot]

Pull Request Overview

This PR introduces subgraph-based piece retrieval by adding a SubgraphService and a SubgraphRetriever, integrates them into the main Synapse flow, and updates types, exports, and documentation accordingly.

• Extend SynapseOptions with subgraphService and subgraphConfig to configure subgraph retrieval.
• Implement SubgraphService (GraphQL client) and SubgraphRetriever (with fallback to chain/CDN retrievers).
• Integrate the new retriever into synapse.ts, export it in the retriever module, and add usage documentation in README.md.

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/types.ts	Added SubgraphConfig and SubgraphRetrievalService options
src/subgraph/service.ts	New GraphQL-based SubgraphService implementation
src/retriever/subgraph.ts	New SubgraphRetriever with child fallback
src/synapse.ts	Hooked up subgraph retriever in Synapse initialization
src/retriever/index.ts	Exported SubgraphRetriever
README.md	Added "Subgraph Service" section and updated Synapse options docs

Comments suppressed due to low confidence (1)

src/subgraph/service.ts:336

• The log prefix 'SubgraphService: queryProviders' in safeConvertHexToCid is misleading since this is CID-conversion logic, not part of queryProviders. Consider updating it to reference safeConvertHexToCid (or removing the incorrect method name) for clarity.

      )

[rvagg]

nice work

[github-actions]

🎉 This PR is included in version 0.19.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀