From 8699b402e0eea625444496845ba8035a32fbb984 Mon Sep 17 00:00:00 2001 From: Yusef Napora Date: Fri, 2 Dec 2022 10:27:38 -0500 Subject: [PATCH] docs: update docs for new ucanto integration (#135) This updates the markdown docs based on the changes in #119. I _think_ I got everything, but @alanshaw should probably take a look :) Co-authored-by: Alan Shaw --- docs/keyring-core.md | 152 ++++++++++++++++++++++++++++++++++++- docs/react-keyring.md | 76 +++++-------------- docs/react-uploader.md | 31 ++------ docs/react-uploads-list.md | 41 +++------- docs/solid-keyring.md | 77 +++++-------------- docs/solid-uploader.md | 32 ++------ docs/solid-uploads-list.md | 34 +++++++-- docs/uploader-core.md | 78 +++++-------------- docs/uploads-list-core.md | 59 ++++++++++++-- docs/vue-keyring.md | 94 ++++++----------------- docs/vue-uploader.md | 42 +++------- docs/vue-uploads-list.md | 40 +++------- 12 files changed, 345 insertions(+), 411 deletions(-) diff --git a/docs/keyring-core.md b/docs/keyring-core.md index e8da344a..cf0cd4c4 100644 --- a/docs/keyring-core.md +++ b/docs/keyring-core.md @@ -5,7 +5,6 @@ ```sh npm install @w3ui/keyring-core ``` - ## Usage ```js @@ -14,14 +13,161 @@ import * as KeyringCore from '@w3ui/keyring-core' ## Exports -* [`createAgent`](#createagent) +**Interfaces** + +- [`KeyringContextState`](#keyringcontextstate) +- [`KeyringContextActions`](#keyringcontextactions) + +**Classes** + +- [`Space`](#space) + - [`name`](#name) + - [`did`](#did) + - [`registered`](#registered) + - [`meta`](#meta) + +**Functions** + +- [`createAgent`](#createagent) +- [`getCurrentSpace`](#getcurrentspace) +- [`getSpaces`](#getspaces) --- +### `KeyringContextState` + +Interface for keyring state. Implementations are framework-specific and found in each framework's `-keyring` module (e.g. `@w3ui/react-keyring`). + +```ts +export interface KeyringContextState { + /** + * The current space. + */ + space?: Space + /** + * Spaces available to this agent. + */ + spaces: Space[] + /** + * The current user agent (this device). + */ + agent?: Signer +} +``` + +### `KeyringContextActions` + +Interface for keyring actions. Implementations are framework-specific and found in each framework's `-keyring` module (e.g. `@w3ui/react-keyring`). + +```ts +export interface KeyringContextActions { + /** + * Load the user agent and all stored data from secure storage. + */ + loadAgent: () => Promise + /** + * Unload the user agent and all stored data from secure storage. Note: this + * does not remove data, use `resetAgent` if that is desired. + */ + unloadAgent: () => Promise + /** + * Unload the current space and agent from memory and remove from secure + * storage. Note: this removes all data and is unrecoverable. + */ + resetAgent: () => Promise + /** + * Create a new space with the passed name and set it as the current space. + */ + createSpace: (name?: string) => Promise + /** + * Use a specific space. + */ + setCurrentSpace: (did: DID) => Promise + /** + * Register the current space, verify the email address and store in secure + * storage. Use cancelRegisterSpace to abort. Automatically sets the + * newly registered space as the current space. + */ + registerSpace: (email: string) => Promise + /** + * Abort an ongoing account registration. + */ + cancelRegisterSpace: () => void, + /** + * Get all the proofs matching the capabilities. Proofs are delegations with + * an audience matching the agent DID. + */ + getProofs: (caps: Capability[]) => Promise +} +``` + +### `Space` + +A subclass of ucanto's `Principal` type that represents a storage location uniquely identified by its DID. + +A `Space` has the following methods: + +#### `name` + +```ts +name(): String +``` + +Returns the "friendly" name for the space, or the space DID if no name is set. + +#### `did` + +```ts +did(): DID +``` + +Returns the DID string for the space. + +#### `registered` + +```ts +registered(): Boolean +``` + +Returns `true` if the space has been registered with the service. + +#### `meta` + +```ts +meta(): Record +``` + +Returns user-defined metadata attached to the space. + ### `createAgent` ```ts -createAgent (options: { url?: URL } = {}): Promise> +createAgent (options: CreateAgentOptions = {}): Promise> ``` Create the user agent and load account information from secure storage. + +`CreateAgentOptions` accepts the following fields: + +| field | type | description | +| ------------------ | ----------------------- | ---------------------------------------------------- | +| `servicePrincipal` | ucanto `Principal` | contains the DID & public key for the access service | +| `connection` | ucanto `ConnectionView` | a connection to the access service | + +If `servicePrincipal` or `connection` are not provided, defaults to the production service. + +### `getCurrentSpace` + +```ts +getCurrentSpace(agent: Agent): Space | undefined +``` + +Returns the given `agent`'s current space, or `undefined` if the agent has no current space set. + +### `getSpaces` + +```ts +getSpaces(agent: Agent): Space[] +``` + +Returns an array of all spaces that the agent has access to. diff --git a/docs/react-keyring.md b/docs/react-keyring.md index 00a1b92a..f14762a8 100644 --- a/docs/react-keyring.md +++ b/docs/react-keyring.md @@ -14,84 +14,44 @@ import * as ReactKeyring from '@w3ui/react-keyring' ## Exports -* [`AuthProvider`](#authprovider) -* [`useAuth`](#useauth) +* [`KeyringProvider`](#keyringprovider) +* [`useKeyring`](#usekeyring) --- -### `AuthProvider` +### `KeyringProvider` -Provider for authentication with the service. +Provider for managing agent creation, key management, and space registration with the service. Example: ```jsx -import { AuthProvider } from '@w3ui/react-keyring' +import { KeyringProvider } from '@w3ui/react-keyring' function App () { return ( - + {/* Application pages/components */} - + ) } ``` -### `useAuth` +You can optionally target a non-production instance of the access service by setting the `servicePrincipal` and `connection` props on `KeyringProvider`. The `servicePrincipal` should be set to the service's DID, and `connection` should be a ucanto `ConnectionView` to the service instance. + +### `useKeyring` ```ts -const auth = useAuth() +const [keyringState, keyringActions] = useKeyring() ``` -Hook to allow use of the [`AuthProvider`](#authprovider) value. The value returned is an `AuthContextValue`: +Hook to allow use of the [`KeyringProvider`](#keyringprovider) value. The value returned is a `KeyringContextValue`: ```ts -interface AuthContextState { - /** - * The current user account. - */ - readonly account?: DID - /** - * The current user agent (this device). - */ - readonly agent?: DID - /** - * Signing authority from the agent that is able to issue UCAN invocations. - */ - readonly issuer?: Signer - /** - * Authentication status of the current identity. - */ - readonly authStatus: AuthStatus -} - -interface AuthContextValue extends AuthContextState { - /** - * Load the user agent and all stored data from secure storage. - */ - loadAgent: () => Promise - /** - * Unload the user agent and all stored data from secure storage. Note: this - * does not remove data, use `resetAgent` if that is desired. - */ - unloadAgent: () => Promise - /** - * Unload the current account and agent from memory and remove from secure - * storage. Note: this removes all data and is unrecoverable. - */ - resetAgent: () => Promise - /** - * Use a specific account. - */ - selectAccount: (did: DID) => Promise - /** - * Register a new account, verify the email address and store in secure - * storage. Use cancelRegisterAccount to abort. - */ - registerAccount: (email: string) => Promise - /** - * Abort an ongoing account registration. - */ - cancelRegisterAccount: () => void -} +export type KeyringContextValue = [ + state: KeyringContextState, + actions: KeyringContextActions +] ``` + +See [keyring-core.md](./keyring-core.md) for the definitions for [`KeyringContextState`](./keyring-core.md#keyringcontextstate) and [`KeyringContextActions`](./keyring-core.md#keyringcontextactions). diff --git a/docs/react-uploader.md b/docs/react-uploader.md index 0981485d..8ea40638 100644 --- a/docs/react-uploader.md +++ b/docs/react-uploader.md @@ -21,7 +21,7 @@ import * as ReactUploader from '@w3ui/react-uploader' ### `UploaderProvider` -Provider for an `Uploader` which allows uploads to the service. Note that this provider uses [`useAuth`](./react-keyring#useauth) and provides an `uploader` only when a current identity is loaded. +Provider for an `Uploader` which allows uploads to the service. Note that this provider uses [`useKeyring`](./react-keyring#usekeyring) and provides an `uploader` only when an Agent with a registered space is loaded. Example: @@ -37,10 +37,12 @@ function App () { } ``` +You can optionally target a non-production instance of the upload service by setting the `servicePrincipal` and `connection` props on `UploaderProvider`. The `servicePrincipal` should be set to the service's DID, and `connection` should be a ucanto `ConnectionView` to the service instance. + ### `useUploader` ```ts -const [progress, uploader] = useUploader() +const [uploaderState, uploaderActions] = useUploader() ``` Hook to allow use of the [`UploaderProvider`](#uploaderprovider) value. The value returned is an `UploaderContextValue`: @@ -50,29 +52,6 @@ type UploaderContextValue = [ state: UploaderContextState, actions: UploaderContextActions ] - -interface UploaderContextState { - storedDAGShards: CARMetadata[] -} - -interface UploaderContextActions { - /** - * Upload a single file to the service. - */ - uploadFile: (file: Blob) => Promise - /** - * Upload a directory of files to the service. - */ - uploadDirectory: (files: File[]) => Promise - /** - * Store a DAG (encoded as a CAR file) to the service. - */ - storeDAG: (data: Blob) => Promise - /** - * Register an "upload" with the service. Note: only required when using - * `storeDAG`. - */ - registerUpload: (root: CID, shards: CID[]) => Promise -} ``` +See [uploader-core.md](./uploader-core.md) for the definitions for [`UploaderContextState`](./uploader-core.md#uploadercontextstate) and [`UploaderContextActions`](./uploader-core.md#uploadercontextactions). \ No newline at end of file diff --git a/docs/react-uploads-list.md b/docs/react-uploads-list.md index bfde90db..57ac793b 100644 --- a/docs/react-uploads-list.md +++ b/docs/react-uploads-list.md @@ -21,7 +21,7 @@ import * as ReactUploadsList from '@w3ui/react-uploads-list' ### `UploadsListProvider` -Provider for a list of items uploaded by the current identity. Note that this provider uses [`useAuth`](./react-keyring#useauth) to obtain the current identity. +Provider for a list of items uploaded by the current agent. Note that this provider uses [`useKeyring`](./react-keyring#usekeyring) to obtain the current agent's identity. Example: @@ -37,44 +37,21 @@ function App () { } ``` +You can optionally target a non-production instance of the upload service by setting the `servicePrincipal` and `connection` props on `UploadsListProvider`. The `servicePrincipal` should be set to the service's DID, and `connection` should be a ucanto `ConnectionView` to the service instance. + ### `useUploadsList` ```ts -const { data, loading, error, reload } = useUploadsList() +const [uploadsListState, uploadsListActions] = useUploadsList() ``` Hook to allow use of the [`UploadsListProvider`](#uploadslistprovider) value. The value returned is an `UploaderContextValue`: ```ts -interface UploadsListContextValue { - /** - * True if the uploads list is currentky being retrieved from the service. - */ - loading: boolean - /** - * Set if an error occurred retrieving the uploads list. - */ - error?: Error - /** - * The content of the uploads list. - */ - data?: ListPage - /** - * Call to reload the uploads list. - */ - reload: () => Promise -} - -interface ListPage { - page: number; - pageSize: number; - results: ListResult[]; -} - -interface ListResult { - dataCid: CID; - carCids: CID[]; - uploadedAt: Date; -} +export type UploadsListContextValue = [ + state: UploadsListContextState, + actions: UploadsListContextActions +] ``` +See [uploads-list-core.md](./uploads-list-core.md) for the definitions for [`UploadsListContextState`](./uploads-list-core.md#uploadslistcontextstate) and [`UploadsListContextActions`](./uploads-list-core.md#uploadslistcontextactions). diff --git a/docs/solid-keyring.md b/docs/solid-keyring.md index 91f5603e..09faad62 100644 --- a/docs/solid-keyring.md +++ b/docs/solid-keyring.md @@ -14,87 +14,44 @@ import * as SolidKeyring from '@w3ui/solid-keyring' ## Exports -* [`AuthProvider`](#authprovider) -* [`useAuth`](#useauth) +* [`KeyringProvider`](#keyringprovider) +* [`useKeyring`](#usekeyring) --- -### `AuthProvider` +### `KeyringProvider` -Provider for authentication with the service. +Provider for managing agent creation, key management, and space registration with the service. Example: ```jsx -import { AuthProvider } from '@w3ui/solid-keyring' +import { KeyringProvider } from '@w3ui/solid-keyring' function App () { return ( - + {/* Application pages/components */} - + ) } ``` -### `useAuth` +You can optionally target a non-production instance of the access service by setting the `servicePrincipal` and `connection` props on `KeyringProvider`. The `servicePrincipal` should be set to the service's DID, and `connection` should be a ucanto `ConnectionView` to the service instance. + +### `useKeyring` ```ts -const [state, actions] = useAuth() +const [state, actions] = useKeyring() ``` -Hook to allow use of the [`AuthProvider`](#authprovider) value. The value returned is an `AuthContextValue`: +Hook to allow use of the [`KeyringProvider`](#keyringprovider) value. The value returned is a `KeyringContextValue`: ```ts -interface AuthContextState { - /** - * The current user account. - */ - readonly account?: DID - /** - * The current user agent (this device). - */ - readonly agent?: DID - /** - * Signing authority from the agent that is able to issue UCAN invocations. - */ - readonly issuer?: Signer - /** - * Authentication status of the current identity. - */ - readonly status: AuthStatus -} - -type AuthContextValue = [ - state: AuthContextState, - actions: { - /** - * Load the user agent and all stored data from secure storage. - */ - loadAgent: () => Promise - /** - * Unload the user agent and all stored data from secure storage. Note: this - * does not remove data, use `resetAgent` if that is desired. - */ - unloadAgent: () => Promise - /** - * Unload the current account and agent from memory and remove from secure - * storage. Note: this removes all data and is unrecoverable. - */ - resetAgent: () => Promise - /** - * Use a specific account. - */ - selectAccount: (did: DID) => Promise - /** - * Register a new account, verify the email address and store in secure - * storage. Use cancelRegisterAccount to abort. - */ - registerAccount: (email: string) => Promise - /** - * Abort an ongoing account registration. - */ - cancelRegisterAccount: () => void - } +export type KeyringContextValue = [ + state: KeyringContextState, + actions: KeyringContextActions ] ``` + +See [keyring-core.md](./keyring-core.md) for the definitions for [`KeyringContextState`](./keyring-core.md#keyringcontextstate) and [`KeyringContextActions`](./keyring-core.md#keyringcontextactions). diff --git a/docs/solid-uploader.md b/docs/solid-uploader.md index 4d55247b..d8fb89b5 100644 --- a/docs/solid-uploader.md +++ b/docs/solid-uploader.md @@ -21,7 +21,7 @@ import * as SolidUploader from '@w3ui/solid-uploader' ### `UploaderProvider` -Provider for an `Uploader` which allows uploads to the service. Note that this provider uses [`useAuth`](./solid-keyring#useauth) and provides an `uploader` that allows uploads only when a current identity is loaded. +Provider for an `Uploader` which allows uploads to the service. Note that this provider uses [`useKeyring`](./solid-keyring#usekeyring) and provides an `uploader` that allows uploads only when an Agent with a registered space is loaded. Example: @@ -37,10 +37,12 @@ function App () { } ``` +You can optionally target a non-production instance of the upload service by setting the `servicePrincipal` and `connection` props on `UploaderProvider`. The `servicePrincipal` should be set to the service's DID, and `connection` should be a ucanto `ConnectionView` to the service instance. + ### `useUploader` ```ts -const [progress, uploader] = useUploader() +const [state, actions] = useUploader() ``` Hook to allow use of the [`UploaderProvider`](#uploaderprovider) value. The value returned is an `UploaderContextValue`: @@ -50,28 +52,6 @@ type UploaderContextValue = [ state: UploaderContextState, actions: UploaderContextActions ] - -interface UploaderContextState { - storedDAGShards: CARMetadata[] -} - -interface UploaderContextActions { - /** - * Upload a single file to the service. - */ - uploadFile: (file: Blob) => Promise - /** - * Upload a directory of files to the service. - */ - uploadDirectory: (files: File[]) => Promise - /** - * Store a DAG (encoded as a CAR file) to the service. - */ - storeDAG: (data: Blob) => Promise - /** - * Register an "upload" with the service. Note: only required when using - * `storeDAG`. - */ - registerUpload: (root: CID, shards: CID[]) => Promise -} ``` + +See [uploader-core.md](./uploader-core.md) for the definitions for [`UploaderContextState`](./uploader-core.md#uploadercontextstate) and [`UploaderContextActions`](./uploader-core.md#uploadercontextactions). \ No newline at end of file diff --git a/docs/solid-uploads-list.md b/docs/solid-uploads-list.md index eeb95935..e25ecde7 100644 --- a/docs/solid-uploads-list.md +++ b/docs/solid-uploads-list.md @@ -21,32 +21,50 @@ import * as SolidUploadsList from '@w3ui/solid-uploads-list' ### `createUploadsListResource` ```ts -function createUploadsListResource (source: ResourceSource, options?: ResourceOptions): ResourceReturn +function createUploadsListResource (source: ResourceSource, options?: ResourceOptions, UploadsListSource>): ResourceReturn> ``` Create a solid resource configured to fetch data from the service. Please see the docs for [`createResource`](https://www.solidjs.com/docs/latest/api#createresource) for parameter and return type descriptions. +`createUploadsListResource` takes an `UploadsListSource`: + +```ts +interface UploadsListSource extends ServiceConfig { + cursor?: string + size?: number + space: Space, + agent: Signer, + getProofs: (caps: Capability[]) => Promise +} +``` + +The `space`, `agent`, and `getProofs` fields can be obtained from the `useKeyring` hook. + +The `size` field sets the number of results returned in each page. + +The `ListResponse` returned by the list resource includes a `cursor` field that can be supplied to set the "starting point" of the next page of results. + Example: ```jsx -import { AuthProvider } from '@w3ui/solid-keyring' +import { KeyringProvider, useKeyring } from '@w3ui/solid-keyring' import { createUploadsListResource } from '@w3ui/solid-uploads-list' function App () { return ( - + - + ) } function List () { - const [auth] = useAuth() - const [data] = createUploadsListResource(() => auth) + const [{ agent, space }, { getProofs }] = useKeyring() + const [data] = createUploadsListResource({ agent, space, getProofs }) return ( - {data() && data().results.map(({ dataCid }) => ( - + {data() && data().results.map(({ dataCID }) => ( + ))}
{dataCid}
{dataCID}
) diff --git a/docs/uploader-core.md b/docs/uploader-core.md index c53fbb9a..0cfe7673 100644 --- a/docs/uploader-core.md +++ b/docs/uploader-core.md @@ -14,76 +14,36 @@ import * as UploaderCore from '@w3ui/uploader-core' ## Exports -* [`encodeCAR`](#encodecar) -* [`encodeDirectory`](#encodedirectory) -* [`encodeFile`](#encodefile) -* [`registerUpload`](#registerupload) -* [`storeDAG`](#storedag) +**Interfaces** +- [`UploaderContextState`](#uploadercontextstate) +- [`UploaderContextActions`](#uploadercontextactions) ---- - -### `encodeCAR` - -```ts -encodeCAR (blocks: Iterable, root?: CID): Promise -``` - -Encode a DAG as a CAR file. - -Example: - -```js -const { cid, blocks } = await encodeFile(new File(['data'], 'doc.txt')) -const car = await encodeCAR(blocks, cid) -``` - -### `encodeDirectory` - -```ts -encodeDirectory (files: Iterable): { cid: CID, blocks: Block[] } -``` +**Functions** +- [`uploadFile`](#uploadfile) +- [`uploadDirectory`](#uploaddirectory) -Create a UnixFS DAG from the passed file data. All files are added to a container directory, with paths in file names preserved. +--- -Example: +### `UploaderContextState` -```js -const { cid, blocks } = encodeDirectory([ - new File(['doc0'], 'doc0.txt'), - new File(['doc1'], 'dir/doc1.txt'), -]) -// DAG structure will be: -// bafybei.../doc0.txt -// bafybei.../dir/doc1.txt -``` - -### `encodeFile` +Interface containing uploader state. Implementations are framework-specific and found in each framework's `-uploader` module (e.g. `@w3ui/react-uploader`). ```ts -encodeFile (file: Blob): { cid: CID, blocks: Block[] } +export interface UploaderContextState { + storedDAGShards: CARMetadata[] +} ``` -Create a UnixFS DAG from the passed file data. +The [`CARMetadata` type](https://github.com/web3-storage/w3protocol/tree/main/packages/upload-client#carmetadata) is defined by the `@web3-storage/upload-client` package and re-exported by `@w3ui/uploader-core`. -Example: +### `UploaderContextActions` -```js -const { cid, blocks } = await encodeFile(new File(['data'], 'doc.txt')) -// Note: file name is not preserved - use encodeDirectory if required. -``` +Interface containing upload actions. Implementations are framework-specific and found in each framework's `-uploader` module (e.g. `@w3ui/react-uploader`). -### `registerUpload` +### `uploadFile` -```ts -registerUpload (account: DID, signer: Signer, root: CID, shards: CID[], options: { retries?: number, signal?: AbortSignal } = {}): Promise -``` - -Register a set of stored CAR files as an "upload" in the system. A DAG can be split between multipe CAR files. Calling this function allows multiple stored CAR files to be considered as a single upload. +Re-exported [`uploadFile` function](https://github.com/web3-storage/w3protocol/tree/main/packages/upload-client#uploadfile) from `@web3-storage/upload-client`. -### `storeDAG` - -```ts -storeDAG (account: DID, signer: Signer, car: Blob, options: { retries?: number, signal?: AbortSignal } = {}): Promise -``` +### `uploadDirectory` -Store a CAR file to the service. +Re-exported [`uploadDirectory` function](https://github.com/web3-storage/w3protocol/tree/main/packages/upload-client#uploaddirectory) from `@web3-storage/upload-client`. diff --git a/docs/uploads-list-core.md b/docs/uploads-list-core.md index df305231..6023762c 100644 --- a/docs/uploads-list-core.md +++ b/docs/uploads-list-core.md @@ -14,21 +14,64 @@ import * as UploadsListCore from '@w3ui/uploads-list-core' ## Exports -* [`listUploads`](#listuploads) +**Interfaces** +- [`UploadsListContextState`](#uploadslistcontextstate) +- [`UploadsListContextActions`](#uploadslistcontextactions) + +**Functions** +* [`list`](#list) --- -### `listUploads` +### `UploadsListContextState` + +Interface containing uploads list state. Implementations are framework-specific and found in each framework's `-uploads-list` module (e.g. `@w3ui/react-uploads-list`). ```ts -listUploads (principal: SigningPrincipal, options: { signal?: AbortSignal } = {}): Promise +export interface UploadsListContextState { + /** + * True if the uploads list is currently being retrieved from the service. + */ + loading: boolean + /** + * Set if an error occurred retrieving the uploads list. + */ + error?: Error + /** + * The content of the uploads list. + */ + data?: UploadListResult[] +} ``` -List CIDs of uploaded CAR files. +The `UploadListResult` type is re-exported from `@web3-storage/upload-client` and has the following shape: -Example: +```ts +export interface UploadListResult { + uploaderDID: string + dataCID: string + carCID: string + uploadedAt: string +} +``` -```js -const controller = new AbortController() -const cids = await listUploads(identity.signingPrincipal, { signal: controller.signal }) +### `UploadsListContextActions` + +Interface containing upload listing actions. Implementations are framework-specific and found in each framework's `-uploads-list` module (e.g. `@w3ui/react-uploads-list`). + +```ts +export interface UploadsListContextActions { + /** + * Load the next page of results. + */ + next: () => Promise + /** + * Call to reload the uploads list (discarding the current page). + */ + reload: () => Promise +} ``` + +### `list` + +Re-exported [`Upload.list` function](https://github.com/web3-storage/w3protocol/tree/main/packages/upload-client#uploadlist) from `@web3-storage/upload-client`. diff --git a/docs/vue-keyring.md b/docs/vue-keyring.md index d78649ca..666aaf67 100644 --- a/docs/vue-keyring.md +++ b/docs/vue-keyring.md @@ -14,11 +14,11 @@ import * as VueKeyring from '@w3ui/vue-keyring' ## Exports -* [`AuthProvider`](#authprovider) +* [`KeyringProvider`](#keyringprovider) --- -### `AuthProvider` +### `KeyringProvider` [Provider](https://vuejs.org/guide/components/provide-inject.html) for authentication with the service. @@ -26,100 +26,54 @@ Example: ```vue ``` -Once mounted, the `AuthProvider` provides the following injection keys: +Once mounted, the `KeyringProvider` provides the following injection keys: ```ts -type AuthProviderInjectionKey = { - account: InjectionKey> - agent: InjectionKey> - issuer: InjectionKey> - status: InjectionKey> - loadAgent: InjectionKey - unloadAgent: InjectionKey - resetAgent: InjectionKey - selectAccount: InjectionKey - registerAccount: InjectionKey - cancelRegisterAccount: InjectionKey -} - -export interface AuthContextState { - /** - * The current user account. - */ - account?: DID - /** - * The current user agent (this device). - */ - agent?: DID - /** - * Signing authority from the agent that is able to issue UCAN invocations. - */ - issuer?: Signer - /** - * Authentication status of the current identity. - */ - status: AuthStatus -} - -export interface AuthContextActions { - /** - * Load the user agent and all stored data from secure storage. - */ - loadAgent: () => Promise - /** - * Unload the user agent and all stored data from secure storage. Note: this - * does not remove data, use `resetAgent` if that is desired. - */ - unloadAgent: () => Promise - /** - * Unload the current account and agent from memory and remove from secure - * storage. Note: this removes all data and is unrecoverable. - */ - resetAgent: () => Promise - /** - * Use a specific account. - */ - selectAccount: (did: DID) => Promise - /** - * Register a new account, verify the email address and store in secure - * storage. Use cancelRegisterAccount to abort. - */ - registerAccount: (email: string) => Promise - /** - * Abort an ongoing account registration. - */ - cancelRegisterAccount: () => void +type KeyringProviderInjectionKey = { + space: InjectionKey>, + spaces: InjectionKey>, + agent: InjectionKey>, + loadAgent: InjectionKey, + unloadAgent: InjectionKey, + resetAgent: InjectionKey, + createSpace: InjectionKey, + setCurrentSpace: InjectionKey, + registerSpace: InjectionKey, + cancelRegisterSpace: InjectionKey, + getProofs: InjectionKey } ``` +See [keyring-core.md](./keyring-core.md) for the definitions for [`KeyringContextState`](./keyring-core.md#keyringcontextstate) and [`KeyringContextActions`](./keyring-core.md#keyringcontextactions). + These keys may be used in child components e.g. ```vue ``` diff --git a/docs/vue-uploader.md b/docs/vue-uploader.md index 6c9ac63b..6aa4b2fc 100644 --- a/docs/vue-uploader.md +++ b/docs/vue-uploader.md @@ -20,26 +20,26 @@ import * as VueUploader from '@w3ui/vue-uploader' ### `UploaderProvider` -[Provider](https://vuejs.org/guide/components/provide-inject.html) for an `Uploader` which allows uploads to the service. Note that _this_ provider injects values from [`AuthProvider`](./vue-keyring#authprovider). +[Provider](https://vuejs.org/guide/components/provide-inject.html) for an `Uploader` which allows uploads to the service. Note that _this_ provider injects values from [`KeyringProvider`](./vue-keyring#keyringprovider). Example: ```vue ``` @@ -47,38 +47,14 @@ Once mounted, the `UploaderProvider` provides the following injection keys: ```ts type UploaderProviderInjectionKey = { - uploadFile: InjectionKey - uploadDirectory: InjectionKey - storeDAG: InjectionKey - registerUpload: InjectionKey + uploadFile: InjectionKey, + uploadDirectory: InjectionKey, storedDAGShards: InjectionKey> } - -interface UploaderContextState { - storedDAGShards: CARMetadata[] -} - -interface UploaderContextActions { - /** - * Upload a single file to the service. - */ - uploadFile: (file: Blob) => Promise - /** - * Upload a directory of files to the service. - */ - uploadDirectory: (files: File[]) => Promise - /** - * Store a DAG (encoded as a CAR file) to the service. - */ - storeDAG: (data: Blob) => Promise - /** - * Register an "upload" with the service. Note: only required when using - * `storeDAG`. - */ - registerUpload: (root: CID, shards: CID[]) => Promise -} ``` +See [uploader-core.md](./uploader-core.md) for the definitions for [`UploaderContextState`](./uploader-core.md#uploadercontextstate) and [`UploaderContextActions`](./uploader-core.md#uploadercontextactions). + These keys may be used in child components e.g. ```vue diff --git a/docs/vue-uploads-list.md b/docs/vue-uploads-list.md index 0617bc89..522272d3 100644 --- a/docs/vue-uploads-list.md +++ b/docs/vue-uploads-list.md @@ -20,13 +20,14 @@ import * as VueUploadsList from '@w3ui/vue-uploads-list' ### `UploadsListProvider` -[Provider](https://vuejs.org/guide/components/provide-inject.html) for a list of items uploaded by the current identity. Note that _this_ provider injects values from [`AuthProvider`](./vue-keyring#authprovider). +[Provider](https://vuejs.org/guide/components/provide-inject.html) for a list of items uploaded by the current identity. Note that _this_ provider injects values from [`KeyringProvider`](./vue-keyring#keyringprovider). Example: ```vue ``` @@ -47,32 +50,13 @@ type UploadsListProviderInjectionKey = { loading: InjectionKey>, error: InjectionKey>, data: InjectionKey>, + next: InjectionKey, reload: InjectionKey } - -interface UploadsListContextState { - /** - * True if the uploads list is currently being retrieved from the service. - */ - loading: boolean - /** - * Set if an error occurred retrieving the uploads list. - */ - error?: Error - /** - * The content of the uploads list. - */ - data?: ListPage -} - -interface UploadsListContextActions { - /** - * Call to reload the uploads list. - */ - reload: () => Promise -} ``` +See [uploads-list-core.md](./uploads-list-core.md) for the definitions for [`UploadsListContextState`](./uploads-list-core.md#uploadslistcontextstate) and [`UploadsListContextActions`](./uploads-list-core.md#uploadslistcontextactions). + These keys may be used in child components e.g. ```vue @@ -88,7 +72,7 @@ export default { ```