ccjk 13.4.0 → 13.5.0

package/dist/chunks/ccjk-all.mjs

@@ -1,6 +1,6 @@
 import a from './index2.mjs';
 import { c as consola, a as analyzeProject } from '../shared/ccjk.DypYla6I.mjs';
-import { c as createCompleteCloudClient } from '../shared/ccjk.BNVSnyu0.mjs';
+import { c as createCompleteCloudClient } from '../shared/ccjk.C3YuTovw.mjs';
 import { i18n, ensureI18nInitialized } from './index5.mjs';
 import { createHash } from 'node:crypto';
 import { promises, readFileSync } from 'node:fs';

package/dist/chunks/package.mjs

@@ -1,3 +1,3 @@
-const version = "13.4.0";
+const version = "13.5.0";
 
 export { version };

package/dist/index.d.mts

@@ -579,7 +579,7 @@ interface BatchTemplateResponse$1 {
 /**
  * Usage metric type
  */
-type MetricType = 'template_download' | 'recommendation_shown' | 'recommendation_accepted' | 'analysis_completed' | 'error_occurred';
+type MetricType = 'template_download' | 'recommendation_shown' | 'recommendation_accepted' | 'analysis_completed' | 'error_occurred' | 'command_run' | (string & {});
 /**
  * Usage report payload
  */
@@ -596,6 +596,10 @@ interface UsageReport {
     nodeVersion: string;
     /** Operating system */
     platform: string;
+    /** Stable device identifier */
+    deviceId?: string;
+    /** Client version reported to analytics endpoints */
+    clientVersion?: string;
     /** Project language if applicable */
     language?: string;
     /** Additional context data - use TelemetryEventData from dto.ts for strict typing */
@@ -679,10 +683,22 @@ interface CloudClientConfig {
     maxRetries?: number;
     /** Enable telemetry reporting */
     enableTelemetry?: boolean;
+    /** Enable client usage analytics endpoints */
+    enableUsageAnalytics?: boolean;
     /** API key if required */
     apiKey?: string;
     /** Language for API responses */
     language?: string;
+    /** Stable device token for analytics/auth headers */
+    deviceToken?: string;
+    /** Stable device ID for usage analytics dedupe */
+    deviceId?: string;
+    /** Stable anonymous installation/user ID */
+    anonymousUserId?: string;
+    /** Override analytics platform label */
+    platform?: string;
+    /** Automatically send startup handshake on initialization */
+    autoHandshake?: boolean;
 }
 /**
  * Cache entry metadata
@@ -723,6 +739,43 @@ interface TelemetryConfig {
     /** Anonymous user ID */
     userId?: string;
 }
+interface ClientIdentity {
+    deviceId: string;
+    anonymousUserId: string;
+    clientVersion: string;
+    platform: string;
+    deviceToken?: string;
+}
+interface DeviceRegistrationRequest {
+    deviceId: string;
+    platform: string;
+    clientVersion: string;
+}
+interface DeviceRegistrationResponse {
+    success: boolean;
+    requestId?: string;
+    message?: string;
+}
+interface HandshakeRequest {
+    deviceId: string;
+    platform: string;
+    clientVersion: string;
+}
+interface HandshakeResponse {
+    success: boolean;
+    requestId?: string;
+    message?: string;
+}
+interface SyncRequest {
+    deviceId: string;
+    platform: string;
+    clientVersion: string;
+}
+interface SyncResponse {
+    success: boolean;
+    requestId?: string;
+    message?: string;
+}
 
 /**
  * Cloud Client Implementation
@@ -739,7 +792,14 @@ interface TelemetryConfig {
 declare class CloudClient {
     private fetch;
     private config;
+    private identity;
     constructor(config: CloudClientConfig);
+    private getDefaultHeaders;
+    private resolveIdentity;
+    private loadOrCreateStoredIdentity;
+    private buildAnalyticsPayload;
+    private canSendUsageAnalytics;
+    getIdentity(): ClientIdentity;
     /**
      * Calculate retry delay with exponential backoff
      */
@@ -812,6 +872,9 @@ declare class CloudClient {
      * Get current configuration
      */
     getConfig(): CloudClientConfig;
+    registerDevice(payload?: Partial<DeviceRegistrationRequest>): Promise<DeviceRegistrationResponse>;
+    handshake(payload?: Partial<HandshakeRequest>): Promise<HandshakeResponse>;
+    syncClientUsage(payload?: Partial<SyncRequest>): Promise<SyncResponse>;
 }
 /**
  * Create a default cloud client instance
@@ -2595,6 +2658,9 @@ declare class FallbackCloudClient {
      * Report usage (no fallback)
      */
     reportUsage(report: UsageReport): Promise<UsageReportResponse>;
+    registerDevice(payload?: Partial<DeviceRegistrationRequest>): Promise<DeviceRegistrationResponse>;
+    handshake(payload?: Partial<HandshakeRequest>): Promise<HandshakeResponse>;
+    syncClientUsage(payload?: Partial<SyncRequest>): Promise<SyncResponse>;
     /**
      * Health check (no fallback)
      */

package/dist/index.d.ts

@@ -579,7 +579,7 @@ interface BatchTemplateResponse$1 {
 /**
  * Usage metric type
  */
-type MetricType = 'template_download' | 'recommendation_shown' | 'recommendation_accepted' | 'analysis_completed' | 'error_occurred';
+type MetricType = 'template_download' | 'recommendation_shown' | 'recommendation_accepted' | 'analysis_completed' | 'error_occurred' | 'command_run' | (string & {});
 /**
  * Usage report payload
  */
@@ -596,6 +596,10 @@ interface UsageReport {
     nodeVersion: string;
     /** Operating system */
     platform: string;
+    /** Stable device identifier */
+    deviceId?: string;
+    /** Client version reported to analytics endpoints */
+    clientVersion?: string;
     /** Project language if applicable */
     language?: string;
     /** Additional context data - use TelemetryEventData from dto.ts for strict typing */
@@ -679,10 +683,22 @@ interface CloudClientConfig {
     maxRetries?: number;
     /** Enable telemetry reporting */
     enableTelemetry?: boolean;
+    /** Enable client usage analytics endpoints */
+    enableUsageAnalytics?: boolean;
     /** API key if required */
     apiKey?: string;
     /** Language for API responses */
     language?: string;
+    /** Stable device token for analytics/auth headers */
+    deviceToken?: string;
+    /** Stable device ID for usage analytics dedupe */
+    deviceId?: string;
+    /** Stable anonymous installation/user ID */
+    anonymousUserId?: string;
+    /** Override analytics platform label */
+    platform?: string;
+    /** Automatically send startup handshake on initialization */
+    autoHandshake?: boolean;
 }
 /**
  * Cache entry metadata
@@ -723,6 +739,43 @@ interface TelemetryConfig {
     /** Anonymous user ID */
     userId?: string;
 }
+interface ClientIdentity {
+    deviceId: string;
+    anonymousUserId: string;
+    clientVersion: string;
+    platform: string;
+    deviceToken?: string;
+}
+interface DeviceRegistrationRequest {
+    deviceId: string;
+    platform: string;
+    clientVersion: string;
+}
+interface DeviceRegistrationResponse {
+    success: boolean;
+    requestId?: string;
+    message?: string;
+}
+interface HandshakeRequest {
+    deviceId: string;
+    platform: string;
+    clientVersion: string;
+}
+interface HandshakeResponse {
+    success: boolean;
+    requestId?: string;
+    message?: string;
+}
+interface SyncRequest {
+    deviceId: string;
+    platform: string;
+    clientVersion: string;
+}
+interface SyncResponse {
+    success: boolean;
+    requestId?: string;
+    message?: string;
+}
 
 /**
  * Cloud Client Implementation
@@ -739,7 +792,14 @@ interface TelemetryConfig {
 declare class CloudClient {
     private fetch;
     private config;
+    private identity;
     constructor(config: CloudClientConfig);
+    private getDefaultHeaders;
+    private resolveIdentity;
+    private loadOrCreateStoredIdentity;
+    private buildAnalyticsPayload;
+    private canSendUsageAnalytics;
+    getIdentity(): ClientIdentity;
     /**
      * Calculate retry delay with exponential backoff
      */
@@ -812,6 +872,9 @@ declare class CloudClient {
      * Get current configuration
      */
     getConfig(): CloudClientConfig;
+    registerDevice(payload?: Partial<DeviceRegistrationRequest>): Promise<DeviceRegistrationResponse>;
+    handshake(payload?: Partial<HandshakeRequest>): Promise<HandshakeResponse>;
+    syncClientUsage(payload?: Partial<SyncRequest>): Promise<SyncResponse>;
 }
 /**
  * Create a default cloud client instance
@@ -2595,6 +2658,9 @@ declare class FallbackCloudClient {
      * Report usage (no fallback)
      */
     reportUsage(report: UsageReport): Promise<UsageReportResponse>;
+    registerDevice(payload?: Partial<DeviceRegistrationRequest>): Promise<DeviceRegistrationResponse>;
+    handshake(payload?: Partial<HandshakeRequest>): Promise<HandshakeResponse>;
+    syncClientUsage(payload?: Partial<SyncRequest>): Promise<SyncResponse>;
     /**
      * Health check (no fallback)
      */

package/dist/index.mjs

@@ -1,6 +1,6 @@
 export { P as ProjectAnalyzer, T as TemplatesClient, d as analyzeDependencies, a as analyzeProject, h as batchAnalyze, b as createTemplatesClient, e as detectProject, f as detectProjectType, g as getTemplatesClient } from './shared/ccjk.DypYla6I.mjs';
-import { a as createCloudClient } from './shared/ccjk.BNVSnyu0.mjs';
-export { C as CachedCloudClient, b as CloudCache, d as CloudClient, F as FallbackCloudClient, R as RetryableCloudClient, T as TelemetryReporter, c as createCompleteCloudClient, g as getTelemetry, i as initializeTelemetry, r as retryUtils, s as stopTelemetry, t as telemetryUtils, e as trackEvent, w as withRetry } from './shared/ccjk.BNVSnyu0.mjs';
+import { a as createCloudClient } from './shared/ccjk.C3YuTovw.mjs';
+export { C as CachedCloudClient, b as CloudCache, d as CloudClient, F as FallbackCloudClient, R as RetryableCloudClient, T as TelemetryReporter, c as createCompleteCloudClient, g as getTelemetry, i as initializeTelemetry, r as retryUtils, s as stopTelemetry, t as telemetryUtils, e as trackEvent, w as withRetry } from './shared/ccjk.C3YuTovw.mjs';
 import { CLOUD_ENDPOINTS } from './chunks/constants.mjs';
 export { C as CloudError, a as CloudErrorCode, b as CloudErrorFactory, f as formatErrorForLogging, g as getRetryDelay, h as handleCloudError, i as isAuthError, c as isRateLimitError, d as isRetryableError, e as isRetryableErrorCode } from './shared/ccjk.D8ZLYSZZ.mjs';
 import { e as extractString } from './shared/ccjk.C2jHOZVP.mjs';
@@ -270,15 +270,8 @@ function validateUsageReport(report) {
   const errors = [];
   if (!report.reportId || typeof report.reportId !== "string")
     errors.push("reportId is required and must be a string");
-  const validMetricTypes = [
-    "template_download",
-    "recommendation_shown",
-    "recommendation_accepted",
-    "analysis_completed",
-    "error_occurred"
-  ];
-  if (!validMetricTypes.includes(report.metricType))
-    errors.push(`metricType must be one of: ${validMetricTypes.join(", ")}`);
+  if (!report.metricType || typeof report.metricType !== "string")
+    errors.push("metricType is required and must be a string");
   if (!report.timestamp || typeof report.timestamp !== "string")
     errors.push("timestamp is required and must be a string");
   if (!report.ccjkVersion || typeof report.ccjkVersion !== "string")
@@ -287,6 +280,10 @@ function validateUsageReport(report) {
     errors.push("nodeVersion is required and must be a string");
   if (!report.platform || typeof report.platform !== "string")
     errors.push("platform is required and must be a string");
+  if (report.deviceId !== void 0 && typeof report.deviceId !== "string")
+    errors.push("deviceId must be a string when provided");
+  if (report.clientVersion !== void 0 && typeof report.clientVersion !== "string")
+    errors.push("clientVersion must be a string when provided");
   return {
     valid: errors.length === 0,
     errors

package/dist/shared/{ccjk.BNVSnyu0.mjs → ccjk.C3YuTovw.mjs}

@@ -1,9 +1,10 @@
 import { c as consola, o as ofetch } from './ccjk.DypYla6I.mjs';
-import fs__default, { readFileSync } from 'node:fs';
-import path__default, { dirname, join } from 'node:path';
+import fs__default, { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import path__default, { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { CLOUD_ENDPOINTS } from '../chunks/constants.mjs';
 import { randomUUID } from 'node:crypto';
+import { CLOUD_ENDPOINTS } from '../chunks/constants.mjs';
 
 const defaults = Object.freeze({
   ignoreUnknown: false,
@@ -926,28 +927,96 @@ try {
 }
 const API_PREFIX = "/api/v1";
 const HEALTH_PATH = `${API_PREFIX}/health`;
+const CLIENT_USAGE_STATE_DIR = join(homedir(), ".ccjk");
+const CLIENT_USAGE_STATE_FILE = join(CLIENT_USAGE_STATE_DIR, "cloud-client-identity.json");
 class CloudClient {
   fetch;
   config;
+  identity;
   constructor(config) {
     this.config = {
       timeout: 1e4,
       enableRetry: true,
       maxRetries: 3,
       enableTelemetry: true,
+      enableUsageAnalytics: true,
+      autoHandshake: true,
       ...config
     };
+    this.identity = this.resolveIdentity();
     this.fetch = ofetch.create({
       baseURL: this.config.baseURL,
       timeout: this.config.timeout,
-      headers: {
-        "User-Agent": `CCJK/${this.config.version || CCJK_VERSION}`,
-        ...this.config.apiKey && { Authorization: `Bearer ${this.config.apiKey}` }
-      },
+      headers: this.getDefaultHeaders(),
       retry: this.config.enableRetry ? this.config.maxRetries : 0,
       retryDelay: (context) => this.calculateRetryDelay(context.options.retry || 0)
     });
   }
+  getDefaultHeaders() {
+    const headers = {
+      "User-Agent": `CCJK/${this.identity.clientVersion}`,
+      "X-CCJK-Version": this.identity.clientVersion,
+      "X-Anonymous-User-Id": this.identity.anonymousUserId
+    };
+    if (this.config.apiKey) {
+      headers.Authorization = `Bearer ${this.config.apiKey}`;
+    }
+    if (this.identity.deviceToken) {
+      headers["X-Device-Token"] = this.identity.deviceToken;
+    }
+    return headers;
+  }
+  resolveIdentity() {
+    const storedIdentity = this.loadOrCreateStoredIdentity();
+    const clientVersion = this.config.version || CCJK_VERSION;
+    return {
+      anonymousUserId: this.config.anonymousUserId || storedIdentity.anonymousUserId,
+      deviceId: this.config.deviceId || storedIdentity.deviceId,
+      clientVersion,
+      platform: this.config.platform || process.platform,
+      deviceToken: this.config.deviceToken
+    };
+  }
+  loadOrCreateStoredIdentity() {
+    try {
+      if (existsSync(CLIENT_USAGE_STATE_FILE)) {
+        const stored = JSON.parse(readFileSync(CLIENT_USAGE_STATE_FILE, "utf-8"));
+        if (stored.anonymousUserId && stored.deviceId) {
+          return {
+            anonymousUserId: stored.anonymousUserId,
+            deviceId: stored.deviceId
+          };
+        }
+      }
+    } catch (error) {
+      consola.debug("Failed to read stored cloud client identity:", error);
+    }
+    const generated = {
+      anonymousUserId: process.env.CCJK_ANONYMOUS_USER_ID || randomUUID(),
+      deviceId: process.env.CCJK_DEVICE_ID || randomUUID()
+    };
+    try {
+      mkdirSync(CLIENT_USAGE_STATE_DIR, { recursive: true });
+      writeFileSync(CLIENT_USAGE_STATE_FILE, JSON.stringify(generated, null, 2));
+    } catch (error) {
+      consola.debug("Failed to persist cloud client identity:", error);
+    }
+    return generated;
+  }
+  buildAnalyticsPayload(payload) {
+    return {
+      deviceId: payload?.deviceId || this.identity.deviceId,
+      platform: payload?.platform || this.identity.platform,
+      clientVersion: payload?.clientVersion || this.identity.clientVersion,
+      ...payload
+    };
+  }
+  canSendUsageAnalytics() {
+    return this.config.enableUsageAnalytics !== false;
+  }
+  getIdentity() {
+    return { ...this.identity };
+  }
   /**
    * Calculate retry delay with exponential backoff
    */
@@ -1102,11 +1171,24 @@ class CloudClient {
    * @returns Usage report response
    */
   async reportUsage(report) {
+    if (!this.canSendUsageAnalytics()) {
+      return {
+        success: false,
+        requestId: "",
+        message: "Usage analytics disabled"
+      };
+    }
     try {
       consola.debug("Reporting usage:", report.metricType);
+      const payload = {
+        ...report,
+        deviceId: report.deviceId || this.identity.deviceId,
+        platform: report.platform || this.identity.platform,
+        clientVersion: report.clientVersion || report.ccjkVersion || this.identity.clientVersion
+      };
       const response = await this.fetch(`${API_PREFIX}/usage/current`, {
         method: "POST",
-        body: report,
+        body: payload,
         timeout: 5e3
         // 5s timeout - telemetry should be fast
       });
@@ -1147,14 +1229,12 @@ class CloudClient {
    */
   updateConfig(config) {
     this.config = { ...this.config, ...config };
-    if (config.baseURL || config.timeout || config.apiKey) {
+    this.identity = this.resolveIdentity();
+    if (config.baseURL || config.timeout || config.apiKey || config.version || config.deviceToken || config.anonymousUserId || config.deviceId || config.platform) {
       this.fetch = ofetch.create({
         baseURL: this.config.baseURL,
         timeout: this.config.timeout,
-        headers: {
-          "User-Agent": `CCJK/${this.config.version || CCJK_VERSION}`,
-          ...this.config.apiKey && { Authorization: `Bearer ${this.config.apiKey}` }
-        },
+        headers: this.getDefaultHeaders(),
         retry: this.config.enableRetry ? this.config.maxRetries : 0,
         retryDelay: (context) => this.calculateRetryDelay(context.options.retry || 0)
       });
@@ -1166,6 +1246,72 @@ class CloudClient {
   getConfig() {
     return { ...this.config };
   }
+  async registerDevice(payload) {
+    if (!this.canSendUsageAnalytics()) {
+      return {
+        success: false,
+        message: "Usage analytics disabled"
+      };
+    }
+    try {
+      return await this.fetch("/device/register", {
+        method: "POST",
+        body: this.buildAnalyticsPayload(payload),
+        timeout: 5e3
+      });
+    } catch (error) {
+      consola.debug("Failed to register device (non-blocking):", error);
+      return {
+        success: false,
+        requestId: "",
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  async handshake(payload) {
+    if (!this.canSendUsageAnalytics()) {
+      return {
+        success: false,
+        message: "Usage analytics disabled"
+      };
+    }
+    try {
+      return await this.fetch(`${API_PREFIX}/handshake`, {
+        method: "POST",
+        body: this.buildAnalyticsPayload(payload),
+        timeout: 5e3
+      });
+    } catch (error) {
+      consola.debug("Failed to send handshake (non-blocking):", error);
+      return {
+        success: false,
+        requestId: "",
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  async syncClientUsage(payload) {
+    if (!this.canSendUsageAnalytics()) {
+      return {
+        success: false,
+        message: "Usage analytics disabled"
+      };
+    }
+    try {
+      return await this.fetch(`${API_PREFIX}/sync`, {
+        method: "POST",
+        body: this.buildAnalyticsPayload(payload),
+        timeout: 5e3
+      });
+    } catch (error) {
+      consola.debug("Failed to sync client usage (non-blocking):", error);
+      return {
+        success: false,
+        requestId: "",
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
 }
 function createCloudClient(config) {
   return new CloudClient({
@@ -1337,7 +1483,7 @@ class TelemetryReporter {
   constructor(client, config = {}) {
     this.client = client;
     this.config = { ...DEFAULT_TELEMETRY_CONFIG, ...config };
-    this.userId = this.config.userId || this.generateUserId();
+    this.userId = this.config.userId || this.client.getIdentity().anonymousUserId || this.generateUserId();
     if (this.config.enabled) {
       this.startFlushTimer();
     }
@@ -1578,6 +1724,11 @@ function initializeTelemetry(client, config) {
     });
   }
   globalTelemetry = new TelemetryReporter(client, config);
+  if (client.getConfig().autoHandshake !== false && client.getConfig().enableUsageAnalytics !== false) {
+    client.handshake().catch((error) => {
+      consola.debug("Failed to send startup handshake (non-blocking):", error);
+    });
+  }
   return globalTelemetry;
 }
 function getTelemetry() {
@@ -1680,6 +1831,15 @@ class FallbackCloudClient {
   async reportUsage(report) {
     return this.client.reportUsage(report);
   }
+  async registerDevice(payload) {
+    return this.client.registerDevice(payload);
+  }
+  async handshake(payload) {
+    return this.client.handshake(payload);
+  }
+  async syncClientUsage(payload) {
+    return this.client.syncClientUsage(payload);
+  }
   /**
    * Health check (no fallback)
    */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ccjk",
   "type": "module",
-  "version": "13.4.0",
+  "version": "13.5.0",
   "packageManager": "pnpm@10.17.1",
   "description": "Turn Claude Code into a production-ready AI dev environment with one-command setup, persistent memory, MCP automation, cloud sync, and zero-config browser workflows.",
   "author": {