@happyvertical/analytics 0.74.8

package/dist/shared/types.d.ts

@@ -0,0 +1,1235 @@
+/**
+ * Core types and interfaces for the Analytics library
+ */
+/**
+ * Base configuration options for all analytics providers
+ */
+export interface BaseAnalyticsOptions {
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Maximum retry attempts for failed requests */
+    maxRetries?: number;
+    /** Cache TTL in milliseconds for metadata operations */
+    cacheTTL?: number;
+}
+/**
+ * Service account credentials for Google APIs
+ */
+export interface ServiceAccountCredentials {
+    type: 'service_account';
+    project_id: string;
+    private_key_id: string;
+    private_key: string;
+    client_email: string;
+    client_id: string;
+    auth_uri: string;
+    token_uri: string;
+    auth_provider_x509_cert_url: string;
+    client_x509_cert_url: string;
+}
+/**
+ * Google Analytics 4 provider options
+ */
+export interface GA4Options extends BaseAnalyticsOptions {
+    type: 'ga4';
+    /**
+     * Service account credentials for Admin API and Data API
+     * Can be path to JSON key file or parsed JSON object
+     */
+    serviceAccountKey?: string | ServiceAccountCredentials;
+    /**
+     * Measurement ID (G-XXXXXXX) for Measurement Protocol
+     * Required for server-side event tracking
+     */
+    measurementId?: string;
+    /**
+     * API Secret for Measurement Protocol
+     * Required for server-side event tracking
+     */
+    apiSecret?: string;
+    /**
+     * Default property ID for operations that don't specify one
+     */
+    defaultPropertyId?: string;
+}
+/**
+ * Plausible Analytics provider options
+ */
+export interface PlausibleOptions extends BaseAnalyticsOptions {
+    type: 'plausible';
+    /**
+     * Plausible API key
+     */
+    apiKey: string;
+    /**
+     * Base URL for self-hosted instances
+     * @default "https://plausible.io"
+     */
+    baseUrl?: string;
+    /**
+     * Default site ID (domain) for operations
+     */
+    defaultSiteId?: string;
+}
+/**
+ * Matomo Analytics provider options
+ *
+ * Matomo's Reporting API authenticates via per-user `token_auth` values; admin
+ * provisioning operations require a token belonging to a super-user.
+ */
+export interface MatomoOptions extends BaseAnalyticsOptions {
+    type: 'matomo';
+    /**
+     * Matomo base URL (e.g. `https://matomo.example.com`).
+     *
+     * Trailing slashes and explicit `/index.php` suffixes are normalized.
+     */
+    baseUrl: string;
+    /**
+     * `token_auth` for the calling user. Required for all reporting calls.
+     *
+     * For admin provisioning (createSite/createUser/etc.) this token must
+     * belong to a Matomo super-user.
+     */
+    tokenAuth: string;
+    /**
+     * Default site ID (`idSite`) for operations that don't specify one.
+     */
+    defaultSiteId?: string;
+}
+/**
+ * Union type for all provider options
+ */
+export type GetAnalyticsOptions = GA4Options | PlausibleOptions | MatomoOptions;
+/**
+ * Analytics property/site representation
+ */
+export interface Property {
+    /** Unique identifier */
+    id: string;
+    /** Internal name (GA4: properties/123456789) */
+    name: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Creation timestamp (ISO 8601) */
+    createTime: string;
+    /** Last update timestamp (ISO 8601) */
+    updateTime?: string;
+    /** Property timezone */
+    timeZone?: string;
+    /** Currency code (e.g., 'USD', 'EUR') */
+    currencyCode?: string;
+    /** Industry category */
+    industryCategory?: string;
+    /** Service level */
+    serviceLevel?: 'STANDARD' | 'PREMIUM';
+}
+/**
+ * Options for listing properties
+ */
+export interface ListPropertiesOptions {
+    /**
+     * Controls whether the provider should hydrate discovered properties with
+     * full metadata.
+     *
+     * Providers that support hydration should default this to `true` to
+     * preserve the existing `listProperties()` behavior. Set this to `false`
+     * to use discovery-only metadata, which may omit fields like `createTime`,
+     * `updateTime`, `timeZone`, and `currencyCode`.
+     */
+    hydrate?: boolean;
+}
+/**
+ * Options for creating a new property
+ */
+export interface CreatePropertyOptions {
+    /** Human-readable display name */
+    displayName: string;
+    /** Timezone (e.g., 'America/Los_Angeles') */
+    timeZone?: string;
+    /** Currency code (e.g., 'USD') */
+    currencyCode?: string;
+    /** Industry category */
+    industryCategory?: string;
+    /** Parent account (GA4: accounts/{account_id}) */
+    parent?: string;
+}
+/**
+ * Options for updating a property
+ */
+export interface UpdatePropertyOptions {
+    /** Human-readable display name */
+    displayName?: string;
+    /** Timezone */
+    timeZone?: string;
+    /** Currency code */
+    currencyCode?: string;
+    /** Industry category */
+    industryCategory?: string;
+}
+/**
+ * Data stream types
+ */
+export type DataStreamType = 'WEB_DATA_STREAM' | 'ANDROID_APP_DATA_STREAM' | 'IOS_APP_DATA_STREAM';
+/**
+ * Data stream representation
+ */
+export interface DataStream {
+    /** Unique identifier */
+    id: string;
+    /** Stream type */
+    type: DataStreamType;
+    /** Human-readable display name */
+    displayName: string;
+    /** Measurement ID for web streams (G-XXXXXXX) */
+    measurementId?: string;
+    /** Firebase App ID for app streams */
+    firebaseAppId?: string;
+    /** Default URI for web streams */
+    defaultUri?: string;
+    /** Creation timestamp */
+    createTime: string;
+    /** Last update timestamp */
+    updateTime?: string;
+}
+/**
+ * Options for creating a data stream
+ */
+export interface CreateDataStreamOptions {
+    /** Stream type */
+    type: DataStreamType;
+    /** Human-readable display name */
+    displayName: string;
+    /** Default URI for web streams */
+    defaultUri?: string;
+    /** Bundle ID for iOS apps */
+    bundleId?: string;
+    /** Package name for Android apps */
+    packageName?: string;
+}
+/**
+ * Scope for custom dimensions
+ */
+export type CustomDimensionScope = 'EVENT' | 'USER' | 'ITEM';
+/**
+ * Custom dimension representation
+ */
+export interface CustomDimension {
+    /** Unique identifier */
+    id: string;
+    /** Resource name */
+    name: string;
+    /** Parameter name used in events */
+    parameterName: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Description */
+    description?: string;
+    /** Scope of the dimension */
+    scope: CustomDimensionScope;
+    /** Whether to disallow ads personalization */
+    disallowAdsPersonalization?: boolean;
+}
+/**
+ * Options for creating a custom dimension
+ */
+export interface CustomDimensionOptions {
+    /** Parameter name used in events */
+    parameterName: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Description */
+    description?: string;
+    /** Scope of the dimension */
+    scope: CustomDimensionScope;
+    /** Whether to disallow ads personalization */
+    disallowAdsPersonalization?: boolean;
+}
+/**
+ * Measurement unit for custom metrics
+ */
+export type MeasurementUnit = 'STANDARD' | 'CURRENCY' | 'FEET' | 'METERS' | 'KILOMETERS' | 'MILES' | 'MILLISECONDS' | 'SECONDS' | 'MINUTES' | 'HOURS';
+/**
+ * Custom metric representation
+ */
+export interface CustomMetric {
+    /** Unique identifier */
+    id: string;
+    /** Resource name */
+    name: string;
+    /** Parameter name used in events */
+    parameterName: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Description */
+    description?: string;
+    /** Scope (always EVENT for metrics) */
+    scope: 'EVENT';
+    /** Measurement unit */
+    measurementUnit: MeasurementUnit;
+    /** Restricted metric type */
+    restrictedMetricType?: 'COST_DATA' | 'REVENUE_DATA';
+}
+/**
+ * Options for creating a custom metric
+ */
+export interface CustomMetricOptions {
+    /** Parameter name used in events */
+    parameterName: string;
+    /** Human-readable display name */
+    displayName: string;
+    /** Description */
+    description?: string;
+    /** Measurement unit */
+    measurementUnit: MeasurementUnit;
+    /** Restricted metric type */
+    restrictedMetricType?: 'COST_DATA' | 'REVENUE_DATA';
+}
+/**
+ * Counting method for key events
+ */
+export type CountingMethod = 'ONCE_PER_EVENT' | 'ONCE_PER_SESSION';
+/**
+ * Key event (conversion) representation
+ */
+export interface KeyEvent {
+    /** Unique identifier */
+    id: string;
+    /** Resource name */
+    name: string;
+    /** Event name that triggers this key event */
+    eventName: string;
+    /** Creation timestamp */
+    createTime: string;
+    /** How to count the conversion */
+    countingMethod?: CountingMethod;
+    /** Default value for the conversion */
+    defaultValue?: {
+        numericValue?: number;
+        currencyCode?: string;
+    };
+}
+/**
+ * Options for creating a key event
+ */
+export interface KeyEventOptions {
+    /** Event name that triggers this key event */
+    eventName: string;
+    /** How to count the conversion */
+    countingMethod?: CountingMethod;
+    /** Default value for the conversion */
+    defaultValue?: {
+        numericValue?: number;
+        currencyCode?: string;
+    };
+}
+/**
+ * Date range for reports
+ */
+export interface DateRange {
+    /** Start date (YYYY-MM-DD or relative: 'today', 'yesterday', '7daysAgo', '30daysAgo') */
+    startDate: string;
+    /** End date (YYYY-MM-DD or relative: 'today', 'yesterday') */
+    endDate: string;
+    /** Optional name for this date range */
+    name?: string;
+}
+/**
+ * Dimension specification for reports
+ */
+export interface Dimension {
+    /** Dimension name (e.g., 'country', 'deviceCategory') */
+    name: string;
+}
+/**
+ * Metric specification for reports
+ */
+export interface Metric {
+    /** Metric name (e.g., 'activeUsers', 'sessions') */
+    name: string;
+}
+/**
+ * Filter match types
+ */
+export type StringMatchType = 'EXACT' | 'BEGINS_WITH' | 'ENDS_WITH' | 'CONTAINS' | 'FULL_REGEXP' | 'PARTIAL_REGEXP';
+/**
+ * Numeric filter operations
+ */
+export type NumericOperation = 'EQUAL' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL';
+/**
+ * Filter value (numeric)
+ */
+export interface NumericValue {
+    int64Value?: string;
+    doubleValue?: number;
+}
+/**
+ * String filter specification
+ */
+export interface StringFilter {
+    matchType: StringMatchType;
+    value: string;
+    caseSensitive?: boolean;
+}
+/**
+ * In-list filter specification
+ */
+export interface InListFilter {
+    values: string[];
+    caseSensitive?: boolean;
+}
+/**
+ * Numeric filter specification
+ */
+export interface NumericFilter {
+    operation: NumericOperation;
+    value: NumericValue;
+}
+/**
+ * Between filter specification
+ */
+export interface BetweenFilter {
+    fromValue: NumericValue;
+    toValue: NumericValue;
+}
+/**
+ * Individual filter specification
+ */
+export interface Filter {
+    fieldName: string;
+    stringFilter?: StringFilter;
+    inListFilter?: InListFilter;
+    numericFilter?: NumericFilter;
+    betweenFilter?: BetweenFilter;
+}
+/**
+ * Filter expression (supports AND/OR/NOT combinations)
+ */
+export interface FilterExpression {
+    andGroup?: {
+        expressions: FilterExpression[];
+    };
+    orGroup?: {
+        expressions: FilterExpression[];
+    };
+    notExpression?: FilterExpression;
+    filter?: Filter;
+}
+/**
+ * Order type for dimension sorting
+ */
+export type DimensionOrderType = 'ALPHANUMERIC' | 'CASE_INSENSITIVE_ALPHANUMERIC' | 'NUMERIC';
+/**
+ * Order specification
+ */
+export interface OrderBy {
+    metric?: {
+        metricName: string;
+    };
+    dimension?: {
+        dimensionName: string;
+        orderType?: DimensionOrderType;
+    };
+    desc?: boolean;
+}
+/**
+ * Minute range for realtime reports
+ */
+export interface MinuteRange {
+    name?: string;
+    startMinutesAgo: number;
+    endMinutesAgo: number;
+}
+/**
+ * Report request options
+ */
+export interface ReportOptions {
+    /** Date ranges to query */
+    dateRanges: DateRange[];
+    /** Dimensions to group by */
+    dimensions?: Dimension[];
+    /** Metrics to retrieve */
+    metrics: Metric[];
+    /** Dimension filter expression */
+    dimensionFilter?: FilterExpression;
+    /** Metric filter expression */
+    metricFilter?: FilterExpression;
+    /** Result offset for pagination */
+    offset?: number;
+    /** Maximum results to return */
+    limit?: number;
+    /** Sort order */
+    orderBys?: OrderBy[];
+    /** Whether to keep empty rows */
+    keepEmptyRows?: boolean;
+    /** Whether to return property quota information */
+    returnPropertyQuota?: boolean;
+}
+/**
+ * Realtime report options
+ */
+export interface RealtimeReportOptions {
+    /** Dimensions to group by */
+    dimensions?: Dimension[];
+    /** Metrics to retrieve */
+    metrics?: Metric[];
+    /** Dimension filter expression */
+    dimensionFilter?: FilterExpression;
+    /** Metric filter expression */
+    metricFilter?: FilterExpression;
+    /** Maximum results to return */
+    limit?: number;
+    /** Minute ranges to query */
+    minuteRanges?: MinuteRange[];
+}
+/**
+ * Report row
+ */
+export interface ReportRow {
+    dimensionValues: {
+        value: string;
+    }[];
+    metricValues: {
+        value: string;
+    }[];
+}
+/**
+ * Quota information
+ */
+export interface QuotaInfo {
+    consumed: number;
+    remaining: number;
+}
+/**
+ * Property quota information
+ */
+export interface PropertyQuota {
+    tokensPerDay: QuotaInfo;
+    tokensPerHour: QuotaInfo;
+    concurrentRequests: QuotaInfo;
+}
+/**
+ * Report result
+ */
+export interface ReportResult {
+    /** Column headers for dimensions */
+    dimensionHeaders: {
+        name: string;
+    }[];
+    /** Column headers for metrics */
+    metricHeaders: {
+        name: string;
+        type: string;
+    }[];
+    /** Data rows */
+    rows: ReportRow[];
+    /** Total row count */
+    rowCount?: number;
+    /** Report metadata */
+    metadata?: {
+        currencyCode?: string;
+        timeZone?: string;
+        dataLossFromOtherRow?: boolean;
+        emptyReason?: string;
+    };
+    /** Property quota usage */
+    propertyQuota?: PropertyQuota;
+}
+/**
+ * Metric type
+ */
+export type MetricType = 'METRIC_TYPE_UNSPECIFIED' | 'TYPE_INTEGER' | 'TYPE_FLOAT' | 'TYPE_SECONDS' | 'TYPE_MILLISECONDS' | 'TYPE_MINUTES' | 'TYPE_HOURS' | 'TYPE_STANDARD' | 'TYPE_CURRENCY' | 'TYPE_FEET' | 'TYPE_MILES' | 'TYPE_METERS' | 'TYPE_KILOMETERS';
+/**
+ * Metric metadata
+ */
+export interface MetricMetadata {
+    /** API name for the metric */
+    apiName: string;
+    /** UI display name */
+    uiName: string;
+    /** Description */
+    description: string;
+    /** Deprecated API names */
+    deprecatedApiNames?: string[];
+    /** Metric data type */
+    type: MetricType;
+    /** Expression for calculated metrics */
+    expression?: string;
+    /** Whether this is a custom definition */
+    customDefinition?: boolean;
+    /** Reasons metric may be blocked */
+    blockedReasons?: string[];
+    /** Category */
+    category?: string;
+}
+/**
+ * Dimension metadata
+ */
+export interface DimensionMetadata {
+    /** API name for the dimension */
+    apiName: string;
+    /** UI display name */
+    uiName: string;
+    /** Description */
+    description: string;
+    /** Deprecated API names */
+    deprecatedApiNames?: string[];
+    /** Whether this is a custom definition */
+    customDefinition?: boolean;
+    /** Category */
+    category?: string;
+}
+/**
+ * Track event payload
+ */
+export interface TrackEvent {
+    /** Event name */
+    name: string;
+    /** Event parameters */
+    params?: Record<string, string | number | boolean>;
+    /** Client ID for anonymous tracking */
+    clientId?: string;
+    /** User ID for identified tracking */
+    userId?: string;
+    /** Event timestamp (Unix epoch in microseconds) */
+    timestamp?: number;
+    /** Whether to disable personalized ads */
+    nonPersonalizedAds?: boolean;
+}
+/**
+ * Pageview event payload
+ */
+export interface PageviewEvent {
+    /** Page path */
+    pagePath: string;
+    /** Page title */
+    pageTitle?: string;
+    /** Full page location URL */
+    pageLocation?: string;
+    /** Client ID for anonymous tracking */
+    clientId?: string;
+    /** User ID for identified tracking */
+    userId?: string;
+    /** Additional parameters */
+    params?: Record<string, string | number | boolean>;
+}
+/**
+ * Generated tracking snippet
+ */
+export interface TrackingSnippet {
+    /** HTML snippet ready to embed */
+    html: string;
+    /** Configuration object */
+    config: Record<string, unknown>;
+    /** External script URLs */
+    scripts: string[];
+}
+/**
+ * Options for snippet generation
+ */
+export interface SnippetOptions {
+    /** Whether to anonymize IP addresses */
+    anonymizeIp?: boolean;
+    /** Whether to send initial pageview */
+    sendPageView?: boolean;
+    /** Cookie flags */
+    cookieFlags?: string;
+    /** Custom configuration options */
+    customConfig?: Record<string, unknown>;
+}
+/**
+ * Options for config generation
+ */
+export interface ConfigOptions {
+    /** Whether to anonymize IP addresses */
+    anonymizeIp?: boolean;
+    /** Whether to send initial pageview */
+    sendPageView?: boolean;
+    /** User ID for cross-device tracking */
+    userId?: string;
+    /** Custom dimensions to set */
+    customDimensions?: Record<string, string>;
+}
+/**
+ * Analytics provider capabilities
+ */
+export interface AnalyticsCapabilities {
+    /** Whether property management is supported */
+    propertyManagement: boolean;
+    /** Whether data streams are supported */
+    dataStreams: boolean;
+    /** Whether custom dimensions are supported */
+    customDimensions: boolean;
+    /** Whether custom metrics are supported */
+    customMetrics: boolean;
+    /** Whether key events (conversions) are supported */
+    keyEvents: boolean;
+    /** Whether reporting is supported */
+    reporting: boolean;
+    /** Whether realtime reporting is supported */
+    realtimeReporting: boolean;
+    /** Whether server-side tracking is supported */
+    serverSideTracking: boolean;
+    /** Whether client-side snippet generation is supported */
+    clientSideSnippet: boolean;
+    /** Whether user identification is supported */
+    userIdentification: boolean;
+    /** Whether batch tracking is supported */
+    batchTracking: boolean;
+}
+/**
+ * Core analytics interface that all providers must implement
+ */
+export interface AnalyticsInterface {
+    /**
+     * Create a new analytics property
+     */
+    createProperty(options: CreatePropertyOptions): Promise<Property>;
+    /**
+     * List all properties accessible to this account
+     */
+    listProperties(options?: ListPropertiesOptions): Promise<Property[]>;
+    /**
+     * Get a specific property by ID
+     */
+    getProperty(propertyId: string): Promise<Property>;
+    /**
+     * Update a property
+     */
+    updateProperty(propertyId: string, data: UpdatePropertyOptions): Promise<Property>;
+    /**
+     * Delete a property
+     */
+    deleteProperty(propertyId: string): Promise<void>;
+    /**
+     * Get all data streams for a property
+     */
+    getDataStreams(propertyId: string): Promise<DataStream[]>;
+    /**
+     * Create a new data stream
+     */
+    createDataStream(propertyId: string, options: CreateDataStreamOptions): Promise<DataStream>;
+    /**
+     * Delete a data stream
+     */
+    deleteDataStream(propertyId: string, streamId: string): Promise<void>;
+    /**
+     * Get all custom dimensions for a property
+     */
+    getCustomDimensions(propertyId: string): Promise<CustomDimension[]>;
+    /**
+     * Create a new custom dimension
+     */
+    createCustomDimension(propertyId: string, options: CustomDimensionOptions): Promise<CustomDimension>;
+    /**
+     * Archive (soft-delete) a custom dimension
+     */
+    archiveCustomDimension(propertyId: string, dimensionId: string): Promise<void>;
+    /**
+     * Get all custom metrics for a property
+     */
+    getCustomMetrics(propertyId: string): Promise<CustomMetric[]>;
+    /**
+     * Create a new custom metric
+     */
+    createCustomMetric(propertyId: string, options: CustomMetricOptions): Promise<CustomMetric>;
+    /**
+     * Archive (soft-delete) a custom metric
+     */
+    archiveCustomMetric(propertyId: string, metricId: string): Promise<void>;
+    /**
+     * Get all key events for a property
+     */
+    getKeyEvents(propertyId: string): Promise<KeyEvent[]>;
+    /**
+     * Create a new key event
+     */
+    createKeyEvent(propertyId: string, options: KeyEventOptions): Promise<KeyEvent>;
+    /**
+     * Delete a key event
+     */
+    deleteKeyEvent(propertyId: string, eventId: string): Promise<void>;
+    /**
+     * Run a report query
+     */
+    runReport(propertyId: string, options: ReportOptions): Promise<ReportResult>;
+    /**
+     * Run a realtime report query
+     */
+    runRealtimeReport(propertyId: string, options?: RealtimeReportOptions): Promise<ReportResult>;
+    /**
+     * Get available metrics for a property
+     */
+    getMetrics(propertyId: string): Promise<MetricMetadata[]>;
+    /**
+     * Get available dimensions for a property
+     */
+    getDimensions(propertyId: string): Promise<DimensionMetadata[]>;
+    /**
+     * Track a single event
+     */
+    track(event: TrackEvent): Promise<void>;
+    /**
+     * Track a pageview
+     */
+    trackPageview(pageview: PageviewEvent): Promise<void>;
+    /**
+     * Track multiple events in a batch
+     */
+    trackBatch(events: TrackEvent[]): Promise<void>;
+    /**
+     * Identify a user with traits
+     */
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void>;
+    /**
+     * Generate a tracking snippet for embedding in HTML
+     */
+    generateTrackingSnippet(propertyId: string, options?: SnippetOptions): TrackingSnippet;
+    /**
+     * Generate a configuration object for programmatic use
+     */
+    generateConfig(propertyId: string, options?: ConfigOptions): Record<string, unknown>;
+    /**
+     * Get provider capabilities
+     */
+    getCapabilities(): Promise<AnalyticsCapabilities>;
+    /**
+     * Provisioning admin operations exposed by providers that support them.
+     *
+     * Optional. Providers that don't support tenant/site/user provisioning leave
+     * this undefined. Implementations should mirror the pattern used by
+     * `@happyvertical/ai`'s `AIAdminInterface`.
+     */
+    admin?: AnalyticsAdminInterface;
+}
+/**
+ * Site descriptor returned by admin providers.
+ */
+export interface AnalyticsSite {
+    /**
+     * Provider site ID. For Matomo this is the numeric `idSite` as a string.
+     */
+    id: string;
+    /**
+     * Human-readable site name as stored by the provider.
+     */
+    name: string;
+    /**
+     * Primary URL or domain for the site.
+     */
+    url?: string;
+    /**
+     * Site timezone (e.g. `America/Edmonton`).
+     */
+    timezone?: string;
+    /**
+     * Currency code where applicable (e.g. `CAD`).
+     */
+    currency?: string;
+    /**
+     * Tenant identifier this site is associated with, when supplied at create time.
+     */
+    tenantId?: string;
+    /**
+     * Provider that owns this site descriptor.
+     */
+    provider: string;
+    /**
+     * Raw provider response.
+     */
+    raw?: unknown;
+}
+/**
+ * Options for creating a site.
+ */
+export interface CreateAnalyticsSiteOptions {
+    /**
+     * Human-readable site name.
+     */
+    name: string;
+    /**
+     * Site URL(s). At least one is required for Matomo.
+     */
+    urls: string[];
+    /**
+     * Site timezone (IANA, e.g. `America/Edmonton`). Defaults to provider default.
+     */
+    timezone?: string;
+    /**
+     * Currency code. Defaults to provider default.
+     */
+    currency?: string;
+    /**
+     * Optional tenant identifier to associate with this site.
+     */
+    tenantId?: string;
+    /**
+     * Provider-specific request body overrides.
+     */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Options for updating an existing site.
+ *
+ * Reuses the `createSite` field shapes — every field except `siteId` is
+ * optional, and omitted fields are left unchanged on the provider (partial
+ * update).
+ */
+export interface UpdateAnalyticsSiteOptions extends Partial<CreateAnalyticsSiteOptions> {
+    /**
+     * Provider site ID of the site to update. For Matomo this is the numeric
+     * `idSite` as a string.
+     */
+    siteId: string;
+}
+/**
+ * User access role assignable to an analytics site.
+ */
+export type AnalyticsAccessRole = 'noaccess' | 'view' | 'write' | 'admin';
+/**
+ * Analytics user descriptor returned by admin providers.
+ */
+export interface AnalyticsUser {
+    /**
+     * Login or username used to authenticate the user.
+     */
+    login: string;
+    /**
+     * Email address recorded for the user.
+     */
+    email?: string;
+    /**
+     * Tenant identifier this user is associated with, when supplied at create time.
+     */
+    tenantId?: string;
+    /**
+     * Whether the user has been granted super-user access.
+     */
+    isSuperUser?: boolean;
+    /**
+     * Provider that owns this user descriptor.
+     */
+    provider: string;
+    /**
+     * Raw provider response.
+     */
+    raw?: unknown;
+}
+/**
+ * Options for creating a user.
+ */
+export interface CreateAnalyticsUserOptions {
+    /**
+     * Login or username for the new user.
+     */
+    login: string;
+    /**
+     * Email address for the new user.
+     */
+    email: string;
+    /**
+     * Initial password. Implementations may generate one if omitted, but should
+     * surface it on the returned user. For Matomo the password is required.
+     */
+    password?: string;
+    /**
+     * Optional tenant identifier to associate with this user (stored in
+     * provider metadata where supported).
+     */
+    tenantId?: string;
+    /**
+     * Provider-specific request body overrides.
+     */
+    raw?: Record<string, unknown>;
+}
+/**
+ * Options for granting site access to a user.
+ */
+export interface SetUserAccessOptions {
+    /**
+     * Login or username to grant access to.
+     */
+    login: string;
+    /**
+     * Access level to grant.
+     */
+    access: AnalyticsAccessRole;
+    /**
+     * Site IDs the access applies to.
+     */
+    siteIds: string[];
+}
+/**
+ * Options for verifying that a user has sufficient access to a site.
+ */
+export interface VerifyUserSiteAccessOptions {
+    /**
+     * Login or username to inspect.
+     */
+    login: string;
+    /**
+     * Site ID the user should be able to access.
+     */
+    siteId: string;
+    /**
+     * Minimum required access. Defaults to `view`.
+     */
+    minimumAccess?: AnalyticsAccessRole;
+}
+/**
+ * Options for verifying that a token can read a site.
+ */
+export interface VerifyTokenSiteAccessOptions {
+    /**
+     * Token to probe. This is the token under test, not necessarily the admin
+     * token used by the provider instance.
+     */
+    tokenAuth: string;
+    /**
+     * Site ID the token should be able to read.
+     */
+    siteId: string;
+}
+/**
+ * Result returned by access-verification helpers.
+ */
+export interface AnalyticsAccessVerificationResult {
+    /**
+     * Whether the requested access check passed.
+     */
+    ok: boolean;
+    /**
+     * Provider that performed the check.
+     */
+    provider: string;
+    /**
+     * Login that was inspected, when the check targets a user.
+     */
+    login?: string;
+    /**
+     * Site ID that was inspected.
+     */
+    siteId: string;
+    /**
+     * Observed access level. Token probes report `view` when the token can read
+     * the site and `noaccess` when it cannot.
+     */
+    access?: AnalyticsAccessRole;
+    /**
+     * Required access level used by the check.
+     */
+    requiredAccess?: AnalyticsAccessRole;
+    /**
+     * Failure reason when `ok` is false.
+     */
+    error?: string;
+    /**
+     * Provider-specific failure code when `ok` is false.
+     */
+    errorCode?: string;
+    /**
+     * Raw provider response. This is intended for debugging and may include more
+     * provider data than the specific access check asked for; avoid logging it
+     * verbatim in application logs.
+     */
+    raw?: unknown;
+}
+/**
+ * Options for minting a per-user auth token scoped to a user's permissions.
+ */
+export interface MintUserTokenOptions {
+    /**
+     * Login or username to mint the token for.
+     */
+    login: string;
+    /**
+     * Description of the token (where supported).
+     */
+    description?: string;
+    /**
+     * The target user's password. Matomo's `createAppSpecificTokenAuth`
+     * confirms the *target* user's password (not the caller's) — this prevents
+     * a stolen super-user token from minting tokens for arbitrary other users.
+     *
+     * Other providers may not need this; it's optional in the shared interface
+     * but Matomo will throw without it.
+     */
+    passwordConfirmation?: string;
+}
+/**
+ * Auth token descriptor returned by admin providers.
+ */
+export interface AnalyticsUserToken {
+    /**
+     * The token value. Show-once for most providers; not stored in plaintext on
+     * the provider side.
+     */
+    token: string;
+    /**
+     * Login the token belongs to.
+     */
+    login: string;
+    /**
+     * Description recorded on the provider.
+     */
+    description?: string;
+    /**
+     * Provider that owns this token descriptor.
+     */
+    provider: string;
+    /**
+     * Raw provider response.
+     */
+    raw?: unknown;
+}
+/**
+ * Result of a provider health probe.
+ */
+export interface AnalyticsHealthResult {
+    /**
+     * Whether the probe was able to reach the provider AND complete an authed
+     * round-trip (if the probe is authed).
+     */
+    ok: boolean;
+    /**
+     * Provider version string, when available.
+     */
+    version?: string;
+    /**
+     * Failure reason when `ok` is false.
+     */
+    error?: string;
+}
+/**
+ * Admin operations exposed by analytics providers that support provisioning.
+ *
+ * Mirrors the shape of `@happyvertical/ai`'s `AIAdminInterface`. Methods that a
+ * particular provider can't support (e.g. `mintUserToken` against GA4) are left
+ * out of that provider's admin object — callers should feature-check via
+ * `typeof admin.mintUserToken === 'function'`.
+ *
+ * Because that feature-check idiom typically narrows a method into a local
+ * (`const fn = admin.mintUserToken; if (fn) await fn(...)`), implementations
+ * MUST keep these methods detachment-safe — i.e. bind them to the instance so a
+ * detached/destructured reference still carries `this`. See `MatomoAdmin`'s
+ * constructor for the reference implementation (https://github.com/happyvertical/sdk/issues/1043).
+ */
+export interface AnalyticsAdminInterface {
+    /**
+     * Create a site/property for a tenant.
+     */
+    createSite(options: CreateAnalyticsSiteOptions): Promise<AnalyticsSite>;
+    /**
+     * List all sites visible to the calling token.
+     */
+    listSites(): Promise<AnalyticsSite[]>;
+    /**
+     * Look up a site by id. Resolves to undefined when the site does not exist.
+     */
+    getSite(siteId: string): Promise<AnalyticsSite | undefined>;
+    /**
+     * Update an existing site in place. Optional capability — partial update:
+     * only the fields supplied in the options change on the provider.
+     *
+     * Implementations should resolve to the post-update site as read back from
+     * the provider, normalized the same way `createSite`'s result is.
+     */
+    updateSite?(options: UpdateAnalyticsSiteOptions): Promise<AnalyticsSite>;
+    /**
+     * Delete a site.
+     */
+    deleteSite(siteId: string): Promise<void>;
+    /**
+     * Create a user.
+     */
+    createUser?(options: CreateAnalyticsUserOptions): Promise<AnalyticsUser>;
+    /**
+     * Look up a user by login. Resolves to undefined when the user does not exist.
+     */
+    getUser?(login: string): Promise<AnalyticsUser | undefined>;
+    /**
+     * Delete a user.
+     */
+    deleteUser?(login: string): Promise<void>;
+    /**
+     * Grant a user access to one or more sites at the given role.
+     */
+    setUserAccess?(options: SetUserAccessOptions): Promise<void>;
+    /**
+     * Verify that a user has at least the requested access to a site.
+     */
+    verifyUserSiteAccess?(options: VerifyUserSiteAccessOptions): Promise<AnalyticsAccessVerificationResult>;
+    /**
+     * Verify that a token can read a site.
+     */
+    verifyTokenSiteAccess?(options: VerifyTokenSiteAccessOptions): Promise<AnalyticsAccessVerificationResult>;
+    /**
+     * Mint a per-user auth token scoped to that user's existing permissions.
+     *
+     * The returned token is shown-once on most providers — implementations are
+     * expected to return the live value in the response and not refetch it.
+     */
+    mintUserToken?(options: MintUserTokenOptions): Promise<AnalyticsUserToken>;
+    /**
+     * Probe provider reachability and auth. Always available — providers that
+     * lack a public health endpoint should make a cheap authed call instead.
+     */
+    health(): Promise<AnalyticsHealthResult>;
+}
+/**
+ * Base error class for analytics operations
+ */
+export declare class AnalyticsError extends Error {
+    code: string;
+    provider?: string | undefined;
+    propertyId?: string | undefined;
+    constructor(message: string, code: string, provider?: string | undefined, propertyId?: string | undefined);
+}
+/**
+ * Authentication failed
+ */
+export declare class AuthenticationError extends AnalyticsError {
+    constructor(provider?: string, message?: string, code?: string);
+}
+/**
+ * Rate limit exceeded
+ */
+export declare class RateLimitError extends AnalyticsError {
+    retryAfter?: number;
+    constructor(provider?: string, retryAfter?: number);
+}
+/**
+ * Property not found
+ */
+export declare class PropertyNotFoundError extends AnalyticsError {
+    constructor(propertyId: string, provider?: string);
+}
+/**
+ * Invalid dimension specified
+ */
+export declare class InvalidDimensionError extends AnalyticsError {
+    dimension: string;
+    constructor(dimension: string, provider?: string);
+}
+/**
+ * Invalid metric specified
+ */
+export declare class InvalidMetricError extends AnalyticsError {
+    metric: string;
+    constructor(metric: string, provider?: string);
+}
+/**
+ * Quota exceeded
+ */
+export declare class QuotaExceededError extends AnalyticsError {
+    quotaType?: string;
+    constructor(provider?: string, quotaType?: string);
+}
+/**
+ * Feature not supported by this provider
+ */
+export declare class NotSupportedError extends AnalyticsError {
+    feature: string;
+    constructor(feature: string, provider?: string);
+}
+//# sourceMappingURL=types.d.ts.map