In late September, we launched the beta version of w3up with a new client and command line tools. This was a significant upgrade since it introduced UCANs, and our new frontend toolkit, w3ui. You might recall that UCANs allow for permission and authorization delegation without relying on a central authority, and w3ui is designed to make writing applications using web3.storage super easy.

w3up-client version 4.0.0 introduces some major API changes, as we’ve refined and iterated on some of our core components.

We think these updates will make your web3.storage experience one that is simpler, faster, and more scalable – and enable builders to integrate the service directly with apps. Further, these changes will also set the foundation for updates and upgrades we are eyeing in 2023 👀. This would not have been possible without feedback from our users, so we wanted to thank you for helping us make w3up better!

If you’ve already built and shipped an app using the previous version of w3up-client, don’t worry, it will still work 😎. We did not change any of the live endpoints; however, the latest w3up-client talks to the new API, so if you upgrade, check out the list of breaking changes.

This update changes some of the terminology that you would’ve become familiar with in the previous w3up-client. We are no longer using the term accounts. Spaces replace the accounts that were used for a similar purpose in previous versions of the client. To create and register a space, you need to create an Agent. Now let’s dive into the updates!

First, we’ve made creating and using a client much simpler, with sensible defaults:

import { create } from '@web3-storage/w3up-client'

const client = await create()

This automatically creates a new Agent, which is a new component in charge of signing requests and managing your local configuration data.

One of the things that Agents manage is a collection of Spaces, which are used to group your uploads into namespaces. When you upload files, the DID of your currently active Space is included with the request and associated with your upload.

To get started uploading, you’ll need to create and register at least one Space:

const space = await client.createSpace()
await client.setCurrentSpace(space.did())

try {
  await client.registerSpace('you@email.host')
} catch (err) {
  console.error('registration failed:', err)
}

That will cause an email with a verification link to be sent to the given address. Once the email is verified, you can upload files with client.uploadFile or client.uploadDirectory.

We’ve also made a few changes to the delegation methods, mostly to bring them in line with the new Space-based world. See the list of breaking changes below for details.

Finally, we’ve moved some of the more advanced functionality into the client.capability API, which exposes the underlying capability-based ucanto API via methods that are configured to use your client’s Agent to make authenticated requests to the w3up service.

Breaking changes

  • client.account() has been removed, use client.currentSpace()
  • client.exportDelegation() has been removed, use client.createDelegation() and then call export() on the returned value and encode the returned blocks as a CAR file using the @ipld/car library.
  • client.identity() has been removed, use client.agent() + client.currentSpace() + client.delegations()
  • client.importDelegation() has been removed, use client.addProof() (for general delegations to your agent) or client.addSpace() (to add a proof and also add the space to your list of spaces).
  • client.insights() has been removed - this was never working
  • client.invoke() has been removed
  • client.list() has been removed, use client.capability.upload.list()
  • client.makeDelegation() has been renamed and signature has changed, use client.createDelegation()
  • client.register() has been removed, use client.registerSpace()
  • client.remove() has been removed, use client.capability.store.remove()
  • client.removeUpload() has been removed, use client.capability.upload.remove()
  • client.stat() has been removed, use client.capability.store.list()
  • client.upload() has been removed, use client.capability.store.add()
  • client.uploadAdd() has been removed, use client.capability.upload.add()
  • client.whoami() has been removed, use client.capability.space.info()

For more information on the changes made this week and our future plans, please check out this week’s newsletter!