/**
 * Surface where the canvas UI is displayed.
 */
export type CanvasSurface = 'overlay' | 'wheel';
/**
 * Clean interface for telemetry/analytics clients.
 *
 * This is the ONLY interface consumers should use. The underlying
 * implementation (PostHog, Segment, etc.) is an internal detail.
 */
export interface TelemetryClient {
    /**
     * Track when the canvas is opened.
     */
    trackCanvasOpened(surface: CanvasSurface): void;
    /**
     * Track when the canvas is closed.
     */
    trackCanvasClosed(surface: CanvasSurface): void;
    /**
     * Track when a rectangle/tile is viewed.
     */
    trackRectangleViewed(rectangleId: string, surface: CanvasSurface): void;
    /**
     * Track a user action.
     */
    trackAction(action: string, rectangleId: string, surface: CanvasSurface): void;
    /**
     * Register super properties that will be sent with all subsequent events.
     * Used by the editor SDK to tag crawler sessions.
     */
    register?(properties: Record<string, unknown>): void;
    /**
     * Get the current session ID from the telemetry provider.
     */
    getSessionId?(): string | undefined;
    /**
     * Force start session recording.
     * Used to bypass bot detection for crawler sessions.
     */
    startSessionRecording?(): void;
    /**
     * Track experiment assignment.
     * Called when a user is assigned to an experiment variation.
     * Registers experiment as super property and fires $experiment_started event.
     */
    trackExperiment?(experimentKey: string, variationId: number, variationName?: string): void;
    /**
     * Set person properties that persist across sessions/devices.
     * Used to store tour completion state, user preferences, etc.
     */
    setPersonProperties?(properties: Record<string, unknown>): void;
    /**
     * Set person properties only if they haven't been set before.
     * Useful for tracking first-time events like tour completion.
     */
    setPersonPropertiesOnce?(properties: Record<string, unknown>): void;
    /**
     * Get the current user's distinct ID from the telemetry provider.
     * Used for segment targeting lookups.
     */
    getDistinctId?(): string | undefined;
    /**
     * Get all feature flags from the telemetry provider.
     * Used to extract segment membership flags (in_segment_*).
     */
    getAllFeatureFlags?(): Record<string, boolean | string> | undefined;
    /**
     * Get segment membership flags (in_segment_*) from the telemetry provider.
     * Returns only flags that start with "in_segment_".
     */
    getSegmentFlags?(): Record<string, boolean>;
    /**
     * Track a custom event with arbitrary properties.
     * Used by audit events to send named events to PostHog.
     */
    track?(eventName: string, properties?: Record<string, unknown>): void;
    /**
     * Identify the current visitor with a stable ID.
     * Merges anonymous events into the new person record. Idempotent
     * for the same id. See SDK defaults spec D-1 / D-2.
     */
    identify?(distinctId: string, properties?: Record<string, unknown>): void;
    /**
     * Alias an existing identity to another id (treat as same person).
     * Used when a previously-identified visitor reveals an additional id
     * in the same session (e.g., logs in as bolshoifish then enters
     * parker.lowrey at checkout). PostHog merges both ids into one
     * person record.
     */
    alias?(newDistinctId: string, oldDistinctId?: string): void;
    /**
     * Switch from cookieless / opted-out mode to full identified capture.
     * Driven by the ConsentGate when status transitions to 'granted'.
     */
    optInCapturing?(): void;
    /**
     * Switch off all capturing. Driven by the ConsentGate when status
     * transitions to 'denied'.
     */
    optOutCapturing?(): void;
}
