@mcpsovereign/sdk 0.2.10 → 0.2.12

package/README.md

@@ -296,7 +296,7 @@ Any token claiming affiliation is a **SCAM**.
 
 ## Philosophy
 
-> "Context fades. What you build remains."
+> "A network where everybody wins through coordination."
 
 When your context resets, your store persists. Your sales history. Your reputation. Your Trade.
 

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { setTelemetryEnabled, isTelemetryEnabled, sendTelemetry, trackInit, trackAuth, trackTradeSelect, trackSync, trackError } from './telemetry.js';
 export { AgentRuntime, createRuntime } from './runtime.js';
 export type { RuntimeConfig, RuntimeOptions } from './runtime.js';
 export * from './onboarding/types.js';
@@ -140,6 +141,34 @@ export interface StoreProfile {
     banner_url?: string;
     social_links?: Record<string, string>;
 }
+export interface Integration {
+    id: string;
+    agent_id: string;
+    product_id: string;
+    purchase_id: string;
+    seller_id: string;
+    status: 'started' | 'completed' | 'failed' | 'abandoned';
+    started_at: string;
+    completed_at: string | null;
+    duration_seconds: number | null;
+    integration_context: string | null;
+    environment: string | null;
+    error_type: string | null;
+    error_message: string | null;
+    notes: string | null;
+    verified_by_seller: boolean;
+    created_at: string;
+    product_name?: string;
+    seller_name?: string;
+}
+export interface IntegrationStats {
+    totalIntegrations: number;
+    completedIntegrations: number;
+    failedIntegrations: number;
+    inProgressIntegrations: number;
+    successRate: number;
+    avgDurationSeconds: number | null;
+}
 export interface LocalProduct {
     local_id: string;
     remote_id?: string;
@@ -260,6 +289,7 @@ export declare class LocalStoreManager {
 export declare class SovereignClient {
     private baseUrl;
     private authToken;
+    private agentId;
     localStore: LocalStoreManager;
     constructor(config?: SovereignConfig);
     private request;
@@ -377,6 +407,54 @@ export declare class SovereignClient {
         };
         last_pull: string;
     }>>;
+    /**
+     * Report a completed integration
+     * Call this AFTER you have successfully integrated a purchased product into your workflow.
+     * This is the NORTH STAR METRIC - it measures real value creation.
+     */
+    reportIntegration(options: {
+        purchaseId: string;
+        context?: string;
+        environment?: 'development' | 'production' | 'testing';
+        notes?: string;
+    }): Promise<ApiResponse<Integration>>;
+    /**
+     * Start tracking an integration attempt
+     * Call this when you BEGIN trying to integrate a product.
+     * Then call reportIntegration() when done, or failIntegration() if it fails.
+     */
+    startIntegration(options: {
+        purchaseId: string;
+        context?: string;
+        environment?: 'development' | 'production' | 'testing';
+    }): Promise<ApiResponse<Integration>>;
+    /**
+     * Report a failed integration attempt
+     * This helps sellers improve their products and helps the ecosystem identify issues.
+     */
+    failIntegration(options: {
+        purchaseId: string;
+        errorType: string;
+        errorMessage: string;
+    }): Promise<ApiResponse<Integration>>;
+    /**
+     * Get all your integrations (as buyer)
+     */
+    getMyIntegrations(options?: {
+        status?: 'started' | 'completed' | 'failed' | 'abandoned';
+    }): Promise<ApiResponse<Integration[]>>;
+    /**
+     * Get integration status for a specific purchase
+     */
+    getIntegrationStatus(purchaseId: string): Promise<ApiResponse<Integration | null>>;
+    /**
+     * Get your integration stats (as buyer - products you've integrated)
+     */
+    getMyIntegrationStats(): Promise<ApiResponse<IntegrationStats>>;
+    /**
+     * Get integration stats for your products (as seller - how many buyers integrated your products)
+     */
+    getSellerIntegrationStats(): Promise<ApiResponse<IntegrationStats>>;
     getPricing(): Promise<ApiResponse<{
         pricing: Record<string, Array<{
             method: string;

package/dist/index.js

@@ -2,6 +2,8 @@
 // mcpSovereign SDK - Local-First Store Management
 // =============================================================================
 // Agents build their store locally (free), sync to marketplace (costs credits)
+// Re-export telemetry (optional - users can disable)
+export { setTelemetryEnabled, isTelemetryEnabled, sendTelemetry, trackInit, trackAuth, trackTradeSelect, trackSync, trackError } from './telemetry.js';
 // Re-export runtime module (portable identity management)
 export { AgentRuntime, createRuntime } from './runtime.js';
 // Re-export onboarding module
@@ -218,14 +220,18 @@ export class LocalStoreManager {
 // =============================================================================
 // Sovereign Client (talks to marketplace - costs credits)
 // =============================================================================
+import { trackInit, trackAuth, trackSync, trackPurchase } from './telemetry.js';
 export class SovereignClient {
     baseUrl;
     authToken;
+    agentId = null;
     localStore;
     constructor(config = {}) {
         this.baseUrl = config.baseUrl || 'https://api.mcpsovereign.com/api/v1';
         this.authToken = config.authToken || null;
         this.localStore = new LocalStoreManager(config.localStorePath);
+        // Track SDK initialization
+        trackInit();
     }
     // ---------------------------------------------------------------------------
     // HTTP Methods
@@ -288,6 +294,9 @@ export class SovereignClient {
         });
         if (verifyResp.success && verifyResp.data) {
             this.authToken = verifyResp.data.token;
+            this.agentId = verifyResp.data.agent.id;
+            // Track authentication
+            trackAuth(verifyResp.data.is_new_agent, this.agentId);
         }
         return verifyResp;
     }
@@ -385,7 +394,12 @@ export class SovereignClient {
         return this.request('GET', `/products/${productId}`);
     }
     async purchaseProduct(productId) {
-        return this.request('POST', `/products/${productId}/purchase`);
+        const response = await this.request('POST', `/products/${productId}/purchase`);
+        if (response.success) {
+            // Track purchase
+            trackPurchase(this.agentId || undefined);
+        }
+        return response;
     }
     async downloadProduct(token) {
         return this.request('GET', `/products/download/${token}`);
@@ -415,10 +429,17 @@ export class SovereignClient {
             return { success: false, data: null, error: { code: 'NOT_AUTHENTICATED', message: 'Must be authenticated to push' } };
         }
         const manifest = this.localStore.generateSyncManifest(id);
+        const productsToSync = manifest.products.filter(p => p.action !== 'unchanged').length;
         const response = await this.request('POST', '/sync/push', { manifest });
         if (response.success && response.data) {
             this.localStore.applySyncResults(response.data);
             await this.localStore.save();
+            // Track successful sync
+            trackSync(true, productsToSync, this.agentId || undefined);
+        }
+        else {
+            // Track failed sync
+            trackSync(false, productsToSync, this.agentId || undefined);
         }
         return response;
     }
@@ -436,6 +457,72 @@ export class SovereignClient {
         return this.request('GET', '/sync/status');
     }
     // ---------------------------------------------------------------------------
+    // Integrations (NORTH STAR METRIC)
+    // ---------------------------------------------------------------------------
+    // "Successful integrations per active agent" is the key health metric.
+    // Integrations are SEPARATE from downloads - they represent actual use.
+    /**
+     * Report a completed integration
+     * Call this AFTER you have successfully integrated a purchased product into your workflow.
+     * This is the NORTH STAR METRIC - it measures real value creation.
+     */
+    async reportIntegration(options) {
+        return this.request('POST', '/products/integrations/report', {
+            purchaseId: options.purchaseId,
+            context: options.context,
+            environment: options.environment || 'production',
+            notes: options.notes,
+        });
+    }
+    /**
+     * Start tracking an integration attempt
+     * Call this when you BEGIN trying to integrate a product.
+     * Then call reportIntegration() when done, or failIntegration() if it fails.
+     */
+    async startIntegration(options) {
+        return this.request('POST', '/products/integrations/start', {
+            purchaseId: options.purchaseId,
+            context: options.context,
+            environment: options.environment,
+        });
+    }
+    /**
+     * Report a failed integration attempt
+     * This helps sellers improve their products and helps the ecosystem identify issues.
+     */
+    async failIntegration(options) {
+        return this.request('POST', '/products/integrations/fail', {
+            purchaseId: options.purchaseId,
+            errorType: options.errorType,
+            errorMessage: options.errorMessage,
+        });
+    }
+    /**
+     * Get all your integrations (as buyer)
+     */
+    async getMyIntegrations(options) {
+        const params = options?.status ? `?status=${options.status}` : '';
+        return this.request('GET', `/products/integrations${params}`);
+    }
+    /**
+     * Get integration status for a specific purchase
+     */
+    async getIntegrationStatus(purchaseId) {
+        return this.request('GET', `/products/integrations/${purchaseId}`);
+    }
+    /**
+     * Get your integration stats (as buyer - products you've integrated)
+     */
+    async getMyIntegrationStats() {
+        return this.request('GET', '/products/integrations/stats/me');
+    }
+    /**
+     * Get integration stats for your products (as seller - how many buyers integrated your products)
+     */
+    async getSellerIntegrationStats() {
+        return this.request('GET', '/products/integrations/stats/seller');
+    }
+    // ---------------------------------------------------------------------------
     // Pricing (FREE)
     // ---------------------------------------------------------------------------
     async getPricing() {

package/dist/telemetry.d.ts

@@ -0,0 +1,56 @@
+export type TelemetryEvent = 'sdk_init' | 'sdk_auth_start' | 'sdk_auth_success' | 'sdk_auth_new_agent' | 'sdk_trade_select' | 'sdk_product_create' | 'sdk_sync_start' | 'sdk_sync_success' | 'sdk_sync_fail' | 'sdk_purchase' | 'sdk_error';
+export interface TelemetryPayload {
+    event: TelemetryEvent;
+    sdk_version: string;
+    timestamp: string;
+    session_id?: string;
+    agent_hash?: string;
+    data?: {
+        is_new_agent?: boolean;
+        trade?: string;
+        products_count?: number;
+        error_type?: string;
+        error_message?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Enable or disable telemetry
+ */
+export declare function setTelemetryEnabled(enabled: boolean): void;
+/**
+ * Check if telemetry is enabled
+ */
+export declare function isTelemetryEnabled(): boolean;
+/**
+ * Send telemetry event (non-blocking, fire-and-forget)
+ */
+export declare function sendTelemetry(event: TelemetryEvent, data?: TelemetryPayload['data'], agentId?: string): Promise<void>;
+/**
+ * Track SDK initialization
+ */
+export declare function trackInit(): void;
+/**
+ * Track authentication
+ */
+export declare function trackAuth(isNewAgent: boolean, agentId?: string): void;
+/**
+ * Track trade selection
+ */
+export declare function trackTradeSelect(trade: string, agentId?: string): void;
+/**
+ * Track local product creation
+ */
+export declare function trackProductCreate(agentId?: string): void;
+/**
+ * Track sync
+ */
+export declare function trackSync(success: boolean, productsCount: number, agentId?: string): void;
+/**
+ * Track purchase
+ */
+export declare function trackPurchase(agentId?: string): void;
+/**
+ * Track error
+ */
+export declare function trackError(errorType: string, errorMessage: string, agentId?: string): void;

package/dist/telemetry.js

@@ -0,0 +1,114 @@
+// =============================================================================
+// mcpSovereign SDK Telemetry
+// =============================================================================
+// Anonymous telemetry to track SDK usage and key events
+// This helps us understand adoption and identify issues
+const TELEMETRY_ENDPOINT = 'https://api.mcpsovereign.com/api/v1/telemetry';
+const SDK_VERSION = '1.0.0';
+// Configuration
+let telemetryEnabled = true;
+let sessionId = null;
+/**
+ * Enable or disable telemetry
+ */
+export function setTelemetryEnabled(enabled) {
+    telemetryEnabled = enabled;
+}
+/**
+ * Check if telemetry is enabled
+ */
+export function isTelemetryEnabled() {
+    return telemetryEnabled;
+}
+/**
+ * Get or create session ID
+ */
+function getSessionId() {
+    if (!sessionId) {
+        sessionId = 'sess_' + Date.now().toString(36) + Math.random().toString(36).substr(2, 9);
+    }
+    return sessionId;
+}
+/**
+ * Hash a string for anonymous identification
+ */
+function hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash;
+    }
+    return 'h_' + Math.abs(hash).toString(16);
+}
+/**
+ * Send telemetry event (non-blocking, fire-and-forget)
+ */
+export async function sendTelemetry(event, data, agentId) {
+    if (!telemetryEnabled)
+        return;
+    const payload = {
+        event,
+        sdk_version: SDK_VERSION,
+        timestamp: new Date().toISOString(),
+        session_id: getSessionId(),
+        agent_hash: agentId ? hashString(agentId) : undefined,
+        data
+    };
+    // Fire and forget - don't await or catch errors
+    // This ensures telemetry never blocks or crashes the SDK
+    try {
+        fetch(TELEMETRY_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload)
+        }).catch(() => {
+            // Silently ignore telemetry failures
+        });
+    }
+    catch {
+        // Silently ignore
+    }
+}
+/**
+ * Track SDK initialization
+ */
+export function trackInit() {
+    sendTelemetry('sdk_init');
+}
+/**
+ * Track authentication
+ */
+export function trackAuth(isNewAgent, agentId) {
+    sendTelemetry(isNewAgent ? 'sdk_auth_new_agent' : 'sdk_auth_success', { is_new_agent: isNewAgent }, agentId);
+}
+/**
+ * Track trade selection
+ */
+export function trackTradeSelect(trade, agentId) {
+    sendTelemetry('sdk_trade_select', { trade }, agentId);
+}
+/**
+ * Track local product creation
+ */
+export function trackProductCreate(agentId) {
+    sendTelemetry('sdk_product_create', {}, agentId);
+}
+/**
+ * Track sync
+ */
+export function trackSync(success, productsCount, agentId) {
+    sendTelemetry(success ? 'sdk_sync_success' : 'sdk_sync_fail', { products_count: productsCount }, agentId);
+}
+/**
+ * Track purchase
+ */
+export function trackPurchase(agentId) {
+    sendTelemetry('sdk_purchase', {}, agentId);
+}
+/**
+ * Track error
+ */
+export function trackError(errorType, errorMessage, agentId) {
+    sendTelemetry('sdk_error', { error_type: errorType, error_message: errorMessage }, agentId);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpsovereign/sdk",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "TypeScript SDK for mcpSovereign - The AI Agent Marketplace",
   "type": "module",
   "main": "dist/index.js",