@appwrite.io/console 18.3.0-rc.1 → 18.3.0

package/types/services/analytics-tracking.d.ts

@@ -1,211 +0,0 @@
-/**
- * Analytics auto-tracking helpers.
- *
- * These are hand-written companions to the generated `Analytics` service.
- * The generated service exposes `createEvent(params)` for arbitrary events;
- * this module wires up common auto-tracking behaviours (pageviews, outbound
- * links, downloads, scroll depth, active engagement) on top of it.
- *
- * The tracking helpers accept a plain event-emitter function so they do not
- * hard-couple to the generated `Analytics` class. The emitter adapts this
- * module's option shape to `createEvent`: `url` is required there, and `props`
- * is a flat alternating key/value list rather than an object.
- *
- * ```ts
- * const analytics = new Analytics(client);
- * const tracking = new AnalyticsTracking(
- *     (name, options) => analytics.createEvent({
- *         propertyId: options?.propertyId ?? '<PROPERTY_ID>',
- *         name,
- *         url: options?.url ?? window.location.href,
- *         referrer: options?.referrer,
- *         scrollDepth: options?.scrollDepth,
- *         engagementTime: options?.engagementTime,
- *         props: Object.entries(options?.props ?? {}).flatMap(
- *             ([key, value]) => [key, String(value)],
- *         ),
- *     }),
- *     { propertyId: '<PROPERTY_ID>' }
- * );
- * tracking.enableAllAutoTracking();
- * ```
- *
- * `propertyId` is optional: when set it is merged into the options of every
- * emitted event, so an emitter that forwards `options.propertyId` (as above)
- * picks it up instead of every caller hand-rolling it into the closure.
- * Per-event `propertyId` always wins over the configured default.
- *
- * All helpers respect `navigator.doNotTrack === '1'` by default; opt out with
- * `respectDoNotTrack: false` in the constructor options.
- *
- * Engagement time follows Plausible's model: rather than one total at unload,
- * a delta is emitted at every natural checkpoint of the visit (tab hidden, SPA
- * route change, unload). See `enableAutoEngagementTime` for details.
- *
- * Auto-emitted event names follow `snake_case` + lowercase (`pageview`,
- * `outbound_link`, `file_download`, `screen_view`, etc.). Any prop keys use
- * camelCase to match the endpoint's parameter naming. Callers can pass any
- * custom event name; the auto-track methods only own the events they emit
- * themselves.
- */
-export type AnalyticsEventOptions = {
-    props?: Record<string, unknown>;
-    url?: string;
-    referrer?: string;
-    propertyId?: string;
-    scrollDepth?: number;
-    engagementTime?: number;
-};
-export type AnalyticsEventEmitter = (name: string, options?: AnalyticsEventOptions) => unknown;
-export type AnalyticsTrackingOptions = {
-    /**
-     * When true (default) the tracker becomes a no-op if `navigator.doNotTrack`
-     * is set to `'1'`. Set to false to always fire regardless of the DNT signal.
-     */
-    respectDoNotTrack?: boolean;
-    /**
-     * Analytics property (or snippet) ID to attach to every emitted event.
-     * Optional — omit it when the emitter closure already supplies one. A
-     * `propertyId` passed on an individual event takes precedence.
-     */
-    propertyId?: string;
-};
-export type OutboundTrackingOptions = {
-    /**
-     * When true, links pointing at the current host's subdomains are treated
-     * as outbound. Defaults to false (subdomains are same-origin for tracking).
-     */
-    includeSubdomains?: boolean;
-};
-export type DownloadTrackingOptions = {
-    /**
-     * File extensions (without the leading dot) that mark an anchor as a
-     * download. Defaults cover the common set.
-     */
-    extensions?: string[];
-};
-export declare class AnalyticsTracking {
-    private readonly emit;
-    private readonly respectDoNotTrack;
-    private readonly propertyId?;
-    private pageviewCleanups;
-    private outboundCleanup?;
-    private downloadCleanup?;
-    private scrollCleanups;
-    private engagementCleanups;
-    private currentPath?;
-    private maxScrollDepth;
-    private scrollTicking;
-    private lastScrollReport;
-    private engagementStart;
-    private engagementAccumulatedMs;
-    private engagementActive;
-    constructor(emit: AnalyticsEventEmitter, options?: AnalyticsTrackingOptions);
-    /**
-     * Enable the opinionated default auto-tracking set: pageviews, outbound
-     * links, scroll depth and active engagement time. Downloads must be opted
-     * into separately via `enableAutoDownloadTracking()` because the extension
-     * list is application-specific.
-     */
-    enableAllAutoTracking(): void;
-    /**
-     * Track an event manually. Respects the DNT setting and swallows emitter
-     * exceptions so tracking failures never surface to the host page.
-     */
-    track(name: string, options?: AnalyticsEventOptions): void;
-    /**
-     * Convenience wrapper for pageview-shaped events.
-     */
-    pageview(url?: string, referrer?: string): void;
-    /**
-     * Enable SPA-aware pageview tracking. Fires an initial pageview on
-     * enable, then again on every `pushState`, `replaceState`, `popstate`
-     * or hashchange. Idempotent — repeat calls no-op.
-     */
-    enableAutoPageviews(): void;
-    /**
-     * Disable auto-pageview tracking installed by `enableAutoPageviews`.
-     * Safe to call when auto-pageviews were never enabled.
-     */
-    disableAutoPageviews(): void;
-    /**
-     * Enable click-based outbound link tracking. Detects anchor clicks that
-     * navigate to a different origin and fires an `outbound_link` event
-     * (with `hostname` and `href` props) before the browser navigates.
-     */
-    enableAutoOutboundTracking(options?: OutboundTrackingOptions): void;
-    /**
-     * Disable outbound-link tracking installed by `enableAutoOutboundTracking`.
-     * Safe to call when auto-outbound was never enabled.
-     */
-    disableAutoOutboundTracking(): void;
-    /**
-     * Enable click-based download tracking. Detects anchor clicks that point
-     * at a file whose extension appears in the configured list and fires a
-     * `file_download` event with `filename`, `extension` and `href` props.
-     */
-    enableAutoDownloadTracking(options?: DownloadTrackingOptions): void;
-    /**
-     * Disable file-download tracking installed by `enableAutoDownloadTracking`.
-     * Safe to call when auto-download was never enabled.
-     */
-    disableAutoDownloadTracking(): void;
-    /**
-     * Enable passive scroll-depth tracking. Records the maximum percent of the
-     * document scrolled and reports it on `beforeunload` and on SPA route
-     * changes. Uses a throttled passive listener so it is safe on hot paths.
-     */
-    enableAutoScrollDepth(): void;
-    /**
-     * Disable scroll-depth tracking installed by `enableAutoScrollDepth`. Safe
-     * to call when auto-scroll-depth was never enabled. Any accumulated depth
-     * for the current page is dropped.
-     */
-    disableAutoScrollDepth(): void;
-    /**
-     * Enable active engagement-time tracking. Counts time the tab is visible
-     * and uses `visibilitychange` to exclude background time.
-     *
-     * Delivery follows Plausible's model rather than a single total at the
-     * end of the visit: an `engagement_time` event is emitted at every natural
-     * checkpoint — the tab going hidden, an SPA route change, and finally
-     * `beforeunload`/`pagehide`. Unload is kept only as a best-effort last
-     * flush; it is the least reliable moment to send anything (browsers
-     * routinely cancel in-flight requests there, and `sendBeacon` cannot set
-     * the `X-Appwrite-Project` header the endpoint requires), so it must never
-     * be the only delivery.
-     *
-     * Each event carries a **delta** — the seconds accrued since the previous
-     * flush, not a running total — so the values are additive per session and
-     * a lost event costs only its own slice.
-     *
-     * There is deliberately no periodic ping. The cadence is driven by
-     * navigation and tab switches, so request volume tracks what the visitor
-     * actually does instead of multiplying with time on page.
-     */
-    enableAutoEngagementTime(): void;
-    /**
-     * Disable engagement-time tracking installed by `enableAutoEngagementTime`.
-     * Safe to call when auto-engagement was never enabled. Any accumulated
-     * engagement time is dropped without being emitted.
-     */
-    disableAutoEngagementTime(): void;
-    /**
-     * Merge the configured `propertyId` into an event's options. Returns the
-     * caller's object untouched when no default is configured (or the event
-     * already carries one), so emitters written against the pre-`propertyId`
-     * shape keep receiving exactly what they received before.
-     */
-    private withPropertyId;
-    private canTrack;
-    private currentPageUrl;
-    private findAnchor;
-    private parseUrl;
-    private isExternal;
-    private rootDomain;
-    private computeScrollDepth;
-    private flushScrollDepth;
-    private startEngagement;
-    private pauseEngagement;
-    private flushEngagement;
-}

package/types/services/analytics.d.ts

@@ -1,254 +0,0 @@
-import { Client } from '../client';
-import type { Models } from '../models';
-import { AnalyticsInterval } from '../enums/analytics-interval';
-import { AnalyticsDimension } from '../enums/analytics-dimension';
-export declare class Analytics {
-    client: Client;
-    constructor(client: Client);
-    /**
-     * List analytics properties for the current project.
-     *
-     * @param {string[]} params.queries - Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, domain, timezone, enabled, public, snippetId
-     * @param {string} params.search - Search term to filter your list results. Matches the property ID, name and domain. Max length: 256 chars.
-     * @param {boolean} params.total - When set to false, the total count returned will be 0 and will not be calculated.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsPropertyList>}
-     */
-    listProperties(params?: {
-        queries?: string[];
-        search?: string;
-        total?: boolean;
-    }): Promise<Models.AnalyticsPropertyList>;
-    /**
-     * List analytics properties for the current project.
-     *
-     * @param {string[]} queries - Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, domain, timezone, enabled, public, snippetId
-     * @param {string} search - Search term to filter your list results. Matches the property ID, name and domain. Max length: 256 chars.
-     * @param {boolean} total - When set to false, the total count returned will be 0 and will not be calculated.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsPropertyList>}
-     * @deprecated Use the object parameter style method for a better developer experience.
-     */
-    listProperties(queries?: string[], search?: string, total?: boolean): Promise<Models.AnalyticsPropertyList>;
-    /**
-     * Create a new analytics property to track a website or application.
-     *
-     * @param {string} params.propertyId - Unique ID. Choose a custom ID or generate a random ID with `ID.unique()`. Max length is 36 chars.
-     * @param {string} params.name - Human-readable name for this property.
-     * @param {string} params.domain - Primary domain to track (e.g. example.com). Optional for native apps.
-     * @param {string} params.timezone - IANA timezone used for daily boundaries.
-     * @param {boolean} params.enabled - Whether tracking is enabled.
-     * @param {boolean} params.xpublic - Whether stats are publicly viewable.
-     * @param {string[]} params.allowedOrigins - Allowed origins for tracking. Use ["*"] to allow all.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsProperty>}
-     */
-    createProperty(params: {
-        propertyId: string;
-        name: string;
-        domain?: string;
-        timezone?: string;
-        enabled?: boolean;
-        xpublic?: boolean;
-        allowedOrigins?: string[];
-    }): Promise<Models.AnalyticsProperty>;
-    /**
-     * Create a new analytics property to track a website or application.
-     *
-     * @param {string} propertyId - Unique ID. Choose a custom ID or generate a random ID with `ID.unique()`. Max length is 36 chars.
-     * @param {string} name - Human-readable name for this property.
-     * @param {string} domain - Primary domain to track (e.g. example.com). Optional for native apps.
-     * @param {string} timezone - IANA timezone used for daily boundaries.
-     * @param {boolean} enabled - Whether tracking is enabled.
-     * @param {boolean} xpublic - Whether stats are publicly viewable.
-     * @param {string[]} allowedOrigins - Allowed origins for tracking. Use ["*"] to allow all.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsProperty>}
-     * @deprecated Use the object parameter style method for a better developer experience.
-     */
-    createProperty(propertyId: string, name: string, domain?: string, timezone?: string, enabled?: boolean, xpublic?: boolean, allowedOrigins?: string[]): Promise<Models.AnalyticsProperty>;
-    /**
-     * Get an analytics property by ID.
-     *
-     * @param {string} params.propertyId - Analytics property unique ID.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsProperty>}
-     */
-    getProperty(params: {
-        propertyId: string;
-    }): Promise<Models.AnalyticsProperty>;
-    /**
-     * Get an analytics property by ID.
-     *
-     * @param {string} propertyId - Analytics property unique ID.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsProperty>}
-     * @deprecated Use the object parameter style method for a better developer experience.
-     */
-    getProperty(propertyId: string): Promise<Models.AnalyticsProperty>;
-    /**
-     * Update an analytics property. Only the attributes you pass are changed; omitted attributes keep their current value.
-     *
-     * @param {string} params.propertyId - Analytics property unique ID.
-     * @param {string} params.name - Human-readable name for this property.
-     * @param {string} params.domain - Primary domain to track (e.g. example.com). Pass an empty string to clear it.
-     * @param {string} params.timezone - IANA timezone used for daily boundaries.
-     * @param {boolean} params.enabled - Whether tracking is enabled.
-     * @param {boolean} params.xpublic - Whether stats are publicly viewable.
-     * @param {string[]} params.allowedOrigins - Allowed origins for tracking. Use ["*"] to allow all.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsProperty>}
-     */
-    updateProperty(params: {
-        propertyId: string;
-        name?: string;
-        domain?: string;
-        timezone?: string;
-        enabled?: boolean;
-        xpublic?: boolean;
-        allowedOrigins?: string[];
-    }): Promise<Models.AnalyticsProperty>;
-    /**
-     * Update an analytics property. Only the attributes you pass are changed; omitted attributes keep their current value.
-     *
-     * @param {string} propertyId - Analytics property unique ID.
-     * @param {string} name - Human-readable name for this property.
-     * @param {string} domain - Primary domain to track (e.g. example.com). Pass an empty string to clear it.
-     * @param {string} timezone - IANA timezone used for daily boundaries.
-     * @param {boolean} enabled - Whether tracking is enabled.
-     * @param {boolean} xpublic - Whether stats are publicly viewable.
-     * @param {string[]} allowedOrigins - Allowed origins for tracking. Use ["*"] to allow all.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsProperty>}
-     * @deprecated Use the object parameter style method for a better developer experience.
-     */
-    updateProperty(propertyId: string, name?: string, domain?: string, timezone?: string, enabled?: boolean, xpublic?: boolean, allowedOrigins?: string[]): Promise<Models.AnalyticsProperty>;
-    /**
-     * Delete an analytics property along with every event and session collected for it. This cannot be undone.
-     *
-     * @param {string} params.propertyId - Analytics property unique ID.
-     * @throws {AppwriteException}
-     * @returns {Promise<{}>}
-     */
-    deleteProperty(params: {
-        propertyId: string;
-    }): Promise<{}>;
-    /**
-     * Delete an analytics property along with every event and session collected for it. This cannot be undone.
-     *
-     * @param {string} propertyId - Analytics property unique ID.
-     * @throws {AppwriteException}
-     * @returns {Promise<{}>}
-     * @deprecated Use the object parameter style method for a better developer experience.
-     */
-    deleteProperty(propertyId: string): Promise<{}>;
-    /**
-     * Send a tracking event from a browser, native app, or server-side SDK.
-     *
-     * @param {string} params.propertyId - Analytics property ID or snippet ID identifying the property.
-     * @param {string} params.name - Event name. "pageview" is just a conventional event name; events are not modeled specially.
-     * @param {string} params.url - Full page URL or screen identifier.
-     * @param {string} params.domain - Hostname (e.g. example.com).
-     * @param {string} params.referrer - Referrer URL.
-     * @param {number} params.screenWidth - Viewport width in CSS pixels.
-     * @param {string} params.sessionHash - Optional session hash (provided by SDK).
-     * @param {number} params.scrollDepth - Scroll depth percentage 0-100.
-     * @param {number} params.engagementTime - Engagement time in seconds, 0-4294967295.
-     * @param {string[]} params.props - Custom string properties as a flat key=value list (max 32 entries, alternating key,value).
-     * @param {string} params.userId - Override user ID. Requires API-key auth with analytics.write scope.
-     * @param {string} params.ip - Override IP address. Requires API-key auth with analytics.write scope.
-     * @param {string} params.userAgent - Override user agent. Requires API-key auth with analytics.write scope.
-     * @throws {AppwriteException}
-     * @returns {Promise<{}>}
-     */
-    createEvent(params: {
-        propertyId: string;
-        name: string;
-        url: string;
-        domain?: string;
-        referrer?: string;
-        screenWidth?: number;
-        sessionHash?: string;
-        scrollDepth?: number;
-        engagementTime?: number;
-        props?: string[];
-        userId?: string;
-        ip?: string;
-        userAgent?: string;
-    }): Promise<{}>;
-    /**
-     * Send a tracking event from a browser, native app, or server-side SDK.
-     *
-     * @param {string} propertyId - Analytics property ID or snippet ID identifying the property.
-     * @param {string} name - Event name. "pageview" is just a conventional event name; events are not modeled specially.
-     * @param {string} url - Full page URL or screen identifier.
-     * @param {string} domain - Hostname (e.g. example.com).
-     * @param {string} referrer - Referrer URL.
-     * @param {number} screenWidth - Viewport width in CSS pixels.
-     * @param {string} sessionHash - Optional session hash (provided by SDK).
-     * @param {number} scrollDepth - Scroll depth percentage 0-100.
-     * @param {number} engagementTime - Engagement time in seconds, 0-4294967295.
-     * @param {string[]} props - Custom string properties as a flat key=value list (max 32 entries, alternating key,value).
-     * @param {string} userId - Override user ID. Requires API-key auth with analytics.write scope.
-     * @param {string} ip - Override IP address. Requires API-key auth with analytics.write scope.
-     * @param {string} userAgent - Override user agent. Requires API-key auth with analytics.write scope.
-     * @throws {AppwriteException}
-     * @returns {Promise<{}>}
-     * @deprecated Use the object parameter style method for a better developer experience.
-     */
-    createEvent(propertyId: string, name: string, url: string, domain?: string, referrer?: string, screenWidth?: number, sessionHash?: string, scrollDepth?: number, engagementTime?: number, props?: string[], userId?: string, ip?: string, userAgent?: string): Promise<{}>;
-    /**
-     * Read analytics metrics (visitors, sessions, pageviews, events, bounceRate, …) for a property over a date range.
-     *
-     * **Three response shapes**, chosen by `dimensions[]` and `interval`:
-     * - Neither: one row aggregating the whole window, with `value` and `date` null. Only this shape carries `pageviews`, `visits`, `bounceRate`, `visitDuration`, `viewsPerVisit`, `scrollDepth` and `engagementTime`.
-     * - `dimensions[]`: one row per dimension value, ranked by visitors, with `value` set and `date` null.
-     * - `interval`: one row per time bucket in chronological order, with `date` set and `value` null.
-     *
-     * Combining `dimensions[]` with `interval` is not supported yet. `queries[]` filters the underlying events using standard Utopia query syntax.
-     *
-     * @param {string} params.propertyId - Analytics property unique ID.
-     * @param {string[]} params.queries - Up to 10 filter queries in Utopia syntax. Allowed attributes: country, region, city, browser, operatingSystem, device, screenSize, referrerSource, channel, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, page, hostname, botName, botCategory, eventName. page, eventName are only accepted alongside `interval`, or with a breakdown on a dimension other than entryPage, exitPage. Allowed methods: equal, notEqual, contains, startsWith, endsWith. Example: `queries[]=equal("country", ["US"])`.
-     * @param {AnalyticsInterval} params.interval - Time bucket size. Omit (null) for a flat aggregate over the whole window. Allowed: 1h, 1d, 1w, 1m.
-     * @param {AnalyticsDimension[]} params.dimensions - Dimension to break the metrics down by. One at most for now; the parameter is a list so that cap can be raised without a breaking change. Allowed: country, region, city, browser, operatingSystem, device, screenSize, referrerSource, channel, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, page, hostname, entryPage, exitPage, trafficType, botName, botCategory, eventName.
-     * @param {string} params.dateRange - Date range shorthand (e.g. 7d, 30d). Ignored for any bound you supply explicitly via startAt/endAt.
-     * @param {string} params.startAt - Explicit window start in ISO 8601. Defaults to endAt minus dateRange.
-     * @param {string} params.endAt - Explicit window end in ISO 8601. Defaults to the current time.
-     * @param {number} params.limit - Maximum number of ranked values to return.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsMetricList>}
-     */
-    listMetrics(params: {
-        propertyId: string;
-        queries?: string[];
-        interval?: AnalyticsInterval;
-        dimensions?: AnalyticsDimension[];
-        dateRange?: string;
-        startAt?: string;
-        endAt?: string;
-        limit?: number;
-    }): Promise<Models.AnalyticsMetricList>;
-    /**
-     * Read analytics metrics (visitors, sessions, pageviews, events, bounceRate, …) for a property over a date range.
-     *
-     * **Three response shapes**, chosen by `dimensions[]` and `interval`:
-     * - Neither: one row aggregating the whole window, with `value` and `date` null. Only this shape carries `pageviews`, `visits`, `bounceRate`, `visitDuration`, `viewsPerVisit`, `scrollDepth` and `engagementTime`.
-     * - `dimensions[]`: one row per dimension value, ranked by visitors, with `value` set and `date` null.
-     * - `interval`: one row per time bucket in chronological order, with `date` set and `value` null.
-     *
-     * Combining `dimensions[]` with `interval` is not supported yet. `queries[]` filters the underlying events using standard Utopia query syntax.
-     *
-     * @param {string} propertyId - Analytics property unique ID.
-     * @param {string[]} queries - Up to 10 filter queries in Utopia syntax. Allowed attributes: country, region, city, browser, operatingSystem, device, screenSize, referrerSource, channel, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, page, hostname, botName, botCategory, eventName. page, eventName are only accepted alongside `interval`, or with a breakdown on a dimension other than entryPage, exitPage. Allowed methods: equal, notEqual, contains, startsWith, endsWith. Example: `queries[]=equal("country", ["US"])`.
-     * @param {AnalyticsInterval} interval - Time bucket size. Omit (null) for a flat aggregate over the whole window. Allowed: 1h, 1d, 1w, 1m.
-     * @param {AnalyticsDimension[]} dimensions - Dimension to break the metrics down by. One at most for now; the parameter is a list so that cap can be raised without a breaking change. Allowed: country, region, city, browser, operatingSystem, device, screenSize, referrerSource, channel, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, page, hostname, entryPage, exitPage, trafficType, botName, botCategory, eventName.
-     * @param {string} dateRange - Date range shorthand (e.g. 7d, 30d). Ignored for any bound you supply explicitly via startAt/endAt.
-     * @param {string} startAt - Explicit window start in ISO 8601. Defaults to endAt minus dateRange.
-     * @param {string} endAt - Explicit window end in ISO 8601. Defaults to the current time.
-     * @param {number} limit - Maximum number of ranked values to return.
-     * @throws {AppwriteException}
-     * @returns {Promise<Models.AnalyticsMetricList>}
-     * @deprecated Use the object parameter style method for a better developer experience.
-     */
-    listMetrics(propertyId: string, queries?: string[], interval?: AnalyticsInterval, dimensions?: AnalyticsDimension[], dateRange?: string, startAt?: string, endAt?: string, limit?: number): Promise<Models.AnalyticsMetricList>;
-}