\n\n## About\n\n`@web3-storage/w3up-client` is a JavaScript library that provides a convenient interface to the w3up platform, a simple \"on-ramp\" to the content-addressed decentralized IPFS network.\n\nThis library is the user-facing \"porcelain\" client for interacting with w3up services from JavaScript. It wraps the lower-level [`@web3-storage/access`][access-client-github] and [`@web3-storage/upload-client`][upload-client-github] client packages, which target individual w3up services. We recommend using `w3up-client` instead of using those \"plumbing\" packages directly, but you may find them useful if you need more context on w3up's architecture and internals.\n\n**`w3up-client` requires modern browser or Node 18+**.\n\n> ⚠️❗ __Public Data__ 🌎: All data uploaded to w3up is available to anyone who requests it using the correct CID. Do not store any private or sensitive information in an unencrypted form using w3up.\n\n> ⚠️❗ __Permanent Data__ ♾️: Removing files from w3up 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 w3up for data that may need to be permanently deleted in the future.\n\n- [Install](#install)\n- [Usage](#usage)\n - [How w3up and w3up-client use UCANs](#how-w3up-and-w3up-client-use-ucans)\n - [Space](#space)\n - [Agent](#agent)\n - [Basic usage with web3.storage](#basic-usage-with-web3-storage)\n - [Creating a client object](#creating-a-client-object)\n - [Creating and registering Spaces](#creating-and-registering-spaces)\n - [Delegating from Space to Agent](#delegating-from-space-to-agent)\n - [Bringing your own Agent and delegation](#bringing-your-own-agent-and-delegation)\n - [Uploading data](#uploading-data)\n - [Integration options](#integration-options)\n - [Client-server](#client-server)\n - [Delegated](#delegated)\n - [User owned](#user-owned)\n - [Environments requiring wasm import](#environments-requiring-wasm-imports)\n- [API](#api)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Install\n\nYou can add the `@web3-storage/w3up-client` package to your JavaScript or TypeScript project with `npm`:\n\n```sh\nnpm install @web3-storage/w3up-client\n```\n\n## Usage\n\n[API Reference](#api)\n\nMost users' usage of `w3up-client` will be for interacting with web3.storage, a hosted storage product that developed w3up for their upload APIs. However, any user that has an implementation of w3up ([specs](https://github.com/storacha/specs), [protocol](https://github.com/storacha/w3up)) can configure `w3up-client` for their usage.\n\nFor authorization, w3up services use [ucanto][ucanto], a Remote Procedure Call (RPC) framework built around [UCAN](https://ucan.xzy), or User Controlled Authorization Networks. UCANs are a powerful capability-based authorization system that allows fine-grained sharing of permissions through a process called _delegation_ on top of [public key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography). See our [intro to UCAN blog post](https://blog.web3.storage/posts/intro-to-ucan) for an overview of UCAN.\n\nYou can think about UCAN replacing bearer tokens in traditional APIs for authorization with w3up. Since any actor can be represented by a cryptographic keypair and permissions can be delegated to them, users can interact with w3up directly in cases where a developer might have needed to previously run additional back-end infrastructure to keep API keys secure. This can be extended even to have end users using applications integrated with w3up using their own keypair-based identity.\n\n### How w3up and w3up-client use UCANs\n\n`w3up-client` and `ucanto` take care of the details of UCANs for you, but a few of the underlying terms and concepts may \"bubble up\" to the surface of the API, so we'll cover the basics here. We'll also go over some terms that are specific to w3up that you might not have encountered elsewhere.\n\nUCAN-based APIs are centered around _capabilities_, which are comprised of an _ability_ and a _resource_. Together, the ability and resource determine what action a client can perform and what objects in the system can be acted upon. When invoking a service method, a client will present a UCAN token that includes an ability and resource, along with _proofs_ that verify that they should be allowed to exercise the capability. The proof might be signed directly by the capability owner, or have a chain of signatures (_delegations_) where the actor invoking the capability has been verifiably delegated permission to do so.\n\n#### Space\n\nWhen you upload data to w3up, your uploads are linked to a unique _Space_ that acts as a \"namespace\" for the data you upload. Each Space corresponds to a _DID_, or [Decentralized Identity Document](https://www.w3.org/TR/did-core/). In web3.storage's implementation of w3up, these Space DIDs generally use the key DID method, of the form `did:key:publicKey` with a corresponding private signing key.\n\nWhen creating a Space using `w3up-client`, it generates this private key and `did:key` for you locally. To use web3.storage, you then register a Space by associating it with your email address. From there, when invoking storage capabilities with web3.storage, the Space `did:key` is the \"resource\" portion of the capability, while the ability is an action like `blob/add` or `blob/remove`. (A Space registered with web3.storage is imperfectly analogous to an \"account\" with web3.storage.)\n\nUnder the hood in the email registration process, your Space delegates the capabilities needed to use w3up to your email address, and this delegation is stored by web3.storage. If you need access to your Space in the future from any device, web3.storage allows you to reclaim those capabilities the same way you would reset a password in other services - using an email verification process. This means you don't need to store or manage Space private keys to use w3up - just create a new space, register it with w3up and use it from as many devices as you like. More on this \"sign in\" process is detailed in the next section on Agents.\n\n#### Agent\n\nTo invoke a capability like `blob/add` on a Space using `w3up-client`, the client must have an _Agent_. Like a Space, an Agent corresponds to a `did:key` whose private key is generated locally. An Agent is useful once `w3up-client` has a UCAN delegation where a registered Space(s) delegates the Agent its capabilities. (An imperfect analogy is Agent with login session.)\n\nThe first time `w3up-client` is instantiated on a device, it creates an Agent automatically. Alternatively, if you have your own Agent corresponding to a specific private key locally available, you can pass it to the client.\n\nThe delegation from a Space to your Agent that `w3up-client` needs can be passed either by verifying the email address the Space is registered to and claiming the UCAN delegation (`login(email)` then `capability.access.claim`) or directly if you have the UCAN delegation available locally (`addSpace(delegation)`).\n\n### Basic usage with web3.storage\n\n```mermaid\nflowchart TD\n A[w3up-client instance] -->|Automatic if specific Agent is not passed when client object created|B(Create local Agent DID and key)\n B --> |If Space has not yet been created|S(Create local Space, login client with your email address, and register Space + email address with web3.storage)\n S --> C(Get UCAN delegation from Space to Agent)\n C --> D(Upload to Space using Agent)\n```\n\nAll uses of `w3up-client` to upload with web3.storage follow the flow above. This section shows the most basic way to use the client to start storing data. For more complex integration options, check out the [integration options][https://github.com/storacha/w3up/blob/main/packages/w3up-client/README.md#integration-options] docs. For reference, check out the [API reference docs][docs] or the source code of the [`w3cli` package][w3cli-github], which uses `w3up-client` throughout.\n\n> By you or your users registering a w3up Space via email confirmation with [web3.storage](http://web3.storage), you agree to the [Terms of Service](https://web3.storage/docs/terms/). \n\n#### Creating a client object\n\nThe package provides a [static `create` function][docs-create] that returns a [`Client` object][docs-Client]. \n\n```js\nimport { create } from '@web3-storage/w3up-client'\n\nconst client = await create()\n```\n\nBy default, clients will create a new [`Agent`][access-docs-Agent] and put it in a persistent local [`Store`](https://github.com/storacha/w3up/tree/main/packages/access-client) if it can't find an existing one to load (so the next time the client is initialized on the same device, it will use the same `Agent`).\n\n`create` accepts an optional [`ClientFactoryOptions` object][docs-ClientFactoryOptions] that can be used configured to use a non-default persistent `Store`. See the [`@web3-storage/access` docs](https://github.com/storacha/w3up/tree/main/packages/access-client) for more about `Store` configuration. If you'd like to bring your own Agent, you can initialize the client with your own storage [Driver](https://github.com/storacha/w3up/blob/main/packages/w3up-client/README.md#driver). An example would be using `Signer` from the [ucanto][ucanto] package.\n\n```js\nimport { create } from '@web3-storage/w3up-client'\nimport * as Signer from '@ucanto/principal/ed25519' // Agents on Node should use Ed25519 keys\n\nconst principal = Signer.parse(agentPrivateKey) // created by `npx ucan-key ed --json` in command line\nconst client = await create({ principal })\n```\n\nOnce initialized, you can access the client's `Agent` with the [`agent` getter][docs-Client#agent].\n\n##### Pre-built bundle\n\nYou can also import a pre-built bundle, which adds the exports from the client to a _global_ variable `w3up`:\n\n```html\n\n\n\n```\n\n#### Creating and registering Spaces\n\nA [`Space`][docs-Space] acts as a namespace for your uploads, and what your Agent will need a delegation from to store data with w3up. The first thing to do is login your Agent with your email address. Calling `login` will cause an email to be sent to the given address. Once a user clicks the confirmation link in the email, the `login` method will resolve. Make sure to check for errors, as `login` will fail if the email is not confirmed within the expiration timeout. Authorization needs to happen only once per agent.\n\n```js\nconst account = await client.login('zaphod@beeblebrox.galaxy')\n```\n\nIf your account doesn't have a payment plan yet, you'll be prompted to select one after verifying your email. A payment plan is required to provision a space. You can use the following loop to wait until a payment plan is selected:\n\n```js\n// Wait for a payment plan with a 1-second polling interval and 15-minute timeout\nawait account.plan.wait()\n```\n\nSpaces can be created using the [`createSpace` client method][docs-client#createSpace]:\n\n```js\nconst space = await client.createSpace('my-awesome-space', { account })\n```\n\nAlternatively, you can use the w3cli command [`w3 space create`](https://github.com/storacha/w3cli#w3-space-create-name).\n\nThe `name` parameter is optional. If provided, it will be stored in your client's local state store and can be used to provide a friendly name for user interfaces.\n\nIf an `account` is provided in the options, a delegated recovery account is automatically created and provisioned, allowing you to store data and delegate access to the recovery account. This means you can access your space from other devices, as long as you have access to your account.\n\nIf this is your Agent's first space, it will automatically be set as the \"current space.\" If you already have spaces and want to set the new one as current, you can do so manually:\n\n```js\nawait client.setCurrentSpace(space.did())\n```\n\nℹ️ Note: If you do not create the space passing the account parameter you run the risk of losing access to your space!\n\n#### Delegating from Space to Agent\n\nIn order to store data with w3up, your Agent will need a delegation from a Space. This automatically happens if you called `createSpace`. However, if you are initializing the client with a previously created Space, you can `login(email)` then claim a delegation granted to the account associated with your email:\n\n```js\nawait client.login('zaphod@beeblebrox.galaxy')\nawait client.setCurrentSpace(space.did()) # select the relevant Space DID that is associated with your account\n```\n\n```mermaid\nsequenceDiagram\n Client->>web3.storage w3up service: Here is my email address and Agent DID\n web3.storage w3up service-->>Client: Please click the link to validate\n Client-->>web3.storage w3up service: Email address validated\n web3.storage w3up service->>Client: Here is a UCAN delegating permission from Space DID to Agent DID\n```\n\n##### Bringing your own Agent and delegation\n\nFor uses of `w3up-client` in environments where the Agent is not persisted and/or the email verification step would be prohibitive (e.g., serverless backend environment where local Store with the Agent is dropped in between runs, and going through the email verification flow isn't practical), you can manually add a delegation for access to a Space created by a different authorized agent (see the [`addSpace` client method](docs-client#addSpace)). An example (where [w3cli](https://github.com/storacha/w3cli) is set up with the Space that we want to delegate permissions from in our client instance):\n\n```js\nimport * as Signer from '@ucanto/principal/ed25519' // Agents on Node should use Ed25519 keys\nimport { importDAG } from '@ucanto/core/delegation'\nimport { CarReader } from '@ipld/car'\nimport * as Client from '@web3-storage/w3up-client'\nimport { StoreMemory } from '@web3-storage/w3up-client/stores/memory'\n\nasync function main () {\n // from \"bring your own Agent\" example in `Creating a client object\" section`\n // used command line to generate KEY and PROOF (stored in env variables)\n // KEY: `npx ucan-key ed --json` in command line, which returns private key and DID for Agent (the private key is stored in KEY)\n // PROOF: w3cli used to run `w3 delegation create --can 'blob/add' --can 'index/add' --can 'filecoin/offer' --can 'upload/add' | base64`, which returns the delegation from Space to the Agent we're using (stored in PROOF)\n const principal = Signer.parse(process.env.KEY)\n const store = new StoreMemory()\n const client = await Client.create({ principal, store })\n \n // now give Agent the delegation from the Space\n const proof = await parseProof(process.env.PROOF)\n const space = await client.addSpace(proof)\n await client.setCurrentSpace(space.did())\n \n // READY to go!\n}\n\n/** @param {string} data Base64 encoded CAR file */\nasync function parseProof (data) {\n const blocks = []\n const reader = await CarReader.fromBytes(Buffer.from(data, 'base64'))\n for await (const block of reader.blocks()) {\n blocks.push(block)\n }\n return importDAG(blocks)\n}\n```\n\n#### Uploading data\n\nOnce you've [created and registered a Space](#creating-and-registering-spaces) and [authorized your Agent](#authorizing-your-agent), you can upload files to the w3up platform.\n\nCall [`uploadFile`][docs-Client#uploadFile] to upload a single file, or [`uploadDirectory`][docs-Client#uploadDirectory] to upload multiple files.\n\n`uploadFile` expects a \"Blob like\" input, which can be a [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) or [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) when running in a browser. On node.js, see the [`filesFromPath` library](https://github.com/storacha/files-from-path), which can load compatible objects from the local filesystem.\n\n`uploadDirectory` requires `File`-like objects instead of `Blob`s, as the file's `name` property is used to build the directory hierarchy. \n\nYou can control the directory layout and create nested directory structures by using `/` delimited paths in your filenames:\n\n```js\nconst files = [\n new File(['some-file-content'], 'readme.md'),\n new File(['import foo'], 'src/main.py'),\n new File([someBinaryData], 'images/example.png'),\n]\n\nconst directoryCid = await client.uploadDirectory(files)\n```\n\nIn the example above, `directoryCid` resolves to an IPFS directory with the following layout:\n\n```\n.\n├── images\n│ └── example.png\n├── readme.md\n└── src\n └── main.py\n```\n\n\n### Integration options\n\nAs mentioned, UCAN opens up a number of options in how to integrate with w3up: Should you, the developer, own the Space? Should you delegate permissions to your users? Or should your user own their own Space? Broadly, there are three ways to integrate:\n- (Simplest) Client-server: You (the developer) own the Space, and your user uploads to your backend infra before you upload it to the service\n- (More complex) Delegated: You own the Space, but you give a delegated UCAN token to your user's Agent to upload directly to the service (rather than needing to touch the upload in your backend)\n- (Most complex) User-owned: Your user owns the Space and registers it and they use it to upload directly with the service; if you want to instrument visibility into what they’re uploading, you’ll have to write separate code in your app for it\n\nYou can implement each of these in a number of ways, but we talk through some considerations when implementing a given option.\n\n#### Client-server\n```mermaid\nsequenceDiagram\n participant User\n w3up-client in backend->>w3up-client in backend: Client set with Agent with delegation from Space\n User->>w3up-client in backend: Upload data\n w3up-client in backend->>web3.storage w3up service: Upload data\n```\n- For your backend to be scalable, you might consider using serverless workers or a queue in front of a server\n- In either case, you'll need a registered Space, and your client instance in your backend to have an Agent with a delegation from this Space\n - (Recommended) It's likely easiest to create and register your Space using [w3cli](https://github.com/storacha/w3cli) rather than using `w3up-client` to do so (especially if your backend isn't persistent); you can then generate your own Agent and delegate the ability to upload to your Space using something like [this example](#bringing-your-own-agent-and-delegation)\n - If your backend is persistent, you can do this or do everything in the client directly ([create Space](#creating-and-registering-spaces) and [get delegation](#delegating-from-space-to-agent))\n- After this, once your user uploads data to your backend, you can run any of the `upload` methods\n\n#### Delegated\n```mermaid\nsequenceDiagram\n participant w3up-client in user\n participant w3up-client in backend\n participant web3.storage w3up service\n w3up-client in backend->>w3up-client in backend: Client created with Agent and delegation from Space\n w3up-client in user->>w3up-client in user: Client instantiated with default Agent\n w3up-client in user->>w3up-client in backend: Request delegation with user's Agent DID\n w3up-client in backend->>w3up-client in user: Send delegation from Space to user's Agent DID\n w3up-client in user->>web3.storage w3up service: Upload data\n```\n- You will likely have `w3up-client` running in your end-user's client code, as well as backend code that's able to generate UCANs that delegate the ability to upload and pass them to your users (e.g., `w3up-client` running in a serverless worker)\n- For your backend to be scalable, you might consider using serverless workers or a queue in front of a server\n- As the developer, you'll need a registered Space, and your client instance in your backend to have an Agent with a delegation from this Space\n - (Recommended) It's likely easiest to create and register your Space using [w3cli](https://github.com/storacha/w3cli) rather than using `w3up-client` to do so (especially if your backend isn't persistent); you can then generate your own Agent and delegate the ability to upload to your Space using something like [this example](#bringing-your-own-agent-and-delegation)\n - If your backend is persistent, you can do this or do everything in the client directly ([create Space](#creating-and-registering-spaces) and [get delegation](#delegating-from-space-to-agent))\n- Your user does not need a registered Space - just an Agent with a delegation from your Space\n - `w3up-client` in the end user environment should have a unique Agent for each user, which should happen by default (since when `w3up-client` is instantiated it creates a new Agent anyway, or uses the one in local Store)\n - From there, when your end user is ready to upload, they should request from your backend a delegation from your developer-owned Space to their Agent (which can be derived via [`client.agent`](docs-Client#agent))\n - In your backend, you can call [`client.createDelegation()`](docs-Client#createDelegation) passing in the Agent object from `client.agent()` in your end user's instance, and passing through `options?` params to limit the scope of the delegation (e.g., `blob/add`, `upload/add`, expiration time)\n - You can serialize this using `delegation.archive()` and send it to your user\n - The end user instance of the client should not need to call `client.login(email)`, as it is not claiming any delegations via email address (but rather getting the delegation directly from your backend)\n- Once your user receives the delegation, they can deserialize it using [`ucanto.Delegation.extract()`](https://github.com/storacha/ucanto/blob/c8999a59852b61549d163532a83bac62290b629d/packages/core/src/delegation.js#L399) and pass it in using `client.addSpace()`, and from there they can run any of the `upload` methods\n - Note that this alone does not give visibility into which of your end users are uploading what; to track this, you'll probably need them to send you that information separately (e.g., once they've run `upload` and get back a content CID, you can have them send that CID to you for tracking)\n- A code example that does this can be found below\n\n```js\nimport { CarReader } from '@ipld/car';\nimport * as DID from '@ipld/dag-ucan/did';\nimport * as Delegation from '@ucanto/core/delegation';\nimport { importDAG } from '@ucanto/core/delegation';\nimport * as Signer from '@ucanto/principal/ed25519';\nimport * as Client from '@web3-storage/w3up-client';\n\nasync function backend(did: string) {\n // Load client with specific private key\n const principal = Signer.parse(process.env.KEY);\n const client = await Client.create({ principal });\n\n // Add proof that this agent has been delegated capabilities on the space\n const proof = await parseProof(process.env.PROOF);\n const space = await client.addSpace(proof);\n await client.setCurrentSpace(space.did());\n\n // Create a delegation for a specific DID\n const audience = DID.parse(did);\n const abilities = ['blob/add', 'index/add', 'filecoin/offer', 'upload/add'];\n const expiration = Math.floor(Date.now() / 1000) + 60 * 60 * 24; // 24 hours from now\n const delegation = await client.createDelegation(audience, abilities, {\n expiration,\n });\n\n // Serialize the delegation and send it to the client\n const archive = await delegation.archive();\n return archive.ok;\n}\n\n/** @param {string} data Base64 encoded CAR file */\nasync function parseProof(data) {\n const blocks = [];\n const reader = await CarReader.fromBytes(Buffer.from(data, 'base64'));\n for await (const block of reader.blocks()) {\n blocks.push(block);\n }\n return importDAG(blocks);\n}\n\nasync function frontend() {\n // Create a new client\n const client = await Client.create();\n\n // Fetch the delegation from the backend\n const apiUrl = `/api/w3up-delegation/${client.agent().did()}`;\n const response = await fetch(apiUrl);\n const data = await response.arrayBuffer();\n\n // Deserialize the delegation\n const delegation = await Delegation.extract(new Uint8Array(data));\n if (!delegation.ok) {\n throw new Error('Failed to extract delegation');\n }\n\n // Add proof that this agent has been delegated capabilities on the space\n const space = await client.addSpace(delegation.ok);\n client.setCurrentSpace(space.did());\n\n // READY to go!\n}\n```\n\n#### User-owned\n```mermaid\nsequenceDiagram\n participant User\n participant Application backend\n participant web3.storage w3up service\n Application backend->>User: Front end code that includes w3up-client\n User->>web3.storage w3up service: (If needed) Create Space and register it\n User->>web3.storage w3up service: (If needed) Use Agent email verification to \"log in\" to Space\n User->>web3.storage w3up service: Upload data using w3up-client\n```\n- If you want your user to own their own Space, you'll likely be relying on the `w3up-client` methods to create a Space, authorize the Space, and authorize the Agent on the end user-side; from there they can run any of the `upload` methods\n - Doing this does take some of the UX out of your control; for instance, when web3.storage fully launches with w3up, your users will have to set up their payment methods with web3.storage\n - Note that this alone does not give visibility into which of your end users are uploading what; to track this, you'll probably need them to send you that information separately (e.g., once they've run `upload` and get back a content CID, you can have them send that CID to you for tracking)\n- There is a world of possibilities with your users \"bringing their own identity\" for their Space; you could explore how crypto wallet private keys, Apple Passkey, and more might map to Space DIDs and have the client use those\n- If you have code snippet(s) that works for you, please share them in a PR or [Github issue](https://github.com/storacha/w3up/issues) and we'll link them here!\n\n### Environments requiring wasm import\n\nSome environments (for instance Cloudflare Workers) require wasm bytecode to be imported. All other paths to load wasmm are disallowed by embedder. For these use cases, the default export of `w3up-client` (most compatible) won't work out of the box. A custom build will need to be created to get the client working.\n\nWe created a `esbuild-plugin` [esbuild-plugin-w3up-client-wasm-import](https://github.com/vasco-santos/esbuild-plugin-w3up-client-wasm-import) that you can easily use. There is also an [example repository](https://github.com/vasco-santos/worker-w3up-client-example).\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- [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 w3up 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 concurrentRequests?: number\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 concurrentRequests?: number\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 concurrentRequests?: number\n rootCID?: CID\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\nfunction agent (): 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### `authorize`\n\n```ts\nfunction authorize (email: string, options?: { signal?: AbortSignal }): 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(name?: string, options?: {account: Account}): 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\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\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 (\n taskCid: CID\n): 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 (\n account: AccountDID\n): Promise\n```\n\nGet information about an account's billing plan.\n\n### `capability.plan.set`\n\n```ts\nfunction set (\n account: AccountDID,\n product: DID\n): 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: { 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 (\n content: CID,\n piece: PieceLink,\n): 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 (\n piece: PieceLink\n): Promise\n```\n\nGet know deals and aggregate info of a Filecoin \"piece\" previously offered.\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\nexport interface 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\nexport type Ability = `${string}/${string}` | \"*\"\n\nexport type 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 `@web3-storage/capabilities` package](https://github.com/storacha/w3up/tree/main/packages/capabilities) for more information about capabilities and how they are defined in w3up services.\n\n### `CARMetadata`\n\nMetadata pertaining to a CAR file.\n\n```ts\nexport interface 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### `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 `w3up-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 can be obtained from [`@web3-storage/access/stores`](https://github.com/storacha/w3up/tree/main/packages/access-client). They persist data created and managed by an agent.\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 /**\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 /**\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## Contributing\n\nFeel free to join in. All welcome. Please [open an issue](https://github.com/storacha/w3up/issues)!\n\n## License\n\nDual-licensed under [MIT + Apache 2.0](https://github.com/storacha/w3up/blob/main/packages/w3up-client/LICENSE.md)\n\n[w3cli-github]: https://github.com/storacha/w3cli\n[access-client-github]: https://github.com/storacha/w3up/tree/main/packages/access-client\n[upload-client-github]: https://github.com/storacha/w3up/tree/main/packages/upload-client\n[elastic-ipfs]: https://github.com/elastic-ipfs/elastic-ipfs\n[ucanto]: https://github.com/storacha/ucanto\n[car-spec]: https://ipld.io/specs/transport/car/\n[web3storage-docs-cars]: https://web3.storage/docs/concepts/car/\n\n[docs]: https://web3-storage.github.io/w3up/modules/_web3_storage_w3up_client.html\n[docs-Client]: https://web3-storage.github.io/w3up/classes/_web3_storage_w3up_client.Client.html\n[docs-Client#agent]: https://web3-storage.github.io/w3up/classes/_web3_storage_w3up_client.Client.html#agent\n[docs-Client#createDelegation]: https://web3-storage.github.io/w3up/classes/_web3_storage_w3up_client.Client.html#createDelegation\n[docs-Client#createSpace]: https://web3-storage.github.io/w3up/classes/_web3_storage_w3up_client.Client.html#createSpace\n[docs-Client#setCurrentSpace]: https://web3-storage.github.io/w3up/classes/_web3_storage_w3up_client.Client.html#setCurrentSpace\n[docs-Client#uploadFile]: https://web3-storage.github.io/w3up/classes/_web3_storage_w3up_client.Client.html#uploadFile\n[docs-Client#uploadDirectory]: https://web3-storage.github.io/w3up/classes/_web3_storage_w3up_client.Client.html#uploadDirectory\n[docs-Space]: https://web3-storage.github.io/w3up/modules/_web3_storage_access.Space.html\n\n[docs-create]: #create\n[docs-ClientFactoryOptions]: https://web3-storage.github.io/w3up/interfaces/_web3_storage_w3up_client.unknown.ClientFactoryOptions.html\n\n[access-docs-Agent]: https://web3-storage.github.io/w3up/classes/_web3_storage_access.Agent.html\n","readmeFilename":"README.md"}
![](\"https://bafybeia4luuns6dgymy5kau5rm7r4qzrrzg6cglpzpogussprpy42cmcn4.ipfs.w3s.link/w3up-logo.png\"){kind=logo}
![\"GitHub](\"https://img.shields.io/github/actions/workflow/status/storacha/w3up/w3up-client.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-web3storage-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}