\n\n`@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...](./READMOAR.md)\n\n> ⚠️❗ **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.\n\n> ⚠️❗ **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.\n\n## Install\n\nYou can add the `@storacha/client` package to your JavaScript or TypeScript project with `npm`:\n\n```sh\nnpm install @storacha/client\n```\n\nNote: a modern browser or Node 18+ is required.\n\n## Usage\n\n[API Reference](#api)\n\n### Example\n\n```js\nimport * as Client from '@storacha/client'\n\nconst client = await Client.create()\n\n// Note: first time setup is required - either login or load delegations, see:\n// https://docs.storacha.network/how-to/upload/\n\nconst root = await client.uploadDirectory([new File(['Hello World!'], 'hello.txt')])\n\n// `root` is a CID - a hash of the data, use it in an IPFS gateway URL to access:\nconsole.log(`https://storacha.link/ipfs/${root}/hello.txt`)\n```\n\n## API\n\n- [`create`](#create)\n- `Client`\n - [`uploadDirectory`](#uploaddirectory)\n - [`uploadFile`](#uploadfile)\n - [`uploadCAR`](#uploadcar)\n - [`agent`](#agent)\n - [`login`](#login)\n - [`accounts`](#accounts)\n - [`currentSpace`](#currentspace)\n - [`setCurrentSpace`](#setcurrentspace)\n - [`spaces`](#spaces)\n - [`createSpace`](#createspace)\n - [`addSpace`](#addSpace)\n - [`proofs`](#proofs)\n - [`addProof`](#addproof)\n - [`delegations`](#delegations)\n - [`createDelegation`](#createdelegation)\n - [`remove`](#remove)\n - [`capability.access.authorize`](#capabilityaccessauthorize)\n - [`capability.access.claim`](#capabilityaccessclaim)\n - [`capability.blob.add`](#capabilityblobadd)\n - [`capability.blob.list`](#capabilitybloblist)\n - [`capability.blob.remove`](#capabilityblobremove)\n - [`capability.index.add`](#capabilityindexadd)\n - [`capability.plan.get`](#capabilityplanget)\n - [`capability.plan.set`](#capabilityplanset)\n - [`capability.plan.createAdminSession`](#capabilityplancreateadminsession)\n - [`capability.space.info`](#capabilityspaceinfo)\n - [`capability.upload.add`](#capabilityuploadadd)\n - [`capability.upload.list`](#capabilityuploadlist)\n - [`capability.upload.remove`](#capabilityuploadremove)\n - [`capability.filecoin.offer`](#capabilityfilecoinoffer)\n - [`capability.filecoin.info`](#capabilityfilecoininfo)\n - [`capability.usage.report`](#capabilityusagereport)\n- [Types](#types)\n - [`BlobListResult`](#bloblistresult)\n - [`Capability`](#capability)\n - [`CARMetadata`](#carmetadata)\n - [`ClientFactoryOptions`](#clientfactoryoptions)\n - [`Delegation`](#delegation)\n - [`Driver`](#driver)\n - [`ListResponse`](#listresponse)\n - [`ServiceConf`](#serviceconf)\n - [`ShardStoredCallback`](#shardstoredcallback)\n - [`Space`](#space)\n - [`UploadListResult`](#uploadlistresult)\n\n---\n\n### `create`\n\n```ts\nfunction create(options?: ClientFactoryOptions): Promise\n```\n\nCreate a new Storacha client.\n\nIf no backing store is passed one will be created that is appropriate for the environment.\n\nIf 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.\n\nIf the backing store already has data stored, it will be loaded and used.\n\nMore information: [`ClientFactoryOptions`](#clientfactoryoptions)\n\n### `uploadDirectory`\n\n```ts\nfunction uploadDirectory(\n files: File[],\n options: {\n retries?: number\n signal?: AbortSignal\n onShardStored?: ShardStoredCallback\n shardSize?: number\n dedupe?: boolean\n } = {}\n): Promise\n```\n\nUploads 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.\n\nMore information: [`ShardStoredCallback`](#shardstoredcallback)\n\n### `uploadFile`\n\n```ts\nfunction uploadFile(\n file: Blob,\n options: {\n retries?: number\n signal?: AbortSignal\n onShardStored?: ShardStoredCallback\n shardSize?: number\n dedupe?: boolean\n } = {}\n): Promise\n```\n\nUploads a file to the service and returns the root data CID for the generated DAG.\n\nMore information: [`ShardStoredCallback`](#shardstoredcallback)\n\n### `uploadCAR`\n\n```ts\nfunction uploadCAR(\n car: Blob,\n options: {\n retries?: number\n signal?: AbortSignal\n onShardStored?: ShardStoredCallback\n shardSize?: number\n rootCID?: CID\n dedupe?: boolean\n } = {}\n): Promise\n```\n\nUploads a CAR file to the service. The difference between this function and [capability.store.add](#capabilitystoreadd) is that the CAR file is automatically sharded and an \"upload\" is registered (see [`capability.upload.add`](#capabilityuploadadd)), linking the individual shards. Use the `onShardStored` callback to obtain the CIDs of the CAR file shards.\n\nMore information: [`ShardStoredCallback`](#shardstoredcallback)\n\n### `agent`\n\n```ts\nagent: Signer\n```\n\nThe user agent. The agent is a signer - an entity that can sign UCANs with keys from a `Principal` using a signing algorithm.\n\n### `login`\n\n```ts\nfunction login(\n email: string,\n options?: { signal?: AbortSignal }\n): Promise\n```\n\nAuthorize the current agent to use capabilities granted to the passed email account.\n\n### `accounts`\n\n```ts\nfunction accounts(): Record\n```\n\nList all accounts the agent has stored access to.\n\n### `currentSpace`\n\n```ts\nfunction currentSpace(): Space | undefined\n```\n\nThe current space in use by the agent.\n\n### `setCurrentSpace`\n\n```ts\nfunction setCurrentSpace(did: DID): Promise\n```\n\nUse a specific space.\n\n### `spaces`\n\n```ts\nfunction spaces(): Space[]\n```\n\nSpaces available to this agent.\n\n### `createSpace`\n\n```ts\nasync function createSpace(\n name?: string,\n options?: { account: Account }\n): Promise\n```\n\nCreate a new space with an optional name.\n\n### `addSpace`\n\n```ts\nasync function addSpace(proof: Delegation): Promise\n```\n\nAdd a space from a received proof. Proofs are delegations with an _audience_ matching the agent DID.\n\n### `proofs`\n\n```ts\nfunction proofs(capabilities?: Capability[]): Delegation[]\n```\n\nGet all the proofs matching the capabilities. Proofs are delegations with an _audience_ matching the agent DID.\n\nMore information: [`Capability`](#capability)\n\n### `addProof`\n\n```ts\nfunction addProof(proof: Delegation): Promise\n```\n\nAdd 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).\n\n### `delegations`\n\n```ts\nfunction delegations(capabilities?: Capability[]): Delegation[]\n```\n\nGet delegations created by the agent for others. Filtered optionally by capability.\n\nMore information: [`Capability`](#capability)\n\n### `createDelegation`\n\n```ts\nfunction createDelegation(\n audience: Principal,\n abilities: string[],\n options?: UCANOptions\n): Promise\n```\n\nCreate a delegation to the passed audience for the given abilities with the _current_ space as the resource.\n\n### `remove`\n\n```ts\nfunction remove (\n contentCID?: CID\n options: {\n shards?: boolean\n } = {}\n): Promise\n```\n\nRemoves association of a content CID with the space. Optionally, also removes association of CAR shards with space.\n\n⚠️ 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.\n\n### `getReceipt`\n\n```ts\nfunction getReceipt(taskCid: CID): Promise\n```\n\nGet a receipt for an executed task by its CID.\n\n### `capability.access.authorize`\n\n```ts\nfunction authorize(\n email: string,\n options: { signal?: AbortSignal } = {}\n): Promise\n```\n\nAuthorize the current agent to use capabilities granted to the passed email account.\n\n### `capability.access.claim`\n\n```ts\nfunction claim(): Promise[]>\n```\n\nClaim delegations granted to the account associated with this agent. Note: the received delegations are added to the agent's persistent store.\n\n### `capability.blob.add`\n\n```ts\nfunction add(\n blob: Blob,\n options: { retries?: number; signal?: AbortSignal } = {}\n): Promise\n```\n\nStore a blob to the service.\n\n### `capability.blob.list`\n\n```ts\nfunction list(\n options: { retries?: number; signal?: AbortSignal } = {}\n): Promise>\n```\n\nList blobs stored in the current space.\n\nMore information: [`BlobListResult`](#bloblistresult), [`ListResponse`](#listresponse)\n\n### `capability.blob.remove`\n\n```ts\nfunction remove(\n digest: MultihashDigest,\n options: { retries?: number; signal?: AbortSignal } = {}\n): Promise\n```\n\nRemove a stored blob by multihash digest.\n\n### `capability.index.add`\n\n```ts\nfunction add(\n index: CID,\n options: { retries?: number; signal?: AbortSignal } = {}\n): Promise\n```\n\nRegister an \"index\" with the service. The `index` CID should be the CID of a CAR file, containing an index ad defined by [w3-index](https://github.com/storacha/specs/blob/main/w3-index.md).\n\nRequired delegated capability proofs: `index/add`\n\n### `capability.plan.get`\n\n```ts\nfunction get(account: AccountDID): Promise\n```\n\nGet information about an account's billing plan.\n\n### `capability.plan.set`\n\n```ts\nfunction set(account: AccountDID, product: DID): Promise<{}>\n```\n\nSwitch an account's \"plan\" to the given product. **This may result in\nchanges to your billing or unexpected billing cycles depending on the\ntype of change.**\n\n### `capability.plan.createAdminSession`\n\n```ts\nfunction createAdminSession(\n account: AccountDID,\n returnURL: string\n): Promise<{ url: string }>\n```\n\nCreate a billing customer portal admin session. Returns a URL that\nthe customer can visit to administer `account`. Design and implementation driven\nby our Stripe integration and may not be supported by all billing providers.\n\n### `capability.upload.add`\n\n```ts\nfunction add(\n root: CID,\n shards: CID[],\n options: { retries?: number; signal?: AbortSignal } = {}\n): Promise\n```\n\nRegister 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.\n\n### `capability.upload.list`\n\n```ts\nfunction list(\n options: { cursor?: string, size?: number, retries?: number; signal?: AbortSignal } = {}\n): Promise>\n```\n\nList uploads created in the current space.\n\nMore information: [`UploadListResult`](#uploadlistresult), [`ListResponse`](#listresponse)\n\n### `capability.upload.remove`\n\n```ts\nfunction remove(\n link: CID,\n options: { retries?: number; signal?: AbortSignal } = {}\n): Promise\n```\n\nRemove a upload by root data CID.\n\n### `capability.filecoin.offer`\n\n```ts\nfunction offer(content: CID, piece: PieceLink): Promise\n```\n\nOffer a Filecoin \"piece\" to be added to an aggregate that will be offered for Filecoin deal(s).\n\n### `capability.filecoin.info`\n\n```ts\nfunction info(piece: PieceLink): Promise\n```\n\nGet know deals and aggregate info of a Filecoin \"piece\" previously offered.\n\n### `capability.usage.report`\n\n```ts\nfunction report(\n space: DID,\n period: { from: Date, to: Date },\n options?: { nonce?: string }\n): Promise\n```\n\nGet a usage report for the passed space in the given time period.\n\nMore information: [`UsageReportSuccess`](#usagereportsuccess)\n\n## Types\n\n### `BlobListResult`\n\n```ts\ninterface BlobListResult {\n blob: {\n digest: Uint8Array\n size: number\n }\n}\n```\n\n### `Capability`\n\nAn object describing a UCAN capability, which specifies what action the UCAN holder `can` perform `with` some resource.\n\nDefined by the [`@ipld/dag-ucan` package](https://github.com/ipld/js-dag-ucan).\n\n```ts\ninterface Capability<\n Can extends Ability = Ability,\n With extends Resource = Resource,\n Caveats extends unknown = unknown\n> {\n with: With\n can: Can\n nb?: Caveats\n}\n\ntype Ability = `${string}/${string}` | '*'\n\ntype Resource = `${string}:${string}`\n```\n\nThe `can` field contains a string ability identifier, e.g. `blob/add` or `space/info`.\n\nThe `with` field contains a resource URI, often a `did:key` URI that identifies a Space.\n\nThe optional `nb` (_nota bene_) field contains \"caveats\" that add supplemental information to a UCAN invocation or delegation.\n\nSee [the `@storacha/capabilities` package](https://github.com/storacha/upload-service/tree/main/packages/capabilities) for more information about capabilities and how they are defined in Storacha services.\n\n### `CARMetadata`\n\nMetadata pertaining to a CAR file.\n\n```ts\ninterface CARMetadata {\n /**\n * CAR version number.\n */\n version: number\n /**\n * Root CIDs present in the CAR header.\n */\n roots: CID[]\n /**\n * CID of the CAR file (not the data it contains).\n */\n cid: CID\n /**\n * Size of the CAR file in bytes.\n */\n size: number\n}\n```\n\n### `ClientFactoryOptions`\n\nOptions for creating a new Storacha client.\n\n```ts\ninterface ClientFactoryOptions {\n /**\n * A storage driver that persists exported agent data.\n */\n store?: Driver\n /**\n * Use this principal to sign UCANs. Note: if the store is non-empty and the\n * principal saved in the store is not the same principal as the one passed\n * here an error will be thrown.\n */\n principal?: Signer\n}\n```\n\nSee the [storage driver docs](#driver) for the types of storage driver available. If a store is not specified a store appropriate for the environment is picked.\n\n### `Delegation`\n\nAn in-memory view of a UCAN delegation, including proofs that can be used to invoke capabilities or delegate to other agents.\n\n```ts\nimport { Delegation as CoreDelegation } from '@ucanto/core/delegation'\nexport interface Delegation extends CoreDelegation {\n /**\n * User defined delegation metadata.\n */\n meta(): Record\n}\n```\n\nThe `Delegation` type in `@storacha/client` extends the `Delegation` type defined by [`ucanto`][ucanto]:\n\n```ts\nexport interface Delegation {\n readonly root: UCANBlock\n readonly blocks: Map\n\n readonly cid: UCANLink\n readonly bytes: ByteView>\n readonly data: UCAN.View\n\n asCID: UCANLink\n\n export(): IterableIterator\n\n issuer: UCAN.Principal\n audience: UCAN.Principal\n capabilities: C\n expiration?: UCAN.UTCUnixTimestamp\n notBefore?: UCAN.UTCUnixTimestamp\n\n nonce?: UCAN.Nonce\n\n facts: Fact[]\n proofs: Proof[]\n iterate(): IterableIterator\n}\n```\n\nDelegations can be serialized by calling `export()` and piping the returned `Block` iterator into a `CarWriter` from the [`@ipld/car` package](https://www.npmjs.com/package/@ipld/car).\n\n### `Driver`\n\nStorage drivers persist data created and managed by an agent. Currently 3 storage drivers are available:\n\n* Conf (`@storacha/client/stores/conf`) - a store for use in Node.js that is backed by the [conf module](https://www.npmjs.com/package/conf).\n* IndexedDB (`@storacha/client/stores/indexeddb`) - a browser only store for persiance backed by IndexedDB.\n* 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!\n\n### `ListResponse`\n\nA paginated list of items.\n\n```ts\ninterface ListResponse {\n cursor?: string\n size: number\n results: R[]\n}\n```\n\n### `ServiceConf`\n\nService DID and URL configuration.\n\n### `ShardStoredCallback`\n\nA function called after a DAG shard has been successfully stored by the service:\n\n```ts\ntype ShardStoredCallback = (meta: CARMetadata) => void\n```\n\nMore information: [`CARMetadata`](#carmetadata)\n\n### `Space`\n\nAn object representing a storage location. Spaces must be [registered](#registerspace) with the service before they can be used for storage.\n\n```ts\ninterface Space {\n /**\n * The given space name.\n */\n name(): string\n\n /**\n * The DID of the space.\n */\n did(): string\n\n /**\n * Whether the space has been registered with the service.\n */\n registered(): boolean\n\n /**\n * User defined space metadata.\n */\n meta(): Record\n}\n```\n\n### `UploadListResult`\n\n```ts\ninterface UploadListResult {\n root: CID\n shards?: CID[]\n}\n```\n\n### `UsageReportSuccess`\n\n```ts\ntype UsageReportSuccess = Record\n\ninterface UsageData {\n /** Provider the report concerns, e.g. `did:web:storacha.network` */\n provider: DID\n /** Space the report concerns. */\n space: DID\n /** Period the report applies to. */\n period: {\n /** ISO datetime the report begins from (inclusive). */\n from: ISO8601Date\n /** ISO datetime the report ends at (inclusive). */\n to: ISO8601Date\n }\n /** Observed space size for the period. */\n size: {\n /** Size at the beginning of the report period. */\n initial: number\n /** Size at the end of the report period. */\n final: number\n }\n /** Events that caused the size to change during the period. */\n events: Array<{\n /** CID of the invoked task that caused the size to change. */\n cause: Link\n /** Number of bytes that were added or removed. */\n delta: number\n /** ISO datetime that the receipt was issued for the change. */\n receiptAt: ISO8601Date\n }>\n}\n```\n\n## Contributing\n\nFeel free to join in. All welcome. Please [open an issue](https://github.com/storacha/upload-service/issues)!\n\n## License\n\nDual-licensed under [MIT + Apache 2.0](https://github.com/storacha/upload-service/blob/main/packages/@storacha/client/LICENSE.md)\n\n[ucanto]: https://github.com/storacha/ucanto\n","readmeFilename":"README.md"}
![](\"https://bafybeich5z6anhfhf23tlnb67y32nl37nttkjfyqv6maeehur3unuuhd2e.ipfs.w3s.link/transparent-red.png\"){kind=spacer}
![\"GitHub](\"https://img.shields.io/github/actions/workflow/status/storacha/upload-service/ci.yml?branch=main&style=for-the-badge\")
![](\"https://img.shields.io/badge/chat-discord?style=for-the-badge&logo=discord&label=discord&logoColor=ffffff&color=7389D8\"){kind=icon}
![\"X](\"https://img.shields.io/badge/follow-storacha-black?style=for-the-badge&logo=x\"){kind=icon}
![\"License:](\"https://img.shields.io/badge/LICENSE-Apache--2.0%20OR%20MIT-yellow?style=for-the-badge\"){kind=icon}