@passlock/client 2.0.1 → 2.0.3

package/README.md

@@ -36,7 +36,7 @@ in README.template.md and outputs to README.md
 
 Powerful features including signals and related origin requests...
 
-1. **🔓 No lock-in**
+1. **🔓 No lock-in**  
 Framework agnostic. Standards compliant.
 
 2. **🔑 Related origins (domain migration)**  
@@ -48,7 +48,7 @@ Works out of the box with sensible defaults.
 4. **📱 Credential management**  
 Programmatically manage passkeys on end user devices
 
-5. **💪 Powerful**
+5. **💪 Powerful**  
 User verification, autofill, roaming authenticators and more.
 
 ## More information

package/README.template.md

@@ -36,7 +36,7 @@ in README.template.md and outputs to README.md
 
 Powerful features including signals and related origin requests...
 
-1. **🔓 No lock-in**
+1. **🔓 No lock-in**  
 Framework agnostic. Standards compliant.
 
 2. **🔑 Related origins (domain migration)**  
@@ -48,7 +48,7 @@ Works out of the box with sensible defaults.
 4. **📱 Credential management**  
 Programmatically manage passkeys on end user devices
 
-5. **💪 Powerful**
+5. **💪 Powerful**  
 User verification, autofill, roaming authenticators and more.
 
 ## More information

package/dist/index.d.ts

@@ -1,41 +1,245 @@
-import type { AuthenticationError, AuthenticationOptions, AuthenticationSuccess, PasskeyNotFound } from "./passkey/authentication";
-import type { CredentialMapping, DeletionError, SyncError, UpdateError, UpdateUserDetails } from "./passkey/signals";
-import type { PasslockOptions } from "./shared/options";
+/**
+ * _unsafe_ functions that could throw an error. Be sure to catch errors and use one of the
+ * type guards to narrow the thrown error down to a specific type.
+ *
+ * @categoryDescription Passkeys (core)
+ * Creating, authenticating, updating and deleting passkeys. {@link registerPasskey}
+ * and {@link authenticatePasskey} are the key functions.
+ *
+ * @categoryDescription Passkeys (other)
+ * Testing for browser capabilities related to passkeys, type guards and other utilities.
+ *
+ * @showCategories
+ * @module unsafe
+ */
 import { Logger } from "./logger";
-import { type RegistrationError, type RegistrationOptions, type RegistrationSuccess } from "./passkey/registration";
-export type { PasslockOptions } from "./shared/options";
-export { ConsoleLogger, EventLogger, LogEvent, Logger, LogLevel } from "./logger";
+import type { AuthenticationOptions, AuthenticationSuccess } from "./passkey/authentication/authentication";
+import type { RegistrationOptions, RegistrationSuccess } from "./passkey/registration/registration";
+import type { DeleteCredentialOptions, DeletePasskeyOptions, DeleteSuccess, PrunePasskeyOptions, PruningSuccess, UpdateCredentialOptions, UpdatePasskeyOptions, UpdateSuccess } from "./passkey/signals/signals";
+import type { OrphanedPasskeyError } from "./safe";
 /**
- * Register a passkey on the local device and store the
- * associated public key in your Passlock vault.
+ * Registers a passkey on the user's device, then saves the server-side component in your vault.
+ * If successful, this function returns both a `code` and an `id_token` (JWT).
+ * Send either value to your backend for verification.
+ * See [register a passkey](https://passlock.dev/passkeys/registration/) in the documentation.
+ *
  * @param options
- * @returns
+ *
+ * @returns A successful registration payload.
+ *
+ * @see {@link isRegistrationSuccess}
+ * @see {@link isPasskeyUnsupportedError}
+ * @see {@link isDuplicatePasskeyError}
+ * @see {@link isOtherPasskeyError}
+ *
+ * @throws {@link RegistrationError} (alias to a union of potential errors)
+ * @throws {@link PasskeyUnsupportedError} if the device does not support passkeys
+ * @throws {@link DuplicatePasskeyError} if `excludeCredentials` includes a passkey that already exists on the device
+ * @throws {@link OtherPasskeyError} typically a low level failure
+ * @throws {@link NetworkError}
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ * const username = "jdoe@gmail.com";
+ *
+ * try {
+ *   const result = await registerPasskey({ tenancyId, username });
+ *   // send this to your backend for verification
+ *   console.log(result.code);
+ * } catch (error) {
+ *   if (isPasskeyUnsupportedError(error)) {
+ *     alert("passkeys not supported on this device");
+ *   } else {
+ *     console.log(error);
+ *   }
+ * }
+ *
+ * @category Passkeys (core)
  */
-export declare const registerPasskey: (options: RegistrationOptions, logger?: typeof Logger.Service) => Promise<RegistrationSuccess | RegistrationError>;
-export type { RegistrationError, RegistrationOptions, RegistrationSuccess, } from "./passkey/registration";
-export { isOtherPasskeyError, isPasskeyUnsupported, OtherPasskeyError, PasskeyUnsupportedError, } from "./passkey/errors";
-export { DuplicatePasskeyError, isDuplicatePasskey, isRegistrationSuccess, } from "./passkey/registration";
-export { isUnexpectedError, UnexpectedError } from "./shared/network";
+export declare const registerPasskey: (options: RegistrationOptions, 
+/** @hidden */
+logger?: typeof Logger.Service) => Promise<RegistrationSuccess>;
 /**
- * Trigger local passkey authentication then verify the passkey in the Passlock vault.
- * Returns a code and id_token that can be exchanged/decoded in your backend.
+ * Asks the client to present a passkey, which is then verified against the server-side component in your vault.
+ * If successful, this function returns both a `code` and an `id_token` (JWT). Send either value to your backend for verification.
+ * See
+ * [authenticate a passkey](https://passlock.dev/passkeys/authentication/) in the documentation.
  *
  * @param options
- * @returns
+ *
+ * @returns A successful authentication payload.
+ *
+ * @see {@link isAuthenticationSuccess}
+ * @see {@link isPasskeyUnsupportedError}
+ * @see {@link isOrphanedPasskeyError}
+ * @see {@link isOtherPasskeyError}
+ *
+ * @throws {@link AuthenticationError} (alias to a union of potential errors)
+ * @throws {@link PasskeyUnsupportedError} if the device does not support passkeys
+ * @throws {@link OrphanedPasskeyError} if the passkey is orphaned i.e. deleted from the vault but still present on the local device
+ * @throws {@link OtherPasskeyError} typically a low level failure
+ * @throws {@link NetworkError}
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ *
+ * try {
+ *   const result = await authenticatePasskey({ tenancyId });
+ *   // send this to your backend for verification
+ *   console.log(result.code);
+ * } catch (error) {
+ *   if (isPasskeyUnsupportedError(error)) {
+ *     alert("passkeys not supported on this device");
+ *   } else {
+ *     console.log(error);
+ *   }
+ * }
+ *
+ * @category Passkeys (core)
+ */
+export declare const authenticatePasskey: (options: AuthenticationOptions, 
+/** @hidden */
+logger?: typeof Logger.Service) => Promise<AuthenticationSuccess>;
+/**
+ * Attempt to update the username or display name for a passkey (client-side only).
+ *
+ * Useful if the user has changed their account identifier. For example, they register
+ * using jdoe@gmail.com but later change their account username to jdoe@yahoo.com.
+ * Even after you update their account details in your backend, their local password
+ * manager will continue to display jdoe@gmail.com.
+ *
+ * By calling this function and supplying a new username/display name, their local
+ * password manager will align with their updated account identifier.
+ *
+ * @param options You will typically supply a target `passkeyId` via {@link UpdatePasskeyOptions}. {@link UpdateCredentialOptions} is for advanced use cases.
+ * @returns Update status
+ * @see {@link isUpdateError}
+ * @throws {@link UpdateError} if the passkey cannot be updated
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ * const passkeyId = "myPasskeyId";
+ * const username = "newUsername@gmail.com";
+ * const displayName = "New Account Name";
+ *
+ * try {
+ *   const result = await updatePasskey({ tenancyId, passkeyId, username, displayName });
+ *   console.log("passkey updated");
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ * @category Passkeys (core)
+ */
+export declare const updatePasskey: (options: UpdatePasskeyOptions | UpdateCredentialOptions, 
+/** @hidden */
+logger?: typeof Logger.Service) => Promise<UpdateSuccess>;
+/**
+ * Attempts to delete a passkey from a local device. There are two scenarios in which this function proves useful:
+ *
+ * 1. **Deleting a passkey**. Use the `@passlock/node` package or make vanilla REST calls from your
+ * backend to delete the server-side component, then use this function to delete the client-side component.
+ *
+ * 2. **Missing passkey**. The user tried to present a passkey, but the server-side component could not be found.
+ * Remove the passkey from the local device to prevent it happening again.
+ *
+ * See [deleting passkeys](https://passlock.dev/passkeys/passkey-removal/) and
+ * [handling missing passkeys](https://passlock.dev/handling-missing-passkeys/) in the documentation.
+ *
+ * @param options You typically pass a {@link DeletePasskeyOptions}, the other types are for advanced edge-cases.
+ * @returns A {@link DeleteSuccess} payload if the passkey is deleted.
+ * @see {@link isDeleteError}
+ * @throws {@link DeleteError} if the passkey cannot be deleted
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ * const passkeyId = "myPasskeyId";
+ *
+ * try {
+ *   const result = await deletePasskey({ tenancyId, passkeyId });
+ *   console.log("passkey deleted");
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ * @category Passkeys (core)
+ */
+export declare const deletePasskey: (options: DeletePasskeyOptions | DeleteCredentialOptions | OrphanedPasskeyError, 
+/** @hidden */
+logger?: typeof Logger.Service) => Promise<DeleteSuccess>;
+/**
+ * Attempt to prune local passkeys by keeping only the passkey IDs you trust.
+ *
+ * This is useful when your backend is the source of truth for which passkeys
+ * should still exist for a given account on this device.
+ *
+ * @param options Pass the passkeys you want to retain.
+ * @returns A {@link PruningSuccess} payload if local passkeys were pruned.
+ * @see {@link isPruningError}
+ *
+ * @throws {@link PruningError}
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ * const allowablePasskeyIds = ["passkey-1", "passkey-2"];
+ *
+ * try {
+ *   const result = await prunePasskeys({ tenancyId, allowablePasskeyIds });
+ *   console.log("local passkeys pruned", result);
+ * } catch (error) {
+ *   if (isPruningError(error)) {
+ *     console.log(error.code);
+ *   } else {
+ *     console.log(error);
+ *   }
+ * }
+ *
+ * @category Passkeys (core)
+ */
+export declare const prunePasskeys: (options: PrunePasskeyOptions, 
+/** @hidden */
+logger?: typeof Logger.Service) => Promise<PruningSuccess>;
+/**
+ * Does the local device support programmatic passkey deletion
+ *
+ * @returns `true` if local passkey deletion is supported.
+ *
+ * @category Passkeys (other)
+ */
+export declare const isPasskeyDeleteSupport: () => boolean;
+/**
+ * Does the local device support programmatic passkey pruning
+ *
+ * @returns `true` if local passkey pruning is supported.
+ *
+ * @category Passkeys (other)
+ */
+export declare const isPasskeyPruningSupport: () => boolean;
+/**
+ * Does the local device support programmatic passkey updates
+ *
+ * @returns `true` if local passkey updates are supported.
+ *
+ * @category Passkeys (other)
  */
-export declare const authenticatePasskey: (options: AuthenticationOptions, logger?: typeof Logger.Service) => Promise<AuthenticationSuccess | AuthenticationError>;
-export type { AuthenticationError, AuthenticationOptions, AuthenticationSuccess, PasskeyNotFound, } from "./passkey/authentication";
-export { isAuthenticationSuccess, isPasskeyNotFound, } from "./passkey/authentication";
-export declare const isPasskeyDeletionSupport: () => boolean;
-export declare const isPasskeySyncSupport: () => boolean;
 export declare const isPasskeyUpdateSupport: () => boolean;
-export declare const deletePasskey: (identifiers: string | CredentialMapping | PasskeyNotFound, options: PasslockOptions, logger?: typeof Logger.Service) => Promise<boolean | DeletionError>;
-export type { CredentialMapping } from "./passkey/signals";
-export { DeletionError, isDeletionError } from "./passkey/signals";
-export declare const syncPasskeys: (passkeyIds: Array<string>, options: PasslockOptions, logger?: typeof Logger.Service) => Promise<boolean | SyncError>;
-export { isSyncError, SyncError } from "./passkey/signals";
-export declare const updateUserDetails: (options: UpdateUserDetails, logger?: typeof Logger.Service) => Promise<boolean | UpdateError>;
-export type { UpdateUserDetails } from "./passkey/signals";
-export { isUpdateError, UpdateError } from "./passkey/signals";
-export { isAutofillSupport, isPasskeySupport } from "./passkey/support";
+export { isNetworkError, NetworkError } from "./internal/network";
+export { LogEvent, Logger, LogLevel, } from "./logger";
+export type { PasslockOptions } from "./options";
+export type { AuthenticationError, AuthenticationEvent, AuthenticationEvents, AuthenticationOptions, AuthenticationSuccess, OnAuthenticationEvent, } from "./passkey/authentication/authentication";
+export { AuthenticationHelper, isAuthenticationSuccess, } from "./passkey/authentication/authentication";
+export type { ErrorCode } from "./passkey/errors";
+export { DeleteError, DuplicatePasskeyError, isDeleteError, isDuplicatePasskeyError, isOrphanedPasskeyError, isOtherPasskeyError, isPasskeyUnsupportedError, isPruningError, isUpdateError, OrphanedPasskeyError, OtherPasskeyError, PasskeyUnsupportedError, PruningError, UpdateError, } from "./passkey/errors";
+export type { OnRegistrationEvent, RegistrationError, RegistrationEvent, RegistrationOptions, RegistrationSuccess, } from "./passkey/registration/registration";
+export { isRegistrationSuccess, RegistrationHelper, } from "./passkey/registration/registration";
+export type { UserVerification } from "./passkey/shared";
+export type { CredentialMapping, DeleteCredentialOptions, DeletePasskeyOptions, DeleteSuccess, PrunePasskeyOptions, PruningSuccess, UpdateCredentialOptions, UpdatePasskeyOptions, UpdateSuccess, } from "./passkey/signals/signals";
+export { isDeleteSuccess, isPruningSuccess, isUpdateSuccess, } from "./passkey/signals/signals";
+export { isAutofillSupport, isPasskeySupport, } from "./passkey/support";
+export type { Principal } from "./principal";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,SAAS,EACT,WAAW,EACX,iBAAiB,EAClB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEvD,OAAO,EAAe,MAAM,EAAE,MAAM,UAAU,CAAA;AAK9C,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAEzB,MAAM,wBAAwB,CAAA;AAY/B,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAIjF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,mBAAmB,EAC5B,SAAQ,OAAO,MAAM,CAAC,OAAqB,KAC1C,OAAO,CAAC,mBAAmB,GAAG,iBAAiB,CAM/C,CAAA;AAEH,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAIrE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,SAAS,qBAAqB,EAC9B,SAAQ,OAAO,MAAM,CAAC,OAAqB,KAC1C,OAAO,CAAC,qBAAqB,GAAG,mBAAmB,CAMnD,CAAA;AAEH,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,GAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,0BAA0B,CAAA;AAIjC,eAAO,MAAM,wBAAwB,eAAuD,CAAA;AAC5F,eAAO,MAAM,oBAAoB,eAAmD,CAAA;AACpF,eAAO,MAAM,sBAAsB,eAAqD,CAAA;AAExF,eAAO,MAAM,aAAa,GACxB,aAAa,MAAM,GAAG,iBAAiB,GAAG,eAAe,EACzD,SAAS,eAAe,EACxB,SAAQ,OAAO,MAAM,CAAC,OAAqB,KAC1C,OAAO,CAAC,OAAO,GAAG,aAAa,CAOjC,CAAA;AAED,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAElE,eAAO,MAAM,YAAY,GACvB,YAAY,KAAK,CAAC,MAAM,CAAC,EACzB,SAAS,eAAe,EACxB,SAAQ,OAAO,MAAM,CAAC,OAAqB,KAC1C,OAAO,CAAC,OAAO,GAAG,SAAS,CAG7B,CAAA;AAED,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAE1D,eAAO,MAAM,iBAAiB,GAC5B,SAAS,iBAAiB,EAC1B,SAAQ,OAAO,MAAM,CAAC,OAAqB,KAC1C,OAAO,CAAC,OAAO,GAAG,WAAW,CAG/B,CAAA;AAED,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAI9D,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,52 +1,253 @@
+/**
+ * _unsafe_ functions that could throw an error. Be sure to catch errors and use one of the
+ * type guards to narrow the thrown error down to a specific type.
+ *
+ * @categoryDescription Passkeys (core)
+ * Creating, authenticating, updating and deleting passkeys. {@link registerPasskey}
+ * and {@link authenticatePasskey} are the key functions.
+ *
+ * @categoryDescription Passkeys (other)
+ * Testing for browser capabilities related to passkeys, type guards and other utilities.
+ *
+ * @showCategories
+ * @module unsafe
+ */
 import { Micro, pipe } from "effect";
-import { EventLogger, Logger } from "./logger";
-import { AuthenticationHelper, authenticatePasskey as authenticatePasskeyM, } from "./passkey/authentication";
-import { RegistrationHelper, registerPasskey as registerPasskeyM, } from "./passkey/registration";
-import { deletePasskey as deletePasskeyM, isPasskeyDeletionSupport as isPasskeyDeletionSupportM, isPasskeySyncSupport as isPasskeySyncSupportM, isPasskeyUpdateSupport as isPasskeyUpdateSupportM, signalCredentialRemoval, syncPasskeys as syncPasskeysM, updateUserDetails as updateUserDetailsM, } from "./passkey/signals";
-import { runToPromise } from "./shared/promise";
-export { ConsoleLogger, EventLogger, LogEvent, Logger, LogLevel } from "./logger";
+import { runToPromiseUnsafe } from "./internal";
+import { eventLogger, Logger } from "./logger";
+import { AuthenticationHelper, authenticatePasskey as authenticatePasskeyM, } from "./passkey/authentication/authentication";
+import { RegistrationHelper, registerPasskey as registerPasskeyM, } from "./passkey/registration/registration";
+import { deletePasskey as deletePasskeyM, isPasskeyDeleteSupport as isPasskeyDeleteSupportM, isPasskeyPruningSupport as isPasskeyPruningSupportM, isPasskeyUpdateSupport as isPasskeyUpdateSupportM, prunePasskeys as prunePasskeysM, updatePasskey as updatePasskeyM, } from "./passkey/signals/signals";
 /* Registration */
 /**
- * Register a passkey on the local device and store the
- * associated public key in your Passlock vault.
+ * Registers a passkey on the user's device, then saves the server-side component in your vault.
+ * If successful, this function returns both a `code` and an `id_token` (JWT).
+ * Send either value to your backend for verification.
+ * See [register a passkey](https://passlock.dev/passkeys/registration/) in the documentation.
+ *
  * @param options
- * @returns
+ *
+ * @returns A successful registration payload.
+ *
+ * @see {@link isRegistrationSuccess}
+ * @see {@link isPasskeyUnsupportedError}
+ * @see {@link isDuplicatePasskeyError}
+ * @see {@link isOtherPasskeyError}
+ *
+ * @throws {@link RegistrationError} (alias to a union of potential errors)
+ * @throws {@link PasskeyUnsupportedError} if the device does not support passkeys
+ * @throws {@link DuplicatePasskeyError} if `excludeCredentials` includes a passkey that already exists on the device
+ * @throws {@link OtherPasskeyError} typically a low level failure
+ * @throws {@link NetworkError}
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ * const username = "jdoe@gmail.com";
+ *
+ * try {
+ *   const result = await registerPasskey({ tenancyId, username });
+ *   // send this to your backend for verification
+ *   console.log(result.code);
+ * } catch (error) {
+ *   if (isPasskeyUnsupportedError(error)) {
+ *     alert("passkeys not supported on this device");
+ *   } else {
+ *     console.log(error);
+ *   }
+ * }
+ *
+ * @category Passkeys (core)
  */
-export const registerPasskey = async (options, logger = EventLogger) => pipe(registerPasskeyM(options), Micro.provideService(Logger, logger), Micro.provideService(RegistrationHelper, RegistrationHelper.Default), runToPromise);
-export { isOtherPasskeyError, isPasskeyUnsupported, OtherPasskeyError, PasskeyUnsupportedError, } from "./passkey/errors";
-export { DuplicatePasskeyError, isDuplicatePasskey, isRegistrationSuccess, } from "./passkey/registration";
-export { isUnexpectedError, UnexpectedError } from "./shared/network";
+export const registerPasskey = async (options, 
+/** @hidden */
+logger = eventLogger) => pipe(registerPasskeyM(options), Micro.provideService(RegistrationHelper, RegistrationHelper.Default), Micro.provideService(Logger, logger), runToPromiseUnsafe);
 /* Authentication */
 /**
- * Trigger local passkey authentication then verify the passkey in the Passlock vault.
- * Returns a code and id_token that can be exchanged/decoded in your backend.
+ * Asks the client to present a passkey, which is then verified against the server-side component in your vault.
+ * If successful, this function returns both a `code` and an `id_token` (JWT). Send either value to your backend for verification.
+ * See
+ * [authenticate a passkey](https://passlock.dev/passkeys/authentication/) in the documentation.
  *
  * @param options
- * @returns
+ *
+ * @returns A successful authentication payload.
+ *
+ * @see {@link isAuthenticationSuccess}
+ * @see {@link isPasskeyUnsupportedError}
+ * @see {@link isOrphanedPasskeyError}
+ * @see {@link isOtherPasskeyError}
+ *
+ * @throws {@link AuthenticationError} (alias to a union of potential errors)
+ * @throws {@link PasskeyUnsupportedError} if the device does not support passkeys
+ * @throws {@link OrphanedPasskeyError} if the passkey is orphaned i.e. deleted from the vault but still present on the local device
+ * @throws {@link OtherPasskeyError} typically a low level failure
+ * @throws {@link NetworkError}
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ *
+ * try {
+ *   const result = await authenticatePasskey({ tenancyId });
+ *   // send this to your backend for verification
+ *   console.log(result.code);
+ * } catch (error) {
+ *   if (isPasskeyUnsupportedError(error)) {
+ *     alert("passkeys not supported on this device");
+ *   } else {
+ *     console.log(error);
+ *   }
+ * }
+ *
+ * @category Passkeys (core)
  */
-export const authenticatePasskey = (options, logger = EventLogger) => pipe(authenticatePasskeyM(options), Micro.provideService(Logger, logger), Micro.provideService(AuthenticationHelper, AuthenticationHelper.Default), runToPromise);
-export { isAuthenticationSuccess, isPasskeyNotFound, } from "./passkey/authentication";
+export const authenticatePasskey = (options, 
+/** @hidden */
+logger = eventLogger) => pipe(authenticatePasskeyM(options), Micro.provideService(AuthenticationHelper, AuthenticationHelper.Default), Micro.provideService(Logger, logger), runToPromiseUnsafe);
 /* Signals */
-export const isPasskeyDeletionSupport = () => pipe(isPasskeyDeletionSupportM, Micro.runSync);
-export const isPasskeySyncSupport = () => pipe(isPasskeySyncSupportM, Micro.runSync);
-export const isPasskeyUpdateSupport = () => pipe(isPasskeyUpdateSupportM, Micro.runSync);
-export const deletePasskey = (identifiers, options, logger = EventLogger) => {
-    const micro = typeof identifiers === "string"
-        ? deletePasskeyM(identifiers, options)
-        : signalCredentialRemoval(identifiers);
-    return pipe(micro, Micro.provideService(Logger, logger), runToPromise);
+/**
+ * Attempt to update the username or display name for a passkey (client-side only).
+ *
+ * Useful if the user has changed their account identifier. For example, they register
+ * using jdoe@gmail.com but later change their account username to jdoe@yahoo.com.
+ * Even after you update their account details in your backend, their local password
+ * manager will continue to display jdoe@gmail.com.
+ *
+ * By calling this function and supplying a new username/display name, their local
+ * password manager will align with their updated account identifier.
+ *
+ * @param options You will typically supply a target `passkeyId` via {@link UpdatePasskeyOptions}. {@link UpdateCredentialOptions} is for advanced use cases.
+ * @returns Update status
+ * @see {@link isUpdateError}
+ * @throws {@link UpdateError} if the passkey cannot be updated
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ * const passkeyId = "myPasskeyId";
+ * const username = "newUsername@gmail.com";
+ * const displayName = "New Account Name";
+ *
+ * try {
+ *   const result = await updatePasskey({ tenancyId, passkeyId, username, displayName });
+ *   console.log("passkey updated");
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ * @category Passkeys (core)
+ */
+export const updatePasskey = (options, 
+/** @hidden */
+logger = eventLogger) => {
+    const micro = updatePasskeyM(options);
+    return pipe(micro, Micro.provideService(Logger, logger), runToPromiseUnsafe);
 };
-export { DeletionError, isDeletionError } from "./passkey/signals";
-export const syncPasskeys = (passkeyIds, options, logger = EventLogger) => {
-    const micro = syncPasskeysM(passkeyIds, options);
-    return pipe(micro, Micro.provideService(Logger, logger), runToPromise);
+/**
+ * Attempts to delete a passkey from a local device. There are two scenarios in which this function proves useful:
+ *
+ * 1. **Deleting a passkey**. Use the `@passlock/node` package or make vanilla REST calls from your
+ * backend to delete the server-side component, then use this function to delete the client-side component.
+ *
+ * 2. **Missing passkey**. The user tried to present a passkey, but the server-side component could not be found.
+ * Remove the passkey from the local device to prevent it happening again.
+ *
+ * See [deleting passkeys](https://passlock.dev/passkeys/passkey-removal/) and
+ * [handling missing passkeys](https://passlock.dev/handling-missing-passkeys/) in the documentation.
+ *
+ * @param options You typically pass a {@link DeletePasskeyOptions}, the other types are for advanced edge-cases.
+ * @returns A {@link DeleteSuccess} payload if the passkey is deleted.
+ * @see {@link isDeleteError}
+ * @throws {@link DeleteError} if the passkey cannot be deleted
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ * const passkeyId = "myPasskeyId";
+ *
+ * try {
+ *   const result = await deletePasskey({ tenancyId, passkeyId });
+ *   console.log("passkey deleted");
+ * } catch (error) {
+ *   console.log(error);
+ * }
+ *
+ * @category Passkeys (core)
+ */
+export const deletePasskey = (options, 
+/** @hidden */
+logger = eventLogger) => {
+    const micro = deletePasskeyM(options);
+    return pipe(micro, Micro.provideService(Logger, logger), runToPromiseUnsafe);
 };
-export { isSyncError, SyncError } from "./passkey/signals";
-export const updateUserDetails = (options, logger = EventLogger) => {
-    const micro = updateUserDetailsM(options);
-    return pipe(micro, Micro.provideService(Logger, logger), runToPromise);
+/**
+ * Attempt to prune local passkeys by keeping only the passkey IDs you trust.
+ *
+ * This is useful when your backend is the source of truth for which passkeys
+ * should still exist for a given account on this device.
+ *
+ * @param options Pass the passkeys you want to retain.
+ * @returns A {@link PruningSuccess} payload if local passkeys were pruned.
+ * @see {@link isPruningError}
+ *
+ * @throws {@link PruningError}
+ *
+ * @example
+ * // from your Passlock console settings
+ * const tenancyId = "myTenancyId";
+ * const allowablePasskeyIds = ["passkey-1", "passkey-2"];
+ *
+ * try {
+ *   const result = await prunePasskeys({ tenancyId, allowablePasskeyIds });
+ *   console.log("local passkeys pruned", result);
+ * } catch (error) {
+ *   if (isPruningError(error)) {
+ *     console.log(error.code);
+ *   } else {
+ *     console.log(error);
+ *   }
+ * }
+ *
+ * @category Passkeys (core)
+ */
+export const prunePasskeys = (options, 
+/** @hidden */
+logger = eventLogger) => {
+    const micro = prunePasskeysM(options);
+    return pipe(micro, Micro.provideService(Logger, logger), runToPromiseUnsafe);
 };
-export { isUpdateError, UpdateError } from "./passkey/signals";
 /* Support */
-export { isAutofillSupport, isPasskeySupport } from "./passkey/support";
+/**
+ * Does the local device support programmatic passkey deletion
+ *
+ * @returns `true` if local passkey deletion is supported.
+ *
+ * @category Passkeys (other)
+ */
+export const isPasskeyDeleteSupport = () => pipe(isPasskeyDeleteSupportM, Micro.runSync);
+/**
+ * Does the local device support programmatic passkey pruning
+ *
+ * @returns `true` if local passkey pruning is supported.
+ *
+ * @category Passkeys (other)
+ */
+export const isPasskeyPruningSupport = () => pipe(isPasskeyPruningSupportM, Micro.runSync);
+/**
+ * Does the local device support programmatic passkey updates
+ *
+ * @returns `true` if local passkey updates are supported.
+ *
+ * @category Passkeys (other)
+ */
+export const isPasskeyUpdateSupport = () => pipe(isPasskeyUpdateSupportM, Micro.runSync);
+/* Re-exports */
+export { isNetworkError, NetworkError } from "./internal/network";
+export { LogEvent, Logger, LogLevel, } from "./logger";
+export { AuthenticationHelper, isAuthenticationSuccess, } from "./passkey/authentication/authentication";
+export { DeleteError, DuplicatePasskeyError, isDeleteError, isDuplicatePasskeyError, isOrphanedPasskeyError, isOtherPasskeyError, isPasskeyUnsupportedError, isPruningError, isUpdateError, OrphanedPasskeyError, OtherPasskeyError, PasskeyUnsupportedError, PruningError, UpdateError, } from "./passkey/errors";
+export { isRegistrationSuccess, RegistrationHelper, } from "./passkey/registration/registration";
+export { isDeleteSuccess, isPruningSuccess, isUpdateSuccess, } from "./passkey/signals/signals";
+export { isAutofillSupport, isPasskeySupport, } from "./passkey/support";
 //# sourceMappingURL=index.js.map