FilBeamService

Defined in: packages/synapse-sdk/src/filbeam/service.ts:68

Service for interacting with FilBeam infrastructure and APIs.

Example

import { mainnet } from '@filoz/synapse-core/chains'
import { Synapse } from '@filoz/synapse-sdk'
import { FilBeamService } from '@filoz/synapse-sdk/filbeam'
import { privateKeyToAccount } from 'viem/accounts'

// Access through Synapse (uses the Synapse chain)
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'my-app' })
const synapseStats = await synapse.filbeam.getDataSetStats(12345)

// Or create the service directly for a chain
const service = new FilBeamService(mainnet)
const stats = await service.getDataSetStats(12345)
console.log('Remaining CDN Egress (cache hits):', stats.cdnEgressQuota)
console.log('Remaining Cache Miss Egress:', stats.cacheMissEgressQuota)

Remarks

All quota values are returned as BigInt for precision when handling large byte values.

See

FilBeam Documentation for detailed API specifications and usage guides

Constructors

Constructor

new FilBeamService(chain, fetchImpl?): FilBeamService

Defined in: packages/synapse-sdk/src/filbeam/service.ts:72

Parameters

Parameter	Type	Default value
chain	Chain	undefined
fetchImpl	{(input, init?): Promise<Response>; (input, init?): Promise<Response>; }	globalThis.fetch

Returns

FilBeamService

Methods

getDataSetStats()

getDataSetStats(dataSetId, options?): Promise<DataSetStats>

Defined in: packages/synapse-sdk/src/filbeam/service.ts:144

Retrieves remaining pay-per-byte statistics for a specific data set from FilBeam.

Fetches the remaining CDN and cache miss egress quotas for a data set. These quotas track how many bytes can still be retrieved through FilBeam’s trusted measurement layer before needing to add more credits:

• CDN Egress Quota: Remaining bytes that can be served from FilBeam’s cache (fast, direct delivery)
• Cache Miss Egress Quota: Remaining bytes that can be retrieved from storage providers (triggers caching)

Both types of egress are billed based on volume. Query current pricing via WarmStorageService.getPriceList or see https://docs.filbeam.com for rates.

Parameters

Parameter	Type	Description
dataSetId	string | number	The unique identifier of the data set to query
options	GetDataSetStatsOptions	Optional abort signal and timeout. See GetDataSetStatsOptions.

Returns

Promise<DataSetStats>

A promise that resolves to the data set statistics with remaining quotas as BigInt values

Throws

Throws an error if:

• The data set is not found (404)
• The API returns an invalid response format
• Network or other HTTP errors occur
• The request times out or is aborted

Example

try {
  const stats = await service.getDataSetStats('my-dataset-123')

  // Display remaining quotas
  console.log(`Remaining CDN Egress: ${stats.cdnEgressQuota} bytes`)
  console.log(`Remaining Cache Miss: ${stats.cacheMissEgressQuota} bytes`)
} catch (error) {
  console.error('Failed to get stats:', error.message)
}