@storacha/client

JavaScript client for the Storacha Network

@storacha/client is a JavaScript library that provides a convenient interface to the Storacha platform, a simple "on-ramp" to the content-addressed decentralized IPFS network. Learn more...

⚠️❗ Public Data 🌎: All data uploaded to Storacha is available to anyone who requests it using the correct CID. Do not store any private or sensitive information in an unencrypted form using Storacha.

⚠️❗ Permanent Data ♾️: Removing files from Storacha will remove them from the file listing for your account, but that doesn’t prevent nodes on the decentralized storage network from retaining copies of the data indefinitely. Do not use Storacha for data that may need to be permanently deleted in the future.

Install

You can add the @storacha/client package to your JavaScript or TypeScript project with npm:

npm install @storacha/client

Note: a modern browser or Node 18+ is required.

Usage

API Reference

Example

import * as Client from '@storacha/client'

const client = await Client.create()

// Note: first time setup is required - either login or load delegations, see:
// https://docs.storacha.network/how-to/upload/

const root = await client.uploadDirectory([new File(['Hello World!'], 'hello.txt')])

// `root` is a CID - a hash of the data, use it in an IPFS gateway URL to access:
console.log(`https://storacha.link/ipfs/${root}/hello.txt`)

API

• create
• Client
  • uploadDirectory
  • uploadFile
  • uploadCAR
  • agent
  • login
  • accounts
  • currentSpace
  • setCurrentSpace
  • spaces
  • createSpace
  • addSpace
  • proofs
  • addProof
  • delegations
  • createDelegation
  • remove
  • capability.access.authorize
  • capability.access.claim
  • capability.blob.add
  • capability.blob.list
  • capability.blob.remove
  • capability.index.add
  • capability.plan.get
  • capability.plan.set
  • capability.plan.createAdminSession
  • capability.space.info
  • capability.upload.add
  • capability.upload.list
  • capability.upload.remove
  • capability.filecoin.offer
  • capability.filecoin.info
  • capability.usage.report
• Types
  • BlobListResult
  • Capability
  • CARMetadata
  • ClientFactoryOptions
  • Delegation
  • Driver
  • ListResponse
  • ServiceConf
  • ShardStoredCallback
  • Space
  • UploadListResult

create

function create(options?: ClientFactoryOptions): Promise<Client>

Create a new Storacha client.

If no backing store is passed one will be created that is appropriate for the environment.

If the backing store is empty, a new signing key will be generated and persisted to the store. In the browser an unextractable RSA key will be generated by default. In other environments an Ed25519 key is generated.

If the backing store already has data stored, it will be loaded and used.

More information: ClientFactoryOptions

uploadDirectory

function uploadDirectory(
  files: File[],
  options: {
    retries?: number
    signal?: AbortSignal
    onShardStored?: ShardStoredCallback
    shardSize?: number
    dedupe?: boolean
  } = {}
): Promise<CID>

Uploads a directory of files to the service and returns the root data CID for the generated DAG. All files are added to a container directory, with paths in file names preserved.

More information: ShardStoredCallback

uploadFile

function uploadFile(
  file: Blob,
  options: {
    retries?: number
    signal?: AbortSignal
    onShardStored?: ShardStoredCallback
    shardSize?: number
    dedupe?: boolean
  } = {}
): Promise<CID>

Uploads a file to the service and returns the root data CID for the generated DAG.

More information: ShardStoredCallback

uploadCAR

function uploadCAR(
  car: Blob,
  options: {
    retries?: number
    signal?: AbortSignal
    onShardStored?: ShardStoredCallback
    shardSize?: number
    rootCID?: CID
    dedupe?: boolean
  } = {}
): Promise<CID>

Uploads a CAR file to the service. The difference between this function and capability.store.add is that the CAR file is automatically sharded and an "upload" is registered (see capability.upload.add), linking the individual shards. Use the onShardStored callback to obtain the CIDs of the CAR file shards.

More information: ShardStoredCallback

agent

agent: Signer

The user agent. The agent is a signer - an entity that can sign UCANs with keys from a Principal using a signing algorithm.

login

function login(
  email: string,
  options?: { signal?: AbortSignal }
): Promise<void>

Authorize the current agent to use capabilities granted to the passed email account.

accounts

function accounts(): Record<DID, Account>

List all accounts the agent has stored access to.

currentSpace

function currentSpace(): Space | undefined

The current space in use by the agent.

setCurrentSpace

function setCurrentSpace(did: DID): Promise<void>

Use a specific space.

spaces

function spaces(): Space[]

Spaces available to this agent.

createSpace

async function createSpace(
  name?: string,
  options?: { account: Account }
): Promise<Space>

Create a new space with an optional name.

addSpace

async function addSpace(proof: Delegation): Promise<Space>

Add a space from a received proof. Proofs are delegations with an audience matching the agent DID.

proofs

function proofs(capabilities?: Capability[]): Delegation[]

Get all the proofs matching the capabilities. Proofs are delegations with an audience matching the agent DID.

More information: Capability

addProof

function addProof(proof: Delegation): Promise<void>

Add a proof to the agent. Proofs are delegations with an audience matching the agent DID. Note: addSpace should be used for delegating from Space to Agent (i.e., you want the Agent to fully be able to act on behalf of the Space), as it calls addProof with some additional client logic. addProof is for more generically adding delegations to the Agent (e.g., delegation targets a resource other than a Space).

delegations

function delegations(capabilities?: Capability[]): Delegation[]

Get delegations created by the agent for others. Filtered optionally by capability.

More information: Capability

createDelegation

function createDelegation(
  audience: Principal,
  abilities: string[],
  options?: UCANOptions
): Promise<Delegation>

Create a delegation to the passed audience for the given abilities with the current space as the resource.

remove

function remove (
  contentCID?: CID
  options: {
    shards?: boolean
  } = {}
): Promise<void>

Removes association of a content CID with the space. Optionally, also removes association of CAR shards with space.

⚠️ If shards option is true all shards will be deleted even if there is another upload(s) that reference same shards, which in turn could corrupt those uploads.

getReceipt

function getReceipt(taskCid: CID): Promise<Receipt>

Get a receipt for an executed task by its CID.

capability.access.authorize

function authorize(
  email: string,
  options: { signal?: AbortSignal } = {}
): Promise<void>

Authorize the current agent to use capabilities granted to the passed email account.

capability.access.claim

function claim(): Promise<Delegation<Capabilities>[]>

Claim delegations granted to the account associated with this agent. Note: the received delegations are added to the agent's persistent store.

capability.blob.add

function add(
  blob: Blob,
  options: { retries?: number; signal?: AbortSignal } = {}
): Promise<MultihashDigest>

Store a blob to the service.

capability.blob.list

function list(
  options: { retries?: number; signal?: AbortSignal } = {}
): Promise<ListResponse<BlobListResult>>

List blobs stored in the current space.

More information: BlobListResult, ListResponse

capability.blob.remove

function remove(
  digest: MultihashDigest,
  options: { retries?: number; signal?: AbortSignal } = {}
): Promise<void>

Remove a stored blob by multihash digest.

capability.index.add

function add(
  index: CID,
  options: { retries?: number; signal?: AbortSignal } = {}
): Promise<IndexAddResponse>

Register an "index" with the service. The index CID should be the CID of a CAR file, containing an index ad defined by w3-index.

Required delegated capability proofs: index/add

capability.plan.get

function get(account: AccountDID): Promise<PlanGetSuccess>

Get information about an account's billing plan.

capability.plan.set

function set(account: AccountDID, product: DID): Promise<{}>

Switch an account's "plan" to the given product. This may result in changes to your billing or unexpected billing cycles depending on the type of change.

capability.plan.createAdminSession

function createAdminSession(
  account: AccountDID,
  returnURL: string
): Promise<{ url: string }>

Create a billing customer portal admin session. Returns a URL that the customer can visit to administer account. Design and implementation driven by our Stripe integration and may not be supported by all billing providers.

capability.upload.add

function add(
  root: CID,
  shards: CID[],
  options: { retries?: number; signal?: AbortSignal } = {}
): Promise<UploadAddResponse>

Register a set of stored CAR files as an "upload" in the system. A DAG can be split between multiple CAR files. Calling this function allows multiple stored CAR files to be considered as a single upload.

capability.upload.list

function list(
  options: { cursor?: string, size?: number, retries?: number; signal?: AbortSignal } = {}
): Promise<ListResponse<UploadListResult>>

List uploads created in the current space.

More information: UploadListResult, ListResponse

capability.upload.remove

function remove(
  link: CID,
  options: { retries?: number; signal?: AbortSignal } = {}
): Promise<void>

Remove a upload by root data CID.

capability.filecoin.offer

function offer(content: CID, piece: PieceLink): Promise<FilecoinOfferResponse>

Offer a Filecoin "piece" to be added to an aggregate that will be offered for Filecoin deal(s).

capability.filecoin.info

function info(piece: PieceLink): Promise<FilecoinInfoResponse>

Get know deals and aggregate info of a Filecoin "piece" previously offered.

capability.usage.report

function report(
  space: DID,
  period: { from: Date, to: Date },
  options?: { nonce?: string }
): Promise<UsageReportSuccess>

Get a usage report for the passed space in the given time period.

More information: UsageReportSuccess

Types

BlobListResult

interface BlobListResult {
  blob: {
    digest: Uint8Array
    size: number
  }
}

Capability

An object describing a UCAN capability, which specifies what action the UCAN holder can perform with some resource.

Defined by the @ipld/dag-ucan package.

interface Capability<
  Can extends Ability = Ability,
  With extends Resource = Resource,
  Caveats extends unknown = unknown
> {
  with: With
  can: Can
  nb?: Caveats
}

type Ability = `${string}/${string}` | '*'

type Resource = `${string}:${string}`

The can field contains a string ability identifier, e.g. blob/add or space/info.

The with field contains a resource URI, often a did:key URI that identifies a Space.

The optional nb (nota bene) field contains "caveats" that add supplemental information to a UCAN invocation or delegation.

See the @storacha/capabilities package for more information about capabilities and how they are defined in Storacha services.

CARMetadata

Metadata pertaining to a CAR file.

interface CARMetadata {
  /**
   * CAR version number.
   */
  version: number
  /**
   * Root CIDs present in the CAR header.
   */
  roots: CID[]
  /**
   * CID of the CAR file (not the data it contains).
   */
  cid: CID
  /**
   * Size of the CAR file in bytes.
   */
  size: number
}

ClientFactoryOptions

Options for creating a new Storacha client.

interface ClientFactoryOptions {
  /**
   * A storage driver that persists exported agent data.
   */
  store?: Driver<AgentDataExport>
  /**
   * Use this principal to sign UCANs. Note: if the store is non-empty and the
   * principal saved in the store is not the same principal as the one passed
   * here an error will be thrown.
   */
  principal?: Signer<DID>
}

See the storage driver docs for the types of storage driver available. If a store is not specified a store appropriate for the environment is picked.

Delegation

An in-memory view of a UCAN delegation, including proofs that can be used to invoke capabilities or delegate to other agents.

import { Delegation as CoreDelegation } from '@ucanto/core/delegation'
export interface Delegation extends CoreDelegation {
  /**
   * User defined delegation metadata.
   */
  meta(): Record<string, any>
}

The Delegation type in @storacha/client extends the Delegation type defined by ucanto:

export interface Delegation<C extends Capabilities = Capabilities> {
  readonly root: UCANBlock<C>
  readonly blocks: Map<string, Block>

  readonly cid: UCANLink<C>
  readonly bytes: ByteView<UCAN.UCAN<C>>
  readonly data: UCAN.View<C>

  asCID: UCANLink<C>

  export(): IterableIterator<Block>

  issuer: UCAN.Principal
  audience: UCAN.Principal
  capabilities: C
  expiration?: UCAN.UTCUnixTimestamp
  notBefore?: UCAN.UTCUnixTimestamp

  nonce?: UCAN.Nonce

  facts: Fact[]
  proofs: Proof[]
  iterate(): IterableIterator<Delegation>
}

Delegations can be serialized by calling export() and piping the returned Block iterator into a CarWriter from the @ipld/car package.

Driver

Storage drivers persist data created and managed by an agent. Currently 3 storage drivers are available:

• Conf (@storacha/client/stores/conf) - a store for use in Node.js that is backed by the conf module.
• IndexedDB (@storacha/client/stores/indexeddb) - a browser only store for persiance backed by IndexedDB.
• Memory (@storacha/client/stores/memory) - in memory store for clients that load state from environment variables/secrets, ephemeral clients and for testing. Note: not persisted!

ListResponse

A paginated list of items.

interface ListResponse<R> {
  cursor?: string
  size: number
  results: R[]
}

ServiceConf

Service DID and URL configuration.

ShardStoredCallback

A function called after a DAG shard has been successfully stored by the service:

type ShardStoredCallback = (meta: CARMetadata) => void

More information: CARMetadata

Space

An object representing a storage location. Spaces must be registered with the service before they can be used for storage.

interface Space {
  /**
   * The given space name.
   */
  name(): string

  /**
   * The DID of the space.
   */
  did(): string

  /**
   * Whether the space has been registered with the service.
   */
  registered(): boolean

  /**
   * User defined space metadata.
   */
  meta(): Record<string, any>
}

UploadListResult

interface UploadListResult {
  root: CID
  shards?: CID[]
}

UsageReportSuccess

type UsageReportSuccess = Record<DID, UsageData>

interface UsageData {
  /** Provider the report concerns, e.g. `did:web:storacha.network` */
  provider: DID
  /** Space the report concerns. */
  space: DID
  /** Period the report applies to. */
  period: {
    /** ISO datetime the report begins from (inclusive). */
    from: ISO8601Date
    /** ISO datetime the report ends at (inclusive). */
    to: ISO8601Date
  }
  /** Observed space size for the period. */
  size: {
    /** Size at the beginning of the report period. */
    initial: number
    /** Size at the end of the report period. */
    final: number
  }
  /** Events that caused the size to change during the period. */
  events: Array<{
    /** CID of the invoked task that caused the size to change. */
    cause: Link
    /** Number of bytes that were added or removed. */
    delta: number
    /** ISO datetime that the receipt was issued for the change. */
    receiptAt: ISO8601Date
  }>
}

Contributing

Feel free to join in. All welcome. Please open an issue!

License

Dual-licensed under MIT + Apache 2.0