/**
 * Parameters attached to a recorded Insider event.
 *
 * Sourced from the native SDK — the map is unmodifiable on Android and a defensive copy
 * on iOS. Treat it as READ-ONLY; do not mutate it.
 *
 * Values are normalized for the bridge on both platforms before delivery. In particular a
 * `Date` nested inside the parameters arrives as epoch **MILLISECONDS** (a number),
 * following this SDK's epoch-millis convention for dates crossing the bridge. Note the
 * deliberate contrast with the callback's top-level `timestamp`, which is in SECONDS.
 * Values of a type the bridge cannot represent degrade to their string description rather
 * than being dropped.
 */
export type InsiderRecordedEventParameters = {
	readonly [key: string]: any;
};

/**
 * Callback invoked for every event recorded by the Insider SDK.
 *
 * ⚠️ `timestamp` IS IN **SECONDS**, NOT MILLISECONDS. ⚠️
 *
 * @param name - The recorded event name.
 * @param parameters - Read-only event parameters.
 * @param timestamp - Whole seconds since the Unix epoch. Convert with
 *                    `new Date(timestamp * 1000)`.
 */
export type InsiderEventRecordedCallback = (
	name: string,
	parameters: InsiderRecordedEventParameters,
	timestamp: number
) => void;

/** Handle returned by `events.addObserver`; call `remove()` to unsubscribe. */
export interface InsiderEventSubscription {
	/**
	 * Unsubscribes this listener. When the last subscriber is removed the underlying
	 * native observer is unregistered as well.
	 */
	remove(): void;
}

/**
 * Main API for subscribing to the Insider SDK's recorded-event stream.
 *
 * Mirrors the native SDK namespaces — `[[Insider events] addObserver:]` on iOS,
 * `Insider.Instance.events().addObserver(...)` on Android — so the wrapper reads
 * the way the SDK it wraps does.
 */
interface InsiderEvents {
	/**
	 * Subscribes to every event recorded by the Insider SDK.
	 *
	 * ## ⚠️ `timestamp` is in SECONDS, not milliseconds
	 *
	 * The `timestamp` argument is passed through from the native SDKs **unchanged**, in
	 * **whole seconds** since the Unix epoch (this is deliberate — it keeps parity with the
	 * native Android/iOS SDKs). JavaScript's `Date` constructor and `Date.now()` both use
	 * **milliseconds**, so you MUST multiply by 1000 before building a `Date`:
	 *
	 * ```typescript
	 * Insider.events.addObserver((name, parameters, timestamp) => {
	 *   const date = new Date(timestamp * 1000); // ✅ correct — timestamp is in SECONDS
	 *   // const wrong = new Date(timestamp);    // ❌ WRONG — yields a date in 1970
	 * });
	 * ```
	 *
	 * ## Threading
	 *
	 * The native SDK delivers on a dedicated background thread, so the callback may be
	 * invoked off the JS main work loop. Keep the callback cheap and non-blocking.
	 *
	 * ## Parameters are read-only
	 *
	 * `parameters` is unmodifiable on Android / a defensive copy on iOS. Do not mutate it.
	 *
	 * ## Unsubscribing
	 *
	 * Unlike `insiderIDListener`, this method returns a subscription. Call `remove()` on it
	 * to unsubscribe — important because this fires on EVERY event. Multiple subscribers are
	 * supported; the native observer is registered once and torn down only when the last
	 * subscriber is removed.
	 *
	 * @param callback - Invoked as `(name, parameters, timestamp)` for each recorded event.
	 * @returns A subscription handle, or `undefined` if the SDK is unavailable or the
	 *          callback failed validation.
	 */
	addObserver(callback: InsiderEventRecordedCallback): InsiderEventSubscription | undefined;
}

declare const InsiderEvents: InsiderEvents;

export default InsiderEvents;