@passlock/server 2.1.0 → 2.3.0

package/dist/safe.d.ts

@@ -1,19 +1,46 @@
 /**
- * Safe functions that return discriminated unions representing
- * the successful outcome or expected failures.
+ * Safe functions that return result envelopes over the original
+ * tagged success and error payloads. The returned value keeps
+ * its original `_tag` shape, and is also augmented with a
+ * result envelope for `success`- or `failure`-style branching.
  *
  * Note: unexpected runtime failures may still throw.
  *
+ * ```ts
+ * const result = await exchangeCode({
+ *   apiKey,
+ *   code,
+ *   tenancyId,
+ * })
+ *
+ * if (result.success) {
+ *   console.log(result.value.id)
+ * }
+ *
+ * if (result.failure) {
+ *   console.log(result.error.message)
+ * }
+ *
+ * if (isExtendedPrincipal(result)) {
+ *   console.log(result.id)
+ * }
+ * ```
+ *
  * @categoryDescription Passkeys
- * Functions and related types for managing passkeys
+ * Functions and related types for managing passkeys.
+ *
+ * @categoryDescription Principal
+ * Functions and related types for exchanging client codes and verifying
+ * Passlock tokens.
  *
  * @showCategories
  *
  * @module safe
  */
 import type { ForbiddenError, InvalidCodeError, NotFoundError, VerificationError } from "./errors.js";
-import type { AssignUserOptions, DeletePasskeyOptions, FindAllPasskeys, GetPasskeyOptions, ListPasskeyOptions, Passkey, UpdatedPasskeyUsernames, UpdatePasskeyOptions, UpdatePasskeyUsernamesOptions } from "./passkey/passkey.js";
+import type { AssignUserOptions, DeletedPasskey, DeletedPasskeys, DeletePasskeyOptions, DeleteUserPasskeysOptions, FindAllPasskeys, GetPasskeyOptions, ListPasskeyOptions, Passkey, UpdatedCredentials, UpdatePasskeyOptions, UpdateUsernamesOptions } from "./passkey/passkey.js";
 import type { ExchangeCodeOptions, VerifyIdTokenOptions } from "./principal/principal.js";
+import { type Result } from "./safe-result.js";
 import type { ExtendedPrincipal, Principal } from "./schemas/principal.js";
 /**
  * Assign a custom User ID to a passkey. Will be reflected in the next
@@ -27,14 +54,14 @@ import type { ExtendedPrincipal, Principal } from "./schemas/principal.js";
  * @see [credential](https://passlock.dev/rest-api/credential/)
  *
  * @param request
- * @returns A promise resolving to either a passkey or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * a passkey and whose error branch contains an API error.
  *
  * @category Passkeys
  */
-export declare const assignUser: (request: AssignUserOptions) => Promise<Passkey | NotFoundError | ForbiddenError>;
+export declare const assignUser: (request: AssignUserOptions) => Promise<Result<Passkey, NotFoundError | ForbiddenError>>;
 /**
- * Can also be used to assign a custom User ID, but also allows you to update
- * the username.
+ * Update a passkey's custom user ID and/or username metadata.
  *
  * **Important:** changing the username has no bearing on authentication, as
  * it's typically only used in the client-side component of the passkey
@@ -44,27 +71,37 @@ export declare const assignUser: (request: AssignUserOptions) => Promise<Passkey
  * client-side component to simplify end user support.
  *
  * @param request
- * @returns A promise resolving to either a passkey or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * a passkey and whose error branch contains an API error.
  *
  * @category Passkeys
  */
-export declare const updatePasskey: (request: UpdatePasskeyOptions) => Promise<Passkey | NotFoundError | ForbiddenError>;
+export declare const updatePasskey: (request: UpdatePasskeyOptions) => Promise<Result<Passkey, NotFoundError | ForbiddenError>>;
 /**
- * Update the username for all passkeys belonging to a given user.
+ * Update the stored username metadata for all passkeys belonging to a given
+ * user, and prepare client-side credential updates for those passkeys.
  *
- * **Important:** changing the username has no bearing on authentication, as
- * it's typically only used in the client-side component of the passkey
- * (so the user knows which account the passkey relates to).
+ * **Important:** changing these values has no bearing on authentication. The
+ * server-side operation updates the username stored in Passlock. The optional
+ * `displayName` is only included in the returned credential updates for
+ * follow-up use with `@passlock/client`; it is not persisted in the vault.
  *
  * However you might choose to align the username in your vault with the
  * client-side component to simplify end user support.
  *
+ * **Note:** This can be used alongside `@passlock/client`'s
+ * `updatePasskeyUsernames` helper to update those details on the user's device.
+ *
  * @param request
- * @returns A promise resolving to either updated passkey usernames or an API error.
+ * @returns A promise resolving to a {@link Result}.
+ * The success branch contains an {@link UpdatedCredentials} payload, whose
+ * `credentials` array can be passed into the client's `updatePasskeyUsernames` function.
+ * The error branch contains
+ * an API error.
  *
  * @category Passkeys
  */
-export declare const updatePasskeyUsernames: (request: UpdatePasskeyUsernamesOptions) => Promise<UpdatedPasskeyUsernames | NotFoundError | ForbiddenError>;
+export declare const updatePasskeyUsernames: (request: UpdateUsernamesOptions) => Promise<Result<UpdatedCredentials, NotFoundError | ForbiddenError>>;
 /**
  * Delete a passkey from your vault.
  *
@@ -85,11 +122,25 @@ export declare const updatePasskeyUsernames: (request: UpdatePasskeyUsernamesOpt
  * @see [handling missing passkeys](https://passlock.dev/handling-missing-passkeys/)
  *
  * @param options
- * @returns A promise resolving to either the deleted passkey or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * the deleted credential and whose error branch contains an API error.
+ *
+ * @category Passkeys
+ */
+export declare const deletePasskey: (options: DeletePasskeyOptions) => Promise<Result<DeletedPasskey, ForbiddenError | NotFoundError>>;
+/**
+ * Delete all passkeys associated with a user.
+ *
+ * @param request
+ * @returns A promise resolving to a {@link Result}.
+ * The success branch contains a {@link DeletedPasskeys} payload whose
+ * `deleted` array can be passed directly into `@passlock/client`'s
+ * `deleteUserPasskeys` helper for follow-up client-side passkey removal.
+ * The error branch contains an API error.
  *
  * @category Passkeys
  */
-export declare const deletePasskey: (options: DeletePasskeyOptions) => Promise<Passkey | ForbiddenError | NotFoundError>;
+export declare const deleteUserPasskeys: (request: DeleteUserPasskeysOptions) => Promise<Result<DeletedPasskeys, ForbiddenError | NotFoundError>>;
 /**
  * Fetch details about a passkey. **Important**: Not to be confused with
  * the {@link exchangeCode} or {@link verifyIdToken} functions, which
@@ -97,21 +148,23 @@ export declare const deletePasskey: (options: DeletePasskeyOptions) => Promise<P
  * Use this function for passkey management, not authentication.
  *
  * @param options
- * @returns A promise resolving to either passkey details or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * passkey details and whose error branch contains an API error.
  *
  * @category Passkeys
  */
-export declare const getPasskey: (options: GetPasskeyOptions) => Promise<Passkey | ForbiddenError | NotFoundError>;
+export declare const getPasskey: (options: GetPasskeyOptions) => Promise<Result<Passkey, ForbiddenError | NotFoundError>>;
 /**
  * List passkeys for the given tenancy. Note: This could return a cursor.
  * If so, call again, passing the cursor back in.
  *
  * @param options
- * @returns A promise resolving to a page of passkey summaries or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * a page of passkey summaries and whose error branch contains an API error.
  *
  * @category Passkeys
  */
-export declare const listPasskeys: (options: ListPasskeyOptions) => Promise<FindAllPasskeys | ForbiddenError>;
+export declare const listPasskeys: (options: ListPasskeyOptions) => Promise<Result<FindAllPasskeys, ForbiddenError>>;
 /**
  * The @passlock/client library generates codes, which you should send to
  * your backend. Use this function to exchange the code for details about
@@ -121,32 +174,36 @@ export declare const listPasskeys: (options: ListPasskeyOptions) => Promise<Find
  * @see {@link ExtendedPrincipal}
  *
  * @param options
- * @returns A promise resolving to an extended principal or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * an extended principal and whose error branch contains an API error.
  *
  * @category Principal
  */
-export declare const exchangeCode: (options: ExchangeCodeOptions) => Promise<ExtendedPrincipal | ForbiddenError | InvalidCodeError>;
+export declare const exchangeCode: (options: ExchangeCodeOptions) => Promise<Result<ExtendedPrincipal, ForbiddenError | InvalidCodeError>>;
 /**
  * Decode and verify an id_token (JWT) locally.
+ *
  * **Note:** This will make a network call to
  * `https://api.passlock.dev/.well-known/jwks.json` (or your configured `endpoint`)
  * to fetch the relevant public key. The response will be cached, however
- * bear in mind that for something like AWS Lambda it will make the call on every
- * cold start so might actually be slower than {@link exchangeCode}
+ * bear in mind that for environments such as AWS Lambda it will make the call
+ * on each cold start, so it might be slower than {@link exchangeCode}.
  *
  * @see {@link Principal}
  *
  * @param options
- * @returns A promise resolving to a verified principal or verification failure.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * a verified principal and whose error branch contains a verification error.
  *
  * @category Principal
  */
-export declare const verifyIdToken: (options: VerifyIdTokenOptions) => Promise<Principal | VerificationError>;
+export declare const verifyIdToken: (options: VerifyIdTokenOptions) => Promise<Result<Principal, VerificationError>>;
 export type { BadRequestError, DuplicateEmailError, ForbiddenError, InvalidCodeError, InvalidEmailError, InvalidTenancyError, NotFoundError, PasskeyNotFoundError, UnauthorizedError, VerificationError, } from "./errors.js";
 export { isBadRequestError, isDuplicateEmailError, isForbiddenError, isInvalidCodeError, isInvalidEmailError, isInvalidTenancyError, isNotFoundError, isPasskeyNotFoundError, isUnauthorizedError, isVerificationError, } from "./errors.js";
-export type { AssignUserOptions, Credential, DeletePasskeyOptions, FindAllPasskeys, GetPasskeyOptions, ListPasskeyOptions, Passkey, PasskeySummary, Platform, UpdatedPasskeys, UpdatedPasskeyUsernames, UpdatePasskeyOptions, UpdatePasskeyUsernamesOptions, } from "./passkey/passkey.js";
-export { isPasskey, isPasskeySummary, isUpdatedPasskeys, isUpdatedPasskeyUsernames, } from "./passkey/passkey.js";
+export type { AssignUserOptions, Credential, DeletedPasskey, DeletedPasskeys, DeletePasskeyOptions, DeleteUserPasskeysOptions, FindAllPasskeys, GetPasskeyOptions, ListPasskeyOptions, Passkey, PasskeyCredential, PasskeySummary, Platform, UpdatedCredentials as UpdatedUserDetails, UpdatedPasskeys, UpdatePasskeyOptions, UpdateUsernamesOptions as UpdateUserDetailsOptions, } from "./passkey/passkey.js";
+export { isDeletedPasskeys, isPasskey, isPasskeySummary, isUpdatedPasskeys, isUpdatedUserDetails, } from "./passkey/passkey.js";
 export type { ExchangeCodeOptions, VerifyIdTokenOptions, } from "./principal/principal.js";
+export type { Err, Ok, Result } from "./safe-result.js";
 export type { CredentialDeviceType, Transports, } from "./schemas/passkey.js";
 export type { ExtendedPrincipal, Principal } from "./schemas/principal.js";
 export { isExtendedPrincipal, isPrincipal } from "./schemas/principal.js";

package/dist/safe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe.d.ts","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"safe.d.ts","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"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"}

package/dist/safe.js

@@ -1,19 +1,50 @@
 /**
- * Safe functions that return discriminated unions representing
- * the successful outcome or expected failures.
+ * Safe functions that return result envelopes over the original
+ * tagged success and error payloads. The returned value keeps
+ * its original `_tag` shape, and is also augmented with a
+ * result envelope for `success`- or `failure`-style branching.
  *
  * Note: unexpected runtime failures may still throw.
  *
+ * ```ts
+ * const result = await exchangeCode({
+ *   apiKey,
+ *   code,
+ *   tenancyId,
+ * })
+ *
+ * if (result.success) {
+ *   console.log(result.value.id)
+ * }
+ *
+ * if (result.failure) {
+ *   console.log(result.error.message)
+ * }
+ *
+ * if (isExtendedPrincipal(result)) {
+ *   console.log(result.id)
+ * }
+ * ```
+ *
  * @categoryDescription Passkeys
- * Functions and related types for managing passkeys
+ * Functions and related types for managing passkeys.
+ *
+ * @categoryDescription Principal
+ * Functions and related types for exchanging client codes and verifying
+ * Passlock tokens.
  *
  * @showCategories
  *
  * @module safe
  */
-import { Effect, identity, pipe } from "effect";
-import { assignUser as assignUserE, deletePasskey as deletePasskeyE, getPasskey as getPasskeyE, listPasskeys as listPasskeysE, updatePasskey as updatePasskeyE, updatePasskeyUsernames as updatePasskeyUsernamesE, } from "./passkey/passkey.js";
+import { Effect, pipe } from "effect";
+import { assignUser as assignUserE, deletePasskey as deletePasskeyE, deleteUserPasskeys as deleteUserPasskeysE, getPasskey as getPasskeyE, listPasskeys as listPasskeysE, updatePasskey as updatePasskeyE, updatePasskeyUsernames as updatePasskeyUsernamesE, } from "./passkey/passkey.js";
 import { exchangeCode as exchangeCodeE, verifyIdToken as verifyIdTokenE, } from "./principal/principal.js";
+import { toErrResult, toOkResult } from "./safe-result.js";
+const runSafe = (effect) => pipe(effect, Effect.match({
+    onFailure: (error) => toErrResult(error),
+    onSuccess: (value) => toOkResult(value),
+}), Effect.runPromise);
 /**
  * Assign a custom User ID to a passkey. Will be reflected in the next
  * {@link Principal} or {@link ExtendedPrincipal} generated.
@@ -26,14 +57,14 @@ import { exchangeCode as exchangeCodeE, verifyIdToken as verifyIdTokenE, } from
  * @see [credential](https://passlock.dev/rest-api/credential/)
  *
  * @param request
- * @returns A promise resolving to either a passkey or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * a passkey and whose error branch contains an API error.
  *
  * @category Passkeys
  */
-export const assignUser = (request) => pipe(assignUserE(request), Effect.match({ onFailure: identity, onSuccess: identity }), Effect.runPromise);
+export const assignUser = (request) => runSafe(assignUserE(request));
 /**
- * Can also be used to assign a custom User ID, but also allows you to update
- * the username.
+ * Update a passkey's custom user ID and/or username metadata.
  *
  * **Important:** changing the username has no bearing on authentication, as
  * it's typically only used in the client-side component of the passkey
@@ -43,27 +74,37 @@ export const assignUser = (request) => pipe(assignUserE(request), Effect.match({
  * client-side component to simplify end user support.
  *
  * @param request
- * @returns A promise resolving to either a passkey or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * a passkey and whose error branch contains an API error.
  *
  * @category Passkeys
  */
-export const updatePasskey = (request) => pipe(updatePasskeyE(request), Effect.match({ onFailure: identity, onSuccess: identity }), Effect.runPromise);
+export const updatePasskey = (request) => runSafe(updatePasskeyE(request));
 /**
- * Update the username for all passkeys belonging to a given user.
+ * Update the stored username metadata for all passkeys belonging to a given
+ * user, and prepare client-side credential updates for those passkeys.
  *
- * **Important:** changing the username has no bearing on authentication, as
- * it's typically only used in the client-side component of the passkey
- * (so the user knows which account the passkey relates to).
+ * **Important:** changing these values has no bearing on authentication. The
+ * server-side operation updates the username stored in Passlock. The optional
+ * `displayName` is only included in the returned credential updates for
+ * follow-up use with `@passlock/client`; it is not persisted in the vault.
  *
  * However you might choose to align the username in your vault with the
  * client-side component to simplify end user support.
  *
+ * **Note:** This can be used alongside `@passlock/client`'s
+ * `updatePasskeyUsernames` helper to update those details on the user's device.
+ *
  * @param request
- * @returns A promise resolving to either updated passkey usernames or an API error.
+ * @returns A promise resolving to a {@link Result}.
+ * The success branch contains an {@link UpdatedCredentials} payload, whose
+ * `credentials` array can be passed into the client's `updatePasskeyUsernames` function.
+ * The error branch contains
+ * an API error.
  *
  * @category Passkeys
  */
-export const updatePasskeyUsernames = (request) => pipe(updatePasskeyUsernamesE(request), Effect.match({ onFailure: identity, onSuccess: identity }), Effect.runPromise);
+export const updatePasskeyUsernames = (request) => runSafe(updatePasskeyUsernamesE(request));
 /**
  * Delete a passkey from your vault.
  *
@@ -84,11 +125,25 @@ export const updatePasskeyUsernames = (request) => pipe(updatePasskeyUsernamesE(
  * @see [handling missing passkeys](https://passlock.dev/handling-missing-passkeys/)
  *
  * @param options
- * @returns A promise resolving to either the deleted passkey or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * the deleted credential and whose error branch contains an API error.
+ *
+ * @category Passkeys
+ */
+export const deletePasskey = (options) => runSafe(deletePasskeyE(options));
+/**
+ * Delete all passkeys associated with a user.
+ *
+ * @param request
+ * @returns A promise resolving to a {@link Result}.
+ * The success branch contains a {@link DeletedPasskeys} payload whose
+ * `deleted` array can be passed directly into `@passlock/client`'s
+ * `deleteUserPasskeys` helper for follow-up client-side passkey removal.
+ * The error branch contains an API error.
  *
  * @category Passkeys
  */
-export const deletePasskey = (options) => pipe(deletePasskeyE(options), Effect.match({ onFailure: identity, onSuccess: identity }), Effect.runPromise);
+export const deleteUserPasskeys = (request) => runSafe(deleteUserPasskeysE(request));
 /**
  * Fetch details about a passkey. **Important**: Not to be confused with
  * the {@link exchangeCode} or {@link verifyIdToken} functions, which
@@ -96,21 +151,23 @@ export const deletePasskey = (options) => pipe(deletePasskeyE(options), Effect.m
  * Use this function for passkey management, not authentication.
  *
  * @param options
- * @returns A promise resolving to either passkey details or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * passkey details and whose error branch contains an API error.
  *
  * @category Passkeys
  */
-export const getPasskey = (options) => pipe(getPasskeyE(options), Effect.match({ onFailure: identity, onSuccess: identity }), Effect.runPromise);
+export const getPasskey = (options) => runSafe(getPasskeyE(options));
 /**
  * List passkeys for the given tenancy. Note: This could return a cursor.
  * If so, call again, passing the cursor back in.
  *
  * @param options
- * @returns A promise resolving to a page of passkey summaries or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * a page of passkey summaries and whose error branch contains an API error.
  *
  * @category Passkeys
  */
-export const listPasskeys = (options) => pipe(listPasskeysE(options), Effect.match({ onFailure: identity, onSuccess: identity }), Effect.runPromise);
+export const listPasskeys = (options) => runSafe(listPasskeysE(options));
 /**
  * The @passlock/client library generates codes, which you should send to
  * your backend. Use this function to exchange the code for details about
@@ -120,28 +177,31 @@ export const listPasskeys = (options) => pipe(listPasskeysE(options), Effect.mat
  * @see {@link ExtendedPrincipal}
  *
  * @param options
- * @returns A promise resolving to an extended principal or an API error.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * an extended principal and whose error branch contains an API error.
  *
  * @category Principal
  */
-export const exchangeCode = (options) => pipe(exchangeCodeE(options), Effect.match({ onFailure: identity, onSuccess: identity }), Effect.runPromise);
+export const exchangeCode = (options) => runSafe(exchangeCodeE(options));
 /**
  * Decode and verify an id_token (JWT) locally.
+ *
  * **Note:** This will make a network call to
  * `https://api.passlock.dev/.well-known/jwks.json` (or your configured `endpoint`)
  * to fetch the relevant public key. The response will be cached, however
- * bear in mind that for something like AWS Lambda it will make the call on every
- * cold start so might actually be slower than {@link exchangeCode}
+ * bear in mind that for environments such as AWS Lambda it will make the call
+ * on each cold start, so it might be slower than {@link exchangeCode}.
  *
  * @see {@link Principal}
  *
  * @param options
- * @returns A promise resolving to a verified principal or verification failure.
+ * @returns A promise resolving to a {@link Result} whose success branch contains
+ * a verified principal and whose error branch contains a verification error.
  *
  * @category Principal
  */
-export const verifyIdToken = (options) => pipe(verifyIdTokenE(options), Effect.match({ onFailure: identity, onSuccess: identity }), Effect.runPromise);
+export const verifyIdToken = (options) => runSafe(verifyIdTokenE(options));
 export { isBadRequestError, isDuplicateEmailError, isForbiddenError, isInvalidCodeError, isInvalidEmailError, isInvalidTenancyError, isNotFoundError, isPasskeyNotFoundError, isUnauthorizedError, isVerificationError, } from "./errors.js";
-export { isPasskey, isPasskeySummary, isUpdatedPasskeys, isUpdatedPasskeyUsernames, } from "./passkey/passkey.js";
+export { isDeletedPasskeys, isPasskey, isPasskeySummary, isUpdatedPasskeys, isUpdatedUserDetails, } from "./passkey/passkey.js";
 export { isExtendedPrincipal, isPrincipal } from "./schemas/principal.js";
 //# sourceMappingURL=safe.js.map

package/dist/safe.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe.js","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Safe functions that return discriminated unions representing\n * the successful outcome or expected failures.\n *\n * Note: unexpected runtime failures may still throw.\n *\n * @categoryDescription Passkeys\n * Functions and related types for managing passkeys\n *\n * @showCategories\n *\n * @module safe\n */\n\nimport { Effect, identity, pipe } from \"effect\"\nimport type {\n  ForbiddenError,\n  InvalidCodeError,\n  NotFoundError,\n  VerificationError,\n} from \"./errors.js\"\nimport type {\n  AssignUserOptions,\n  DeletePasskeyOptions,\n  FindAllPasskeys,\n  GetPasskeyOptions,\n  ListPasskeyOptions,\n  Passkey,\n  UpdatedPasskeyUsernames,\n  UpdatePasskeyOptions,\n  UpdatePasskeyUsernamesOptions,\n} from \"./passkey/passkey.js\"\nimport {\n  assignUser as assignUserE,\n  deletePasskey as deletePasskeyE,\n  getPasskey as getPasskeyE,\n  listPasskeys as listPasskeysE,\n  updatePasskey as updatePasskeyE,\n  updatePasskeyUsernames as updatePasskeyUsernamesE,\n} from \"./passkey/passkey.js\"\nimport type {\n  ExchangeCodeOptions,\n  VerifyIdTokenOptions,\n} from \"./principal/principal.js\"\nimport {\n  exchangeCode as exchangeCodeE,\n  verifyIdToken as verifyIdTokenE,\n} from \"./principal/principal.js\"\nimport type { ExtendedPrincipal, Principal } from \"./schemas/principal.js\"\n\n/**\n * Assign a custom User ID to a passkey. Will be reflected in the next\n * {@link Principal} or {@link ExtendedPrincipal} generated.\n *\n * **Note:** This does not change the underlying WebAuthn credential's `userId`.\n * Instead we apply a layer of indirection.\n *\n * @see {@link Principal}\n * @see {@link ExtendedPrincipal}\n * @see [credential](https://passlock.dev/rest-api/credential/)\n *\n * @param request\n * @returns A promise resolving to either a passkey or an API error.\n *\n * @category Passkeys\n */\nexport const assignUser = (\n  request: AssignUserOptions\n): Promise<Passkey | NotFoundError | ForbiddenError> =>\n  pipe(\n    assignUserE(request),\n    Effect.match({ onFailure: identity, onSuccess: identity }),\n    Effect.runPromise\n  )\n\n/**\n * Can also be used to assign a custom User ID, but also allows you to update\n * the username.\n *\n * **Important:** changing the username has no bearing on authentication, as\n * it's typically only used in the client-side component of the passkey\n * (so the user knows which account the passkey relates to).\n *\n * However you might choose to align the username in your vault with the\n * client-side component to simplify end user support.\n *\n * @param request\n * @returns A promise resolving to either a passkey or an API error.\n *\n * @category Passkeys\n */\nexport const updatePasskey = (\n  request: UpdatePasskeyOptions\n): Promise<Passkey | NotFoundError | ForbiddenError> =>\n  pipe(\n    updatePasskeyE(request),\n    Effect.match({ onFailure: identity, onSuccess: identity }),\n    Effect.runPromise\n  )\n\n/**\n * Update the username for all passkeys belonging to a given user.\n *\n * **Important:** changing the username has no bearing on authentication, as\n * it's typically only used in the client-side component of the passkey\n * (so the user knows which account the passkey relates to).\n *\n * However you might choose to align the username in your vault with the\n * client-side component to simplify end user support.\n *\n * @param request\n * @returns A promise resolving to either updated passkey usernames or an API error.\n *\n * @category Passkeys\n */\nexport const updatePasskeyUsernames = (\n  request: UpdatePasskeyUsernamesOptions\n): Promise<UpdatedPasskeyUsernames | NotFoundError | ForbiddenError> =>\n  pipe(\n    updatePasskeyUsernamesE(request),\n    Effect.match({ onFailure: identity, onSuccess: identity }),\n    Effect.runPromise\n  )\n\n/**\n * Delete a passkey from your vault.\n *\n * **Note:** The user will still retain the passkey on their device so\n * you will need to either:\n *\n * a) Use the @passlock/client functions to delete the passkey from the user's device.\n * b) Remind the user to delete the passkey\n *\n * See [deleting passkeys](https://passlock.dev/passkeys/passkey-removal/) in the documentation.\n *\n * In addition, during authentication you should handle a missing passkey scenario.\n * This happens when a user tries to authenticate with a passkey that is missing from\n * your vault. The @passlock/client library can help with this. See\n * [handling missing passkeys](https://passlock.dev/handling-missing-passkeys/)\n *\n * @see [deleting passkeys](https://passlock.dev/passkeys/passkey-removal/)\n * @see [handling missing passkeys](https://passlock.dev/handling-missing-passkeys/)\n *\n * @param options\n * @returns A promise resolving to either the deleted passkey or an API error.\n *\n * @category Passkeys\n */\nexport const deletePasskey = (\n  options: DeletePasskeyOptions\n): Promise<Passkey | ForbiddenError | NotFoundError> =>\n  pipe(\n    deletePasskeyE(options),\n    Effect.match({ onFailure: identity, onSuccess: identity }),\n    Effect.runPromise\n  )\n\n/**\n * Fetch details about a passkey. **Important**: Not to be confused with\n * the {@link exchangeCode} or {@link verifyIdToken} functions, which\n * return details about specific authentication or registration operations.\n * Use this function for passkey management, not authentication.\n *\n * @param options\n * @returns A promise resolving to either passkey details or an API error.\n *\n * @category Passkeys\n */\nexport const getPasskey = (\n  options: GetPasskeyOptions\n): Promise<Passkey | ForbiddenError | NotFoundError> =>\n  pipe(\n    getPasskeyE(options),\n    Effect.match({ onFailure: identity, onSuccess: identity }),\n    Effect.runPromise\n  )\n\n/**\n * List passkeys for the given tenancy. Note: This could return a cursor.\n * If so, call again, passing the cursor back in.\n *\n * @param options\n * @returns A promise resolving to a page of passkey summaries or an API error.\n *\n * @category Passkeys\n */\nexport const listPasskeys = (\n  options: ListPasskeyOptions\n): Promise<FindAllPasskeys | ForbiddenError> =>\n  pipe(\n    listPasskeysE(options),\n    Effect.match({ onFailure: identity, onSuccess: identity }),\n    Effect.runPromise\n  )\n\n/**\n * The @passlock/client library generates codes, which you should send to\n * your backend. Use this function to exchange the code for details about\n * the registration or authentication operation. **Note:** a code is valid\n * for 5 minutes.\n *\n * @see {@link ExtendedPrincipal}\n *\n * @param options\n * @returns A promise resolving to an extended principal or an API error.\n *\n * @category Principal\n */\nexport const exchangeCode = (\n  options: ExchangeCodeOptions\n): Promise<ExtendedPrincipal | ForbiddenError | InvalidCodeError> =>\n  pipe(\n    exchangeCodeE(options),\n    Effect.match({ onFailure: identity, onSuccess: identity }),\n    Effect.runPromise\n  )\n\n/**\n * Decode and verify an id_token (JWT) locally.\n * **Note:** This will make a network call to\n * `https://api.passlock.dev/.well-known/jwks.json` (or your configured `endpoint`)\n * to fetch the relevant public key. The response will be cached, however\n * bear in mind that for something like AWS Lambda it will make the call on every\n * cold start so might actually be slower than {@link exchangeCode}\n *\n * @see {@link Principal}\n *\n * @param options\n * @returns A promise resolving to a verified principal or verification failure.\n *\n * @category Principal\n */\nexport const verifyIdToken = (\n  options: VerifyIdTokenOptions\n): Promise<Principal | VerificationError> =>\n  pipe(\n    verifyIdTokenE(options),\n    Effect.match({ onFailure: identity, onSuccess: identity }),\n    Effect.runPromise\n  )\n\n/* Re-exports */\n\nexport type {\n  BadRequestError,\n  DuplicateEmailError,\n  ForbiddenError,\n  InvalidCodeError,\n  InvalidEmailError,\n  InvalidTenancyError,\n  NotFoundError,\n  PasskeyNotFoundError,\n  UnauthorizedError,\n  VerificationError,\n} from \"./errors.js\"\nexport {\n  isBadRequestError,\n  isDuplicateEmailError,\n  isForbiddenError,\n  isInvalidCodeError,\n  isInvalidEmailError,\n  isInvalidTenancyError,\n  isNotFoundError,\n  isPasskeyNotFoundError,\n  isUnauthorizedError,\n  isVerificationError,\n} from \"./errors.js\"\nexport type {\n  AssignUserOptions,\n  Credential,\n  DeletePasskeyOptions,\n  FindAllPasskeys,\n  GetPasskeyOptions,\n  ListPasskeyOptions,\n  Passkey,\n  PasskeySummary,\n  Platform,\n  UpdatedPasskeys,\n  UpdatedPasskeyUsernames,\n  UpdatePasskeyOptions,\n  UpdatePasskeyUsernamesOptions,\n} from \"./passkey/passkey.js\"\nexport {\n  isPasskey,\n  isPasskeySummary,\n  isUpdatedPasskeys,\n  isUpdatedPasskeyUsernames,\n} from \"./passkey/passkey.js\"\nexport type {\n  ExchangeCodeOptions,\n  VerifyIdTokenOptions,\n} from \"./principal/principal.js\"\nexport type {\n  CredentialDeviceType,\n  Transports,\n} from \"./schemas/passkey.js\"\nexport type { ExtendedPrincipal, Principal } from \"./schemas/principal.js\"\nexport { isExtendedPrincipal, isPrincipal } from \"./schemas/principal.js\"\nexport type {\n  AuthenticatedOptions,\n  PasslockOptions,\n} from \"./shared.js\"\n"]}
+{"version":3,"file":"safe.js","sourceRoot":"","sources":["../src/safe.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Safe functions that return result envelopes over the original\n * tagged success and error payloads. The returned value keeps\n * its original `_tag` shape, and is also augmented with a\n * result envelope for `success`- or `failure`-style branching.\n *\n * Note: unexpected runtime failures may still throw.\n *\n * ```ts\n * const result = await exchangeCode({\n *   apiKey,\n *   code,\n *   tenancyId,\n * })\n *\n * if (result.success) {\n *   console.log(result.value.id)\n * }\n *\n * if (result.failure) {\n *   console.log(result.error.message)\n * }\n *\n * if (isExtendedPrincipal(result)) {\n *   console.log(result.id)\n * }\n * ```\n *\n * @categoryDescription Passkeys\n * Functions and related types for managing passkeys.\n *\n * @categoryDescription Principal\n * Functions and related types for exchanging client codes and verifying\n * Passlock tokens.\n *\n * @showCategories\n *\n * @module safe\n */\n\nimport { Effect, pipe } from \"effect\"\nimport type {\n  ForbiddenError,\n  InvalidCodeError,\n  NotFoundError,\n  VerificationError,\n} from \"./errors.js\"\nimport type {\n  AssignUserOptions,\n  DeletedPasskey,\n  DeletedPasskeys,\n  DeletePasskeyOptions,\n  DeleteUserPasskeysOptions,\n  FindAllPasskeys,\n  GetPasskeyOptions,\n  ListPasskeyOptions,\n  Passkey,\n  UpdatedCredentials,\n  UpdatePasskeyOptions,\n  UpdateUsernamesOptions,\n} from \"./passkey/passkey.js\"\nimport {\n  assignUser as assignUserE,\n  deletePasskey as deletePasskeyE,\n  deleteUserPasskeys as deleteUserPasskeysE,\n  getPasskey as getPasskeyE,\n  listPasskeys as listPasskeysE,\n  updatePasskey as updatePasskeyE,\n  updatePasskeyUsernames as updatePasskeyUsernamesE,\n} from \"./passkey/passkey.js\"\nimport type {\n  ExchangeCodeOptions,\n  VerifyIdTokenOptions,\n} from \"./principal/principal.js\"\nimport {\n  exchangeCode as exchangeCodeE,\n  verifyIdToken as verifyIdTokenE,\n} from \"./principal/principal.js\"\nimport { type Result, toErrResult, toOkResult } from \"./safe-result.js\"\nimport type { ExtendedPrincipal, Principal } from \"./schemas/principal.js\"\n\nconst runSafe = <A extends object, E extends object>(\n  effect: Effect.Effect<A, E>\n): Promise<Result<A, E>> =>\n  pipe(\n    effect,\n    Effect.match({\n      onFailure: (error): Result<A, E> => toErrResult(error) as Result<A, E>,\n      onSuccess: (value): Result<A, E> => toOkResult(value) as Result<A, E>,\n    }),\n    Effect.runPromise\n  )\n\n/**\n * Assign a custom User ID to a passkey. Will be reflected in the next\n * {@link Principal} or {@link ExtendedPrincipal} generated.\n *\n * **Note:** This does not change the underlying WebAuthn credential's `userId`.\n * Instead we apply a layer of indirection.\n *\n * @see {@link Principal}\n * @see {@link ExtendedPrincipal}\n * @see [credential](https://passlock.dev/rest-api/credential/)\n *\n * @param request\n * @returns A promise resolving to a {@link Result} whose success branch contains\n * a passkey and whose error branch contains an API error.\n *\n * @category Passkeys\n */\nexport const assignUser = (\n  request: AssignUserOptions\n): Promise<Result<Passkey, NotFoundError | ForbiddenError>> =>\n  runSafe(assignUserE(request))\n\n/**\n * Update a passkey's custom user ID and/or username metadata.\n *\n * **Important:** changing the username has no bearing on authentication, as\n * it's typically only used in the client-side component of the passkey\n * (so the user knows which account the passkey relates to).\n *\n * However you might choose to align the username in your vault with the\n * client-side component to simplify end user support.\n *\n * @param request\n * @returns A promise resolving to a {@link Result} whose success branch contains\n * a passkey and whose error branch contains an API error.\n *\n * @category Passkeys\n */\nexport const updatePasskey = (\n  request: UpdatePasskeyOptions\n): Promise<Result<Passkey, NotFoundError | ForbiddenError>> =>\n  runSafe(updatePasskeyE(request))\n\n/**\n * Update the stored username metadata for all passkeys belonging to a given\n * user, and prepare client-side credential updates for those passkeys.\n *\n * **Important:** changing these values has no bearing on authentication. The\n * server-side operation updates the username stored in Passlock. The optional\n * `displayName` is only included in the returned credential updates for\n * follow-up use with `@passlock/client`; it is not persisted in the vault.\n *\n * However you might choose to align the username in your vault with the\n * client-side component to simplify end user support.\n *\n * **Note:** This can be used alongside `@passlock/client`'s\n * `updatePasskeyUsernames` helper to update those details on the user's device.\n *\n * @param request\n * @returns A promise resolving to a {@link Result}.\n * The success branch contains an {@link UpdatedCredentials} payload, whose\n * `credentials` array can be passed into the client's `updatePasskeyUsernames` function.\n * The error branch contains\n * an API error.\n *\n * @category Passkeys\n */\nexport const updatePasskeyUsernames = (\n  request: UpdateUsernamesOptions\n): Promise<Result<UpdatedCredentials, NotFoundError | ForbiddenError>> =>\n  runSafe(updatePasskeyUsernamesE(request))\n\n/**\n * Delete a passkey from your vault.\n *\n * **Note:** The user will still retain the passkey on their device so\n * you will need to either:\n *\n * a) Use the @passlock/client functions to delete the passkey from the user's device.\n * b) Remind the user to delete the passkey\n *\n * See [deleting passkeys](https://passlock.dev/passkeys/passkey-removal/) in the documentation.\n *\n * In addition, during authentication you should handle a missing passkey scenario.\n * This happens when a user tries to authenticate with a passkey that is missing from\n * your vault. The @passlock/client library can help with this. See\n * [handling missing passkeys](https://passlock.dev/handling-missing-passkeys/)\n *\n * @see [deleting passkeys](https://passlock.dev/passkeys/passkey-removal/)\n * @see [handling missing passkeys](https://passlock.dev/handling-missing-passkeys/)\n *\n * @param options\n * @returns A promise resolving to a {@link Result} whose success branch contains\n * the deleted credential and whose error branch contains an API error.\n *\n * @category Passkeys\n */\nexport const deletePasskey = (\n  options: DeletePasskeyOptions\n): Promise<Result<DeletedPasskey, ForbiddenError | NotFoundError>> =>\n  runSafe(deletePasskeyE(options))\n\n/**\n * Delete all passkeys associated with a user.\n *\n * @param request\n * @returns A promise resolving to a {@link Result}.\n * The success branch contains a {@link DeletedPasskeys} payload whose\n * `deleted` array can be passed directly into `@passlock/client`'s\n * `deleteUserPasskeys` helper for follow-up client-side passkey removal.\n * The error branch contains an API error.\n *\n * @category Passkeys\n */\nexport const deleteUserPasskeys = (\n  request: DeleteUserPasskeysOptions\n): Promise<Result<DeletedPasskeys, ForbiddenError | NotFoundError>> =>\n  runSafe(deleteUserPasskeysE(request))\n\n/**\n * Fetch details about a passkey. **Important**: Not to be confused with\n * the {@link exchangeCode} or {@link verifyIdToken} functions, which\n * return details about specific authentication or registration operations.\n * Use this function for passkey management, not authentication.\n *\n * @param options\n * @returns A promise resolving to a {@link Result} whose success branch contains\n * passkey details and whose error branch contains an API error.\n *\n * @category Passkeys\n */\nexport const getPasskey = (\n  options: GetPasskeyOptions\n): Promise<Result<Passkey, ForbiddenError | NotFoundError>> =>\n  runSafe(getPasskeyE(options))\n\n/**\n * List passkeys for the given tenancy. Note: This could return a cursor.\n * If so, call again, passing the cursor back in.\n *\n * @param options\n * @returns A promise resolving to a {@link Result} whose success branch contains\n * a page of passkey summaries and whose error branch contains an API error.\n *\n * @category Passkeys\n */\nexport const listPasskeys = (\n  options: ListPasskeyOptions\n): Promise<Result<FindAllPasskeys, ForbiddenError>> =>\n  runSafe(listPasskeysE(options))\n\n/**\n * The @passlock/client library generates codes, which you should send to\n * your backend. Use this function to exchange the code for details about\n * the registration or authentication operation. **Note:** a code is valid\n * for 5 minutes.\n *\n * @see {@link ExtendedPrincipal}\n *\n * @param options\n * @returns A promise resolving to a {@link Result} whose success branch contains\n * an extended principal and whose error branch contains an API error.\n *\n * @category Principal\n */\nexport const exchangeCode = (\n  options: ExchangeCodeOptions\n): Promise<Result<ExtendedPrincipal, ForbiddenError | InvalidCodeError>> =>\n  runSafe(exchangeCodeE(options))\n\n/**\n * Decode and verify an id_token (JWT) locally.\n *\n * **Note:** This will make a network call to\n * `https://api.passlock.dev/.well-known/jwks.json` (or your configured `endpoint`)\n * to fetch the relevant public key. The response will be cached, however\n * bear in mind that for environments such as AWS Lambda it will make the call\n * on each cold start, so it might be slower than {@link exchangeCode}.\n *\n * @see {@link Principal}\n *\n * @param options\n * @returns A promise resolving to a {@link Result} whose success branch contains\n * a verified principal and whose error branch contains a verification error.\n *\n * @category Principal\n */\nexport const verifyIdToken = (\n  options: VerifyIdTokenOptions\n): Promise<Result<Principal, VerificationError>> =>\n  runSafe(verifyIdTokenE(options))\n\n/* Re-exports */\n\nexport type {\n  BadRequestError,\n  DuplicateEmailError,\n  ForbiddenError,\n  InvalidCodeError,\n  InvalidEmailError,\n  InvalidTenancyError,\n  NotFoundError,\n  PasskeyNotFoundError,\n  UnauthorizedError,\n  VerificationError,\n} from \"./errors.js\"\nexport {\n  isBadRequestError,\n  isDuplicateEmailError,\n  isForbiddenError,\n  isInvalidCodeError,\n  isInvalidEmailError,\n  isInvalidTenancyError,\n  isNotFoundError,\n  isPasskeyNotFoundError,\n  isUnauthorizedError,\n  isVerificationError,\n} from \"./errors.js\"\nexport type {\n  AssignUserOptions,\n  Credential,\n  DeletedPasskey,\n  DeletedPasskeys,\n  DeletePasskeyOptions,\n  DeleteUserPasskeysOptions,\n  FindAllPasskeys,\n  GetPasskeyOptions,\n  ListPasskeyOptions,\n  Passkey,\n  PasskeyCredential,\n  PasskeySummary,\n  Platform,\n  UpdatedCredentials as UpdatedUserDetails,\n  UpdatedPasskeys,\n  UpdatePasskeyOptions,\n  UpdateUsernamesOptions as UpdateUserDetailsOptions,\n} from \"./passkey/passkey.js\"\nexport {\n  isDeletedPasskeys,\n  isPasskey,\n  isPasskeySummary,\n  isUpdatedPasskeys,\n  isUpdatedUserDetails,\n} from \"./passkey/passkey.js\"\nexport type {\n  ExchangeCodeOptions,\n  VerifyIdTokenOptions,\n} from \"./principal/principal.js\"\nexport type { Err, Ok, Result } from \"./safe-result.js\"\nexport type {\n  CredentialDeviceType,\n  Transports,\n} from \"./schemas/passkey.js\"\nexport type { ExtendedPrincipal, Principal } from \"./schemas/principal.js\"\nexport { isExtendedPrincipal, isPrincipal } from \"./schemas/principal.js\"\nexport type {\n  AuthenticatedOptions,\n  PasslockOptions,\n} from \"./shared.js\"\n"]}