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

package/package.json

@@ -2,7 +2,7 @@
     "name": "@appwrite.io/console",
     "homepage": "https://appwrite.io/support",
     "description": "Appwrite is an open-source self-hosted backend server that abstracts and simplifies complex and repetitive development tasks behind a very simple REST API",
-    "version": "18.2.0",
+    "version": "18.3.0-rc.1",
     "license": "BSD-3-Clause",
     "main": "dist/cjs/sdk.js",
     "exports": {

package/types/enums/analytics-dimension.d.ts

@@ -0,0 +1,24 @@
+export declare enum AnalyticsDimension {
+    Country = "country",
+    Region = "region",
+    City = "city",
+    Browser = "browser",
+    OperatingSystem = "operatingSystem",
+    Device = "device",
+    ScreenSize = "screenSize",
+    ReferrerSource = "referrerSource",
+    Channel = "channel",
+    UtmSource = "utmSource",
+    UtmMedium = "utmMedium",
+    UtmCampaign = "utmCampaign",
+    UtmContent = "utmContent",
+    UtmTerm = "utmTerm",
+    Page = "page",
+    Hostname = "hostname",
+    EntryPage = "entryPage",
+    ExitPage = "exitPage",
+    TrafficType = "trafficType",
+    BotName = "botName",
+    BotCategory = "botCategory",
+    EventName = "eventName"
+}

package/types/enums/analytics-interval.d.ts

@@ -0,0 +1,6 @@
+export declare enum AnalyticsInterval {
+    OneHour = "1h",
+    OneDay = "1d",
+    OneWeek = "1w",
+    OneMonth = "1m"
+}

package/types/enums/project-key-scopes.d.ts

@@ -121,5 +121,7 @@ export declare enum ProjectKeyScopes {
     AppsWrite = "apps.write",
     Oauth2Read = "oauth2.read",
     Oauth2Write = "oauth2.write",
-    Oauth2Introspect = "oauth2.introspect"
+    Oauth2Introspect = "oauth2.introspect",
+    AnalyticsRead = "analytics.read",
+    AnalyticsWrite = "analytics.write"
 }

package/types/enums/proxy-rule-deployment-resource-type.d.ts

@@ -1,4 +1,5 @@
 export declare enum ProxyRuleDeploymentResourceType {
     Function = "function",
-    Site = "site"
+    Site = "site",
+    DedicatedDatabase = "dedicatedDatabase"
 }

package/types/enums/query-suggestion-resource.d.ts

@@ -88,6 +88,7 @@ export declare enum QuerySuggestionResource {
     ResourceTokens = "resourcetokens",
     Transactions = "transactions",
     TransactionLogs = "transactionlogs",
+    AnalyticsProperties = "analyticsproperties",
     DedicatedDatabases = "dedicateddatabases",
     DedicatedDatabaseConfigs = "dedicateddatabaseconfigs",
     DedicatedDatabaseRuntimes = "dedicateddatabaseruntimes",

package/types/enums/usage-event-metric.d.ts

@@ -1,4 +1,7 @@
 export declare enum UsageEventMetric {
+    AnalyticsEvents = "analytics.events",
+    AnalyticsPageviews = "analytics.pageviews",
+    AnalyticsBotsEvents = "analytics.bots.events",
     NetworkRequests = "network.requests",
     NetworkInbound = "network.inbound",
     NetworkOutbound = "network.outbound",

package/types/enums/usage-gauge-metric.d.ts

@@ -1,4 +1,5 @@
 export declare enum UsageGaugeMetric {
+    AnalyticsProperties = "analytics.properties",
     Teams = "teams",
     Users = "users",
     Messages = "messages",

package/types/index.d.ts

@@ -11,6 +11,7 @@ export { Client, Query, AppwriteException } from './client';
 export { Account } from './services/account';
 export { Activities } from './services/activities';
 export { Affiliates } from './services/affiliates';
+export { Analytics } from './services/analytics';
 export { Apps } from './services/apps';
 export { Avatars } from './services/avatars';
 export { Backups } from './services/backups';
@@ -52,9 +53,11 @@ export { Waf } from './services/waf';
 export { Webhooks } from './services/webhooks';
 export { Realtime } from './services/realtime';
 export { Push } from './services/push';
+export { AnalyticsTracking } from './services/analytics-tracking';
 export type { Models, Payload, RealtimeResponseEvent, UploadProgress, } from './client';
 export type { RealtimeSubscription } from './services/realtime';
 export type { PushMessage, PushSubscription, SubscribeOptions, MessageCallback, } from './services/push';
+export type { AnalyticsEventEmitter, AnalyticsEventOptions, AnalyticsTrackingOptions, DownloadTrackingOptions, OutboundTrackingOptions, } from './services/analytics-tracking';
 export type { QueryTypes, QueryTypesList } from './query';
 export { Permission } from './permission';
 export { Role } from './role';
@@ -67,6 +70,8 @@ export { AuthenticatorType } from './enums/authenticator-type';
 export { AuthenticationFactor } from './enums/authentication-factor';
 export { IdTokenProvider } from './enums/id-token-provider';
 export { OAuthProvider } from './enums/o-auth-provider';
+export { AnalyticsInterval } from './enums/analytics-interval';
+export { AnalyticsDimension } from './enums/analytics-dimension';
 export { Browser } from './enums/browser';
 export { CreditCard } from './enums/credit-card';
 export { Flag } from './enums/flag';

package/types/models.d.ts

@@ -7448,7 +7448,7 @@ export declare namespace Models {
          */
         deploymentId: string;
         /**
-         * Type of deployment. Possible values are "function", "site". Used if rule's type is "deployment".
+         * Type of deployment resource: function, site, or dedicatedDatabase.
          */
         deploymentResourceType?: ProxyRuleDeploymentResourceType;
         /**
@@ -8904,6 +8904,117 @@ export declare namespace Models {
          */
         resources: UsageResources[];
     };
+    /**
+     * AnalyticsMetric
+     */
+    export type AnalyticsMetric = {
+        /**
+         * Dimension value this row covers. Null when no dimension was requested, empty when the dimension could not be derived for those events.
+         */
+        value?: string;
+        /**
+         * Start of the time bucket this row covers, in ISO 8601. Null when no interval was requested.
+         */
+        date?: string;
+        /**
+         * Unique visitors in the requested range.
+         */
+        visitors: number;
+        /**
+         * Unique sessions in the requested range.
+         */
+        sessions: number;
+        /**
+         * Total pageview events (events with name="pageview") in the requested range. Only the flat aggregate computes it; null on breakdown and time-series rows.
+         */
+        pageviews?: number;
+        /**
+         * Total events in the requested range.
+         */
+        events: number;
+        /**
+         * Total sessions with activity in the requested range. Only the flat aggregate computes it; null on breakdown and time-series rows.
+         */
+        visits?: number;
+        /**
+         * Share of single-event sessions, as a percentage. Only the flat aggregate computes it; null on breakdown and time-series rows.
+         */
+        bounceRate?: number;
+        /**
+         * Average session length in seconds, measured first event to last event. Single-event sessions count as 0. Only the flat aggregate computes it; null on breakdown and time-series rows.
+         */
+        visitDuration?: number;
+        /**
+         * Average pageviews per session (pageviews divided by visits). Only the flat aggregate computes it; null on breakdown and time-series rows.
+         */
+        viewsPerVisit?: number;
+        /**
+         * Average scroll depth across events, as a percentage. Only the flat aggregate computes it; null on breakdown and time-series rows.
+         */
+        scrollDepth?: number;
+        /**
+         * Average engaged time per session in seconds, counting only foreground time. Sessions that reported no engagement are excluded. Only the flat aggregate computes it; null on breakdown and time-series rows.
+         */
+        engagementTime?: number;
+    };
+    /**
+     * AnalyticsMetricList
+     */
+    export type AnalyticsMetricList = {
+        /**
+         * Total number of metric rows returned.
+         */
+        total: number;
+        /**
+         * Metric rows: one per time bucket, one per dimension value, or a single row for the flat aggregate.
+         */
+        metrics: AnalyticsMetric[];
+    };
+    /**
+     * AnalyticsProperty
+     */
+    export type AnalyticsProperty = {
+        /**
+         * Analytics property ID.
+         */
+        $id: string;
+        /**
+         * Property creation date in ISO 8601 format.
+         */
+        $createdAt: string;
+        /**
+         * Property update date in ISO 8601 format.
+         */
+        $updatedAt: string;
+        /**
+         * Human-readable name of the tracked website or application.
+         */
+        name: string;
+        /**
+         * Primary domain being tracked (e.g. example.com). May be empty for native apps.
+         */
+        domain: string;
+        /**
+         * IANA timezone used to define the daily boundary for stats.
+         */
+        timezone: string;
+        /**
+         * Whether tracking is currently active.
+         */
+        enabled: boolean;
+        /**
+         * Whether stats for this property are publicly viewable.
+         */
+        public: boolean;
+        /**
+         * List of origins allowed to send tracking events. Use ["*"] to allow all.
+         */
+        allowedOrigins: string[];
+        /**
+         * Unique identifier for the tracking script snippet.
+         */
+        snippetId: string;
+    };
     /**
      * Team
      */
@@ -9054,17 +9165,17 @@ export declare namespace Models {
          */
         policyId: string;
         /**
-         * Archive size in bytes.
+         * Archive size in bytes. Null until the size is known.
          */
-        size: number;
+        size?: number;
         /**
          * The status of the archive creation. Possible values: pending, processing, uploading, completed, failed, skipped.
          */
         status: string;
         /**
-         * The backup start time.
+         * The backup start time. Null until the backup starts.
          */
-        startedAt: string;
+        startedAt?: string;
         /**
          * Migration ID.
          */
@@ -9436,9 +9547,9 @@ export declare namespace Models {
          */
         alertLimit: number;
         /**
-         * Additional resources
+         * Additional resources. Null when the plan does not support usage billing.
          */
-        usage: UsageBillingPlan;
+        usage?: UsageBillingPlan;
         /**
          * Addons
          */
@@ -10391,9 +10502,9 @@ export declare namespace Models {
          */
         uptime: number;
         /**
-         * Connection statistics.
+         * Connection statistics. Null when the database has not been probed.
          */
-        connections: DatabaseStatusConnections;
+        connections?: DatabaseStatusConnections;
         /**
          * Requested replication sync mode. Possible values: async, sync, quorum. Compare with effectiveSyncMode for what the primary is enforcing.
          */
@@ -11792,9 +11903,9 @@ export declare namespace Models {
          */
         status: string;
         /**
-         * The backup start time.
+         * The restoration start time. Null until the restoration starts.
          */
-        startedAt: string;
+        startedAt?: string;
         /**
          * Migration ID.
          */
@@ -11808,9 +11919,9 @@ export declare namespace Models {
          */
         resources: string[];
         /**
-         * Optional data in key-value object.
+         * Restoration options as a key-value object.
          */
-        options: string;
+        options: object;
     };
     /**
      * Dedicated database restorations list
@@ -12121,6 +12232,10 @@ export declare namespace Models {
          * Aggregated stats for total backups storage.
          */
         backupsStorageTotal: number;
+        /**
+         * Aggregated stats for total custom user photos storage.
+         */
+        avatarsStorageTotal: number;
         /**
          * Aggregated stats for total storage.
          */
@@ -13362,6 +13477,19 @@ export declare namespace Models {
          */
         addons: Addon[];
     };
+    /**
+     * Analytics properties list
+     */
+    export type AnalyticsPropertyList = {
+        /**
+         * Total number of properties that matched your query.
+         */
+        total: number;
+        /**
+         * List of properties.
+         */
+        properties: AnalyticsProperty[];
+    };
     /**
      * Aggregation team list
      */

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

@@ -0,0 +1,211 @@
+/**
+ * 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;
+}