@incodetech/core 2.1.0-rc.0 → 2.1.0-rc.2

package/dist/tri-CtxWthxz.esm.js

@@ -0,0 +1,389 @@
+import { t as BrowserTimerProvider } from "./BrowserTimerProvider-BVgutW_b.esm.js";
+
+//#region ../infra/src/providers/browser/BrowserLazyImportProvider.ts
+/**
+* Per-module {@link LazyImport} handle.
+*
+* Encapsulates the caching, deduplication, and optional-timeout logic for a
+* single lazily-imported module:
+*  - Caches the resolved module (via a dedicated `loaded` flag, so a module
+*    that legitimately resolves `undefined` is still cached) and returns it
+*    immediately on subsequent calls.
+*  - Deduplicates concurrent `load()` calls behind a single in-flight promise.
+*  - Optionally races the dynamic import against a configurable timeout (ms).
+*  - On timeout or import error: emits a `console.warn`, clears the in-flight
+*    promise so the next `load()` call retries, and resolves `undefined`.
+*
+* An attempt-generation token (`attempt`) guards against a stale import
+* mutating state after it has been superseded: when a load times out (or the
+* handle is `reset()`), the token is bumped so the still-pending import can no
+* longer write to `cachedValue` / `loaded`.
+*/
+var LazyImportHandle = class {
+	constructor(_loader, _options, _timer) {
+		this._loader = _loader;
+		this._options = _options;
+		this._timer = _timer;
+		this._loaded = false;
+		this._attempt = 0;
+	}
+	get() {
+		return this._cachedValue;
+	}
+	load() {
+		if (this._loaded) return Promise.resolve(this._cachedValue);
+		if (!this._inFlight) this._inFlight = this.startLoad();
+		return this._inFlight;
+	}
+	reset() {
+		this._cachedValue = void 0;
+		this._loaded = false;
+		this._inFlight = void 0;
+		this._attempt++;
+	}
+	startLoad() {
+		const attempt = ++this._attempt;
+		const { timeoutMs } = this._options;
+		let loaderResult;
+		try {
+			loaderResult = this._loader();
+		} catch (err) {
+			loaderResult = Promise.reject(err);
+		}
+		const loadPromise = loaderResult.then((value) => {
+			if (attempt === this._attempt) {
+				this._cachedValue = value;
+				this._loaded = true;
+			}
+			return value;
+		}, (err) => {
+			if (attempt === this._attempt) {
+				this.warnFailure(err);
+				this._inFlight = void 0;
+			}
+		});
+		if (timeoutMs === void 0) return loadPromise;
+		let timeoutHandle;
+		const timeoutPromise = new Promise((resolve) => {
+			timeoutHandle = this._timer.setTimeout(() => {
+				if (attempt === this._attempt) {
+					this.warnTimeout(timeoutMs);
+					this._inFlight = void 0;
+					this._attempt++;
+				}
+				resolve(void 0);
+			}, timeoutMs);
+		});
+		return Promise.race([loadPromise, timeoutPromise]).finally(() => {
+			if (timeoutHandle !== void 0) this._timer.clearTimeout(timeoutHandle);
+		});
+	}
+	warnFailure(err) {
+		const { label, moduleName } = this._options;
+		console.warn(`[${label}] Failed to load ${moduleName}; ${this.fallback()}`, err);
+	}
+	warnTimeout(timeoutMs) {
+		const { label, moduleName } = this._options;
+		console.warn(`[${label}] ${moduleName} failed to load within ${timeoutMs / 1e3}s; ${this.fallback()}`);
+	}
+	fallback() {
+		return this._options.disabledMessage ?? "module will be unavailable.";
+	}
+};
+/**
+* Concrete implementation of {@link ILazyImportCapability}.
+*
+* `create()` returns a per-module {@link LazyImportHandle}. The
+* {@link ITimerCapability} is injected so tests can replace the real
+* `setTimeout`/`clearTimeout` with a controllable fake.
+*/
+var BrowserLazyImportProvider = class BrowserLazyImportProvider {
+	constructor(timer) {
+		this._timer = timer ?? BrowserTimerProvider.getInstance();
+	}
+	static getInstance() {
+		return this._instance ??= new BrowserLazyImportProvider();
+	}
+	static resetInstance() {
+		this._instance = void 0;
+	}
+	create(loader, options) {
+		return new LazyImportHandle(loader, options, this._timer);
+	}
+};
+
+//#endregion
+//#region ../infra/src/providers/browser/TransactionalRiskIntelligenceProvider.ts
+const LAZY_IMPORT_OPTIONS = {
+	label: "TRI",
+	moduleName: "@incodetech/tri-sdk",
+	timeoutMs: 1e4,
+	disabledMessage: "TRI will be disabled for this session."
+};
+const importSdk = () => import("./tri.esm-CrWAulDi.esm.js");
+/**
+* Concrete implementation of {@link ITransactionalRiskIntelligenceCapability}.
+*
+* This is the **only** file in the repo that references `@incodetech/tri-sdk`.
+* The third-party module is loaded via a dynamic `import()` the first time
+* {@link setup} is called, so consumers that never opt into TRI (i.e. never
+* pass `tri` to `setup()`) do not pay the bundle cost.
+*
+* `start()`, `stop()`, `reset()`, and `linkInterview()` require a prior
+* successful `setup()` call. The SDK cannot start without the foundation,
+* collection-status check, and managers that `setup()` establishes. Calling
+* these methods before `setup()` is a no-op that returns `'init-failed'` or
+* `false` respectively.
+*
+* The dynamic `import('@incodetech/tri-sdk')` is managed by
+* {@link BrowserLazyImportProvider}, which races the import against a
+* {@link LOAD_TIMEOUT_MS}-ms timeout. On timeout the provider warns, clears
+* the cached promise (so a subsequent `setup()` can retry), and resolves
+* `undefined`, gracefully disabling TRI for the session.
+*/
+var TransactionalRiskIntelligenceProvider = class TransactionalRiskIntelligenceProvider {
+	constructor() {
+		this._isStarted = false;
+		this._lazySdk = BrowserLazyImportProvider.getInstance().create(importSdk, LAZY_IMPORT_OPTIONS);
+	}
+	static getInstance() {
+		return this._instance ??= new TransactionalRiskIntelligenceProvider();
+	}
+	static resetInstance() {
+		this._instance = void 0;
+	}
+	get isStarted() {
+		return this._isStarted;
+	}
+	/**
+	* Lazy-loads `@incodetech/tri-sdk` (shared lazy handle) and exchanges the
+	* organization API key for a short-lived SDK token via the module's
+	* `createSession`. On a load timeout/failure returns an error-shaped session
+	* rather than throwing, so the boot path is never blocked.
+	*/
+	async createSession(apiKey, options) {
+		const module = await this._lazySdk.load();
+		if (!module) return {
+			token: null,
+			expiresAt: null,
+			tokenType: null,
+			eventsCollectionEnabled: false,
+			error: {
+				status: 0,
+				message: "TRI SDK failed to load"
+			}
+		};
+		return module.createSession(apiKey, options);
+	}
+	/**
+	* Lazy-loads `@incodetech/tri-sdk` on first call (with a {@link LOAD_TIMEOUT_MS}-ms
+	* timeout), then delegates to its `setup()`. Returns a promise that resolves
+	* once the SDK module has been fetched and the backend collection-status
+	* check has completed.
+	*
+	* When `config.autostart` is `true` (the default), the underlying `setup()`
+	* also calls `start()` and returns `'started'` on success. `_isStarted` is
+	* updated to reflect the resulting state so that `isTRIStarted()` is
+	* accurate immediately after `setup()` returns.
+	*/
+	async setup(config) {
+		try {
+			const module = await this._lazySdk.load();
+			if (!module) return "init-failed";
+			const state = await module.default.setup(config);
+			if (state === "started") this._isStarted = true;
+			return state;
+		} catch {
+			return "init-failed";
+		}
+	}
+	/**
+	* Begins behavioral data collection. Requires a prior successful `setup()`.
+	* Returns `'init-failed'` without starting if called before `setup()`.
+	*/
+	async start() {
+		const state = await (this._getSdk()?.start() ?? Promise.resolve("init-failed"));
+		this._isStarted = state === "started";
+		return state;
+	}
+	/**
+	* Stops all collectors and managers. No-op when called before `setup()`.
+	*/
+	async stop() {
+		const state = await (this._getSdk()?.stop() ?? Promise.resolve("init-failed"));
+		this._isStarted = false;
+		return state;
+	}
+	/**
+	* Resets the TRI SDK to its initial state. No-op when called before `setup()`.
+	*/
+	async reset() {
+		const state = await (this._getSdk()?.reset() ?? Promise.resolve("init-failed"));
+		this._isStarted = false;
+		return state;
+	}
+	/**
+	* Links an interview to the current TRI activity. Returns `false` when
+	* called before `setup()` or when the backend request fails. Never throws,
+	* so the boot/flow path is never blocked by a failed link.
+	*
+	* @param sessionToken - The Incode session token to link.
+	*/
+	async linkInterview(sessionToken) {
+		try {
+			return await this._getSdk()?.linkInterview(sessionToken) ?? false;
+		} catch {
+			return false;
+		}
+	}
+	_getSdk() {
+		return this._lazySdk.get()?.default ?? null;
+	}
+};
+
+//#endregion
+//#region src/integrations/tri/tri.ts
+/**
+* Returns the active TRI capability implementation.
+*
+* Core functions depend on {@link ITransactionalRiskIntelligenceCapability}
+* (the interface) rather than the concrete provider class. The provider is
+* referenced here only to supply the default singleton. This integration
+* module is the single owner of the concrete provider reference — the rest of
+* core goes through these functions ({@link isTRIStarted},
+* {@link resetTRIProviderInstance}, etc.) instead of importing the provider.
+*/
+function getProvider() {
+	return TransactionalRiskIntelligenceProvider.getInstance();
+}
+/**
+* Returns `true` when TRI collectors are currently running (a successful
+* `setupTRI()` autostart or explicit `startTRI()`, with no subsequent
+* `stopTRI()`/`resetTRI()`). Returns `false` before setup or after teardown.
+*/
+function isTRIStarted() {
+	return getProvider().isStarted;
+}
+/**
+* Discards the cached TRI provider singleton so the next access constructs a
+* fresh instance. Call from the SDK's `reset()` after `resetTRI()` to clear
+* the `isStarted` flag and lazy-import state.
+*/
+function resetTRIProviderInstance() {
+	TransactionalRiskIntelligenceProvider.resetInstance();
+}
+/**
+* Exchanges an organization API key for a short-lived TRI SDK token. This is
+* the entry point that triggers the lazy-load of `@incodetech/tri-sdk` (via the
+* provider's dynamic `import()`); the cached lazy handle is reused by a
+* subsequent `setupTRI()`.
+*
+* In production the exchange should happen server-side. On a load timeout or
+* failure the returned session carries `token: null` and an `error`, rather
+* than throwing.
+*
+* @param apiKey  - Organization API key.
+* @param options - Optional `apiURL`, `signal`, and `timeout` overrides.
+*/
+async function createTRISession(apiKey, options) {
+	return getProvider().createSession(apiKey, options);
+}
+/**
+* Initializes TRI in a single step: resolves the config, calls `setupTRI`
+* (which autostarts unless `config.autostart` is `false`), and optionally
+* links the current Incode session.
+*
+* Returns the resolved {@link TransactionalRiskIntelligenceState}. If the
+* config cannot be resolved (e.g. missing `token` or `apiURL`), returns
+* `'init-failed'` after emitting a `[TRI]` warning.
+*
+* When `config.autostart` is `false`, the underlying `setupTRI` returns
+* `'ready'` without starting collection — call `startTRI()` explicitly when
+* ready (e.g. after a consent gate). Linking is skipped in that case since
+* TRI has not started.
+*
+* @param config  - TRI setup config (must include `token` and `apiURL`).
+* @param options - Optional session-linking hints (`sessionToken`).
+*/
+async function initializeTRI(config, options = {}) {
+	const resolvedTriConfig = resolveTRIConfig(config);
+	if (!resolvedTriConfig) return "init-failed";
+	const state = await setupTRI(resolvedTriConfig);
+	if (isTRIStarted() && options.sessionToken) await linkSessionWithTRI(options.sessionToken);
+	return state;
+}
+/**
+* Calls the provider's `setup()` with the given config. This is the step that
+* lazy-loads `@incodetech/tri-sdk`, validates the config, and checks the
+* backend collection-status endpoint. When `config.autostart` is `true` (the
+* default), also calls `start()` internally and returns `'started'` on
+* success. Pass `autostart: false` to receive `'ready'` and start explicitly.
+*
+* @param config - Resolved TRI config (`token` and `apiURL` required).
+* @returns The resulting {@link TransactionalRiskIntelligenceState}.
+*/
+async function setupTRI(config) {
+	return getProvider().setup(config);
+}
+/**
+* Begins behavioral data collection. Requires a prior successful `setupTRI()`
+* call with `autostart: false`. Returns `'init-failed'` without starting if
+* called before setup, or is a no-op if already started.
+*
+* @returns The resulting {@link TransactionalRiskIntelligenceState}.
+*/
+async function startTRI() {
+	return getProvider().start();
+}
+/**
+* Stops all TRI collectors and managers. Idempotent. No-op if TRI was never
+* set up.
+*/
+async function stopTRI() {
+	return getProvider().stop();
+}
+/**
+* Resets the TRI SDK to its initial state. Call this from the SDK's `reset()`
+* so that a subsequent `setupTRI` / `startTRI` can begin fresh.
+*/
+async function resetTRI() {
+	return getProvider().reset();
+}
+/**
+* Links the current Incode interview session to the active TRI activity.
+*
+* Returns `false` when the session token is missing or TRI has not been set up.
+*
+* @param sessionToken - Incode session JWT.
+*/
+async function linkSessionWithTRI(sessionToken) {
+	if (!sessionToken) return false;
+	return getProvider().linkInterview(sessionToken);
+}
+/**
+* @private This function is not used outside of this file.
+*
+* Validates and narrows a {@link TransactionalRiskIntelligenceSetupConfig}
+* into a {@link TransactionalRiskIntelligenceConfig} suitable for passing to
+* the provider's `setup()`.
+*
+* Returns `null` (with a `[TRI]` warning) when a required field is missing.
+* Returns `null` silently when `config` is `undefined` (intentional opt-out).
+*
+* @param config - Raw setup-time config from `SetupOptions.tri`.
+*/
+function resolveTRIConfig(config) {
+	if (!config) return null;
+	if (!config.token) {
+		console.warn("[TRI] Not initialized: token is required.");
+		return null;
+	}
+	if (!config.apiURL) {
+		console.warn("[TRI] Not initialized: apiURL is required.");
+		return null;
+	}
+	return config;
+}
+
+//#endregion
+export { resetTRI as a, startTRI as c, linkSessionWithTRI as i, stopTRI as l, initializeTRI as n, resetTRIProviderInstance as o, isTRIStarted as r, setupTRI as s, createTRISession as t };

package/dist/tri.d.ts

@@ -0,0 +1,2 @@
+import { a as startTRI, i as setupTRI, n as isTRIStarted, o as stopTRI, r as resetTRI, s as TransactionalRiskIntelligenceSetupConfig, t as createTRISession } from "./index-52_qi4bd.js";
+export { TransactionalRiskIntelligenceSetupConfig, createTRISession, isTRIStarted, resetTRI, setupTRI, startTRI, stopTRI };