Merge pull request #655 from MasterKale/feat/654-deno-docs-improvements

feat/654-deno-docs-improvements

Author: MasterKale

HANDBOOK.md

@@ -28,7 +28,6 @@ Update `"version"` in the following **deno.json** files for each package that ne
 
 - **@simplewebauthn/browser**: [packages/browser/deno.json](./packages/browser/deno.json)
 - **@simplewebauthn/server**: [packages/server/deno.json](./packages/server/deno.json)
-- **@simplewebauthn/types**: [packages/types/deno.json](./packages/types/deno.json)
 
 Continue using your best judgement on what an appropriate new version number should be.
 
@@ -46,12 +45,6 @@ The following commands can be run from the root of the monorepo to build the res
 then **publish it to both [NPM](https://www.npmjs.com/search?q=%40simplewebauthn) and
 [JSR](https://jsr.io/@simplewebauthn)**.
 
-#### Need to publish @simplewebauthn/types?
-
-```
-deno task publish:types
-```
-
 #### Need to publish @simplewebauthn/browser?
 
 ```
@@ -60,12 +53,6 @@ deno task publish:browser
 
 #### Need to publish @simplewebauthn/server?
 
-1.
-   - [ ] Make sure the correct version of **@simplewebauthn/types** is on NPM
-   - The `npm install` step that dnt performs while building **@simplewebauthn/server** pulls from
-     NPM. The build will fail if the version of **@simplewebauthn/types** specified in
-     [packages/types/deno.json](./packages/types/deno.json) is unavailable on NPM.
-
 ```
 deno task publish:server
 ```

README.md

@@ -20,10 +20,6 @@ incorporate WebAuthn into a website. The following packages are maintained here:
 - [@simplewebauthn/server](https://github.com/MasterKale/SimpleWebAuthn/tree/master/packages/server)
 - [@simplewebauthn/browser](https://github.com/MasterKale/SimpleWebAuthn/tree/master/packages/browser)
 
-An additional package is also included that contains shared TypeScript definitions:
-
-- [@simplewebauthn/types](https://github.com/MasterKale/SimpleWebAuthn/tree/master/packages/types/)
-
 ## Installation
 
 SimpleWebAuthn can be installed from **[NPM](https://www.npmjs.com/search?q=%40simplewebauthn)** and

deno.json

@@ -22,10 +22,19 @@
       ]
     },
     "test:coverage:collect": "deno test -A --coverage=cov_profile",
-    "build:types": "(cd packages/types; deno task build)",
-    "build:browser": "(cd packages/browser; deno task build)",
-    "build:server": "(cd packages/server; deno task build)",
-    "publish:types": "(cd packages/types; deno task publish)",
+    "codegen:types": "(cd packages/types; deno task codegen)",
+    "build:browser": {
+      "command": "(cd packages/browser; deno task build)",
+      "dependencies": [
+        "codegen:types"
+      ]
+    },
+    "build:server": {
+      "command": "(cd packages/server; deno task build)",
+      "dependencies": [
+        "codegen:types"
+      ]
+    },
     "publish:browser": "(cd packages/browser; deno task publish)",
     "publish:server": "(cd packages/server; deno task publish)"
   },

packages/browser/README.md

@@ -22,13 +22,13 @@ and **[JSR](https://jsr.io/@simplewebauthn/browser)**:
 ### Node LTS 20.x and higher
 
 ```sh
-npm install @simplewebauthn/browser @simplewebauthn/types
+npm install @simplewebauthn/browser
 ```
 
 ### Deno v1.43 and higher
 
 ```sh
-deno add jsr:@simplewebauthn/browser jsr:@simplewebauthn/types
+deno add jsr:@simplewebauthn/browser
 ```
 
 ### UMD

packages/browser/build_npm.ts

@@ -57,10 +57,7 @@ async function buildESMAndCJS() {
         'umd',
       ],
       unpkg: 'dist/bundle/index.umd.min.js',
-      dependencies: {
-        // Deno workspaces maps this identifier locally, make sure it's defined in the NPM package
-        '@simplewebauthn/types': `^${typesDenoJSON.version}`,
-      },
+      dependencies: {},
     },
     // Map from Deno package to NPM package for Node build
     mappings: {},

packages/browser/deno.json

@@ -11,6 +11,14 @@
     },
     "test": "deno test -A src/",
     "test:watch": "deno test -A --watch src/",
+    "docs:serve": {
+      "command": "deno run -A jsr:@std/http/file-server --host 127.0.0.1 docs/",
+      "dependencies": [
+        "docs:html"
+      ]
+    },
+    "docs:html": "deno doc --html src/index.ts",
+    "docs:lint": "deno doc --lint src/index.ts",
     "publish": {
       "command": "deno task publish:jsr && deno task publish:npm",
       "dependencies": [

packages/browser/src/helpers/browserSupportsWebAuthn.ts

@@ -8,7 +8,10 @@ export function browserSupportsWebAuthn(): boolean {
   );
 }
 
-// Make it possible to stub the return value during testing
+/**
+ * Make it possible to stub the return value during testing
+ * @ignore Don't include this in docs output
+ */
 export const _browserSupportsWebAuthnInternals = {
   stubThis: (value: boolean) => value,
 };

packages/browser/src/helpers/browserSupportsWebAuthnAutofill.ts

@@ -1,5 +1,4 @@
-import { PublicKeyCredentialFuture } from '@simplewebauthn/types';
-
+import type { PublicKeyCredentialFuture } from '../types/index.ts';
 import { browserSupportsWebAuthn } from './browserSupportsWebAuthn.ts';
 
 /**

packages/browser/src/helpers/toAuthenticatorAttachment.ts

@@ -1,4 +1,4 @@
-import { AuthenticatorAttachment } from '@simplewebauthn/types';
+import type { AuthenticatorAttachment } from '../types/index.ts';
 
 const attachments: AuthenticatorAttachment[] = ['cross-platform', 'platform'];
 

packages/browser/src/helpers/toPublicKeyCredentialDescriptor.ts

@@ -2,8 +2,7 @@ import type {
   AuthenticatorTransport,
   PublicKeyCredentialDescriptor,
   PublicKeyCredentialDescriptorJSON,
-} from '@simplewebauthn/types';
-
+} from '../types/index.ts';
 import { base64URLStringToBuffer } from './base64URLStringToBuffer.ts';
 
 export function toPublicKeyCredentialDescriptor(

packages/browser/src/helpers/webAuthnAbortService.ts

@@ -1,16 +1,19 @@
 interface WebAuthnAbortService {
+  /**
+   * Prepare an abort signal that will help support multiple auth attempts without needing to
+   * reload the page. This is automatically called whenever `startRegistration()` and
+   * `startAuthentication()` are called.
+   */
   createNewAbortSignal(): AbortSignal;
+  /**
+   * Manually cancel any active WebAuthn registration or authentication attempt.
+   */
   cancelCeremony(): void;
 }
 
 class BaseWebAuthnAbortService implements WebAuthnAbortService {
   private controller: AbortController | undefined;
 
-  /**
-   * Prepare an abort signal that will help support multiple auth attempts without needing to
-   * reload the page. This is automatically called whenever `startRegistration()` and
-   * `startAuthentication()` are called.
-   */
   createNewAbortSignal(): AbortSignal {
     // Abort any existing calls to navigator.credentials.create() or navigator.credentials.get()
     if (this.controller) {
@@ -27,9 +30,6 @@ class BaseWebAuthnAbortService implements WebAuthnAbortService {
     return newController.signal;
   }
 
-  /**
-   * Manually cancel any active WebAuthn registration or authentication attempt.
-   */
   cancelCeremony(): void {
     if (this.controller) {
       const abortError = new Error(

packages/browser/src/index.ts

@@ -1,27 +1,10 @@
-/**
- * @packageDocumentation
- * @module @simplewebauthn/browser
- */
-import { startRegistration } from './methods/startRegistration.ts';
-import { startAuthentication } from './methods/startAuthentication.ts';
-import { browserSupportsWebAuthn } from './helpers/browserSupportsWebAuthn.ts';
-import { platformAuthenticatorIsAvailable } from './helpers/platformAuthenticatorIsAvailable.ts';
-import { browserSupportsWebAuthnAutofill } from './helpers/browserSupportsWebAuthnAutofill.ts';
-import { base64URLStringToBuffer } from './helpers/base64URLStringToBuffer.ts';
-import { bufferToBase64URLString } from './helpers/bufferToBase64URLString.ts';
-import { WebAuthnAbortService } from './helpers/webAuthnAbortService.ts';
-import { WebAuthnError } from './helpers/webAuthnError.ts';
-
-export {
-  base64URLStringToBuffer,
-  browserSupportsWebAuthn,
-  browserSupportsWebAuthnAutofill,
-  bufferToBase64URLString,
-  platformAuthenticatorIsAvailable,
-  startAuthentication,
-  startRegistration,
-  WebAuthnAbortService,
-  WebAuthnError,
-};
-
-export type { WebAuthnErrorCode } from './helpers/webAuthnError.ts';
+export * from './methods/startRegistration.ts';
+export * from './methods/startAuthentication.ts';
+export * from './helpers/browserSupportsWebAuthn.ts';
+export * from './helpers/platformAuthenticatorIsAvailable.ts';
+export * from './helpers/browserSupportsWebAuthnAutofill.ts';
+export * from './helpers/base64URLStringToBuffer.ts';
+export * from './helpers/bufferToBase64URLString.ts';
+export * from './helpers/webAuthnAbortService.ts';
+export * from './helpers/webAuthnError.ts';
+export * from './types/index.ts';

packages/browser/src/methods/startAuthentication.test.ts

@@ -7,19 +7,17 @@ import {
   assertRejects,
   assertStringIncludes,
 } from '@std/assert';
-import { assertSpyCalls, type Spy, spy, stub } from '@std/testing/mock';
+import { assertSpyCalls, type Spy, spy } from '@std/testing/mock';
 import { afterEach, beforeEach, describe, it } from '@std/testing/bdd';
 import { JSDOM } from 'jsdom';
-import {
-  AuthenticationCredential,
+import type {
   AuthenticationExtensionsClientInputs,
   AuthenticationExtensionsClientOutputs,
   PublicKeyCredentialRequestOptionsJSON,
-} from '@simplewebauthn/types';
+} from '../types/index.ts';
 
 import { _browserSupportsWebAuthnInternals } from '../helpers/browserSupportsWebAuthn.ts';
 import { _browserSupportsWebAuthnAutofillInternals } from '../helpers/browserSupportsWebAuthnAutofill.ts';
-import { base64URLStringToBuffer } from '../helpers/base64URLStringToBuffer.ts';
 import { bufferToBase64URLString } from '../helpers/bufferToBase64URLString.ts';
 import { WebAuthnError } from '../helpers/webAuthnError.ts';
 import { generateCustomError } from '../helpers/__jest__/generateCustomError.ts';

packages/browser/src/methods/startAuthentication.ts

@@ -1,9 +1,8 @@
-import {
+import type {
   AuthenticationCredential,
   AuthenticationResponseJSON,
   PublicKeyCredentialRequestOptionsJSON,
-} from '@simplewebauthn/types';
-
+} from '../types/index.ts';
 import { bufferToBase64URLString } from '../helpers/bufferToBase64URLString.ts';
 import { base64URLStringToBuffer } from '../helpers/base64URLStringToBuffer.ts';
 import { browserSupportsWebAuthn } from '../helpers/browserSupportsWebAuthn.ts';
@@ -13,11 +12,7 @@ import { identifyAuthenticationError } from '../helpers/identifyAuthenticationEr
 import { WebAuthnAbortService } from '../helpers/webAuthnAbortService.ts';
 import { toAuthenticatorAttachment } from '../helpers/toAuthenticatorAttachment.ts';
 
-export type StartAuthenticationOpts = {
-  optionsJSON: PublicKeyCredentialRequestOptionsJSON;
-  useBrowserAutofill?: boolean;
-  verifyBrowserAutofillInput?: boolean;
-};
+export type StartAuthenticationOpts = Parameters<typeof startAuthentication>[0];
 
 /**
  * Begin authenticator "login" via WebAuthn assertion
@@ -27,7 +22,11 @@ export type StartAuthenticationOpts = {
  * @param verifyBrowserAutofillInput (Optional) Ensure a suitable `<input>` element is present when `useBrowserAutofill` is `true`. Defaults to `true`.
  */
 export async function startAuthentication(
-  options: StartAuthenticationOpts,
+  options: {
+    optionsJSON: PublicKeyCredentialRequestOptionsJSON;
+    useBrowserAutofill?: boolean;
+    verifyBrowserAutofillInput?: boolean;
+  },
 ): Promise<AuthenticationResponseJSON> {
   const {
     optionsJSON,

packages/browser/src/methods/startRegistration.test.ts

@@ -2,11 +2,11 @@
 import { assertEquals, assertInstanceOf, assertRejects, assertStringIncludes } from '@std/assert';
 import { assertSpyCalls, type Spy, spy, stub } from '@std/testing/mock';
 import { afterEach, beforeEach, describe, it } from '@std/testing/bdd';
-import {
+import type {
   AuthenticationExtensionsClientInputs,
   AuthenticationExtensionsClientOutputs,
   PublicKeyCredentialCreationOptionsJSON,
-} from '@simplewebauthn/types';
+} from '../types/index.ts';
 
 import { generateCustomError } from '../helpers/__jest__/generateCustomError.ts';
 import { _browserSupportsWebAuthnInternals } from '../helpers/browserSupportsWebAuthn.ts';

packages/browser/src/methods/startRegistration.ts

@@ -1,10 +1,9 @@
-import {
+import type {
   AuthenticatorTransportFuture,
   PublicKeyCredentialCreationOptionsJSON,
   RegistrationCredential,
   RegistrationResponseJSON,
-} from '@simplewebauthn/types';
-
+} from '../types/index.ts';
 import { bufferToBase64URLString } from '../helpers/bufferToBase64URLString.ts';
 import { base64URLStringToBuffer } from '../helpers/base64URLStringToBuffer.ts';
 import { browserSupportsWebAuthn } from '../helpers/browserSupportsWebAuthn.ts';
@@ -13,10 +12,7 @@ import { identifyRegistrationError } from '../helpers/identifyRegistrationError.
 import { WebAuthnAbortService } from '../helpers/webAuthnAbortService.ts';
 import { toAuthenticatorAttachment } from '../helpers/toAuthenticatorAttachment.ts';
 
-export type StartRegistrationOpts = {
-  optionsJSON: PublicKeyCredentialCreationOptionsJSON;
-  useAutoRegister?: boolean;
-};
+export type StartRegistrationOpts = Parameters<typeof startRegistration>[0];
 
 /**
  * Begin authenticator "registration" via WebAuthn attestation
@@ -25,7 +21,10 @@ export type StartRegistrationOpts = {
  * @param useAutoRegister (Optional) Try to silently create a passkey with the password manager that the user just signed in with. Defaults to `false`.
  */
 export async function startRegistration(
-  options: StartRegistrationOpts,
+  options: {
+    optionsJSON: PublicKeyCredentialCreationOptionsJSON;
+    useAutoRegister?: boolean;
+  },
 ): Promise<RegistrationResponseJSON> {
   const { optionsJSON, useAutoRegister = false } = options;