@iblai/iblai-js 1.0.17 → 1.0.18

package/dist/data-layer/playwright/auth-flow-builder.d.ts

@@ -0,0 +1,13 @@
+import { Page } from '@playwright/test';
+import { StepFn } from './helpers';
+export declare class AuthFlowBuilder {
+    flow: string;
+    idp: string;
+    authHost: string;
+    constructor(flow?: string, idp?: string, authHost?: string);
+    run(page: Page, step: StepFn, username: string, password: string, hostUrl: string, authUrl: string, postLoginUrlMatcher?: (url: URL) => boolean): Promise<void>;
+    usernamePasswordFlow(page: Page, username: string, password: string, hostUrl: string, authUrl: string, postLoginUrlMatcher?: (url: URL) => boolean): Promise<void>;
+    magicLinkFlow(page: Page): Promise<void>;
+    ssoFlow(page: Page, username: string, password: string, hostUrl: string, authUrl: string): Promise<void>;
+    directSsoFlow(page: Page, step: StepFn, username: string, password: string, hostUrl: string, authUrl: string): Promise<void>;
+}

package/dist/data-layer/playwright/auth-helpers.d.ts

@@ -0,0 +1,10 @@
+import { Locator, Page } from '@playwright/test';
+export interface SignUpCredentials {
+    email: string;
+    password: string;
+}
+export declare function signUpWithEmailAndPassword(page: Page, authHost: string, postSignUpUrl: string, credentials?: SignUpCredentials, alreadyInSignupPage?: boolean): Promise<void>;
+export declare function loginWithEmailAndPassword(page: Page, username: string, password: string, hostUrl: string, postLoginUrlMatcher?: (url: URL) => boolean): Promise<void>;
+export declare function loginWithMicrosoftIdp(page: Page, username: string, password: string): Promise<void>;
+export declare function canChatWithEmbedMentor(page: Page, openChatButton: Locator): Promise<void>;
+export declare function getMentorIdFromUrl(url: string): string | null;

package/dist/data-layer/playwright/auth-setup.d.ts

@@ -0,0 +1,34 @@
+export interface AuthSetupConfig {
+    /** The app's host URL (e.g., https://mentor.example.com) */
+    hostUrl: string;
+    /** The auth service host URL (e.g., https://auth.example.com) */
+    authHost: string;
+    /** App name used in the login redirect URL (e.g., 'mentor', 'skills') */
+    appName: string;
+    /** Function to match the post-login URL to confirm authentication succeeded */
+    postLoginUrlMatcher: (url: URL) => boolean;
+    /** Auth flow type. Defaults to reading AUTH_FLOW env var or 'username_password' */
+    authFlow?: 'username_password' | 'magic_link' | 'sso' | 'direct_sso';
+    /** Auth IDP name for SSO flows */
+    authIdp?: string;
+}
+/**
+ * Creates a Playwright setup test function for authentication.
+ * Use this as the test body in your auth.setup.ts file:
+ *
+ * ```ts
+ * import { test as setup } from '@iblai/iblai-js/playwright';
+ * import { createAuthSetup } from '@iblai/iblai-js/playwright';
+ *
+ * setup('authenticate', createAuthSetup({
+ *   hostUrl: process.env.MENTOR_NEXTJS_HOST || '',
+ *   authHost: process.env.AUTH_HOST || '',
+ *   appName: 'mentor',
+ *   postLoginUrlMatcher: (url) => url.href.includes('/platform/'),
+ * }));
+ * ```
+ */
+export declare function createAuthSetup(config: AuthSetupConfig): ({ browser, step }: {
+    browser: any;
+    step: any;
+}, testInfo: any) => Promise<void>;

package/dist/data-layer/playwright/custom-reporter.d.ts

@@ -0,0 +1,12 @@
+import { FullConfig, FullResult, Reporter, Suite, TestCase, TestResult } from '@playwright/test/reporter';
+export default class CustomReporter implements Reporter {
+    onBegin(config: FullConfig, suite: Suite): void;
+    onTestBegin(test: TestCase): void;
+    onTestEnd(test: TestCase, result: TestResult): void;
+    onTimeout(timeout: number): void;
+    onEnd(result: FullResult): Promise<{
+        status?: FullResult['status'];
+    } | undefined | void> | void;
+    onStdOut(chunk: string | Buffer, test: void | TestCase, result: void | TestResult): void;
+    onStdErr(chunk: string | Buffer, test: void | TestCase, result: void | TestResult): void;
+}

package/dist/data-layer/playwright/env-config.d.ts

@@ -0,0 +1,24 @@
+export type AuthFlowType = 'username_password' | 'magic_link' | 'sso' | 'direct_sso';
+export interface EnvConfig {
+    skillHost: string;
+    authHost: string;
+    analyticsHost: string;
+    mentorHost: string;
+    mentorNextjsHost: string;
+    authNextjsHost: string;
+    playwrightUsername: string;
+    playwrightPassword: string;
+    inviteUsername: string;
+    inviteUserPassword: string;
+    authFlow: AuthFlowType;
+    authIdp: string;
+    enableStripeTest: boolean;
+    iblMentorDisabledTabs: string;
+    embedUrl: string;
+    wcagRange: string;
+}
+/**
+ * Create an environment configuration object from process.env with optional overrides.
+ * Each app can call this with their specific defaults.
+ */
+export declare function createEnvConfig(overrides?: Partial<EnvConfig>): EnvConfig;

package/dist/data-layer/playwright/helpers.d.ts

@@ -0,0 +1,11 @@
+import { expect, Page } from '@playwright/test';
+export declare function waitForPageLoad(page: Page): Promise<void>;
+export declare function closeWithEsc(page: Page): Promise<void>;
+export type StepFn = (title: string, fn: () => unknown) => unknown;
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    step: StepFn;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export declare const retry: (action: () => Promise<void>, errorMessage: string, retryCount?: number) => Promise<void>;
+export { expect };
+export declare const isJSON: (value: string) => boolean;
+export { safeWaitForURL, isFirefox } from './navigation';

package/dist/data-layer/playwright/index.d.ts

@@ -0,0 +1,17 @@
+export { test, expect, waitForPageLoad, closeWithEsc, retry, isJSON, safeWaitForURL, isFirefox } from './helpers';
+export type { StepFn } from './helpers';
+export type { SafeWaitForURLOptions } from './navigation';
+export { logger } from './logger';
+export { MailsacClient } from './mail-client';
+export { AuthFlowBuilder } from './auth-flow-builder';
+export { signUpWithEmailAndPassword, loginWithEmailAndPassword, loginWithMicrosoftIdp, canChatWithEmbedMentor, getMentorIdFromUrl, } from './auth-helpers';
+export type { SignUpCredentials } from './auth-helpers';
+export { createAuthSetup } from './auth-setup';
+export type { AuthSetupConfig } from './auth-setup';
+export { default as CustomReporter } from './custom-reporter';
+export { waitForPageReady, checkAdminStatus, waitForElementStable, reliableClick, reliableFill, waitForDialogReady, selectDateFromCalendar, expectNoAccessibilityViolations, expectNoAccessibilityViolationsOnDialogs, } from './page-helpers';
+export { inviteUserTest, navigateToAccountComponent, navigateToDataReports, shouldDisplayReportCards, shouldOpenCSVEditorDialog, shouldDisplayCSVInEditableTableFormat, shouldAllowEditingCellValuesInCSVEditor, shouldAddNewRowWhenClickingAddRowButton, shouldSaveEditedCSVAndTriggerDownload, shouldCloseCSVEditorWithoutSavingWhenClickingCancel, shouldCloseCSVEditorWhenClickingCloseButton, shouldVerifyCSVEditorDialogAccessibility, shouldOpenCSVEditorForUserMetadataReport, shouldDirectlyDownloadChatHistoryReportWithoutCSVEditor, shouldDisableOtherDownloadButtonsWhileGeneratingReport, shouldShowCombiningReportsDialog, shouldCancelCombiningReports, shouldHaveCombinedReportDataTestIds, shouldCombineRecommendationReports, } from './shared-test-helpers';
+export { createEnvConfig } from './env-config';
+export type { EnvConfig, AuthFlowType } from './env-config';
+export { createPlaywrightConfig, generateProjectConfig, generateBrowserSetupProjects, getBrowserKey, } from './playwright-config';
+export type { PlatformConfig, CreatePlaywrightConfigOptions, } from './playwright-config';

package/dist/data-layer/playwright/logger.d.ts

@@ -0,0 +1,3 @@
+import winston from 'winston';
+declare const logger: winston.Logger;
+export { logger };

package/dist/data-layer/playwright/mail-client.d.ts

@@ -0,0 +1,46 @@
+interface MailsacEmail {
+    _id: string;
+    from: Array<{
+        address: string;
+        name?: string;
+    }>;
+    to: Array<{
+        address: string;
+        name?: string;
+    }>;
+    subject: string;
+    inbox: string;
+    received: string;
+    size: number;
+    attachments: string[];
+    ip: string;
+    via: string;
+    folder: string;
+    labels: string[];
+    read: boolean;
+    rtls: boolean;
+    originalInbox: string;
+    spam: boolean;
+}
+export declare class MailsacClient {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string);
+    /**
+     * Get all emails for a specific inbox
+     * @param inbox - The inbox address (e.g., 'test@mailsac.com' or just 'test')
+     */
+    getEmails(inbox: string): Promise<MailsacEmail[]>;
+    /**
+     * Get a specific email by ID
+     * @param email - The email address
+     * @param messageId - The ID of the email to fetch
+     */
+    getEmailById(email: string, messageId: string): Promise<string>;
+    /**
+     * Delete a specific email by ID
+     * @param emailId - The ID of the email to delete
+     */
+    deleteEmail(emailId: string): Promise<any>;
+}
+export {};

package/dist/data-layer/playwright/navigation.d.ts

@@ -0,0 +1,26 @@
+import { Page } from '@playwright/test';
+export interface SafeWaitForURLOptions {
+    timeout?: number;
+    waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
+    maxRetries?: number;
+}
+/**
+ * Check if the current browser is Firefox
+ */
+export declare function isFirefox(page: Page): boolean;
+/**
+ * Safe wrapper around page.waitForURL that handles browser-specific navigation errors
+ *
+ * Firefox has stricter navigation lifecycle handling that can cause NS_BINDING_ABORTED
+ * errors when multiple rapid navigations occur (React router redirects, auth redirects).
+ *
+ * Safari can throw "Navigation canceled by policy check" errors during cross-origin
+ * navigations or when security policies interrupt the navigation flow.
+ *
+ * This utility:
+ * 1. Uses `waitUntil: 'commit'` for Firefox (faster, avoids abort)
+ * 2. Includes retry logic for NS_BINDING_ABORTED errors (Firefox)
+ * 3. Handles "Navigation canceled by policy check" errors (Safari)
+ * 4. Checks if URL is already correct before failing
+ */
+export declare function safeWaitForURL(page: Page, urlPattern: string | RegExp | ((url: URL) => boolean), options?: SafeWaitForURLOptions): Promise<void>;

package/dist/data-layer/playwright/page-helpers.d.ts

@@ -0,0 +1,38 @@
+import { Locator, Page } from '@playwright/test';
+import type { RuleObject } from 'axe-core';
+/**
+ * Wait for a page to be fully ready (DOM complete + brief delay for lazy rendering)
+ */
+export declare function waitForPageReady(page: Page, timeout?: number): Promise<void>;
+/**
+ * Check if the current user is an admin by reading localStorage
+ */
+export declare function checkAdminStatus(page: Page): Promise<boolean>;
+/**
+ * Wait for an element to be fully stable (attached, visible, not animating)
+ */
+export declare function waitForElementStable(page: Page, locator: Locator, timeout?: number): Promise<Locator>;
+/**
+ * Click an element with retry logic and stability checks
+ */
+export declare function reliableClick(page: Page, locator: Locator, timeout?: number, maxRetries?: number): Promise<void>;
+/**
+ * Fill an input element with retry logic, clearing first and verifying the value
+ */
+export declare function reliableFill(page: Page, locator: Locator, value: string, timeout?: number, maxRetries?: number): Promise<void>;
+/**
+ * Wait for a dialog element to be visible and its content loaded
+ */
+export declare function waitForDialogReady(page: Page, dialogLocator: Locator, timeout?: number): Promise<Locator>;
+/**
+ * Select a date from a calendar component, navigating months if needed
+ */
+export declare function selectDateFromCalendar(page: Page, dialogLocator: Locator, targetDate: Date, timeout?: number): Promise<void>;
+/**
+ * Run axe-core accessibility checks against a page
+ */
+export declare function expectNoAccessibilityViolations(page: Page): Promise<void>;
+/**
+ * Run axe-core accessibility checks against visible dialogs
+ */
+export declare function expectNoAccessibilityViolationsOnDialogs(page: Page, rules?: RuleObject, exclude?: string[]): Promise<void>;

package/dist/data-layer/playwright/playwright-config.d.ts

@@ -0,0 +1,81 @@
+import { type PlaywrightTestConfig } from '@playwright/test';
+export interface PlatformConfig {
+    /** Platform name used in project naming (e.g., 'mentornextjs', 'skills') */
+    name: string;
+    /** Devices to test on. Defaults to all 4 desktop browsers */
+    devices?: string[];
+    /** Dependencies for this platform (e.g., ['setup']) */
+    dependencies?: string[];
+    /** Additional test file patterns to match */
+    otherTestMatch?: string[];
+    /** Test files to ignore */
+    testIgnore?: string[];
+}
+export interface CreatePlaywrightConfigOptions {
+    /** Directory containing test files (relative to config file) */
+    testDir?: string;
+    /** Devices to use across all platforms. Defaults to Chrome, Firefox, Safari, Edge */
+    devices?: string[];
+    /** Platform configurations */
+    platforms: PlatformConfig[];
+    /** Path to custom reporter module (relative to config file). Defaults to './custom-reporter' */
+    customReporterPath?: string;
+    /** Additional cleanup or post-test projects */
+    extraProjects?: Array<{
+        name: string;
+        devices?: string[];
+        dependencies: string[];
+        testMatch: string[];
+    }>;
+}
+/** Extract browser key from device name (e.g., 'Desktop Chrome' -> 'chrome') */
+export declare function getBrowserKey(deviceName: string): string;
+/**
+ * Generate per-browser setup projects for Playwright authentication.
+ * Each browser gets its own auth setup project (setup-chrome, setup-firefox, etc.)
+ */
+export declare function generateBrowserSetupProjects(devicesToUse: string[]): {
+    name: string;
+    testMatch: RegExp;
+    use: {
+        viewport: import("@playwright/test").ViewportSize;
+        userAgent: string;
+        deviceScaleFactor: number;
+        isMobile: boolean;
+        hasTouch: boolean;
+        defaultBrowserType: "chromium" | "firefox" | "webkit";
+    };
+}[];
+/**
+ * Generate a Playwright project config for a platform + device combination.
+ */
+export declare function generateProjectConfig(platform: string, deviceName: string, dependencies?: string[], otherTestMatch?: string[], testIgnoreMatch?: string[]): {
+    name: string;
+    testMatch: string[];
+    use: {
+        storageState: string;
+        viewport: import("@playwright/test").ViewportSize;
+        userAgent: string;
+        deviceScaleFactor: number;
+        isMobile: boolean;
+        hasTouch: boolean;
+        defaultBrowserType: "chromium" | "firefox" | "webkit";
+    };
+    dependencies: string[];
+    testIgnore: string[];
+};
+/**
+ * Create a complete Playwright configuration for an IBL.ai application.
+ *
+ * Usage:
+ * ```ts
+ * import { createPlaywrightConfig } from '@iblai/iblai-js/playwright';
+ *
+ * export default createPlaywrightConfig({
+ *   platforms: [
+ *     { name: 'skills', dependencies: ['setup'], otherTestMatch: ['**skills/*\/*.spec.ts'] },
+ *   ],
+ * });
+ * ```
+ */
+export declare function createPlaywrightConfig(options: CreatePlaywrightConfigOptions): PlaywrightTestConfig;

package/dist/data-layer/playwright/shared-test-helpers.d.ts

@@ -0,0 +1,25 @@
+import { Locator, Page } from '@playwright/test';
+export declare function inviteUserTest(page: Page, inviteModal: Locator): Promise<void>;
+export declare function navigateToAccountComponent(page: Page, profileBtn: Locator): Promise<Locator>;
+export declare function navigateToDataReports(page: Page): Promise<void>;
+export declare function shouldDisplayReportCards(page: Page, REPORT_CARDS: {
+    name: string;
+    ariaLabel: string;
+    description: string;
+    expectsCsvEditor: boolean;
+}[]): Promise<void>;
+export declare function shouldOpenCSVEditorDialog(page: Page): Promise<void>;
+export declare function shouldDisplayCSVInEditableTableFormat(page: Page): Promise<void>;
+export declare function shouldAllowEditingCellValuesInCSVEditor(page: Page): Promise<void>;
+export declare function shouldAddNewRowWhenClickingAddRowButton(page: Page): Promise<void>;
+export declare function shouldSaveEditedCSVAndTriggerDownload(page: Page): Promise<void>;
+export declare function shouldCloseCSVEditorWithoutSavingWhenClickingCancel(page: Page): Promise<void>;
+export declare function shouldCloseCSVEditorWhenClickingCloseButton(page: Page): Promise<void>;
+export declare function shouldVerifyCSVEditorDialogAccessibility(page: Page): Promise<void>;
+export declare function shouldOpenCSVEditorForUserMetadataReport(page: Page): Promise<void>;
+export declare function shouldDirectlyDownloadChatHistoryReportWithoutCSVEditor(page: Page): Promise<void>;
+export declare function shouldDisableOtherDownloadButtonsWhileGeneratingReport(page: Page): Promise<void>;
+export declare function shouldShowCombiningReportsDialog(page: Page): Promise<void>;
+export declare function shouldCancelCombiningReports(page: Page): Promise<void>;
+export declare function shouldHaveCombinedReportDataTestIds(page: Page): Promise<void>;
+export declare function shouldCombineRecommendationReports(page: Page): Promise<void>;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iblai/iblai-js",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "Unified JavaScript SDK for IBL.ai — re-exports data-layer, web-containers, and web-utils under a single package",
   "type": "module",
   "engines": {
@@ -37,6 +37,11 @@
       "types": "./dist/web-utils/index.d.ts",
       "import": "./dist/web-utils/index.esm.js",
       "require": "./dist/web-utils/index.js"
+    },
+    "./playwright": {
+      "types": "./dist/playwright/index.d.ts",
+      "import": "./dist/playwright/index.esm.js",
+      "require": "./dist/playwright/index.js"
     }
   },
   "scripts": {
@@ -67,17 +72,28 @@
   "peerDependenciesMeta": {
     "next": {
       "optional": true
+    },
+    "@playwright/test": {
+      "optional": true
+    },
+    "@axe-core/playwright": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.11.1",
+    "@playwright/test": "^1.58.2",
     "@rollup/plugin-node-resolve": "15.3.1",
     "@rollup/plugin-typescript": "11.1.6",
+    "axe-core": "^4.11.1",
+    "axios": "^1.13.5",
     "rollup": "4.40.0",
     "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-dts": "^6.3.0",
     "rollup-plugin-peer-deps-external": "2.2.4",
     "tslib": "2.8.1",
-    "typescript": "5.8.3"
+    "typescript": "5.8.3",
+    "winston": "^3.19.0"
   },
   "packageManager": "pnpm@10.11.0",
   "publishConfig": {

package/dist/playwright/data-layer/index.d.ts

@@ -0,0 +1 @@
+export * from '@iblai/data-layer';