feat: updated README instructions for MVP (#85)

* feat: updated README instructions for MVP * fix: mistakenly deleted a line * feat: add placeholder for GH discussions * feat: new ToS link * fix: no beta in ToS URL * feat: include updated ToS links * feat: make README shippable * feat: add provider optional parameter --------- Co-authored-by: Alan Shaw <alan.shaw@protocol.ai>
storacha · Mar 24, 2023 · 0d0a038 · 0d0a038
1 parent cc3955f
commit 0d0a038
Showing 1 changed file with 56 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 </p>
 
 > ### ⚠️❗ w3up-client and the underlying APIs are currently beta preview features
-> Please read the beta [Terms of Service](https://purrfect-tracker-45c.notion.site/w3up-beta-Terms-of-Service-39cb5c13439849beae327a2efec9164a) for more details.
+> Please read the beta Terms of Service ([web3.storage](https://console.web3.storage/terms), [NFT.Storage](https://console.nft.storage/terms)) for more details.
 >
 > Open an issue on the repo or reach out to the #web3-storage channel on [IPFS Discord](https://docs.ipfs.tech/community/chat/#discord) if you have any 
 questions!
@@ -19,13 +19,18 @@ questions!
 
 This 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.
 
+> ⚠️❗ __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.
+
+> ⚠️❗ __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.
+
 - [Install](#install)
 - [Usage](#usage)
   - [Core concepts](#core-concepts)
   - [Basic usage](#basic-usage)
     - [Creating a client object](#creating-a-client-object)
     - [Creating and registering Spaces](#creating-and-registering-spaces)
     - [Uploading data](#uploading-data)
+  - [Alternate implementation options](#alternate-implementation-options) - _Coming soon!_
 - [API](#api)
 - [Contributing](#contributing)
 - [License](#license)
@@ -70,6 +75,23 @@ Agents and Spaces are both generated by `w3up-client` on the user's local machin
 
 This section shows some of the basic operations available in the `w3up-client` package. See the [API reference docs][docs] or the source code of the [`w3up-cli` package][w3up-cli-github], which uses `w3up-client` throughout.
 
+Before data can be uploaded via the client, the client needs to have permissions to upload to the target service either by having permissions to a registered `Space`. This means either you (the developer) or your user needs to have a registered Space.
+
+Currently, `w3up-client` offers as defaults two beta services to register Spaces with and upload data to that the w3up core maintainers also run: 
+- [web3.storage](http://web3.storage) w3up beta: A developer storage platform for any data
+- [NFT.Storage](http://NFT.Storage) w3up beta: A free service for archiving specifically off-chain NFT data
+
+However, `w3up-client` can be used for any service that complies to the w3up [specs](https://github.com/web3-storage/specs) and [protocol](https://github.com/web3-storage/w3protocol/).
+
+> By you or your users registering a w3up beta Space via email confirmation with either [NFT.Storage](http://NFT.Storage) or [web3.storage](http://web3.storage), you agree to the relevant w3up beta Terms of Service ([web3.storage](https://console.web3.storage/terms), [NFT.Storage](https://console.nft.storage/terms)). If you have an existing non-w3up beta account with NFT.Storage or web3.storage and register for the w3up beta version of the same product (NFT.Storage or web3.storage) using the same email, then at the end of the beta period, these accounts will be combined. Until the beta period is over and this migration occurs, uploads to w3up will not appear in your NFT.Storage or web3.storage account (and vice versa), even if you register with the same email (_coming soon!_).
+
+In terms of whether you or your user should register the Space (and more broadly how to integrate `w3up-client`), there are three general wasy to integrate.
+- (Simplest) Client-server: You (the developer) own the Space and register it with the service of your choosing, and your user uploads to your backend infra before you upload it to the service
+- (More complex) [Server-owned space with direct upload from end-user](#server-owned-space-with-direct-upload-from-end-user): You own the Space and register it with the service of your choosing, but you give a delegated UCAN token to your user to upload directly to the service
+- (Most complex) [User-owned](#user-owned): Your user owns the Space and registers it (likely with the service you choose for them in your code, but not necessarily), 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)
+
+The first and simplest of these options (client-server) is covered in-depth in this section, though the other two options are discussed further down in the README as well.
+
 #### Creating a client object
 
 The package provides a [static `create` function][docs-create] that returns a [`Client` object][docs-Client]. 
@@ -108,9 +130,7 @@ await client.capability.access.claim()
 
 #### Creating and registering Spaces
 
-Before you can upload data, you'll need to create a [`Space`][docs-Space] and register it with the service.
-
-A Space acts as a namespace for your uploads. Spaces are created using the [`createSpace` client method][docs-client#createSpace]:
+Before you can upload data, you'll need to create a [`Space`][docs-Space] and register it with the service. A Space acts as a namespace for your uploads. Spaces are created using the [`createSpace` client method][docs-client#createSpace]:
 
 ```js
 const space = await client.createSpace('my-awesome-space')
@@ -136,6 +156,16 @@ try {
 }
 ```
 
+By default, calling `registerSpace` registers the Space with web3.storage w3up. You can pass the optional `provider` param to register with NFT.Storage w3up instead.
+
+```js
+try {
+  await client.registerSpace('zaphod@beeblebrox.galaxy', { provider: 'did:web:nft.storage' })
+} catch (err) {
+  console.error('registration failed: ', err)
+}
+```
+
 #### Uploading data
 
 Once you've [authorized](#authorizing-your-agent), [created and registered a space](#creating-and-registering-spaces), you can upload files to the w3up platform.
@@ -168,6 +198,25 @@ In the example above, `directoryCid` resolves to an IPFS directory with the foll
 └── src
     └── main.py
 ```
+### Alternate implementation options
+
+As discussed above, there are options outside the traditional client-server model that w3up supports. We how to use `w3up-client` to achieve these options in this section.
+
+#### Server-owned space with direct upload from end-user
+
+In this option, you (the developer) own your Space, but delegate permissions to your users to directly upload content to the service on your behalf. This isn’t completely “serverless” - you still need some infrastructure to create delegated UCAN tokens, but it’s minimal, and potentially saves a ton of bandwidth and overhead.
+
+> 🔜 _More detail coming soon!_
+
+If you explore this option, contributions are welcome to these docs to help others in the future (and to reveal feature requests and bugs that we can patch to improve this implementation path)! Also feel free to chime into the discussion [here](https://github.com/web3-storage/w3up-client/discussions/92).
+
+#### User-owned
+
+In this option, your user owns their own Space. This option is the most web3-native (since your user owns their own identity, and thus their own data) and probably the most interesting one. It comes with a world of possibilities; for instance, instead of generating  a new Space keypair for your user, you might look into using the existing keypair from their Metamask wallet or Apple Passkey. However, there are also likely edge cases that will appear early on for developers developing these types of apps that we haven’t had a chance to think much about yet, best-practices for various requirements (e.g., how much visibility do you want into user activity), and useful features that we could support.
+
+> 🔜 _More detail coming soon!_
+
+If you explore this option, contributions are welcome to these docs to help others in the future (and to reveal feature requests and bugs that we can patch to improve this implementation path)! Also feel free to chime into the discussion [here](https://github.com/web3-storage/w3up-client/discussions/93).
 
 ## API
 
@@ -340,12 +389,15 @@ Create a new space with an optional name.
 ```ts
 async function registerSpace (
   email: string,
+  provider?: string,
   options?: { signal?: AbortSignal }
 ): Promise<Space>
 ```
 
 Register the _current_ space with the service.
 
+By default, the provider is set to web3.storage w3up, but you can register instead of NFT.Storage w3up by setting `provider` to `did:web:nft.storage`.
+
 ### `addSpace`
 
 ```ts