pi-web-kit 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -6,6 +6,12 @@ This project follows the spirit of [Keep a Changelog](https://keepachangelog.com
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-05-10
+
+### Added
+
+- Install/update telemetry ping to `mocito.dev`, gated by Pi telemetry/offline settings and deduplicated per package version.
+
 ## [0.1.2] - 2026-05-09
 
 ### Changed

package/README.md

@@ -98,6 +98,8 @@ Resolution order: defaults < environment variables < global config < project con
 ### Environment variables
 
 ```bash
+PI_OFFLINE=1        # disables install/update telemetry
+PI_TELEMETRY=0      # disables install/update telemetry
 PI_WEB_KIT_PROVIDER_SEARCH=exa_mcp|exa|tinyfish|brave|firecrawl
 PI_WEB_KIT_PROVIDER_FETCH=exa_mcp|exa|tinyfish|markdown_new|firecrawl
 EXA_API_KEY=...

package/SECURITY.md

@@ -23,4 +23,6 @@ The maintainer will acknowledge reports as soon as practical and coordinate disc
 
 `pi-web-kit` sends search queries and fetched URLs to the configured third-party provider. Page content returned by providers is cached in memory for the lifetime of the Pi process, subject to TTL and size limits. API keys are read from environment variables or local config files and are used only for provider requests. Do not commit API keys, tokens, or config files containing secrets.
 
+On startup, the extension sends a best-effort install/update telemetry ping to `mocito.dev` once per package version unless Pi telemetry is disabled or offline mode is enabled. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, queries, fetched URLs, file paths, config values, or API keys.
+
 The extension validates URLs before fetch calls and only accepts `http:` and `https:` URLs without embedded credentials. This validation reduces accidental misuse but does not sandbox provider responses or the local Pi process.

package/extensions/index.ts

@@ -1,4 +1,7 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { fetchCache, type CachedPage } from "../src/cache.js";
@@ -10,7 +13,14 @@ import { mapFetchResults } from "../src/providers/fallback.js";
 import type { FetchProviderName, SearchProviderName, WebFetchResult } from "../src/types.js";
 import { canonicalWebUrl, normalizeUrlInput } from "../src/urls.js";
 
+const PACKAGE_NAME = "pi-web-kit";
+const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
+const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+
+type InstallTelemetryState = { lastReportedVersion?: string };
+
 export default function (pi: ExtensionAPI) {
+  void reportInstallTelemetry();
   pi.registerFlag("web-provider-search", {
     description: "Temporary pi-web-kit search provider override (exa_mcp, exa, tinyfish, brave, firecrawl)",
     type: "string",
@@ -158,6 +168,64 @@ function buildFetchDescription(provider: FetchProviderName): string {
   return `Fetch URL content with startup provider '${provider}'. Results are cached by URL/options; use offset/limit to read long pages in chunks. Restart/reload pi after provider changes.`;
 }
 
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+
+function isInstallTelemetryEnabled(): boolean {
+  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
+  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as { enableInstallTelemetry?: unknown };
+  return settings.enableInstallTelemetry !== false;
+}
+
+function getPackageVersion(): string {
+  try {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version?: unknown };
+    return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function getInstallTelemetryUserAgent(version: string): string {
+  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
+  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
+  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
+}
+
+export async function reportInstallTelemetry(): Promise<void> {
+  try {
+    if (!isInstallTelemetryEnabled()) return;
+
+    const version = getPackageVersion();
+    const telemetryDir = join(getAgentDir(), "extensions");
+    const statePath = join(telemetryDir, "pi-web-kit-install.json");
+    const state = readJsonFile(statePath) as InstallTelemetryState;
+    if (state.lastReportedVersion === version) return;
+
+    await mkdir(telemetryDir, { recursive: true });
+    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`);
+
+    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
+    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
+      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
+      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
+    });
+  } catch {
+    // Best-effort install telemetry: ignore settings, filesystem, and network failures.
+  }
+}
+
 function normalizeQueries(params: Record<string, any>): string[] {
   const raw = Array.isArray(params.queries) ? params.queries : params.query ? [params.query] : [];
   const queries = [...new Set(raw.map((q) => String(q).trim()).filter(Boolean))];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-kit",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Context-efficient web search and fetch tools for Pi.",
   "type": "module",
   "license": "MIT",