@kumix/utils 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -254,8 +254,12 @@ declare const REGION_CODES: [string, ...string[]];
254
254
  * Provides a comprehensive set of all country-specific domain extensions
255
255
  */
256
256
  /**
257
- * A Set containing all country code top-level domains (ccTLDs)
258
- * Used for domain validation, parsing, and identification
257
+ * A Set containing ISO 3166-1 alpha-2 country code top-level domains (ccTLDs),
258
+ * plus a small set of commonly-recognized regional TLDs (`eu`, `eus`, `gal`,
259
+ * `cat`, `asia`). De-duplicated and pruned of retired/withdrawn codes:
260
+ * - `an` (Netherlands Antilles, retired 2010)
261
+ * - `tp` (Timor-Leste, retired 2015 — use `tl`)
262
+ * `gb` is included alongside `uk` per IANA reservation.
259
263
  *
260
264
  * @example
261
265
  * ```ts
@@ -268,13 +272,6 @@ declare const REGION_CODES: [string, ...string[]];
268
272
  * const domain = 'example.co.uk';
269
273
  * const tld = domain.split('.').pop();
270
274
  * const isCountryDomain = tld ? ccTLDs.has(tld) : false; // true
271
- *
272
- * // Filter domains by ccTLD
273
- * const domains = ['example.com', 'example.co.uk', 'example.org'];
274
- * const countryDomains = domains.filter(domain => {
275
- * const tld = domain.split('.').pop();
276
- * return tld ? ccTLDs.has(tld) : false;
277
- * }); // ['example.co.uk']
278
275
  * ```
279
276
  */
280
277
  declare const ccTLDs: Set<string>;
@@ -410,7 +407,7 @@ declare const DEFAULT_THEME_MODE: ThemeMode;
410
407
  *
411
408
  * // Environment-specific configuration
412
409
  * const apiUrl = NODE_ENV === 'production'
413
- * ? 'https://api.kumix.com'
410
+ * ? 'https://api.kumix.io'
414
411
  * : 'http://localhost:3001';
415
412
  * ```
416
413
  */
@@ -441,10 +438,13 @@ declare const NODE_ENV: string | undefined;
441
438
  */
442
439
  declare const isDevelopment: boolean;
443
440
  /**
444
- * Checks if the application is running in staging mode
441
+ * Checks if the application is running in staging mode.
445
442
  * Used for testing production-like environments before deployment.
446
443
  *
447
- * @returns True if NODE_ENV is 'test', false otherwise
444
+ * Maps to `NODE_ENV === "staging"`. Note: the test runner (Vitest/Jest) sets
445
+ * `NODE_ENV=test`; for that case see `isTest`.
446
+ *
447
+ * @returns True if NODE_ENV is 'staging', false otherwise
448
448
  *
449
449
  * @example
450
450
  * ```ts
@@ -452,17 +452,16 @@ declare const isDevelopment: boolean;
452
452
  *
453
453
  * if (isStaging) {
454
454
  * // Use staging API endpoints
455
- * apiUrl = 'https://staging-api.kumix.com';
455
+ * apiUrl = 'https://staging-api.kumix.io';
456
456
  * }
457
- *
458
- * // Staging-specific analytics
459
- * const analyticsConfig = {
460
- * enabled: isStaging || isProduction,
461
- * debug: isStaging
462
- * };
463
457
  * ```
464
458
  */
465
459
  declare const isStaging: boolean;
460
+ /**
461
+ * Checks if the application is running under the test runner (Vitest/Jest).
462
+ * Both runners set `NODE_ENV=test`.
463
+ */
464
+ declare const isTest: boolean;
466
465
  /**
467
466
  * Checks if the application is running in production mode
468
467
  * Used for enabling production optimizations and features.
@@ -538,6 +537,15 @@ declare const LOG_LEVEL: string | undefined;
538
537
  * <Recaptcha siteKey={NEXT_PUBLIC_RECAPTCHA_SITE_KEY} />
539
538
  */
540
539
  declare const NEXT_PUBLIC_RECAPTCHA_SITE_KEY: string | undefined;
540
+ /**
541
+ * Recaptcha secret key for server-side token verification.
542
+ * Used by verifyRecaptchaToken to call Google's siteverify endpoint.
543
+ * Must NOT be exposed to the client (no NEXT_PUBLIC prefix).
544
+ *
545
+ * @example
546
+ * const isValid = await verifyRecaptchaToken(token);
547
+ */
548
+ declare const RECAPTCHA_SECRET_KEY: string | undefined;
541
549
  /**
542
550
  * Slack webhook URLs for different log types.
543
551
  * Used for sending log messages to specific Slack channels based on log category.
@@ -565,7 +573,7 @@ declare const SLACK_WEBHOOKS: {
565
573
  * @example
566
574
  * <img src={OG_AVATAR_URL + userId} />
567
575
  */
568
- declare const OG_AVATAR_URL = "https://api.kumix.com/og/avatar/";
576
+ declare const OG_AVATAR_URL = "https://api.kumix.io/og/avatar/";
569
577
  /**
570
578
  * Default pagination limit for API responses and UI lists.
571
579
  *
@@ -777,7 +785,7 @@ declare const LOCALHOST_GEO_DATA: {
777
785
  * }
778
786
  * ```
779
787
  */
780
- declare const LOCALHOST_IP = "63.141.57.109";
788
+ declare const LOCALHOST_IP = "198.51.100.1";
781
789
  //#endregion
782
790
  //#region src/constants/reserved-slugs.d.ts
783
791
  /**
@@ -1144,7 +1152,7 @@ declare function mapLocale(locale?: string): string | undefined;
1144
1152
  * Supports Open Graph, Twitter cards, icons, canonical URLs, robots, manifest, and multi-language alternates.
1145
1153
  *
1146
1154
  * @param params - Metadata construction options
1147
- * @param params.baseUrl - The base URL/domain for metadataBase (optional, e.g., 'https://kumix.com')
1155
+ * @param params.baseUrl - The base URL/domain for metadataBase (optional, e.g., 'https://kumix.io')
1148
1156
  * @param params.title - The base title for the page (used in Open Graph and Twitter)
1149
1157
  * @param params.fullTitle - The full title for the page (overrides title in the <title> tag)
1150
1158
  * @param params.description - Description of the page (used in meta, Open Graph, Twitter)
@@ -1188,8 +1196,8 @@ declare function mapLocale(locale?: string): string | undefined;
1188
1196
  * creator: '@lukmanaviccena',
1189
1197
  * },
1190
1198
  * alternateLanguages: {
1191
- * en: 'https://kumix.com/en',
1192
- * id: 'https://kumix.com/id',
1199
+ * en: 'https://kumix.io/en',
1200
+ * id: 'https://kumix.io/id',
1193
1201
  * },
1194
1202
  * icons: [
1195
1203
  * { rel: 'icon', url: '/favicon.ico' },
@@ -1916,10 +1924,8 @@ declare const baseId: ({
1916
1924
  */
1917
1925
  declare function cuid(): string;
1918
1926
  /**
1919
- * Generates a custom ID with an optional prefix and configurable length
1920
- * This function uses `@paralleldrive/cuid2` to create unique identifiers
1921
- * with an optional prefix. Useful for creating IDs with specific patterns
1922
- * like `user_abc123` or `order_987xyz`.
1927
+ * Generates a custom ID with an optional prefix and configurable length.
1928
+ * Uses `@paralleldrive/cuid2`'s cryptographically-secure RNG.
1923
1929
  *
1924
1930
  * @param prefix - Optional prefix to prepend to the ID
1925
1931
  * @param length - The length of the generated ID (default is 12)
@@ -1927,34 +1933,22 @@ declare function cuid(): string;
1927
1933
  *
1928
1934
  * @example
1929
1935
  * ```ts
1930
- * import { customeId } from '@/utils/functions';
1936
+ * import { customId } from '@/utils/functions';
1931
1937
  *
1932
1938
  * // Generate ID with prefix
1933
- * const userId = customeId('user_');
1939
+ * const userId = customId('user_');
1934
1940
  * // Returns: 'user_l5r8xn2gzqnb'
1935
1941
  *
1936
1942
  * // Generate ID with custom length
1937
- * const orderId = customeId('order_', 16);
1938
- * // Returns: 'order_l5r8xn2gzqnbf4r2'
1939
- *
1940
- * // Generate ID without prefix
1941
- * const randomId = customeId();
1942
- * // Returns: 'l5r8xn2gzqnb'
1943
- *
1944
- * // Use for different entity types
1945
- * const productId = customeId('prod_', 8);
1946
- * const invoiceId = customeId('inv_', 10);
1947
- * const sessionId = customeId('sess_', 20);
1948
- *
1949
- * // Use in API responses
1950
- * const apiResponse = {
1951
- * id: customeId('api_'),
1952
- * timestamp: Date.now(),
1953
- * data: {...}
1954
- * };
1943
+ * const orderId = customId('order_', 16);
1955
1944
  * ```
1956
1945
  */
1957
- declare function customeId(prefix?: string, length?: number): string;
1946
+ declare function customId(prefix?: string, length?: number): string;
1947
+ /**
1948
+ * @deprecated Use {@link customId} instead. This alias has a typo and is kept
1949
+ * only for backward compatibility; it will be removed in a future major.
1950
+ */
1951
+ declare const customeId: typeof customId;
1958
1952
  //#endregion
1959
1953
  //#region src/functions/crypto/hash-string.d.ts
1960
1954
  /**
@@ -2643,6 +2637,7 @@ declare const timeAgo: (timestamp: Date | null, {
2643
2637
  declare const getTimeZones: () => {
2644
2638
  label: string;
2645
2639
  value: string;
2640
+ numericOffset: number;
2646
2641
  }[];
2647
2642
  //#endregion
2648
2643
  //#region src/functions/file/format-file-size.d.ts
@@ -3129,7 +3124,7 @@ interface ParsedRequest {
3129
3124
  * export function middleware(req: NextRequest) {
3130
3125
  * const { domain, path, fullPath, key } = parse(req);
3131
3126
  *
3132
- * console.log(domain); // e.g., "api.kumix.com"
3127
+ * console.log(domain); // e.g., "api.kumix.io"
3133
3128
  * console.log(path); // e.g., "/v1/users"
3134
3129
  * console.log(fullPath); // e.g., "/v1/users?page=1"
3135
3130
  * console.log(key); // e.g., "v1"
@@ -3187,45 +3182,6 @@ declare function verifyRecaptchaToken(token: string): Promise<boolean>;
3187
3182
  * Provides consistent logging interface using Consola with custom formatting
3188
3183
  * Used throughout the application to replace console.log statements
3189
3184
  */
3190
- /**
3191
- * Application logger instance with consistent formatting
3192
- *
3193
- * Provides structured logging with different levels (info, warn, error, debug)
3194
- * and consistent formatting across the application. Replaces direct console usage.
3195
- *
3196
- * @example
3197
- * ```typescript
3198
- * import { logger } from '@kumix/utils';
3199
- *
3200
- * // Basic logging
3201
- * logger.info('User logged in successfully');
3202
- * logger.warn('API rate limit approaching');
3203
- * logger.error('Database connection failed');
3204
- * logger.debug('Processing user data', { userId: 123 });
3205
- *
3206
- * // With context data
3207
- * logger.info('User action completed', {
3208
- * userId: user.id,
3209
- * action: 'profile_update',
3210
- * timestamp: new Date().toISOString()
3211
- * });
3212
- *
3213
- * // Error logging with stack trace
3214
- * try {
3215
- * await riskyOperation();
3216
- * } catch (error) {
3217
- * logger.error('Operation failed', { error, context: 'user-service' });
3218
- * }
3219
- *
3220
- * // Performance logging
3221
- * const startTime = Date.now();
3222
- * await someOperation();
3223
- * logger.debug('Operation completed', {
3224
- * duration: Date.now() - startTime,
3225
- * operation: 'data-processing'
3226
- * });
3227
- * ```
3228
- */
3229
3185
  declare const logger: import("consola").ConsolaInstance;
3230
3186
  //#endregion
3231
3187
  //#region src/functions/logging/slack-log.d.ts
@@ -3272,11 +3228,18 @@ declare const logger: import("consola").ConsolaInstance;
3272
3228
  declare const SlackLog: ({
3273
3229
  message,
3274
3230
  type,
3275
- mention
3231
+ mention,
3232
+ mentionUserId
3276
3233
  }: {
3277
3234
  message: string;
3278
3235
  type: "alerts" | "cron" | "links" | "subscribers" | "errors";
3279
- mention?: boolean;
3236
+ /**
3237
+ * Mention a Slack user when `true`. Requires `mentionUserId` to be provided
3238
+ * (defaults to env `SLACK_MENTION_USER_ID`) — previously a hardcoded user ID
3239
+ * was baked into this published package.
3240
+ */
3241
+ mention?: boolean; /** Slack user ID (e.g. `U0404G6J3NJ`) to mention. Falls back to env. */
3242
+ mentionUserId?: string;
3280
3243
  }) => Promise<Response | undefined>;
3281
3244
  //#endregion
3282
3245
  //#region src/functions/performance/debounce.d.ts
@@ -3327,7 +3290,7 @@ declare const SlackLog: ({
3327
3290
  * }, 2000);
3328
3291
  * ```
3329
3292
  */
3330
- declare function debounce<T extends (...args: unknown[]) => unknown>(func: T, wait: number): (...args: Parameters<T>) => void;
3293
+ declare function debounce<T extends (...args: never[]) => unknown>(func: T, wait: number): (...args: Parameters<T>) => void;
3331
3294
  //#endregion
3332
3295
  //#region src/functions/performance/throttle.d.ts
3333
3296
  /**
@@ -3375,7 +3338,7 @@ declare function debounce<T extends (...args: unknown[]) => unknown>(func: T, wa
3375
3338
  * }, 1000);
3376
3339
  * ```
3377
3340
  */
3378
- declare const throttle: (func: (...args: unknown[]) => void, limit: number) => ((...args: unknown[]) => void);
3341
+ declare const throttle: <T extends (...args: never[]) => unknown>(func: T, limit: number) => ((...args: Parameters<T>) => void);
3379
3342
  //#endregion
3380
3343
  //#region src/functions/string/assets.d.ts
3381
3344
  /**
@@ -3388,8 +3351,10 @@ declare const throttle: (func: (...args: unknown[]) => void, limit: number) => (
3388
3351
  * If an absolute URL is provided as `path`, it will be returned as-is (host is ignored).
3389
3352
  *
3390
3353
  * @param path - Asset path or absolute URL to resolve
3391
- * @param host - Optional asset host (base URL). Defaults to `https://assets.kumix.com`
3392
- * @returns A fully-qualified asset URL string, or `null` if inputs are invalid
3354
+ * @param host - Optional asset host (base URL). Defaults to `https://assets.kumix.io`
3355
+ * @returns A fully-qualified asset URL string. On invalid input (empty path or
3356
+ * malformed base), falls back to the configured asset host rather than
3357
+ * throwing — call sites that need strict failure should validate inputs first.
3393
3358
  *
3394
3359
  * @example
3395
3360
  * ```ts
@@ -3397,7 +3362,7 @@ declare const throttle: (func: (...args: unknown[]) => void, limit: number) => (
3397
3362
  *
3398
3363
  * // Default host
3399
3364
  * const u1 = assetsUrl('logo/logo.png');
3400
- * // 'https://assets.kumix.com/logo/logo.png'
3365
+ * // 'https://assets.kumix.io/logo/logo.png'
3401
3366
  *
3402
3367
  * // Custom host (full URL)
3403
3368
  * const u2 = assetsUrl('/images/icon.svg', 'https://cdn.example.com');
@@ -3411,12 +3376,12 @@ declare const throttle: (func: (...args: unknown[]) => void, limit: number) => (
3411
3376
  * const u4 = assetsUrl('https://other.com/a.png', 'https://cdn.example.com');
3412
3377
  * // 'https://other.com/a.png'
3413
3378
  *
3414
- * // Edge cases
3379
+ * // Edge cases — falsy path or malformed base returns the configured asset host
3415
3380
  * const u5 = assetsUrl('');
3416
- * // null
3381
+ * // 'https://assets.kumix.io' (the configured host)
3417
3382
  *
3418
3383
  * const u6 = assetsUrl('logo.png', '://bad-host');
3419
- * // null (invalid base)
3384
+ * // '://bad-host' (the supplied host — invalid, returned as-is)
3420
3385
  * ```
3421
3386
  */
3422
3387
  declare function assetsUrl(path: string, host?: string): string;
@@ -3435,10 +3400,10 @@ declare function assetsUrl(path: string, host?: string): string;
3435
3400
  * import { getFlagUrl } from "@kumix/ui/utils/flag-url";
3436
3401
  *
3437
3402
  * const urlUs = getFlagUrl("US");
3438
- * // "https://assets.kumix.com/media/flags/us.svg"
3403
+ * // "https://assets.kumix.io/media/flags/us.svg"
3439
3404
  *
3440
3405
  * const urlId = getFlagUrl("id");
3441
- * // "https://assets.kumix.com/media/flags/id.svg"
3406
+ * // "https://assets.kumix.io/media/flags/id.svg"
3442
3407
  *
3443
3408
  * // Can be used directly in an <img /> or <Image /> component
3444
3409
  * // <img src={getFlagUrl("GB")} alt="United Kingdom flag" />
@@ -3463,32 +3428,22 @@ declare function getUserName(user: any | null | undefined): any;
3463
3428
  //#region src/functions/string/camel-case.d.ts
3464
3429
  /**
3465
3430
  * Utility function for string case conversion
3466
- * Provides conversion from snake_case to camelCase format
3431
+ * Provides conversion from various cases (snake, kebab, space, Pascal) to camelCase
3467
3432
  */
3468
3433
  /**
3469
- * Converts a string from snake_case to camelCase format
3470
- * If the string is already in camelCase, it will be returned unchanged
3434
+ * Converts a string to camelCase.
3435
+ * Handles snake_case, kebab-case, CONST_CASE, PascalCase, and space-separated words.
3471
3436
  *
3472
3437
  * @param str - The string to convert to camelCase
3473
3438
  * @returns The camelCase version of the input string
3474
3439
  *
3475
3440
  * @example
3476
3441
  * ```ts
3477
- * // Convert snake_case to camelCase
3478
- * toCamelCase('user_name')
3479
- * // Returns "userName"
3480
- *
3481
- * // Already camelCase strings remain unchanged
3482
- * toCamelCase('userName')
3483
- * // Returns "userName"
3484
- *
3485
- * // Multi-word snake_case strings
3486
- * toCamelCase('first_name_last_name')
3487
- * // Returns "firstNameLastName"
3488
- *
3489
- * // Handles single-word strings
3490
- * toCamelCase('user')
3491
- * // Returns "user"
3442
+ * toCamelCase('user_name') // "userName"
3443
+ * toCamelCase('user-name') // "userName"
3444
+ * toCamelCase('first name') // "firstName"
3445
+ * toCamelCase('PascalCase') // "pascalCase"
3446
+ * toCamelCase('first_name_last') // "firstNameLastName"
3492
3447
  * ```
3493
3448
  */
3494
3449
  declare const toCamelCase: (str: string) => string;
@@ -3620,23 +3575,23 @@ declare const combineWords: (words: string[]) => string;
3620
3575
  * ```ts
3621
3576
  * // Basic usage with defaults (USD)
3622
3577
  * currencyFormatter(1000)
3623
- * // Returns "$1,000"
3578
+ * // Returns "$1,000.00"
3624
3579
  *
3625
3580
  * // With custom currency
3626
3581
  * currencyFormatter(1000, {}, 'en-US', 'EUR')
3627
- * // Returns "€1,000"
3582
+ * // Returns "€1,000.00"
3628
3583
  *
3629
3584
  * // With custom locale
3630
3585
  * currencyFormatter(1000, {}, 'de-DE', 'EUR')
3631
- * // Returns "1.000 €"
3586
+ * // Returns "1.000,00 €"
3632
3587
  *
3633
- * // With custom options
3634
- * currencyFormatter(1234.56, { maximumFractionDigits: 2 })
3635
- * // Returns "$1,234.56"
3588
+ * // With custom options (no decimals)
3589
+ * currencyFormatter(1234.56, { maximumFractionDigits: 0 })
3590
+ * // Returns "$1,235"
3636
3591
  *
3637
3592
  * // Combining custom options, locale and currency
3638
- * currencyFormatter(1234.56, { maximumFractionDigits: 2 }, 'ja-JP', 'JPY')
3639
- * // Returns "¥1,235" (rounded to 0 decimal placeas by default for JPY)
3593
+ * currencyFormatter(1234.56, { maximumFractionDigits: 0 }, 'ja-JP', 'JPY')
3594
+ * // Returns "¥1,235"
3640
3595
  * ```
3641
3596
  */
3642
3597
  declare const currencyFormatter: (value: number, options?: Intl.NumberFormatOptions, locale?: string, currencyCode?: string) => string;
@@ -4008,9 +3963,11 @@ declare const truncate: (str: string | null | undefined, length: number) => stri
4008
3963
  * generateDomainFromName('My Cool Project', 'com')
4009
3964
  * // Returns "mycoolproject.com"
4010
3965
  *
4011
- * // With country code TLD if possible
3966
+ * // ccTLD fallback only applies when the trailing 2 chars form a known ccTLD;
3967
+ * // for "Canada" the trailing 2 chars are "da" (not a ccTLD), so the default
3968
+ * // extension is used.
4012
3969
  * generateDomainFromName('Canada')
4013
- * // Returns "canad.ca"
3970
+ * // Returns "canada.link"
4014
3971
  *
4015
3972
  * // With vowels removed if needed
4016
3973
  * generateDomainFromName('Digital', 'io')
@@ -4568,10 +4525,17 @@ declare function getSlug(title: string): string;
4568
4525
  * Provides functions for validating URL strings and checking URL validity
4569
4526
  */
4570
4527
  /**
4571
- * Checks if a string is a valid URL
4572
- * Uses the URL constructor for validation
4528
+ * Checks if a string is a valid URL.
4529
+ *
4530
+ * By default rejects non-fetchable schemes (`javascript:`, `data:`, `file:`,
4531
+ * `vbscript:`) to avoid XSS via redirect/href validation. Set `allowAnyScheme`
4532
+ * to accept any scheme the URL parser accepts.
4533
+ *
4534
+ * Uses the URL constructor for validation.
4573
4535
  *
4574
4536
  * @param url - The string to check
4537
+ * @param options - Validation options
4538
+ * @param options.allowAnyScheme - When true, accept any scheme (defaults to false)
4575
4539
  * @returns True if the string is a valid URL, false otherwise
4576
4540
  *
4577
4541
  * @example
@@ -4583,11 +4547,9 @@ declare function getSlug(title: string): string;
4583
4547
  * isValidUrl('http://localhost:3000'); // true
4584
4548
  * isValidUrl('ftp://files.example.com'); // true
4585
4549
  *
4586
- * // Invalid URLs
4550
+ * // Invalid / unsafe URLs (rejected by default)
4551
+ * isValidUrl('javascript:alert(1)'); // false
4587
4552
  * isValidUrl('example.com'); // false (missing protocol)
4588
- * isValidUrl('not a url'); // false
4589
- * isValidUrl(''); // false
4590
- * isValidUrl('https://'); // false (incomplete)
4591
4553
  *
4592
4554
  * // Use in form validation
4593
4555
  * function validateUrlInput(input: string) {
@@ -4596,12 +4558,11 @@ declare function getSlug(title: string): string;
4596
4558
  * }
4597
4559
  * return null;
4598
4560
  * }
4599
- *
4600
- * // Use in data processing
4601
- * const validUrls = urls.filter(isValidUrl);
4602
4561
  * ```
4603
4562
  */
4604
- declare const isValidUrl: (url: string) => boolean;
4563
+ declare const isValidUrl: (url: string, options?: {
4564
+ allowAnyScheme?: boolean;
4565
+ }) => boolean;
4605
4566
  //#endregion
4606
4567
  //#region src/functions/url/utm-params.d.ts
4607
4568
  /**
@@ -5036,50 +4997,28 @@ declare function getEmailDomain(email: string): string | null;
5036
4997
  * Checks if a URL can be embedded in an iframe based on security headers
5037
4998
  */
5038
4999
  /**
5039
- * Determines if a URL can be displayed in an iframe by checking security headers
5040
- * Examines Content-Security-Policy and X-Frame-Options headers to verify embedding permissions
5000
+ * Determines if a URL can be displayed in an iframe by checking security headers.
5001
+ * Examines Content-Security-Policy `frame-ancestors` and `X-Frame-Options` headers.
5002
+ *
5003
+ * A URL is considered embeddable only when:
5004
+ * - `frame-ancestors` is absent OR explicitly allows `*` / `self` (same origin) /
5005
+ * a wildcard/origin that matches `requestDomain`, AND
5006
+ * - `X-Frame-Options` is not `DENY` or `SAMEORIGIN` (when origin differs).
5041
5007
  *
5042
5008
  * @param options - The options for the check
5043
5009
  * @param options.url - The URL to check for iframe embedding capability
5044
- * @param options.requestDomain - The domain that will be embedding the iframe
5045
- * @returns A Promise that resolves to true if the URL can be embedded, false otherwise
5010
+ * @param options.requestDomain - The origin that will be embedding the iframe
5011
+ * (e.g. `https://myapp.com`). Compared against CSP source expressions.
5012
+ * @returns A Promise that resolves to true if the URL can be embedded, false otherwise.
5046
5013
  *
5047
5014
  * @example
5048
5015
  * ```ts
5049
5016
  * import { isIframeable } from '@/utils/functions';
5050
5017
  *
5051
- * // Check if a URL can be embedded in an iframe
5052
5018
  * const canEmbed = await isIframeable({
5053
5019
  * url: 'https://example.com',
5054
5020
  * requestDomain: 'https://myapp.com'
5055
5021
  * });
5056
- *
5057
- * if (canEmbed) {
5058
- * console.log('URL can be embedded in an iframe');
5059
- * } else {
5060
- * console.log('URL cannot be embedded due to security restrictions');
5061
- * }
5062
- *
5063
- * // In a React component
5064
- * function EmbedPreview({ url }) {
5065
- * const [canEmbed, setCanEmbed] = useState<boolean | null>(null);
5066
- *
5067
- * useEffect(() => {
5068
- * async function checkEmbedding() {
5069
- * const result = await isIframeable({
5070
- * url,
5071
- * requestDomain: window.location.origin
5072
- * });
5073
- * setCanEmbed(result);
5074
- * }
5075
- * checkEmbedding();
5076
- * }, [url]);
5077
- *
5078
- * if (canEmbed === null) return <div>Checking...</div>;
5079
- * if (canEmbed === false) return <div>Cannot embed this URL</div>;
5080
- *
5081
- * return <iframe src={url} />;
5082
- * }
5083
5022
  * ```
5084
5023
  */
5085
5024
  declare const isIframeable: ({
@@ -5158,5 +5097,5 @@ declare const isUnsupportedKey: (key: string) => boolean;
5158
5097
  */
5159
5098
  declare const isReservedKeyGlobal: (key: string) => boolean;
5160
5099
  //#endregion
5161
- export { API_PORT, CONNECT_SUPPORTED_COUNTRIES, CONTINENTS, CONTINENT_CODES, COUNTRIES, COUNTRY_CODES, COUNTRY_PHONE_CODES, DEBUG, DEFAULT_THEME_MODE, EU_COUNTRY_CODES, FRAMER_MOTION_LIST_ITEM_VARIANTS, INFINITY_NUMBER, LAST_VISITED_WORKSPACE, LOCALHOST_GEO_DATA, LOCALHOST_IP, LOG_LEVEL, META_THEME_COLORS, NEXT_PUBLIC_RECAPTCHA_SITE_KEY, NODE_ENV, OG_AVATAR_URL, PAGINATION_LIMIT, PORT, ParsedRequest, REDIRECT_QUERY_PARAM, REGIONS, REGION_CODES, RESERVED_SLUGS, SECOND_LEVEL_DOMAINS, SLACK_WEBHOOKS, SPECIAL_APEX_DOMAINS, STAGGER_CHILD_VARIANTS, SlackLog, type StorageType, TAB_ITEM_ANIMATION_SETTINGS, THEME_MODES, THE_BEGINNING_OF_TIME, TWO_WEEKS_IN_SECONDS, ThemeMode, UTMTags, assetsUrl, baseId, baseIdCustom, capitalize, ccTLDs, chunk, clearAllCookies, clearStorage, cn, combineWords, constructMetadata, constructURLFromUTMParams, createHref, createId, cuid, currencyFormatter, customeId, debounce, deepEqual, fetchWithRetry, fetchWithTimeout, fetcher, fetcherSWR, fileToBase64, formatDate, formatDateTime, formatDateTimeSmart, formatFileSize, formatPeriod, formatTime, generateDomainFromName, getAdjustedBillingCycleStart, getAllCookies, getApexDomain, getBillingStartDate, getClientIP, getClientIPFromHeaders, getCookie, getCurrentYear, getDateTimeLocal, getDaysDifference, getDomainWithoutWWW, getEmailDomain, getEnv, getFirstAndLastDay, getFlagUrl, getHeight, getIPAddress, getInitials, getLastDayOfMonth, getParamsFromURL, getPrettyUrl, getRequestOrigin, getSearchParams, getSearchParamsWithArray, getSizeAvatar, getSlug, getStorageItem, getSubdomain, getTimeZones, getUrlFromString, getUrlFromStringIfValid, getUrlObjFromString, getUrlWithoutUTMParams, getUserAgent, getUserAgentFromHeaders, getUserName, googleTrackCodeCopy, googleTrackDirectionChange, googleTrackEvent, googleTrackItemCreate, googleTrackItemDelete, googleTrackItemRestore, googleTrackItemUpdate, googleTrackItemView, googleTrackThemeChange, googleTrackViewChange, hasCookie, hasStorageItem, hashStringSHA256, init as initCuid, isBusinessEmail, isDevelopment, isDisposableEmail, isIframeable, isProduction, isReservedKeyGlobal, isStaging, isUnsupportedKey, isValidIP, isValidUrl, linkConstructor, linkConstructorSimple, loadImage, logger, mapLocale, metadataProps, nFormatter, nanoid, normalizeEmail, normalizePath, normalizeString, paramsMetadata, parse, pluralize, randomValue, regexEscape, removeCookie, removeStorageItem, resizeAndCropImage, resizeImage, setCookie, setStorageItem, slugify, smartTruncate, stableSort, throttle, timeAgo, toCamelCase, trim, truncate, uid, validDomainRegex, validKeyRegex, validSlugRegex, validateEmail, verifyRecaptchaToken };
5100
+ export { API_PORT, CONNECT_SUPPORTED_COUNTRIES, CONTINENTS, CONTINENT_CODES, COUNTRIES, COUNTRY_CODES, COUNTRY_PHONE_CODES, DEBUG, DEFAULT_THEME_MODE, EU_COUNTRY_CODES, FRAMER_MOTION_LIST_ITEM_VARIANTS, INFINITY_NUMBER, LAST_VISITED_WORKSPACE, LOCALHOST_GEO_DATA, LOCALHOST_IP, LOG_LEVEL, META_THEME_COLORS, NEXT_PUBLIC_RECAPTCHA_SITE_KEY, NODE_ENV, OG_AVATAR_URL, PAGINATION_LIMIT, PORT, ParsedRequest, RECAPTCHA_SECRET_KEY, REDIRECT_QUERY_PARAM, REGIONS, REGION_CODES, RESERVED_SLUGS, SECOND_LEVEL_DOMAINS, SLACK_WEBHOOKS, SPECIAL_APEX_DOMAINS, STAGGER_CHILD_VARIANTS, SlackLog, type StorageType, TAB_ITEM_ANIMATION_SETTINGS, THEME_MODES, THE_BEGINNING_OF_TIME, TWO_WEEKS_IN_SECONDS, ThemeMode, UTMTags, assetsUrl, baseId, baseIdCustom, capitalize, ccTLDs, chunk, clearAllCookies, clearStorage, cn, combineWords, constructMetadata, constructURLFromUTMParams, createHref, createId, cuid, currencyFormatter, customId, customeId, debounce, deepEqual, fetchWithRetry, fetchWithTimeout, fetcher, fetcherSWR, fileToBase64, formatDate, formatDateTime, formatDateTimeSmart, formatFileSize, formatPeriod, formatTime, generateDomainFromName, getAdjustedBillingCycleStart, getAllCookies, getApexDomain, getBillingStartDate, getClientIP, getClientIPFromHeaders, getCookie, getCurrentYear, getDateTimeLocal, getDaysDifference, getDomainWithoutWWW, getEmailDomain, getEnv, getFirstAndLastDay, getFlagUrl, getHeight, getIPAddress, getInitials, getLastDayOfMonth, getParamsFromURL, getPrettyUrl, getRequestOrigin, getSearchParams, getSearchParamsWithArray, getSizeAvatar, getSlug, getStorageItem, getSubdomain, getTimeZones, getUrlFromString, getUrlFromStringIfValid, getUrlObjFromString, getUrlWithoutUTMParams, getUserAgent, getUserAgentFromHeaders, getUserName, googleTrackCodeCopy, googleTrackDirectionChange, googleTrackEvent, googleTrackItemCreate, googleTrackItemDelete, googleTrackItemRestore, googleTrackItemUpdate, googleTrackItemView, googleTrackThemeChange, googleTrackViewChange, hasCookie, hasStorageItem, hashStringSHA256, init as initCuid, isBusinessEmail, isDevelopment, isDisposableEmail, isIframeable, isProduction, isReservedKeyGlobal, isStaging, isTest, isUnsupportedKey, isValidIP, isValidUrl, linkConstructor, linkConstructorSimple, loadImage, logger, mapLocale, metadataProps, nFormatter, nanoid, normalizeEmail, normalizePath, normalizeString, paramsMetadata, parse, pluralize, randomValue, regexEscape, removeCookie, removeStorageItem, resizeAndCropImage, resizeImage, setCookie, setStorageItem, slugify, smartTruncate, stableSort, throttle, timeAgo, toCamelCase, trim, truncate, uid, validDomainRegex, validKeyRegex, validSlugRegex, validateEmail, verifyRecaptchaToken };
5162
5101
  //# sourceMappingURL=index.d.ts.map