-
Notifications
You must be signed in to change notification settings - Fork 23
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge remote-tracking branch 'origin/main' into feat/coupon
- Loading branch information
Showing
18 changed files
with
177 additions
and
64 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,10 @@ | ||
| { | ||
| "packages/access-client": "17.0.0", | ||
| "packages/filecoin-api": "4.1.0", | ||
| "packages/filecoin-client": "3.1.0", | ||
| "packages/capabilities": "11.4.0", | ||
| "packages/upload-api": "7.3.1", | ||
| "packages/access-client": "17.1.0", | ||
| "packages/filecoin-api": "4.1.1", | ||
| "packages/filecoin-client": "3.1.1", | ||
| "packages/capabilities": "11.4.1", | ||
| "packages/upload-api": "7.3.2", | ||
| "packages/upload-client": "12.0.0", | ||
| "packages/w3up-client": "10.2.0", | ||
| "packages/w3up-client": "10.3.0", | ||
| "packages/did-mailto": "2.0.2" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| # `w3up` | ||
|
|
||
| This repo implements the web3.storage UCAN protocol [specifications](https://github.com/web3-storage/specs). | ||
|
|
||
| It's the core of the web3.storage server and client implementations. | ||
|
|
||
| ## Usage | ||
|
|
||
| Store your files with web3.storage and retrieve them via their unique Content ID. Our tools make it simple to hash your content locally, so you can verify the service only ever stores the exact bytes you asked us to. Pick the method of using web3.storage that works for you! | ||
|
|
||
| ### Website | ||
|
|
||
| Visit https://console.web3.storage and upload right from the website. | ||
|
|
||
| Under the hood it uses the web3.storage client that we publish to npm to chunk and hash your files to calculate the root IPFS CID **in your browser** before sending them to https://up.web3.storage. | ||
|
|
||
| Once uploaded you can fetch your data from any IPFS gateway via [`https://w3s.link/ipfs/<root cid>`](https://w3s.link/ipfs/bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy) | ||
|
|
||
| ### JS Client | ||
|
|
||
| Add the [`@web3-storage/w3up-client`](https://www.npmjs.com/package/@web3-storage/w3up-client) module into your project, authorize the agent to act on your behalf, create and register a Space, and start uploading files from node.js or the browser. | ||
|
|
||
| **node.js** | ||
| ```js | ||
| import { getFilesFromPaths } from 'files-from-path' | ||
| import { create } from '@web3-storage/w3up-client' | ||
|
|
||
| // authorize your local agent to act on your behalf | ||
| const client = await create() | ||
| await client.authorize('[email protected]') | ||
|
|
||
| // create a Space, a decentralized bucket for your files | ||
| const space = await client.createSpace('my-awesome-space') | ||
| await client.setCurrentSpace(space.did()) | ||
|
|
||
| // lets go! | ||
| const files = await getFilesFromPaths(process.env.PATH_TO_ADD) | ||
| const cid = await client.uploadDirectory(files) | ||
|
|
||
| console.log(`Space DID: ${space.did()}`) | ||
| console.log(`IPFS CID: ${cid}`) | ||
| console.log(`Gateway URL: https://w3s.link/ipfs/${cid}`) | ||
| ``` | ||
|
|
||
| See https://web3.storage/docs/w3up-client for a guide to using the js client for the first time. | ||
|
|
||
| ### Command Line | ||
|
|
||
| Install [`@web3-storage/w3cli`](https://github.com/web3-storage/w3cli#readme) globally, authorize it to act on your behalf, create a space and upload your files. It calculates the root CID for your files locally before sending them to web3.storage. | ||
|
|
||
| **shell** | ||
| ```shell | ||
| # install from npm. don't forget -g | ||
| $ npm install -g @web3-storage/w3cli | ||
|
|
||
| # verify your email | ||
| $ w3 authorize [email protected] | ||
|
|
||
| # create a Space, a DID namespace for your files... like a bucket. | ||
| $ w3 space create Documents | ||
|
|
||
| # lets go! | ||
| $ w3 up ~/Pictures/ayy-lamo.jpg | ||
| ⁂ Stored 1 file | ||
| ⁂ https://w3s.link/ipfs/bafybeid6gpbsqkpfrsx6b6ywrt24je4xqe4eo4y2wldisl6sk7byny5uky | ||
| ``` | ||
|
|
||
| Run `w3 --help` or have a look at https://github.com/web3-storage/w3cli to find out everything it can do. | ||
|
|
||
| ## Contributing | ||
|
|
||
| All welcome! web3.storage is open-source. See the [contributing guide](./CONTRIBUTING.md) | ||
|
|
||
| This project uses node v18 and `pnpm`. It's a monorepo that uses [pnpm workspaces](https://pnpm.io/workspaces) to handle resolving dependencies between the local [`packages`](https://github.com/web3-storage/w3up/tree/main/packages) | ||
|
|
||
| ## License | ||
|
|
||
| Dual-licensed under [MIT + Apache 2.0](license.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -7,12 +7,6 @@ | |
| <a href="https://github.com/web3-storage/w3up-client/blob/main/LICENSE.md"><img alt="License: Apache-2.0 OR MIT" src="https://img.shields.io/badge/LICENSE-Apache--2.0%20OR%20MIT-yellow?style=for-the-badge" /></a> | ||
| </p> | ||
|
|
||
| > ### ⚠️❗ w3up-client and the available hosted APIs are currently beta preview features | ||
| > Please read the beta [Terms of Service](https://console.web3.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! | ||
|
|
||
| ## About | ||
|
|
||
| `@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. | ||
|
|
@@ -82,21 +76,21 @@ To invoke a capability like `store/add` on a Space using `w3up-client`, the clie | |
|
|
||
| The 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. | ||
|
|
||
| The 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 (`authorize(email)` then `capability.access.claim`) or directly if you have the UCAN delegation available locally (`addSpace(delegation)`). | ||
| The 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)`). | ||
|
|
||
| ### Basic usage with web3.storage | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| A[w3up-client instance] -->|Automatic if specific Agent is not passed when client object created|B(Create local Agent DID and key) | ||
| B --> |If Space has not yet been created|S(Create local Space, authorize client with your email address, and register Space + email address with web3.storage) | ||
| 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) | ||
| S --> C(Get UCAN delegation from Space to Agent) | ||
| C --> D(Upload to Space using Agent) | ||
| ``` | ||
|
|
||
| All 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/web3-storage/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 [`w3up-cli` package][w3up-cli-github], which uses `w3up-client` throughout. | ||
|
|
||
| > By you or your users registering a w3up beta Space via email confirmation with [web3.storage](http://web3.storage), you agree to the beta [Terms of Service](https://console.web3.storage/terms). Uploads to w3up will not appear in your web3.storage account (and vice versa). | ||
| > 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/). | ||
| #### Creating a client object | ||
|
|
||
|
|
@@ -124,10 +118,10 @@ Once initialized, you can access the client's `Agent` with the [`agent()` access | |
|
|
||
| #### Creating and registering Spaces | ||
|
|
||
| A [`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 authorize your Agent with your email address. Calling `authorize` will cause an email to be sent to the given address. Once a user clicks the confirmation link in the email, the `authorize` method will resolve. Make sure to check for errors, as `authorize` will fail if the email is not confirmed within the expiration timeout. Authorization needs to happen only once per agent. | ||
| A [`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. | ||
|
|
||
| ```js | ||
| await client.authorize('[email protected]') | ||
| await client.login('[email protected]') | ||
| ``` | ||
|
|
||
| Spaces can be created using the [`createSpace` client method][docs-client#createSpace]: | ||
|
|
@@ -148,7 +142,7 @@ First, set the space as your "current" space using the [`setCurrentSpace` method | |
| await client.setCurrentSpace(space.did()) | ||
| ``` | ||
|
|
||
| Next, call the [`registerSpace` method][docs-Client#registerSpace], which registers the Space with web3.storage and associates it with the email address you authorized: | ||
| Next, call the [`registerSpace` method][docs-Client#registerSpace], which registers the Space with web3.storage and associates it with the email address you login: | ||
|
|
||
| ```js | ||
| try { | ||
|
|
@@ -160,10 +154,10 @@ try { | |
|
|
||
| #### Delegating from Space to Agent | ||
|
|
||
| In order to store data with w3up, your Agent will need a delegation from a Space. This automatically happens if you called `authorize(email)` then `registerSpace()`. However, if you are initializing the client with a previously created Space, you can `authorize(email)` then claim a delegation granted to the account associated with your email: | ||
| In order to store data with w3up, your Agent will need a delegation from a Space. This automatically happens if you called `login(email)` then `registerSpace()`. 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: | ||
|
|
||
| ```js | ||
| await client.authorize('[email protected]') | ||
| await client.login('[email protected]') | ||
| await capability.access.claim() | ||
| await client.setCurrentSpace(space.did()) # select the relevant Space DID that is associated with your account | ||
| ``` | ||
|
|
@@ -292,7 +286,7 @@ sequenceDiagram | |
| - 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)) | ||
| - 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., `store/add`, `upload/add`, expiration time) | ||
| - You can serialize this using `delegation.archive()` and send it to your user | ||
| - The end user instance of the client should not need to call `client.authorize(email)`, as it is not claiming any delegations via email address (but rather getting the delegation directly from your backend) | ||
| - 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) | ||
| - Once your user receives the delegation, they can deserialize it using [`ucanto.Delegation.extract()`](https://github.com/web3-storage/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 | ||
| - 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) | ||
| - A code example that does this can be found below | ||
|
|
@@ -386,7 +380,7 @@ sequenceDiagram | |
| - [`uploadFile`](#uploadfile) | ||
| - [`uploadCAR`](#uploadcar) | ||
| - [`agent`](#agent) | ||
| - [`authorize`](#authorize) | ||
| - [`login`](#login) | ||
| - [`accounts`](#accounts) | ||
| - [`currentSpace`](#currentspace) | ||
| - [`setCurrentSpace`](#setcurrentspace) | ||
|
|
||
Oops, something went wrong.