feat: add use cases package

Add an example of how to delegate all capabilities on a space to a `did:mailto` account. This has come up a few times recently and it's one potential solution to the "I want to change my email address" problem.

I'd like to start collecting use cases for w3up client here. It might be a good idea to run some or all of them as integration tests.

packages/use-cases/README.md

@@ -0,0 +1,3 @@
+# Use Cases
+
+This package is a "cookbook" of different uses for `@web3-storage/w3up-client`.

packages/use-cases/main.js

@@ -0,0 +1 @@
+console.log("this is the use-cases module of w3up - it is not currently intended to be used as a module")

packages/use-cases/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@web3-storage/use-cases",
+  "description": "Use cases for w3up-client",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./main.js",
+  "homepage": "https://web3.storage",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/w3s-project/w3up.git",
+    "directory": "packages/upload-api"
+  },
+  "dependencies": {
+    "@ucanto/core": "^10.0.1",
+    "@ucanto/principal": "^9.0.1",
+    "@web3-storage/did-mailto": "workspace:^",
+    "@web3-storage/w3up-client": "workspace:^"
+  }
+}

packages/use-cases/transfer-control-of-space.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { create } from '@web3-storage/w3up-client'
+import { delegate } from '@ucanto/core'
+import { Absentee } from '@ucanto/principal'
+import * as DidMailto from '@web3-storage/did-mailto'
+
+const CURRENT_EMAIL = 'yourcurrentemail@example.com'
+const NEW_EMAIL = 'yournewemail@example.com'
+const SPACE_DID_TO_DELEGATE = 'did:key:asdf'
+
+const newAccountDID = DidMailto.fromEmail(NEW_EMAIL)
+
+const client = await create()
+await client.login(CURRENT_EMAIL)
+
+
+// Register a delegation with the service that grants all capabilities on 
+// the given space to NEW_EMAIL.
+// 
+// The resulting delegation will delegate from CURRENT_EMAIL to the local agent
+// and then to NEW_EMAIL which is a little ugly.
+await client.capability.access.delegate({
+  space: SPACE_DID_TO_DELEGATE,
+  delegations:
+    [await delegate({
+      issuer: client.agent.issuer,
+      audience: Absentee.from({ id: newAccountDID }),
+      capabilities: [{
+        with: SPACE_DID_TO_DELEGATE,
+        can: '*'
+      }]
+    })]
+})