feat: add use cases package

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: '*'
+      }]
+    })]
+})