@qilin-agent/client-product-analytics 0.0.0-stage → 3.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,31 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/api/product-analytics/README.md
+/:
+  en: 398f54a8df19322f
+  zh: 0304784692321677
+/qilin-agent-client-product-analytics:
+  en: 250636b2ae989acf
+  zh: f6fd7680f4fddf6b
+/qilin-agent-client-product-analytics/summary:
+  en: 117758dc74e2dd5c
+  zh: cc4af24392853000
+/qilin-agent-client-product-analytics/table-of-contents:
+  en: 4e53164159b5ce41
+  zh: adba5f78f4fe4801
+/qilin-agent-client-product-analytics/use-this-package:
+  en: 43b4c57162dc9f6a
+  zh: b87d9f39b133d9bd
+/qilin-agent-client-product-analytics/dev-note:
+  en: 3155a54154dfbdd4
+  zh: a80fb690600452fd
+/qilin-agent-client-product-analytics/model-experience:
+  en: 291751b16b8a37e7
+  zh: 291751b16b8a37e7
+/qilin-agent-client-product-analytics/model-experience/kv-cache-effect:
+  en: 1f5125831808e7a9
+  zh: 1f5125831808e7a9
+/qilin-agent-client-product-analytics/known-limitations-and-deferred-work:
+  en: 80765498b4de1e64
+  zh: 842499d9f28d08c8

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+---
+description: "The product event map the desktop reports usage against, without the collector that upstream ships beside it."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/client-product-analytics
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`@qilin-agent/client-product-analytics` publishes the event names and field types the desktop reports product usage against, plus the desktop renderer's `./client` sender that reports them through the Host's authenticated analytics Remote namespace. It carries no collector: the upstream package's Host plugin, its generated Typert faces, locale files, and environment sampling depend on host packages this repository does not have yet.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Import the map where an event is declared and the event type where one is sent:
+
+
+<a id="dev-note"></a>
+## Dev Note
+
+The upstream package is `the upstream client/product-analytics package` in `deepseek-harness`; its host half depends on `@deepseek-ai/dsh-host-product-telemetry-otel`, which has no counterpart here yet.
+
+## Model Experience
+
+None, as analytics adds no model context or Session events.
+
+#### KV Cache effect
+
+None; collection does not modify model requests.
+
+## Known Limitations and Deferred Work
+
+- The collector, its Host Remote methods, and the locale files are not ported. The `./client` sender needs the analytics Remote namespace the desktop Host serves; nothing in this repository mounts it, so the sender stays unused until the Host half lands.
+- The desktop reports against these events through its own sender, which lives in the desktop application rather than here.

package/README.zh.md

@@ -0,0 +1,45 @@
+---
+description: "桌面端上报产品用量所依据的事件映射，不含上游与之同发的采集器。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-product-analytics
+
+[English](README.md) | 中文
+
+## 概述
+
+`@qilin-agent/client-product-analytics` 发布桌面端上报产品用量所依据的事件名与字段类型，以及桌面渲染端的 `./client` 发送方——它经宿主已鉴权的分析 Remote 命名空间上报。它不带采集器：上游那个包的宿主插件、其生成的 Typert 面、locale 文件与环境采样都依赖本仓暂时没有的宿主包。
+
+## 目录
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+在声明事件处引用映射，在发送处引用事件类型：
+
+
+<a id="dev-note"></a>
+## 开发备注
+
+上游包是 `deepseek-harness` 的 `the upstream client/product-analytics package`；它的宿主半边依赖 `@deepseek-ai/dsh-host-product-telemetry-otel`，本仓暂无对应物。
+
+## Model Experience
+
+None, as analytics adds no model context or Session events.
+
+#### KV Cache effect
+
+None; collection does not modify model requests.
+
+## Known Limitations and Deferred Work
+
+- 采集器、其宿主 Remote 方法与 locale 文件未移植。`./client` 发送方需要桌面宿主提供的分析 Remote 命名空间；本仓没有任何地方挂载它，因此宿主半边落地前该发送方不会被使用。
+- 桌面端通过这些事件上报，发送方在桌面应用内，不在此处。

package/lib/client.js

@@ -0,0 +1,83 @@
+window.__ModuleLoader__.load({
+	id: "@qilin-agent/client-product-analytics",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let _qilin_agent_kylin = require("@qilin-agent/kylin");
+		//#region lib/types/client/index.js
+		/**
+		* Desktop renderer analytics sender; browser applications have no collection
+		* capability.
+		*
+		* The Host half of this package (the collector plugin and its generated Typert
+		* faces) is not ported yet, so the analytics namespace is declared here from
+		* the endpoints the desktop Host already serves. Replace that declaration with
+		* the generated `./remote` face once the Host half lands.
+		*/
+		var DesktopAnalytics = class extends _qilin_agent_kylin.Service {
+			collecting = false;
+			submit;
+			constructor(ctx) {
+				super(ctx, "productAnalytics");
+				this.submit = async (event) => {
+					try {
+						await ctx.remote.productAnalytics.report(event);
+					} catch (_error) {}
+				};
+				if (!("qilinDesktop" in globalThis)) return;
+				const stream = ctx.remote.$stream({
+					name: "product analytics policy",
+					open: (signal) => ctx.remote.productAnalytics.watchPolicy(signal),
+					ended: () => /* @__PURE__ */ new Error("product analytics policy stream ended"),
+					carrierFailed: () => {
+						this.collecting = false;
+					}
+				});
+				ctx.effect(() => () => {
+					this.collecting = false;
+					return stream.dispose();
+				});
+				(async () => {
+					for await (const frame of stream) {
+						this.collecting = frame.value;
+						frame.accept();
+					}
+				})().catch(() => {
+					this.collecting = false;
+				});
+			}
+			/** Whether the synchronized Host configuration currently permits collection. */
+			get enabled() {
+				return this.collecting;
+			}
+			/**
+			* Send an event without retaining it for reconnect or later enablement.
+			* @param name - event name.
+			* @param attributes - approved business fields.
+			* @param timestamp - occurrence time; defaults to the current time.
+			*/
+			track(name, attributes, timestamp = Date.now()) {
+				if (!this.enabled) return;
+				const event = {
+					eventName: name,
+					attributes,
+					timestamp
+				};
+				this.submit(event);
+			}
+		};
+		/** Analytics consumes authenticated RPC and its reconnecting policy stream. */
+		const inject = ["remote", "remote.productAnalytics"];
+		/** @param ctx - browser application context. */
+		function apply(ctx) {
+			ctx.plugin(DesktopAnalytics);
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1 @@
+export {};

package/lib/types/client/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Desktop renderer analytics sender; browser applications have no collection
+ * capability.
+ *
+ * The Host half of this package (the collector plugin and its generated Typert
+ * faces) is not ported yet, so the analytics namespace is declared here from
+ * the endpoints the desktop Host already serves. Replace that declaration with
+ * the generated `./remote` face once the Host half lands.
+ */
+import { Service, type Context } from '@qilin-agent/kylin';
+import type { RemoteResult, RemoteStreamHandle } from '@qilin-agent/typert-protocol';
+import type { ProductEvent, ProductEventMap } from '../events.ts';
+export type { ProductEvent, ProductEventMap, TrackProductEvent } from '../events.ts';
+/** The authenticated analytics namespace mounted by the desktop Client assembly. */
+declare module '@qilin-agent/typert-protocol' {
+    interface TypertRemoteNamespaceMap {
+        productAnalytics: {
+            report: (event: ProductEvent) => Promise<RemoteResult<void>>;
+            watchPolicy: (signal?: AbortSignal) => RemoteStreamHandle<boolean, never>;
+        };
+    }
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        productAnalytics: DesktopAnalytics;
+    }
+}
+declare class DesktopAnalytics extends Service {
+    private collecting;
+    private readonly submit;
+    constructor(ctx: Context);
+    /** Whether the synchronized Host configuration currently permits collection. */
+    get enabled(): boolean;
+    /**
+     * Send an event without retaining it for reconnect or later enablement.
+     * @param name - event name.
+     * @param attributes - approved business fields.
+     * @param timestamp - occurrence time; defaults to the current time.
+     */
+    track<K extends keyof ProductEventMap>(name: K, attributes: ProductEventMap[K], timestamp?: number): void;
+}
+/** Analytics consumes authenticated RPC and its reconnecting policy stream. */
+export declare const inject: string[];
+/** @param ctx - browser application context. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/events.d.ts

@@ -0,0 +1,97 @@
+/** Desktop analytics fields selected by product event owners. */
+import type { SessionId } from '@qilin-agent/session/types';
+import type { MessageId } from '@qilin-agent/llm/brand';
+/** Event names and their selected product attributes. */
+export interface ProductEventMap {
+    desktop_app_launch: Record<string, never>;
+    auth_page_view: Record<string, never>;
+    auth_page_click: {
+        button_name: 'sign_in' | 'api-key';
+    };
+    api_key_save_click: Record<string, never>;
+    onboarding_page_view: {
+        page_name: OnboardingPage;
+    };
+    onboarding_page_click: {
+        page_name: OnboardingPage;
+        button_name: 'next' | 'back' | 'skip' | 'charge' | 'later' | 'continue';
+        selected_content?: 'office' | 'code' | 'code_office' | 'focus_result' | 'key_detail' | 'full_process';
+    };
+    onboarding_popup_view: {
+        popup_name: 'skip_charge' | 'skip_setting';
+    };
+    onboarding_popup_click: {
+        popup_name: 'skip_charge' | 'skip_setting';
+        button_name: 'charge' | 'know' | 'enter' | 'setting' | 'close';
+    };
+    desktop_upgrade_click: Record<string, never>;
+    desktop_upgrade_download_result: {
+        is_success: boolean;
+        error_reason?: string;
+    };
+    desktop_upgrade_install_restart_click: Record<string, never>;
+    send_button_click: {
+        session_id?: SessionId;
+        model_name?: string;
+        thinking_effort?: string;
+        run_mode: 'plan' | 'goal' | 'default';
+        msg_type: 'default' | 'steer' | 'queue';
+    };
+    model_switch: {
+        session_id?: SessionId;
+        switch_from: string;
+        switch_to: string;
+    };
+    thinking_level_switch: {
+        session_id?: SessionId;
+        switch_from: string;
+        switch_to: string;
+        model_name: string;
+    };
+    context_compression: {
+        session_id: SessionId;
+        trigger_type: 'auto' | 'manual';
+    };
+    branch_session_click: {
+        session_id: SessionId;
+        parent_session_id: SessionId;
+        parent_message_id?: MessageId;
+        click_position: 'footer' | 'sidebar';
+    };
+    sidebar_menu_click: {
+        menu_name: 'plugin' | 'cron';
+    };
+    plugin_toggle: {
+        plugin_name: string;
+        plugin_type: 'plugin' | 'bundle';
+        is_enabled: boolean;
+        is_builtin: boolean;
+    };
+    plugin_add_button_click: Record<string, never>;
+    plugin_install_click: {
+        input_value: string;
+    };
+    install_plugin_result: {
+        input_value: string;
+        is_success: boolean;
+        error_reason?: string;
+        duration: number;
+        plugin_name?: string;
+    };
+    confirm_uninstall_plugin: {
+        plugin_name: string;
+    };
+}
+/** Public page names independent of internal onboarding state names. */
+export type OnboardingPage = 'onboarding_welcome' | 'onboarding_recharge' | 'onboarding_use_case' | 'onboarding_process';
+/** Correlated event name and attributes for the authenticated analytics RPC. */
+export type ProductEvent = {
+    [K in keyof ProductEventMap]: {
+        eventName: K;
+        attributes: ProductEventMap[K];
+        timestamp: number;
+    };
+}[keyof ProductEventMap];
+/** Callback passed into presentation components; omitted when collection is disabled. */
+export type TrackProductEvent = <K extends keyof ProductEventMap>(name: K, attributes: ProductEventMap[K]) => void;
+//# sourceMappingURL=events.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Product analytics event map, as the desktop consumes it.
+ *
+ * The upstream package also carries a collector plugin, a remote Typert surface,
+ * and locale files; those depend on host packages this repository does not have
+ * yet, so this package exposes the event map alone.
+ *
+ * @module @qilin-agent/client-product-analytics
+ */
+export type * from './events.ts';
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@qilin-agent/client-product-analytics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Desktop product event collection and authenticated Host reporting",
+  "version": "3.1.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/api/product-analytics"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./types": {
+      "types": "./lib/types/events.d.ts"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.5"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/kylin-plugin-loader": "~1.0.6",
+    "@qilin-agent/app-boot": "3.1.6",
+    "@qilin-agent/session": "3.1.6",
+    "@qilin-agent/llm": "3.1.6",
+    "@qilin-agent/api-gateway": "3.1.6",
+    "@qilin-agent/typert-protocol": "3.1.6"
+  },
+  "dependencies": {},
+  "optionalDependencies": {},
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/api-gateway"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }