feat!: follow up on the capabilities extract (#239)

- [feat: hoist cap files, fix docs paths, clean package.json](b05fe8f) - [feat!: remove caps export from access-client](d5d3f85) - [chore: add more docs to access-client](8416702) - [fix: add preact eslint to api](9a0c9f8) - [chore: clean up workflows](f615c55)
storacha · Dec 2, 2022 · ef5e779 · ef5e779
1 parent 2805ba9
commit ef5e779
Show file tree

Hide file tree

Showing 30 changed files with 220 additions and 188 deletions.
diff --git a/.github/workflows/access-api.yml b/.github/workflows/access-api.yml
@@ -32,7 +32,7 @@ jobs:
       - run: pnpm install
       - run: pnpm -r --filter @web3-storage/access-api run lint
       - run: pnpm -r --filter @web3-storage/access-api run test
-      - run: pnpm --filter @web3-storage/access-api -r exec depcheck
+      - run: pnpm -r --filter @web3-storage/access-api exec depcheck
   deploy-staging:
     needs: test
     if: github.head_ref == 'release-please--branches--main--components--access-api'

diff --git a/.github/workflows/access-client.yml b/.github/workflows/access-client.yml
@@ -28,7 +28,7 @@ jobs:
           node-version: 18
           cache: 'pnpm'
       - run: pnpm install
-      - run: pnpm -r --filter @web3-storage/access run build
+      - run: pnpm run build
       - run: pnpm -r --filter @web3-storage/access run lint
       - run: pnpm -r --filter @web3-storage/access run test
-      - run: pnpm --filter @web3-storage/access -r exec depcheck
+      - run: pnpm -r --filter @web3-storage/access exec depcheck
diff --git a/.github/workflows/capabilities.yml b/.github/workflows/capabilities.yml
@@ -1,4 +1,4 @@
-name: '@web3-storage/capabilities'
+name: Capabilities
 env:
   CI: true
   FORCE_COLOR: 1
@@ -18,27 +18,17 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        pnpm-version:
-          - 7
-        node-version:
-          - 18
-        package:
-          - capabilities
     steps:
       - uses: actions/checkout@v3
       - uses: pnpm/action-setup@v2.2.3
         with:
-          version: ${{ matrix.pnpm-version }}
+          version: 7
       - uses: actions/setup-node@v3
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 18
           cache: 'pnpm'
       - run: pnpm install
-      - name: Typecheck
-        uses: gozala/typescript-error-reporter-action@v1.0.8
-        with:
-          project: packages/${{matrix.package}}/tsconfig.json
-      - run: pnpm -r --filter @web3-storage/${{matrix.package}} run lint
-      - run: pnpm -r --filter @web3-storage/${{matrix.package}} run test
+      - run: pnpm run build
+      - run: pnpm -r --filter @web3-storage/capabilities run lint
+      - run: pnpm -r --filter @web3-storage/capabilities run test
+      - run: pnpm -r --filter @web3-storage/capabilities exec depcheck
diff --git a/.github/workflows/upload-client.yml b/.github/workflows/upload-client.yml
@@ -28,7 +28,7 @@ jobs:
           node-version: 18
           cache: 'pnpm'
       - run: pnpm install
-      - run: pnpm -r --filter @web3-storage/upload-client run build
+      - run: pnpm run build
       - run: pnpm -r --filter @web3-storage/upload-client run lint
       - run: pnpm -r --filter @web3-storage/upload-client run test
-      - run: pnpm --filter @web3-storage/access-api -r exec depcheck
+      - run: pnpm -r --filter @web3-storage/upload-client exec depcheck
diff --git a/packages/access-api/package.json b/packages/access-api/package.json
@@ -39,10 +39,10 @@
     "@sentry/cli": "2.7.0",
     "@types/assert": "^1.5.6",
     "@types/git-rev-sync": "^2.0.0",
-    "@types/node": "^18.11.9",
+    "@types/node": "^18.11.10",
     "@types/qrcode": "^1.5.0",
     "ava": "^5.1.0",
-    "better-sqlite3": "8.0.0",
+    "better-sqlite3": "8.0.1",
     "buffer": "^6.0.3",
     "dotenv": "^16.0.3",
     "esbuild": "^0.15.16",
@@ -58,10 +58,13 @@
   },
   "eslintConfig": {
     "extends": [
-      "./node_modules/hd-scripts/eslint/index.js"
+      "./node_modules/hd-scripts/eslint/preact.js"
     ],
     "parserOptions": {
-      "project": "./tsconfig.json"
+      "project": "./tsconfig.json",
+      "ecmaFeatures": {
+        "jsx": true
+      }
     },
     "globals": {
       "VERSION": "readonly",

diff --git a/packages/access-client/package.json b/packages/access-client/package.json
@@ -28,7 +28,6 @@
   "exports": {
     ".": "./src/index.js",
     "./agent": "./src/agent.js",
-    "./capabilities/*": "./src/capabilities/*.js",
     "./stores/*": "./src/stores/*.js",
     "./types": "./src/types.js",
     "./encoding": "./src/encoding.js"
@@ -44,9 +43,6 @@
       "stores/*": [
         "dist/src/stores/*"
       ],
-      "capabilities/*": [
-        "dist/src/capabilities/*"
-      ],
       "encoding": [
         "dist/src/encoding"
       ]
@@ -85,7 +81,7 @@
     "@types/assert": "^1.5.6",
     "@types/inquirer": "^9.0.3",
     "@types/mocha": "^10.0.0",
-    "@types/node": "^18.11.9",
+    "@types/node": "^18.11.10",
     "@types/ws": "^8.5.3",
     "@ucanto/server": "^3.0.4",
     "assert": "^2.0.0",
@@ -101,13 +97,10 @@
   },
   "eslintConfig": {
     "extends": [
-      "./node_modules/hd-scripts/eslint/preact.js"
+      "./node_modules/hd-scripts/eslint/index.js"
     ],
     "parserOptions": {
-      "project": "./tsconfig.json",
-      "ecmaFeatures": {
-        "jsx": true
-      }
+      "project": "./tsconfig.json"
     },
     "rules": {
       "unicorn/prefer-number-properties": "off",

diff --git a/packages/access-client/readme.md b/packages/access-client/readme.md
@@ -13,6 +13,21 @@ npm install @web3-storage/access
 
 [API Reference](https://web3-storage.github.io/w3protocol/modules/_web3_storage_access.html)
 
+```js
+import { Agent, connection } from '@web3-storage/access/agent'
+import * as Encoding from '@web3-storage/access/encoding'
+import { StoreConf } from '@web3-storage/access/stores/store-conf'
+// for browsers
+import { StoreIndexedDB } from '@web3-storage/access/stores/store-indexeddb'
+
+const store = new StoreConf({ profile: 'app' })
+if (!(await store.exists())) {
+  await store.init({})
+}
+
+const agent = await Agent.create({ store })
+```
+
 ## Contributing
 
 Feel free to join in. All welcome. Please [open an issue](https://github.com/web3-storage/w3protocol/issues)!

diff --git a/packages/access-client/src/agent.js b/packages/access-client/src/agent.js
@@ -25,11 +25,19 @@ import {
 const HOST = 'https://access.web3.storage'
 
 /**
- * @template {string} T
- * @param {Ucanto.Principal<T>} principal
- * @param {typeof fetch} _fetch
- * @param {URL} url
- * @param {Ucanto.Transport.Channel<import('./types').Service>} [channel]
+ * Creates a Ucanto connection for the w3access API
+ *
+ * Usage:
+ *
+ * ```js
+ * import { connection } from '@web3-storage/access/agent'
+ * ```
+ *
+ * @template {string} T - DID method
+ * @param {Ucanto.Principal<T>} principal - w3access API Principal
+ * @param {typeof fetch} _fetch - fetch implementation to use
+ * @param {URL} url - w3access API URL
+ * @param {Ucanto.Transport.Channel<import('./types').Service>} [channel] - Ucanto channel to use
  * @returns {Ucanto.ConnectionView<import('./types').Service>}
  */
 export function connection(principal, _fetch, url, channel) {
@@ -51,8 +59,15 @@ export function connection(principal, _fetch, url, channel) {
 }
 
 /**
- * @template {Ucanto.Signer} T
  * Agent
+ *
+ * Usage:
+ *
+ * ```js
+ * import { Agent } from '@web3-storage/access/agent'
+ * ```
+ *
+ * @template {Ucanto.Signer} T - Ucanto Signer ie. ed25519, RSA or others
  */
 export class Agent {
   /** @type {Ucanto.Principal<"key">|undefined} */
@@ -452,8 +467,6 @@ export class Agent {
   /**
    * Invoke and execute the given capability on the Access service connection
    *
-   * Sugar for :
-   *
    * ```js
    *
    * await agent.invokeAndExecute(Space.recover, {

diff --git a/packages/access-client/src/encoding.js b/packages/access-client/src/encoding.js
@@ -1,7 +1,7 @@
 /**
  * Encoding utilities
  *
- * These can be imported directly with:
+ * It is recommended that you import directly with:
  * ```js
  * import * as Encoding from '@web3-storage/access/encoding'
  *

diff --git a/packages/access-client/src/index.js b/packages/access-client/src/index.js
@@ -1,8 +1,6 @@
 /* eslint-disable jsdoc/check-tag-names */
 export * from './agent.js'
 
-export { Space, Store, Top, Upload, Voucher } from '@web3-storage/capabilities'
-
 // Workaround for typedoc until 0.24 support export maps
 export * as Encoding from './encoding.js'
 export { StoreConf } from './stores/store-conf.js'

diff --git a/packages/access-client/src/stores/store-conf.js b/packages/access-client/src/stores/store-conf.js
@@ -21,7 +21,13 @@ import * as Ucanto from '@ucanto/interface'
  */
 
 /**
- * Store implementation with "conf"
+ * Store implementation with "[conf](https://github.com/sindresorhus/conf)"
+ *
+ * Usage:
+ *
+ * ```js
+ * import { StoreConf } from '@web3-storage/access/stores/store-conf'
+ * ```
  *
  * @implements {Store}
  */

diff --git a/packages/access-client/src/stores/store-indexeddb.js b/packages/access-client/src/stores/store-indexeddb.js
@@ -14,6 +14,12 @@ const DATA_ID = 1
 /**
  * Store implementation for the browser.
  *
+ * Usage:
+ *
+ * ```js
+ * import { StoreIndexedDB } from '@web3-storage/access/stores/store-indexeddb'
+ * ```
+ *
  * @implements {Store}
  */
 export class StoreIndexedDB {

diff --git a/packages/access-ws/package.json b/packages/access-ws/package.json
@@ -23,7 +23,7 @@
     "@cloudflare/workers-types": "^3.18.0",
     "@sentry/cli": "2.7.0",
     "@types/git-rev-sync": "^2.0.0",
-    "@types/node": "^18.11.9",
+    "@types/node": "^18.11.10",
     "ava": "^5.1.0",
     "buffer": "^6.0.3",
     "dotenv": "^16.0.3",

diff --git a/packages/capabilities/package.json b/packages/capabilities/package.json
@@ -15,39 +15,39 @@
   "scripts": {
     "lint": "tsc && eslint '**/*.{js,ts}' && prettier --check '**/*.{js,ts,yml,json}' --ignore-path ../../.gitignore",
     "build": "tsc --build",
-    "test": "pnpm -r --filter @web3-storage/capabilities run build && npm run test:node && npm run test:browser",
-    "test:node": "mocha 'test/**/!(*.browser).test.js' -n experimental-vm-modules -n no-warnings",
-    "test:browser": "playwright-test 'test/**/!(*.node).test.js'",
-    "testw": "watch 'pnpm test' src test --interval 1",
+    "test": "pnpm run test:node && pnpm run test:browser",
+    "test:node": "mocha 'test/**/*.test.js' -n experimental-vm-modules -n no-warnings",
+    "test:browser": "playwright-test",
+    "testw": "watch 'pnpm test:node' src test --interval 1",
     "rc": "npm version prerelease --preid rc"
   },
   "exports": {
     ".": "./src/index.js",
-    "./types": "./dist/src/capabilities/types.d.ts",
-    "./*": "./src/capabilities/*.js"
+    "./types": "./dist/src/types.d.ts",
+    "./*": "./src/*.js"
   },
   "typesVersions": {
     "*": {
       "space": [
-        "dist/src/capabilities/space"
+        "dist/src/space"
       ],
       "store": [
-        "dist/src/capabilities/store"
+        "dist/src/store"
       ],
       "types": [
-        "dist/src/capabilities/types"
+        "dist/src/types"
       ],
       "top": [
-        "dist/src/capabilities/top"
+        "dist/src/top"
       ],
       "upload": [
-        "dist/src/capabilities/upload"
+        "dist/src/upload"
       ],
       "utils": [
-        "dist/src/capabilities/utils"
+        "dist/src/utils"
       ],
       "voucher": [
-        "dist/src/capabilities/voucher"
+        "dist/src/voucher"
       ]
     }
   },
@@ -57,21 +57,16 @@
     "dist/src/**/*.d.ts.map"
   ],
   "dependencies": {
-    "@ipld/car": "^5.0.1",
-    "@ipld/dag-ucan": "^2.0.1",
-    "@ucanto/client": "^3.0.2",
     "@ucanto/core": "^3.0.2",
     "@ucanto/interface": "^3.0.1",
     "@ucanto/principal": "^3.0.1",
-    "@ucanto/server": "^3.0.4",
     "@ucanto/transport": "^3.0.2",
     "@ucanto/validator": "^3.0.4"
   },
   "devDependencies": {
     "@types/assert": "^1.5.6",
     "@types/mocha": "^10.0.0",
-    "@types/node": "^18.11.9",
-    "@web-std/fetch": "^4.1.0",
+    "@types/node": "^18.11.10",
     "assert": "^2.0.0",
     "hd-scripts": "^3.0.2",
     "mocha": "^10.1.0",
@@ -81,7 +76,7 @@
   },
   "eslintConfig": {
     "extends": [
-      "./node_modules/hd-scripts/eslint/preact.js"
+      "./node_modules/hd-scripts/eslint/index.js"
     ],
     "parserOptions": {
       "project": "./tsconfig.json"
@@ -98,5 +93,15 @@
       "dist",
       "coverage"
     ]
+  },
+  "depcheck": {
+    "specials": [
+      "bin"
+    ],
+    "ignores": [
+      "@types/*",
+      "hd-scripts",
+      "assert"
+    ]
   }
 }