feat: #153 (#177)

- typedoc support to generate docs for all the clients
- add list of Abilities types
- renamed `any.js` to `wildcard.js`
- added `parseAbility` and `canDelegateAbility` functions to the
capabilities `utils.js`
- cli is mostly commented out needs to be updated in a follow PR
- StoreData interface revamped
- added more exports to index.js to help with the generated docs until
typedoc supports export maps
- added a bunch of delegation utilities to `delegation.js`
- agent has new methods, `addProof`, `proofs`, `delegations`,
`delegationsWithMeta`, `createSpace`, `setCurrentSpace`, `currentSpace`,
`currentSpaceWithMeta` and `execute`
- old createAccount renamed to `registerSpace`
- a bunch of jsdocs 

preview docs https://vigorous-chandrasekhar-6b427f.netlify.app/

todo:

- [x] rename caps
- [x] rename account to space in api
- [x] finish setup wrangler migrations for staging and prod (using CI)
- [x] more docs for agent methods 
- [x] feedback
- [x] support multiple invocations to be executed on a connection

.github/workflows/manual.yml

@@ -12,6 +12,7 @@ on:
           - upload-client
           - access-client
           - wallet
+          - docs
       environment:
         description: 'Environment to deploy'
         required: true
@@ -96,3 +97,29 @@ jobs:
       - run: pnpm -r --filter @web3-storage/upload-client publish --tag next --access public
         env:
           NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+  deploy-docs:
+    runs-on: ubuntu-latest
+    if: github.event.inputs.package == 'docs'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: pnpm/[email protected]
+        with:
+          version: 7
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+      - run: pnpm install
+      - run: pnpm run lint
+      - run: pnpm run docs
+      - uses: actions/configure-pages@v2
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: './docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.github/workflows/reuse-deploy-api.yml

@@ -41,6 +41,11 @@ jobs:
           node-version: 18
           cache: 'pnpm'
       - run: pnpm install
+      # Migration database
+      - run: pnpm -r --filter @web3-storage/access-api exec wrangler d1 migrations apply __D1_BETA__ --env ${{ inputs.environment }}
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CF_ACCOUNT_ID }}
       # Publish worker to cloudflare
       - uses: cloudflare/[email protected]
         with:

package.json

@@ -11,14 +11,15 @@
     "clean": "rm -rf docs node_modules pnpm-lock.yaml packages/*/{pnpm-lock.yaml,coverage,.nyc_output,dist,node_modules,.next}",
     "lint": "pnpm -r --if-present run lint",
     "test": "pnpm -r --if-present run test",
-    "check": "pnpm -r --if-present run check"
+    "check": "pnpm -r --if-present run check",
+    "docs": "typedoc --out docs"
   },
   "devDependencies": {
     "lint-staged": "^13.0.3",
     "prettier": "2.7.1",
     "simple-git-hooks": "^2.8.1",
-    "typescript": "^4.8.4",
-    "wrangler": "^2.1.13"
+    "typescript": "4.8.4",
+    "wrangler": "^2.4.0"
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"
@@ -35,5 +36,9 @@
   },
   "engines": {
     "node": ">=16"
+  },
+  "dependencies": {
+    "typedoc": "^0.23.21",
+    "typedoc-plugin-missing-exports": "^1.0.0"
   }
 }

packages/access-api/migrations/0000_create_spaces_table.sql

@@ -0,0 +1,11 @@
+-- Migration number: 0000 	 2022-11-17T15:52:48.968Z
+CREATE TABLE
+    IF NOT EXISTS spaces (
+        did TEXT NOT NULL PRIMARY KEY,
+        product TEXT NOT NULL,
+        email TEXT NOT NULL,
+        agent TEXT NOT NULL,
+        inserted_at TEXT NOT NULL DEFAULT (strftime ('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        updated_at TEXT NOT NULL DEFAULT (strftime ('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        UNIQUE (did)
+    );

packages/access-api/package.json

@@ -29,7 +29,7 @@
     "multiformats": "^10.0.2",
     "nanoid": "^4.0.0",
     "p-retry": "^5.1.1",
-    "preact": "^10.11.2",
+    "preact": "^10.11.3",
     "preact-render-to-string": "^5.2.6",
     "qrcode": "^1.5.1",
     "toucan-js": "^2.7.0",
@@ -38,30 +38,31 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^3.18.0",
     "@databases/escape-identifier": "^1.0.3",
+    "@databases/split-sql-query": "^1.0.3",
     "@databases/sql": "^3.2.0",
-    "@sentry/cli": "^2.8.0",
-    "@sentry/webpack-plugin": "^1.19.1",
+    "@sentry/cli": "^2.9.0",
+    "@sentry/webpack-plugin": "^1.20.0",
     "@types/assert": "^1.5.6",
     "@types/git-rev-sync": "^2.0.0",
-    "@types/node": "^18.11.7",
+    "@types/node": "^18.11.9",
     "@types/qrcode": "^1.5.0",
     "assert": "^2.0.0",
-    "ava": "^5.0.1",
+    "ava": "^5.1.0",
     "better-sqlite3": "7.6.2",
     "buffer": "^6.0.3",
     "delay": "^5.0.0",
     "dotenv": "^16.0.3",
-    "esbuild": "^0.15.12",
+    "esbuild": "^0.15.14",
     "execa": "^6.1.0",
-    "git-rev-sync": "^3.0.1",
+    "git-rev-sync": "^3.0.2",
     "hd-scripts": "^3.0.2",
-    "miniflare": "^2.10.0",
+    "miniflare": "^2.11.0",
     "p-wait-for": "^5.0.0",
     "process": "^0.11.10",
-    "readable-stream": "^4.1.0",
-    "sade": "^1.7.4",
+    "readable-stream": "^4.2.0",
+    "sade": "^1.8.1",
     "typescript": "4.8.4",
-    "wrangler": "^2.1.13"
+    "wrangler": "^2.4.0"
   },
   "eslintConfig": {
     "extends": [
@@ -75,7 +76,7 @@
       "COMMITHASH": "readonly",
       "BRANCH": "readonly",
       "DEBUG": "readonly",
-      "ACCOUNTS": "writable",
+      "SPACES": "writable",
       "VALIDATIONS": "writable",
       "BUCKET": "writable",
       "W3ACCESS_METRICS": "writable",

packages/access-api/scripts/cli.js

@@ -12,7 +12,7 @@ import { Log, LogLevel, Miniflare } from 'miniflare'
 
 // @ts-ignore
 import git from 'git-rev-sync'
-import { migrate } from '../sql/migrate.js'
+import { migrate } from './migrate.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const require = createRequire(__dirname)

packages/access-api/scripts/migrate.js

@@ -0,0 +1,47 @@
+// import { escapeSQLiteIdentifier } from '@databases/escape-identifier'
+import split from '@databases/split-sql-query'
+import sql from '@databases/sql'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/** @type {import('@databases/sql').FormatConfig} */
+const sqliteFormat = {
+  // escapeIdentifier: (str) => escapeSQLiteIdentifier(str),
+  // formatValue: (value) => ({ placeholder: '?', value }),
+
+  escapeIdentifier: (_) => '',
+  formatValue: (_, __) => ({ placeholder: '', value: '' }),
+}
+const migrations = [
+  sql.file(`${__dirname}/../migrations/0000_create_spaces_table.sql`),
+]
+
+/**
+ * Migrate from migration files
+ *
+ * @param {D1Database} db
+ */
+export async function migrate(db) {
+  try {
+    for (const m of migrations) {
+      /** @type {import('@databases/sql').SQLQuery[]} */
+      // @ts-ignore
+      const qs = split.default(m)
+      await db.batch(
+        qs.map((q) => {
+          return db.prepare(q.format(sqliteFormat).text.replace(/^--.*$/gm, ''))
+        })
+      )
+    }
+  } catch (error) {
+    const err = /** @type {Error} */ (error)
+    // eslint-disable-next-line no-console
+    console.error('D1 Error', {
+      message: err.message,
+      // @ts-ignore
+      cause: err.cause?.message,
+    })
+  }
+}

packages/access-api/src/bindings.d.ts

@@ -2,7 +2,7 @@ import type { Logging } from '@web3-storage/worker-utils/logging'
 import type { Handler as _Handler } from '@web3-storage/worker-utils/router'
 import type { Signer } from '@ucanto/interface'
 import { Email } from './utils/email.js'
-import { Accounts } from './kvs/accounts.js'
+import { Spaces } from './kvs/spaces.js'
 import { Validations } from './kvs/validations.js'
 import { D1QB } from 'workers-qb'
 import { loadConfig } from './config.js'
@@ -29,7 +29,7 @@ export interface Env {
   POSTMARK_TOKEN: string
   LOGTAIL_TOKEN: string
   // bindings
-  ACCOUNTS: KVNamespace
+  SPACES: KVNamespace
   VALIDATIONS: KVNamespace
   W3ACCESS_METRICS: AnalyticsEngine
   // eslint-disable-next-line @typescript-eslint/naming-convention
@@ -43,7 +43,7 @@ export interface RouteContext {
   url: URL
   email: Email
   kvs: {
-    accounts: Accounts
+    spaces: Spaces
     validations: Validations
   }
   db: D1QB

packages/access-api/src/config.js

@@ -54,7 +54,7 @@ export function loadConfig(env) {
       /** @type {import("./bindings").AnalyticsEngine} */ (
         env.W3ACCESS_METRICS
       ) || createAnalyticsEngine(),
-    ACCOUNTS: env.ACCOUNTS,
+    SPACES: env.SPACES,
     VALIDATIONS: env.VALIDATIONS,
     DB: /** @type {D1Database} */ (env.__D1_BETA__),
   }

packages/access-api/src/kvs/accounts.js → packages/access-api/src/kvs/spaces.js

@@ -4,14 +4,13 @@ import * as Ucanto from '@ucanto/interface'
 import { delegationToString } from '@web3-storage/access/encoding'
 
 /**
- * @typedef {{account: string, proof: string}} AccountValue
- * @typedef {import('@web3-storage/access/types').Account} Account
+ * @typedef {import('@web3-storage/access/types').SpaceD1} SpaceD1
  */
 
 /**
- * Accounts
+ * Spaces
  */
-export class Accounts {
+export class Spaces {
   /**
    *
    * @param {KVNamespace} kv
@@ -28,9 +27,9 @@ export class Accounts {
    */
   async create(capability, invocation) {
     await this.db.insert({
-      tableName: 'accounts',
+      tableName: 'spaces',
       data: {
-        did: capability.nb.account,
+        did: capability.nb.space,
         product: capability.nb.product,
         email: capability.nb.identity.replace('mailto:', ''),
         agent: invocation.issuer.did(),
@@ -39,13 +38,13 @@ export class Accounts {
   }
 
   /**
-   * Get account by DID
+   * Get space by DID
    *
    * @param {string} did
    */
   async get(did) {
     const { results } = await this.db.fetchOne({
-      tableName: 'accounts',
+      tableName: 'spaces',
       fields: '*',
       where: {
         conditions: 'did=?1',
@@ -57,7 +56,7 @@ export class Accounts {
       return
     }
 
-    return /** @type {Account} */ ({
+    return /** @type {SpaceD1} */ ({
       did: results.did,
       agent: results.agent,
       email: results.email,
@@ -68,7 +67,7 @@ export class Accounts {
   }
 
   /**
-   * Save account delegation per email
+   * Save space delegation per email
    *
    * @param {`mailto:${string}`} email
    * @param {Ucanto.Delegation<Ucanto.Capabilities>} delegation
@@ -111,7 +110,7 @@ export class Accounts {
       return
     }
 
-    return /** @type {import('@web3-storage/access/types').EncodedDelegation<[import('@web3-storage/access/types').Any]>[]} */ (
+    return /** @type {import('@web3-storage/access/types').EncodedDelegation<[import('@web3-storage/access/types').Top]>[]} */ (
       r
     )
   }

packages/access-api/src/routes/validate-email.js

@@ -63,7 +63,7 @@ export async function validateEmail(req, env) {
 async function recover(req, env) {
   try {
     const delegation = await env.kvs.validations.put(
-      /** @type {import('@web3-storage/access/src/types.js').EncodedDelegation<[import('@web3-storage/access/src/types.js').AccountRecover]>} */ (
+      /** @type {import('@web3-storage/access/src/types.js').EncodedDelegation<[import('@web3-storage/access/src/types.js').SpaceRecover]>} */ (
         req.query.ucan
       )
     )