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 <alan.shaw@protocol.ai>
storacha · Dec 2, 2022 · 8699b40 · 8699b40
1 parent 9ccbe67
commit 8699b40
Show file tree

Hide file tree

Showing 12 changed files with 345 additions and 411 deletions.
diff --git 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<void>
+  /**
+   * 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<void>
+  /**
+   * Unload the current space and agent from memory and remove from secure
+   * storage. Note: this removes all data and is unrecoverable.
+   */
+  resetAgent: () => Promise<void>
+  /**
+   * Create a new space with the passed name and set it as the current space.
+   */
+  createSpace: (name?: string) => Promise<DID>
+  /**
+   * Use a specific space.
+   */
+  setCurrentSpace: (did: DID) => Promise<void>
+  /**
+   * 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<void>
+  /**
+   * 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<Proof[]>
+}
+```
+
+### `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<string, any>
+```
+
+Returns user-defined metadata attached to the space.
+
 ### `createAgent`
 
 ```ts
-createAgent (options: { url?: URL } = {}): Promise<Agent<RSASigner>> 
+createAgent (options: CreateAgentOptions = {}): Promise<Agent<RSASigner>> 
 ```
 
 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<any>): Space | undefined
+```
+
+Returns the given `agent`'s current space, or `undefined` if the agent has no current space set.
+
+### `getSpaces`
+
+```ts
+getSpaces(agent: Agent<any>): 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
@@ -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 (
-    <AuthProvider>
+    <KeyringProvider>
       {/* Application pages/components */}
-    </AuthProvider>
+    </KeyringProvider>
   )
 }
 ```
 
-### `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<void>
-  /**
-   * 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<void>
-  /**
-   * Unload the current account and agent from memory and remove from secure
-   * storage. Note: this removes all data and is unrecoverable.
-   */
-  resetAgent: () => Promise<void>
-  /**
-   * Use a specific account.
-   */
-  selectAccount: (did: DID) => Promise<void>
-  /**
-   * Register a new account, verify the email address and store in secure
-   * storage. Use cancelRegisterAccount to abort.
-   */
-  registerAccount: (email: string) => Promise<void>
-  /**
-   * 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
@@ -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<CID>
-  /**
-   * Upload a directory of files to the service.
-   */
-  uploadDirectory: (files: File[]) => Promise<CID>
-  /**
-   * Store a DAG (encoded as a CAR file) to the service.
-   */
-  storeDAG: (data: Blob) => Promise<CID>
-  /**
-   * Register an "upload" with the service. Note: only required when using
-   * `storeDAG`.
-   */
-  registerUpload: (root: CID, shards: CID[]) => Promise<void>
-}
 ```
 
+See [uploader-core.md](./uploader-core.md) for the definitions for [`UploaderContextState`](./uploader-core.md#uploadercontextstate) and [`UploaderContextActions`](./uploader-core.md#uploadercontextactions).
diff --git 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<void>
-}
-
-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).