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/action-setup@v2.2.3
+ 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/wrangler-action@2.0.0
  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
  )
  )