@koloseum/utils 0.2.28 → 0.3.0

package/dist/utils.d.ts

@@ -1,394 +0,0 @@
-import type { Database } from "@koloseum/types/database";
-import type { BrowserInfo, CustomError, Microservice, MicroserviceGroup, MicroserviceObject, UserWithCustomMetadata } from "@koloseum/types/general";
-import type { BranchAddressObject, County, IdentityType, PronounsCheckboxes, PronounsItem, Sex, SocialMediaPlatform } from "@koloseum/types/public-auth";
-import type { Page } from "@sveltejs/kit";
-import type { SupabaseClient, FunctionInvokeOptions, PostgrestError } from "@supabase/supabase-js";
-import type { IOptions } from "@suprsend/web-components/dist/types/interface.d.ts";
-import type { MobilePhoneLocale } from "validator";
-export declare const Data: {
-    /**
-     * A generic authenticated user.
-     * @param {string} id - The user ID; defaults to a random UUID
-     * @param {Date} date - The date and time; defaults to the current date and time
-     * @param {string} phone - The phone number; defaults to a generic Kenyan phone number
-     * @param {string} identityId - A default identity ID; defaults to a random UUID
-     * @returns A generic authenticated user.
-     */
-    authenticatedUser: (id?: string, date?: Date, phone?: string, identityId?: string) => UserWithCustomMetadata;
-};
-export declare const Status: {
-    /**
-     * A generic error message.
-     */
-    ERROR: string;
-    /**
-     * A generic loading message.
-     */
-    LOADING: string;
-    /**
-     * A generic password reset request message.
-     */
-    PASSWORD_RESET_REQUESTED: string;
-};
-export declare const Utility: {
-    /**
-     * Calls a Supabase Edge function.
-     * @param {boolean} browser - Whether the function is being called in the browser
-     * @param {SupabaseClient<Database>} supabase - The Supabase client
-     * @param {string} path - The path to the Edge function
-     * @param {FunctionInvokeOptions} [options] - The options to use for the function invocation; defaults to `{ method: "GET" }`
-     * @returns The response from the Edge function
-     */
-    callEdgeFunction: (browser: boolean, supabase: SupabaseClient<Database>, path: string, options?: FunctionInvokeOptions) => Promise<{
-        code: number;
-        data?: any;
-        error?: string;
-        context?: Record<string, any>;
-    }>;
-    /**
-     * Capitalises a given word.
-     * @param {string} word - The word to be capitalised
-     * @returns The capitalised word
-     */
-    capitalise: (word: string) => string;
-    /**
-     * Cleans a URL by removing the protocol and trailing slashes.
-     * @param {string} url - The URL to clean
-     * @returns {string} The cleaned URL
-     */
-    cleanUrl: (url: string) => string;
-    /**
-     * Returns a custom error object.
-     * @param {number} code - The error code; defaults to `500` if not provided or invalid
-     * @param {string} message - The error message
-     * @returns An object with the error `code` and `message`
-     */
-    customError: (code: number | undefined, message: string) => CustomError;
-    /**
-     * A regular expression for E.164 phone numbers.
-     *
-     * - Source: https://www.twilio.com/docs/glossary/what-e164
-     */
-    e164Regex: RegExp;
-    /**
-     * Formats a date in the format DD/MM/YYYY (by default) or YYYY-MM-DD (for client).
-     * @param {string} date - Date to be formatted
-     * @param {boolean} forClient - Specify whether the data is for displaying on the client; defaults to `false`
-     * @returns The formatted date string, or `null` if invalid input or in case of an error
-     */
-    formatDate: (date: string, forClient?: boolean) => string | null;
-    /**
-     * Formats a social media platform for display.
-     * @param {SocialMediaPlatform} platform - The social media platform to be formatted
-     * @returns The formatted social media platform string
-     */
-    formatSocialMediaPlatform: (platform: SocialMediaPlatform) => string;
-    /**
-     * Returns an age in years given a birth date.
-     * @param {Date | string | number | null} dateOfBirth - The date of birth
-     * @returns The age in years, or `NaN` if the input is invalid
-     */
-    getAge: (dateOfBirth: Date | string | number | null) => number;
-    /**
-     * Formats a date as a locale-specific string.
-     * @param {Date | string | number | null} date - Date to be formatted
-     * @param {boolean} withTime - Specify whether the date should include time; defaults to `false`
-     * @param {string} timeZone - The time zone to use for formatting; defaults to `Africa/Nairobi`
-     * @returns The formatted date string, or an empty string if invalid input
-     */
-    getDateString: (date: Date | string | number | null, withTime?: boolean, timeZone?: string) => string;
-    /**
-     * Formats an identity type for display.
-     * @param {IdentityType} identityType - The identity type to be formatted
-     * @returns The formatted identity type string
-     */
-    getIdentityTypeString: (identityType: IdentityType) => string;
-    /**
-     * Returns a list of all counties in Kenya.
-     * @param {"name" | "code"} sortBy - The field to sort the counties by, i.e. `name` or `code`; defaults to `name`
-     * @returns {Promise<County[]>} A list of objects with the county `name`, `code`, and a list of `subCounties`
-     */
-    getKenyaCounties: (sortBy?: "name" | "code") => Promise<County[]>;
-    /**
-     * Formats a date to an ISO string in Kenyan time, i.e. `Africa/Nairobi` (UTC+3).
-     * @param {Date | string | number | null} date - The date to format
-     * @returns {string} The formatted date in ISO string format, or an empty string if invalid input
-     */
-    getKenyanISOString: (date: Date | string | number | null) => string;
-    /**
-     * Returns the URL for a menu item based on the slug.
-     * @param {string} base - The base URL
-     * @param {string} slug - The slug of the menu item
-     * @returns {string} The URL for the menu item
-     */
-    getMenuItemUrl: (base: string, slug: string | undefined) => string;
-    /**
-     * Returns the parent URL for a given base URL.
-     * @param {string} base - The base URL
-     * @returns {string} The parent URL
-     */
-    getParentUrl: (base: string) => string;
-    /**
-     * Returns a pronoun given pronouns and a type.
-     * @param {PronounsItem | null} pronouns - The pronouns to be formatted
-     * @param {"subject" | "object" | "possessive" | "reflexive"} type - The type of pronoun to be returned
-     * @param {Sex} sex - The user's sex; defaults to `undefined`
-     * @returns The formatted pronoun, or `null` if the input is invalid
-     */
-    getPronoun: (pronouns: PronounsItem | null, type: "subject" | "object" | "possessive" | "reflexive", sex?: Sex) => string | null;
-    /**
-     * Returns the redirect URL for a given URI.
-     * @param {string} uri - The URI to get the redirect URL for, i.e. `microserviceGroup:path` (e.g. `players:fgc/tournaments`)
-     * @param {"development" | "production"} env - The environment to use for the redirect URL; defaults to `production`
-     * @returns {string} An object with the redirect `url`, or an `error` if any occurs
-     */
-    getRedirectUrl: (uri: string, env?: "development" | "production") => {
-        url?: string;
-        error?: CustomError;
-    };
-    /**
-     * Generate a SuprSend notification inbox configuration object for a user.
-     * @param {string} userId - The user ID to generate the configuration for.
-     * @param {string} publicApiKey - The public API key to use for SuprSend.
-     * @returns The SuprSend notification inbox configuration object.
-     */
-    getSuprSendInboxConfig: (userId: string, publicApiKey: string) => IOptions;
-    /**
-     * Handles the click event for pronouns checkboxes.
-     * @param {MouseEvent} e - The click event
-     * @param {PronounsCheckboxes} checkboxes - The pronouns checkboxes
-     */
-    handlePronounsCheckboxClick: (e: MouseEvent, checkboxes: PronounsCheckboxes) => void;
-    /**
-     * Checks if a user is authorised to access a microservice.
-     * @param {SupabaseClient<Database>} supabase - The Supabase client.
-     * @param {UserWithCustomMetadata} user - The user to check.
-     * @param {Object} options - The options for the function.
-     * @param {MicroserviceGroup} options.microserviceGroup - The microservice group.
-     * @param {Microservice<MicroserviceGroup> | string} options.microservice - The microservice.
-     * @param {string} options.playersUrl - The URL to the Players microservice.
-     * @param {(role: string) => string} options.requestedPermission - A function that returns the requested permission for a given role.
-     * @returns {Promise<{ isAuthorised?: boolean; redirect?: { code: number; url: string }; error?: CustomError }>} The result of the function.
-     */
-    isUserAuthorised: (supabase: SupabaseClient<Database>, user: UserWithCustomMetadata, options: {
-        microserviceGroup: MicroserviceGroup;
-        microservice: Microservice<MicroserviceGroup> | string;
-        playersUrl?: string;
-        requestedPermission?: (role: string) => string;
-    }) => Promise<{
-        isAuthorised?: boolean;
-        redirect?: {
-            code: number;
-            url: string;
-        };
-        error?: CustomError;
-    }>;
-    /**
-     * A reference of microservices available on the platform, represented as an object with each user group (i.e. `public`, `players`, `lounges`, and `backroom`) having its own array of microservices. Each microservice in a list is an object with the following properties:
-     * - `name`: The name of the microservice.
-     * - `description`: A description of the microservice.
-     * - `slug`: The slug of the microservice.
-     * - `features`: An array of features that the microservice has.
-     * - `roles`: An array of roles attached to the microservice.
-     */
-    microservices: { [key in MicroserviceGroup]: MicroserviceObject<key>[]; };
-    /**
-     * The minimum birth date (from today's date) for a user who is a minor, i.e. `YYYY-MM-DD`
-     */
-    minimumMinorBirthDate: string;
-    /**
-     * Check if a page is active based on the slug and microservice.
-     * @param page - The current page object.
-     * @param slug - The slug of the page to check.
-     * @param microservice - The microservice to check against.
-     * @param base - The base path of the application; defaults to an empty string.
-     * @returns `true` if the page is active, `false` otherwise.
-     */
-    pageIsActive: (page: Page, slug: string | undefined, microservice?: Microservice<MicroserviceGroup>, base?: string) => boolean;
-    /**
-     * Paginates an array.
-     * @template T - The type of array items; defaults to `any`
-     * @param {T[]} array - The array to paginate
-     * @param {number} page - The page number
-     * @param {number} pageSize - The number of items per page; defaults to 10
-     * @returns {Object} The paginated array and total number of pages
-     */
-    paginateArray: <T = any>(array: T[], page: number, pageSize?: number) => {
-        paginatedItems: T[];
-        totalPages: number;
-    };
-    /**
-     * Parses a `CustomError` object within a page/layout server load function and returns an error to be thrown.
-     * @param {CustomError} error - The error object
-     * @returns A new `Error` object if the error is unexpected, or a Svelte error otherwise
-     */
-    parseLoadError: (error: CustomError) => Error | never;
-    /**
-     * Parses a Postgres interval string and returns a string in the specified format.
-     * @param {string} interval - The interval string to parse
-     * @param {"postgres" | "iso" | "iso-short"} type - The format to return the interval in; defaults to `postgres`
-     * @returns A string in the specified format
-     */
-    parsePostgresInterval: (interval: string, type?: "postgres" | "iso" | "iso-short") => string | null;
-    /**
-     * Parses a `PostgrestError` object and returns a custom error object if any has occurred.
-     * @param {PostgrestError | null} postgrestError - The `PostgrestError` object, or `null` if no error occurred
-     * @param {boolean} clientSafe - Whether to clamp 5xx errors down to 422 to prevent Sentry from capturing them as unhandled; defaults to `true`
-     * @returns An object with an `error` if any has occurred
-     */
-    parsePostgrestError: (postgrestError: PostgrestError | null, clientSafe?: boolean) => {
-        error?: CustomError;
-    };
-    /**
-     * A regular expression for user passwords to match during authentication. It covers the following rules:
-     * - at least 8 characters long
-     * - at least one digit
-     * - at least one lowercase letter
-     * - at least one uppercase letter
-     * - at least one symbol
-     */
-    passwordRegex: RegExp;
-    /**
-     * Returns a regular expression for a Koloseum platform ID.
-     * @param {string} type - The type of platform ID to return
-     * @returns A regular expression for the platform ID, or `null` if the type is invalid
-     */
-    platformIdRegex: (type: "lounge" | "loungeBranch" | "player") => RegExp | null;
-    /**
-     * Sanitises any potential HTML injected into user input.
-     * @param {string} input - The input to be sanitised
-     * @returns A sanitised string, or an empty string if the input is invalid
-     */
-    sanitiseHtml: (input: string) => string;
-    /**
-     * Sends a welcome notification to a new user.
-     * @param {SupabaseClient<Database>} supabase - The Supabase client
-     * @param {UserWithCustomMetadata} user - The user to send the notification to
-     * @param {MicroserviceGroup} microserviceGroup - The microservice group the user belongs to
-     * @returns An object with an `error` if any has occurred
-     */
-    sendWelcomeNotification: (supabase: SupabaseClient<Database>, user: UserWithCustomMetadata, microserviceGroup: MicroserviceGroup) => Promise<{
-        error?: CustomError;
-    }>;
-    /**
-     * A regular expression for social media handles, without a leading slash or @ character.
-     *
-     * - Source: https://stackoverflow.com/a/74579651
-     */
-    socialMediaHandleRegex: RegExp;
-    /**
-     * Validates address data submitted in a form and returns the validated data.
-     * @param {FormData} formData - The submitted form data
-     * @returns An object with the validated `address`, or an `error` if any has occurred
-     */
-    validateAddress: (formData: FormData) => Promise<{
-        address?: BranchAddressObject;
-        error?: CustomError;
-    }>;
-    /**
-     * Validates an E.164 phone number.
-     * @param {string} phoneNumber - The phone number to be validated
-     * @param {"any" | MobilePhoneLocale | MobilePhoneLocale[]} [locale="any"] - The locale(s) to validate the phone number against
-     * @returns `true` if the phone number is valid; `false` otherwise
-     */
-    validateE164: (phoneNumber: string, locale?: "any" | MobilePhoneLocale | MobilePhoneLocale[]) => boolean;
-    /**
-     * Validates a social media handle.
-     * @param {string} handle - The social media handle to be validated
-     * @returns `true` if the handle is valid; `false` otherwise
-     */
-    validateSocialMediaHandle: (handle: string) => boolean;
-};
-export declare const Cache: {
-    /**
-     * Delete cached data from Valkey.
-     * @param valkey - The Valkey client instance
-     * @param cachePrefix - The cache prefix
-     * @param key - The cache key
-     */
-    deleteData: (valkey: any, cachePrefix: string, key: string) => Promise<void>;
-    /**
-     * Generate cache key with consistent formatting
-     * @param prefix - The key prefix
-     * @param params - Additional parameters to include in the key
-     * @returns The formatted cache key
-     */
-    generateDataKey: (prefix: string, ...params: (string | number)[]) => string;
-    /**
-     * Get cached data from Valkey.
-     * @param valkey - The Valkey client instance
-     * @param cachePrefix - The cache prefix
-     * @param key - The cache key
-     * @returns The cached data, or `null` if not found
-     */
-    getData: <T>(valkey: any, cachePrefix: string, key: string) => Promise<T | null>;
-    /**
-     * Invalidate cache by pattern
-     * @param valkey - The Valkey client instance
-     * @param cachePrefix - The cache prefix
-     * @param pattern - The pattern to match keys against (e.g., "app-config*")
-     */
-    invalidateDataByPattern: (valkey: any, cachePrefix: string, pattern: string) => Promise<void>;
-    /**
-     * Set data in Valkey cache.
-     * @param valkey - The Valkey client instance
-     * @param cachePrefix - The cache prefix
-     * @param key - The cache key
-     * @param data - The data to cache
-     * @param ttl - The time to live in seconds; defaults to 1 hour
-     */
-    setData: <T>(valkey: any, cachePrefix: string, key: string, data: T, ttl?: number) => Promise<void>;
-};
-export declare const Browser: {
-    /**
-     * Checks if a specific feature is supported by the browser.
-     * @param feature - The feature to check
-     * @param browserName - The name of the browser
-     * @param browserVersion - The version of the browser
-     * @returns `true` if the feature is supported, `false` otherwise
-     */
-    checkFeatureSupport: (feature: string, browserName: string, browserVersion: number) => boolean;
-    /**
-     * Gets detailed browser information for debugging.
-     */
-    getDetailedInfo: () => {
-        browser: string;
-        os: string;
-        platform: string;
-        engine: string;
-        userAgent: string;
-    };
-    /**
-     * Gets comprehensive browser information using Bowser.
-     */
-    getInfo: () => BrowserInfo;
-    /**
-     * Gets specific browser recommendations based on the detected browser.
-     */
-    getRecommendations: () => {
-        title: string;
-        message: string;
-        recommendations: string[];
-        critical: boolean;
-    };
-    /**
-     * Checks if the current browser is compatible with the application.
-     */
-    isBrowserCompatible: () => boolean;
-    /**
-     * Checks if the browser is Internet Explorer.
-     */
-    isInternetExplorer: () => boolean;
-    /**
-     * Checks if the browser is iOS Safari.
-     */
-    isIOSSafari: () => boolean;
-    /**
-     * Checks if the browser is a legacy version that needs updating.
-     */
-    isLegacyBrowser: () => boolean;
-    /**
-     * Checks if the browser is an old version of Safari.
-     */
-    isOldSafari: () => boolean;
-};