@fxhash/errors 0.0.13 → 0.0.14

package/dist/index.d.ts

@@ -1,2 +1,442 @@
-export * from "./errors/_index.js";
-export * from "./utils/_index.js";
+import { IEquatableError, Result } from "@fxhash/utils";
+import { CombinedError, OperationResult } from "@urql/core";
+
+//#region src/errors/common.d.ts
+
+/**
+* Rich Error Messages are messages with extra data for a better usage of errors
+* passed through the stack. Traditionally, error messages are intended for
+* developers only (and some custom implementation for user error feedback is
+* required for clean UIs).
+*/
+interface IRichErrorMessages {
+  dev?: string;
+  user?: string;
+}
+/**
+* Static error messages for "unexpected" errors. This payload is reused accross
+* the stack for when error data is missing.
+*/
+declare const UnexpectedRichErrorMessages: Readonly<Required<IRichErrorMessages>>;
+/**
+* Flatenned Rich Error interface so that Rich Errors can also be passed in a
+* more convenient way. The purpose of this interface is to provide back-
+* compatibility with `Error`, as well as providing an unambiguous `userMessage`
+* property which can be used by front-end applications.
+*/
+interface IRichError {
+  /**
+  * Message intended for developers
+  */
+  message: string;
+  /**
+  * Message intended for users
+  */
+  userMessage: string;
+}
+/**
+* An error which provides messages intended for devs & users. This class should
+* be used accross our stack to provide meaningful error objects which can be
+* used for both developers & users. When typed errors are returned, if they all
+* are instances of `RichError`, then client applications can take some simple
+* shortcuts to provide error feedback to both the developer and the user.
+*
+* @example
+*
+* ```ts
+* export class SomeCustomError extends RichError {
+*   name = "SomeCustomError" as const // `code` will have same value
+*   messages = {
+*     dev: "some message for devs",
+*     user: "some message for users"
+*   }
+* }
+* ```
+*
+* ```ts
+* const res = await something()
+* if (res.isFailure()) {
+*   const err = res.error // if this is typed as `RichError`
+*   displayErrorOnUI(err.userMessage) // safely display user message
+* }
+* ```
+*/
+declare class RichError extends Error implements IRichError, IEquatableError {
+  messages: IRichErrorMessages;
+  messagesOverride: IRichErrorMessages | undefined;
+  constructor(messagesOverride?: IRichErrorMessages);
+  private _message;
+  get message(): string;
+  get userMessage(): string;
+  get code(): string;
+  serialize(): IRichErrorSerialized;
+  static get code(): string;
+  /**
+  * Instanciates a Rich Error, trying to match the serialized error with the
+  * provided Rich Error classes. The `code` property of the serialized payload
+  * is matched against `RichError.name`
+  *
+  * @param serialized A rich error serialized
+  * @param expected A list of Rich Error classes which are expected. If the
+  * serialized error doesn't match any of these, UnexpectedRichError will be
+  * returned.
+  *
+  * @returns An instance of Rich Error which type matches the `code` property,
+  * or {@link UnexpectedRichError} if no match.
+  */
+  static parse<T extends (typeof RichError)[]>(serialized: IRichErrorSerialized, expected: T): RichErrorUnion<T> | UnexpectedRichError;
+  /**
+  * Returns a new instance of {@link UnexpectedRichError}
+  * @param messagesOverride Optional overrides of default unexpected messages
+  */
+  static Unexpected(messagesOverride?: IRichErrorMessages): UnexpectedRichError;
+}
+/**
+* A Rich error serialized,
+*/
+interface IRichErrorSerialized {
+  code: string;
+  messages?: IRichErrorMessages;
+}
+/**
+* A general-purpose error which is thrown when no better error could be
+* inferred from the available context.
+*/
+declare class UnexpectedRichError extends RichError {
+  name: "UnexpectedRichError";
+  messages: typeof UnexpectedRichErrorMessages;
+}
+/**
+* Creates an Union of Rich Error instance types from an array of Rich Error
+* classes.
+*/
+type RichErrorUnion<T extends (typeof RichError)[]> = InstanceType<T[number]>;
+//#endregion
+//#region src/errors/network.d.ts
+declare class NetworkRichError extends RichError {
+  name: "NetworkRichError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+//#endregion
+//#region src/errors/graphql/common.d.ts
+/**
+* Format of the GraphQL error extensions returned by the GraphQL API.
+*/
+interface IFxhashGraphQLErrorExtensions {
+  version: "fxhash@0.1.0";
+  richError: IRichErrorSerialized;
+}
+declare const GraphQLErrors: (typeof UnexpectedRichError | typeof NetworkRichError)[];
+type WithGqlErrors<T extends RichError> = T | RichErrorUnion<typeof GraphQLErrors>;
+//#endregion
+//#region src/errors/graphql/email-otp.d.ts
+declare class EmailOTPLockedError extends RichError {
+  name: "EmailOTPLockedError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare const EmailOTPRequestErrors: (typeof EmailOTPLockedError)[];
+type EmailOTPRequestError = RichErrorUnion<typeof EmailOTPRequestErrors>;
+declare class EmailOTPInvalidError extends RichError {
+  name: "EmailOTPInvalidError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class EmailOTPExpiredError extends RichError {
+  name: "EmailOTPExpiredError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare const EmailOTPVerificationErrors: (typeof EmailOTPLockedError | typeof EmailOTPInvalidError | typeof EmailOTPExpiredError)[];
+type EmailOTPVerificationError = RichErrorUnion<typeof EmailOTPVerificationErrors>;
+//#endregion
+//#region src/errors/graphql/oauth.d.ts
+type OAuthProvider = "google" | "discord";
+declare class OAuthTokenVerificationError extends RichError {
+  name: "OAuthTokenVerificationError";
+  constructor(messages: IRichErrorMessages);
+  constructor(provider: OAuthProvider);
+}
+declare class OAuthMissingInfoError extends RichError {
+  name: "OAuthMissingInfoError";
+  constructor(messages: IRichErrorMessages);
+  constructor(provider: OAuthProvider, missing: string[]);
+}
+declare const OAuthErrors: (typeof OAuthTokenVerificationError | typeof OAuthMissingInfoError)[];
+type OAuthError = RichErrorUnion<typeof OAuthErrors>;
+//#endregion
+//#region src/errors/graphql/wallet-linking.d.ts
+declare class WalletAlreadyOtherAccountMainWalletError extends RichError {
+  static readonly errorType = "WalletAlreadyOtherAccountMainWalletError";
+  name: "WalletAlreadyOtherAccountMainWalletError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class WalletAlreadyLinkedError extends RichError {
+  static readonly errorType = "WalletAlreadyLinkedError";
+  name: "WalletAlreadyLinkedError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class AccountAlreadyLinkedOnNetworkError extends RichError {
+  name: "AccountAlreadyLinkedOnNetworkError";
+  constructor(messages: IRichErrorMessages);
+  constructor(network: string);
+}
+declare const LinkWalletErrors: (typeof WalletAlreadyOtherAccountMainWalletError | typeof WalletAlreadyLinkedError | typeof AccountAlreadyLinkedOnNetworkError)[];
+type LinkWalletError = RichErrorUnion<typeof LinkWalletErrors>;
+declare class WalletNotLinkedToAccountError extends RichError {
+  name: "WalletNotLinkedToAccountError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class MainWalletCannotBeUnlinkedError extends RichError {
+  name: "MainWalletCannotBeUnlinkedError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare const UnlinkWalletErrors: (typeof WalletNotLinkedToAccountError | typeof MainWalletCannotBeUnlinkedError)[];
+type UnlinkWalletError = RichErrorUnion<typeof UnlinkWalletErrors>;
+//#endregion
+//#region src/errors/core.d.ts
+declare class WalletSourceRequestConnectionRejectedError extends RichError {
+  name: "WalletSourceRequestConnectionRejectedError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class WalletSourceRequestConnectionUnknownError extends RichError {
+  name: "WalletSourceRequestConnectionUnknownError";
+  constructor(messages: IRichErrorMessages);
+  constructor(network: string);
+}
+declare class WalletSourceRequestConnectionWalletNotAvailableError extends RichError {
+  name: "WalletSourceRequestConnectionWalletNotAvailableError";
+  constructor(messages: IRichErrorMessages);
+  constructor(network: string);
+}
+declare const WalletSourceRequestConnectionErrors: (typeof WalletSourceRequestConnectionRejectedError | typeof WalletSourceRequestConnectionUnknownError | typeof WalletSourceRequestConnectionWalletNotAvailableError)[];
+type WalletSourceRequestConnectionError = RichErrorUnion<typeof WalletSourceRequestConnectionErrors>;
+declare class NoWalletConnectedForNetworkError extends RichError {
+  name: "NoWalletConnectedForNetworkError";
+  constructor(messages: IRichErrorMessages);
+  constructor(network: string);
+}
+//#endregion
+//#region src/errors/wallet-api.d.ts
+declare class WalletAPIRpcUnknownNetworkError extends RichError {
+  name: "WalletApiRpcHealthError";
+  constructor(messages: IRichErrorMessages);
+  constructor(network: string);
+}
+declare class WalletAPIInvalidRequestError extends RichError {
+  name: "WalletAPIInvalidRequestError";
+  constructor(messages: IRichErrorMessages);
+  constructor(validationErrors?: Array<{
+    path: (string | number)[];
+    message: string;
+  }>);
+}
+declare class WalletAPIFetchError extends RichError {
+  name: "WalletAPIFetchError";
+  constructor(messages: IRichErrorMessages);
+  constructor(url: string, statusCode: number, attempt: number, maxRetries: number);
+}
+declare class WalletAPIFetchTimeoutError extends RichError {
+  name: "WalletAPIFetchTimeoutError";
+  constructor(messages: IRichErrorMessages);
+  constructor(url: string, maxRetries: number, finalError: unknown);
+}
+declare class WalletAPIInvalidURLError extends RichError {
+  name: "WalletAPIInvalidURLError";
+  constructor(messages: IRichErrorMessages);
+  constructor(url: string);
+}
+declare const WalletAPIErrors: (typeof WalletAPIRpcUnknownNetworkError | typeof WalletAPIInvalidRequestError | typeof WalletAPIFetchError | typeof WalletAPIFetchTimeoutError | typeof WalletAPIInvalidURLError)[];
+type WalletAPIError = RichErrorUnion<typeof WalletAPIErrors>;
+//#endregion
+//#region src/errors/web3auth.d.ts
+declare class Web3AuthFrameNotLoading extends RichError {
+  name: "Web3AuthFrameNotLoading";
+  constructor(url: string, error: string | Event);
+  constructor(messages: IRichErrorMessages);
+}
+declare class Web3AuthFrameNotResponding extends RichError {
+  name: "Web3AuthFrameNotResponding";
+  constructor(url: string);
+}
+declare class Web3AuthFrameNotInitialized extends RichError {
+  name: "Web3AuthFrameNotInitialized";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+type Web3AuthFrameInitializationError = Web3AuthFrameNotInitialized | Web3AuthFrameNotLoading | Web3AuthFrameNotResponding;
+declare class Web3AuthFrameAuthenticationError extends RichError {
+  name: "Web3AuthFrameAuthenticationError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class Web3AuthFrameFxhashAuthenticationError extends RichError {
+  name: "Web3AuthFrameFxhashAuthenticationError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class Web3AuthFrameLogoutFailedError extends RichError {
+  name: "Web3AuthFrameLogoutFailedError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class Web3AuthInitializationFailedError extends RichError {
+  name: "Web3AuthInitializationFailedError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare class Web3AuthFrameUnknownError extends RichError {
+  name: "Web3AuthFrameUnknownError";
+  messages: {
+    dev: string;
+    user: string;
+  };
+}
+declare const Web3AuthFrameErrors: {
+  init: (typeof Web3AuthInitializationFailedError)[];
+  getSessionDetails: (typeof Web3AuthFrameAuthenticationError)[];
+  login: (typeof Web3AuthFrameAuthenticationError | typeof Web3AuthFrameFxhashAuthenticationError | typeof Web3AuthFrameUnknownError)[];
+  logout: (typeof Web3AuthFrameLogoutFailedError)[];
+};
+type Web3AuthFrameError = { [K in keyof typeof Web3AuthFrameErrors]: RichErrorUnion<(typeof Web3AuthFrameErrors)[K]> };
+type AllWeb3AuthFrameError = TypeOfRichError<Web3AuthFrameError[keyof Web3AuthFrameError]>;
+declare const AllWeb3AuthFrameErrors: AllWeb3AuthFrameError[];
+//#endregion
+//#region src/utils/rich-error.d.ts
+type TypeOfRichError<T extends RichError> = {
+  new (): T;
+  parse: (typeof RichError)["parse"];
+  Unexpected: (typeof RichError)["Unexpected"];
+  code: (typeof RichError)["code"];
+};
+/**
+* Instanciate a new {@link RichError} using a declarative object. This is
+* useful when Rich Error are instanciated programmatically when type is
+* unknown.
+*/
+declare function richError(params: {
+  name: string;
+  messages?: IRichErrorMessages;
+}): RichError;
+declare function isFxhashErrorExtensions(ext: any): ext is IFxhashGraphQLErrorExtensions;
+/**
+* Test whether a given value is implementing the {@link IRichErrorMessages}
+* interface.
+* @param value Any value
+*/
+declare function isRichErrorMessages(value: any): value is IRichErrorMessages;
+/**
+* Parses the GraphQL error object into a RichError. This function detects
+* fxhash error extensions for outputting user error messages returned by
+* the backend.
+*
+* @param error A GraphQL error response
+*
+* @returns An "untyped" rich error constructed by parsing the GraphQL error
+*/
+declare function richErrorFromGraphQLError(error: CombinedError): RichError | UnexpectedRichError | NetworkRichError;
+/**
+* Parses the GraphQL error response to find the fxhash GraphQL error extension,
+* which is used to instanciate a Rich Error from a list of provided RichErrors.
+* The `name` constant property of such classes will be compared to the `code`
+* property of the fxhash error extension to find a match.
+*
+* @param graphQLError GraphQL error response
+* @param expectedErrors An array of RichError classes which will be parsed to
+* find matches between the RichError `name` constant and the `code` returned
+* by the GraphQL fxhash error extension.
+*
+* @returns A RichError instance matchin the error code, or
+* {@link NetworkRichError} if a network error occured, else
+* {@link UnexpectedRichError}
+*/
+declare function typedRichErrorFromGraphQLError<T extends (typeof RichError)[]>(graphQLError: CombinedError, expectedErrors: T): WithGqlErrors<InstanceType<T[number]>>;
+/**
+* Returns a `Result<Data, TypedRichError>` by parsing a GraphQL response. If
+* the response has an error, {@link typedRichErrorFromGraphQLError} will be
+* called with such error to return a proper error instance based on the error
+* code in the fxhash graphql error extension (or a a generic error if none).
+*
+* @param operationResult A GraphQL response from fxhash hasura endpoint
+* @param getData A function which takes the response and returns the data (if
+* no data is found it should return `null` | `undefined`, in which case it will
+* fail with UnexpectedError)
+* @param potentialErrors An array of Rich Error classes which could be found in
+* the error response.
+*
+* @example
+*
+* ```ts
+* const emailRequestOTP = async (email) => {
+*   return richResultFromGraphQLResponse(
+*     await gqlWrapper.client().mutation(Mu_Web3AuthEmailRequestOTP, {
+*       email,
+*     }),
+*     res => res.data?.web3auth_email_request_otp,
+*     EmailOTPRequestErrors
+*   )
+* },
+* ```
+*/
+declare function richResultFromGraphQLResponse<T extends (typeof RichError)[], Data = any, ExtractedData = any>(operationResult: OperationResult<Data>, getData: (result: OperationResult<Data>) => ExtractedData | undefined | null, potentialErrors: T): Result<ExtractedData, WithGqlErrors<InstanceType<T[number]>>>;
+/**
+* Test if an error is of a certain error kind, among a list of [errors] or
+* [list of errors]. This allows testing multiple array of errors, which are
+* defined quite a lot throughout the errors stack.
+*
+* @param error The error which needs to be tested
+* @param kinds List of [errors]/[array of errors]
+*
+* @returns boolean if error is of given kind
+*
+* @example
+*
+* ```ts
+* isErrorOfKind(
+*   someErr,
+*   UnexpectedRichError,
+*   [SuperError, BigError],
+*   SimpleError
+* )
+* ```
+*/
+declare function isErrorOfKind<Errors extends (IEquatableError | IEquatableError[])[]>(error: IEquatableError, ...kinds: Errors): error is Instance<Flatten<Errors>>;
+type Flatten<T> = T extends (infer U)[] ? Flatten<U> : T;
+type Instance<T> = T extends (abstract new (...args: any) => any) ? InstanceType<T> : T;
+//#endregion
+export { AccountAlreadyLinkedOnNetworkError, AllWeb3AuthFrameError, AllWeb3AuthFrameErrors, EmailOTPExpiredError, EmailOTPInvalidError, EmailOTPLockedError, EmailOTPRequestError, EmailOTPRequestErrors, EmailOTPVerificationError, EmailOTPVerificationErrors, GraphQLErrors, IFxhashGraphQLErrorExtensions, IRichError, IRichErrorMessages, IRichErrorSerialized, LinkWalletError, LinkWalletErrors, MainWalletCannotBeUnlinkedError, NetworkRichError, NoWalletConnectedForNetworkError, OAuthError, OAuthErrors, OAuthMissingInfoError, OAuthTokenVerificationError, RichError, RichErrorUnion, TypeOfRichError, UnexpectedRichError, UnexpectedRichErrorMessages, UnlinkWalletError, UnlinkWalletErrors, WalletAPIError, WalletAPIErrors, WalletAPIFetchError, WalletAPIFetchTimeoutError, WalletAPIInvalidRequestError, WalletAPIInvalidURLError, WalletAPIRpcUnknownNetworkError, WalletAlreadyLinkedError, WalletAlreadyOtherAccountMainWalletError, WalletNotLinkedToAccountError, WalletSourceRequestConnectionError, WalletSourceRequestConnectionErrors, WalletSourceRequestConnectionRejectedError, WalletSourceRequestConnectionUnknownError, WalletSourceRequestConnectionWalletNotAvailableError, Web3AuthFrameAuthenticationError, Web3AuthFrameError, Web3AuthFrameErrors, Web3AuthFrameFxhashAuthenticationError, Web3AuthFrameInitializationError, Web3AuthFrameLogoutFailedError, Web3AuthFrameNotInitialized, Web3AuthFrameNotLoading, Web3AuthFrameNotResponding, Web3AuthFrameUnknownError, Web3AuthInitializationFailedError, WithGqlErrors, isErrorOfKind, isFxhashErrorExtensions, isRichErrorMessages, richError, richErrorFromGraphQLError, richResultFromGraphQLResponse, typedRichErrorFromGraphQLError };
+//# sourceMappingURL=index.d.ts.map