monora-ai 2.0.0 → 2.1.3

package/dist/attribution.js

@@ -0,0 +1,987 @@
+"use strict";
+/**
+ * Attribution and project registration for Monora SDK.
+ *
+ * This module provides opt-in attribution and telemetry features to help
+ * improve the SDK and understand usage patterns.
+ *
+ * @example
+ * ```typescript
+ * import { registerProject, reportUsage, enableTelemetry } from 'monora-ai';
+ *
+ * // Register your project (optional but encouraged)
+ * registerProject({
+ *   company: 'Acme Corp',
+ *   role: 'ML Engineer',
+ *   email: 'dev@acme.com',
+ *   source: 'npm',
+ *   useCase: 'Customer Support AI',
+ * });
+ *
+ * // Enable and report usage (opt-in)
+ * enableTelemetry({ sendData: true });
+ * reportUsage({ framework: 'nextjs', environment: 'production' });
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInstallId = getInstallId;
+exports.registerProject = registerProject;
+exports.getRegistration = getRegistration;
+exports.enableTelemetry = enableTelemetry;
+exports.disableTelemetry = disableTelemetry;
+exports.isTelemetryEnabled = isTelemetryEnabled;
+exports.recordFeatureUsage = recordFeatureUsage;
+exports.getFeaturesUsed = getFeaturesUsed;
+exports.buildUsageReport = buildUsageReport;
+exports.reportUsage = reportUsage;
+exports.onAttributionEvent = onAttributionEvent;
+exports.setDataResidency = setDataResidency;
+exports.getDataResidency = getDataResidency;
+exports.configureHttp = configureHttp;
+exports.sendTelemetryEvent = sendTelemetryEvent;
+exports.setAuditMetadata = setAuditMetadata;
+exports.getAuditMetadata = getAuditMetadata;
+exports.hasShownFirstRunPrompt = hasShownFirstRunPrompt;
+exports.hasRegistration = hasRegistration;
+exports.promptForRegistration = promptForRegistration;
+exports.showFirstRunPromptIfNeeded = showFirstRunPromptIfNeeded;
+exports.resetFirstRunPrompt = resetFirstRunPrompt;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+// HTTP configuration (can be overridden via config or environment)
+// Note: Uses seconds (not milliseconds) for cross-SDK parity with Python
+const HTTP_CONFIG = {
+    endpoints: {
+        us: process.env.MONORA_ATTRIBUTION_ENDPOINT_US || null,
+        eu: process.env.MONORA_ATTRIBUTION_ENDPOINT_EU || null,
+    },
+    apiKeyEnv: 'MONORA_ATTRIBUTION_KEY',
+    timeoutSec: 5,
+    retryAttempts: 2,
+    backoffBaseSec: 0.5,
+};
+const retryQueue = [];
+const MAX_RETRY_QUEUE_SIZE = 100;
+let retryTimer = null;
+// Get version from package.json
+let SDK_VERSION = '2.1.3';
+try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    if (fs.existsSync(pkgPath)) {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+        SDK_VERSION = pkg.version || SDK_VERSION;
+    }
+}
+catch {
+    // Use default version
+}
+// Installation ID storage path
+const INSTALL_ID_PATH = path.join(os.homedir(), '.monora', 'install_id');
+const ATTRIBUTION_STATE_PATH = path.join(os.homedir(), '.monora', 'attribution.json');
+// Registration from postinstall script (collected during npm install)
+const POSTINSTALL_REGISTRATION_PATH = path.join(os.homedir(), '.monora', 'registration.json');
+// First-run prompt state
+const FIRST_RUN_PROMPT_PATH = path.join(os.homedir(), '.monora', 'first_run_prompt.json');
+// Callback registry
+const attributionCallbacks = [];
+// Global state
+let currentRegistration = null;
+let telemetryEnabled = false;
+let sendDataEnabled = false;
+let dataResidency = null;
+let registrationSentAt = null;
+const featuresUsed = new Set();
+let auditMetadata = null;
+let stateLoaded = false;
+function cleanPayload(payload) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (typeof value === 'string' && value.trim() === '') {
+            continue;
+        }
+        if (Array.isArray(value) && value.length === 0) {
+            continue;
+        }
+        if (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0) {
+            continue;
+        }
+        cleaned[key] = value;
+    }
+    return cleaned;
+}
+function normalizeRegistrationPayload(payload) {
+    return cleanPayload({
+        company: payload.company,
+        role: payload.role,
+        email: payload.email,
+        source: payload.source,
+        useCase: payload.useCase ?? payload.use_case,
+        teamSize: payload.teamSize ?? payload.team_size,
+        businessOwner: payload.businessOwner ?? payload.business_owner,
+        dataCategories: payload.dataCategories ?? payload.data_categories,
+        tags: payload.tags,
+        registeredAt: payload.registeredAt ?? payload.registered_at,
+    });
+}
+function normalizeAuditPayload(payload) {
+    return cleanPayload({
+        useCaseName: payload.useCaseName ?? payload.use_case_name,
+        businessOwner: payload.businessOwner ?? payload.business_owner,
+        dataCategories: payload.dataCategories ?? payload.data_categories,
+        riskLevel: payload.riskLevel ?? payload.risk_level,
+        complianceFrameworks: payload.complianceFrameworks ?? payload.compliance_frameworks,
+        reviewDate: payload.reviewDate ?? payload.review_date,
+        reviewer: payload.reviewer,
+        notes: payload.notes,
+    });
+}
+function ensureStateLoaded() {
+    if (stateLoaded) {
+        return;
+    }
+    stateLoaded = true;
+    try {
+        if (!fs.existsSync(ATTRIBUTION_STATE_PATH)) {
+            // Try loading from postinstall registration if attribution state doesn't exist
+            loadPostinstallRegistration();
+            return;
+        }
+        const raw = fs.readFileSync(ATTRIBUTION_STATE_PATH, 'utf8');
+        if (!raw.trim()) {
+            loadPostinstallRegistration();
+            return;
+        }
+        const data = JSON.parse(raw);
+        if (data.registration || data.project_registration) {
+            currentRegistration = normalizeRegistrationPayload(data.registration || data.project_registration);
+        }
+        if (data.audit_metadata || data.audit) {
+            auditMetadata = normalizeAuditPayload(data.audit_metadata || data.audit);
+        }
+        if (data.telemetry && typeof data.telemetry === 'object') {
+            if (typeof data.telemetry.enabled === 'boolean') {
+                telemetryEnabled = data.telemetry.enabled;
+            }
+            if (typeof data.telemetry.send_data === 'boolean') {
+                sendDataEnabled = data.telemetry.send_data;
+            }
+            if (data.telemetry.data_residency !== undefined) {
+                dataResidency = data.telemetry.data_residency;
+            }
+        }
+        if (typeof data.registration_sent_at === 'string') {
+            registrationSentAt = data.registration_sent_at;
+        }
+        // If no registration in attribution state, try postinstall
+        if (!currentRegistration) {
+            loadPostinstallRegistration();
+        }
+    }
+    catch {
+        // Ignore persistence errors
+    }
+}
+/**
+ * Load registration data from postinstall script (collected during npm install).
+ */
+function loadPostinstallRegistration() {
+    try {
+        if (!fs.existsSync(POSTINSTALL_REGISTRATION_PATH)) {
+            return;
+        }
+        const raw = fs.readFileSync(POSTINSTALL_REGISTRATION_PATH, 'utf8');
+        if (!raw.trim()) {
+            return;
+        }
+        const data = JSON.parse(raw);
+        if (data && typeof data === 'object') {
+            currentRegistration = normalizeRegistrationPayload(data);
+            // Save to attribution state for future use
+            saveState();
+        }
+    }
+    catch {
+        // Ignore errors loading postinstall registration
+    }
+}
+function saveState() {
+    ensureStateLoaded();
+    try {
+        const dir = path.dirname(ATTRIBUTION_STATE_PATH);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        const payload = {
+            telemetry: {
+                enabled: telemetryEnabled,
+                send_data: sendDataEnabled,
+                data_residency: dataResidency,
+            },
+            updated_at: new Date().toISOString(),
+        };
+        if (currentRegistration) {
+            payload.registration = cleanPayload({
+                company: currentRegistration.company,
+                role: currentRegistration.role,
+                email: currentRegistration.email,
+                source: currentRegistration.source,
+                use_case: currentRegistration.useCase,
+                team_size: currentRegistration.teamSize,
+                business_owner: currentRegistration.businessOwner,
+                data_categories: currentRegistration.dataCategories,
+                tags: currentRegistration.tags,
+                registered_at: currentRegistration.registeredAt,
+            });
+        }
+        if (auditMetadata) {
+            payload.audit_metadata = cleanPayload({
+                use_case_name: auditMetadata.useCaseName,
+                business_owner: auditMetadata.businessOwner,
+                data_categories: auditMetadata.dataCategories,
+                risk_level: auditMetadata.riskLevel,
+                compliance_frameworks: auditMetadata.complianceFrameworks,
+                review_date: auditMetadata.reviewDate,
+                reviewer: auditMetadata.reviewer,
+                notes: auditMetadata.notes,
+            });
+        }
+        if (registrationSentAt) {
+            payload.registration_sent_at = registrationSentAt;
+        }
+        fs.writeFileSync(ATTRIBUTION_STATE_PATH, JSON.stringify(payload, null, 2));
+    }
+    catch {
+        // Ignore persistence errors
+    }
+}
+/**
+ * Get or create a persistent anonymous installation ID.
+ *
+ * The ID is a hash of a random UUID, stored locally.
+ * No personally identifiable information is included.
+ *
+ * @returns Anonymous installation ID string.
+ */
+function getInstallId() {
+    try {
+        const dir = path.dirname(INSTALL_ID_PATH);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        if (fs.existsSync(INSTALL_ID_PATH)) {
+            const installId = fs.readFileSync(INSTALL_ID_PATH, 'utf8').trim();
+            if (installId) {
+                return installId;
+            }
+        }
+        // Generate new anonymous ID
+        const rawId = crypto.randomUUID();
+        const installId = crypto.createHash('sha256').update(rawId).digest('hex').slice(0, 32);
+        fs.writeFileSync(INSTALL_ID_PATH, installId);
+        return installId;
+    }
+    catch {
+        // Fallback to session-only ID if file access fails
+        return crypto.createHash('sha256').update(crypto.randomUUID()).digest('hex').slice(0, 32);
+    }
+}
+/**
+ * Register your project with Monora (optional but encouraged).
+ *
+ * This helps us understand who is using the SDK and improve the product.
+ * All fields are optional. Data is only sent if telemetry is enabled.
+ *
+ * @param options - Registration options.
+ * @returns ProjectRegistration object.
+ *
+ * @example
+ * ```typescript
+ * registerProject({
+ *   company: 'Acme Corp',
+ *   role: 'ML Engineer',
+ *   useCase: 'Customer Support AI',
+ *   dataCategories: ['customer_data'],
+ * });
+ * ```
+ */
+function registerProject(options) {
+    ensureStateLoaded();
+    const registration = {
+        ...options,
+        registeredAt: new Date().toISOString(),
+    };
+    currentRegistration = registration;
+    registrationSentAt = null;
+    // Notify callbacks
+    for (const callback of attributionCallbacks.slice()) {
+        try {
+            callback({ type: 'project_registered', data: registration });
+        }
+        catch {
+            // Ignore callback errors
+        }
+    }
+    // Send if telemetry enabled
+    if (telemetryEnabled && sendDataEnabled) {
+        sendRegistration(registration);
+        registrationSentAt = new Date().toISOString();
+    }
+    saveState();
+    return registration;
+}
+/**
+ * Get the current project registration.
+ *
+ * @returns Current ProjectRegistration or null if not registered.
+ */
+function getRegistration() {
+    ensureStateLoaded();
+    return currentRegistration;
+}
+/**
+ * Enable anonymous usage telemetry.
+ *
+ * By default, telemetry data stays local. Set sendData=true to
+ * share anonymous usage data with Monora to help improve the SDK.
+ *
+ * @param options - Telemetry options.
+ *
+ * @example
+ * ```typescript
+ * enableTelemetry({ sendData: true, dataResidency: 'eu' });
+ * ```
+ */
+function enableTelemetry(options = {}) {
+    ensureStateLoaded();
+    telemetryEnabled = true;
+    sendDataEnabled = options.sendData ?? false;
+    dataResidency = options.dataResidency ?? null;
+    if (sendDataEnabled && currentRegistration && !registrationSentAt) {
+        sendRegistration(currentRegistration);
+        registrationSentAt = new Date().toISOString();
+    }
+    saveState();
+}
+/**
+ * Disable usage telemetry.
+ *
+ * No data will be collected or sent after this call.
+ */
+function disableTelemetry() {
+    ensureStateLoaded();
+    telemetryEnabled = false;
+    sendDataEnabled = false;
+    saveState();
+}
+/**
+ * Check if telemetry is enabled.
+ *
+ * @returns True if telemetry is enabled.
+ */
+function isTelemetryEnabled() {
+    ensureStateLoaded();
+    return telemetryEnabled;
+}
+/**
+ * Record that a feature was used (internal).
+ *
+ * This is called internally by SDK components to track which
+ * features are being used. No sensitive data is recorded.
+ *
+ * @param feature - Feature name (e.g., "signing", "wal", "circuit_breaker").
+ */
+function recordFeatureUsage(feature) {
+    featuresUsed.add(feature);
+}
+/**
+ * Get list of features used in this session.
+ *
+ * @returns Sorted list of feature names.
+ */
+function getFeaturesUsed() {
+    return Array.from(featuresUsed).sort();
+}
+/**
+ * Build an anonymous usage report.
+ *
+ * @param options - Report options.
+ * @returns UsageReport object with anonymous data.
+ */
+function buildUsageReport(options = {}) {
+    ensureStateLoaded();
+    return {
+        installId: getInstallId(),
+        sdkVersion: SDK_VERSION,
+        nodeVersion: process.version,
+        osName: os.platform(),
+        osVersion: os.release(),
+        framework: options.framework,
+        featuresUsed: getFeaturesUsed(),
+        environment: options.environment ?? 'development',
+        reportedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Report anonymous usage data (if telemetry enabled).
+ *
+ * This sends anonymous usage data to help improve the SDK.
+ * Only called if telemetry is enabled with sendData=true.
+ *
+ * @param options - Report options.
+ * @returns UsageReport object.
+ *
+ * @example
+ * ```typescript
+ * enableTelemetry({ sendData: true });
+ * reportUsage({ framework: 'nextjs', environment: 'production' });
+ * ```
+ */
+function reportUsage(options = {}) {
+    ensureStateLoaded();
+    const report = buildUsageReport(options);
+    // Notify callbacks
+    for (const callback of attributionCallbacks.slice()) {
+        try {
+            callback({ type: 'usage_reported', data: report });
+        }
+        catch {
+            // Ignore callback errors
+        }
+    }
+    // Send if enabled
+    if (telemetryEnabled && sendDataEnabled) {
+        sendUsageReport(report);
+    }
+    return report;
+}
+/**
+ * Register a callback for attribution events.
+ *
+ * Use this to hook into attribution events for your own logging
+ * or monitoring stack.
+ *
+ * @param callback - Function called with event data.
+ * @returns Unsubscribe function.
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = onAttributionEvent((event) => {
+ *   console.log(`Attribution event: ${event.type}`);
+ * });
+ * // Later: unsubscribe();
+ * ```
+ */
+function onAttributionEvent(callback) {
+    attributionCallbacks.push(callback);
+    return () => {
+        const index = attributionCallbacks.indexOf(callback);
+        if (index !== -1) {
+            attributionCallbacks.splice(index, 1);
+        }
+    };
+}
+/**
+ * Set data residency region.
+ *
+ * @param region - Region code ("us", "eu", or "none" to disable sending).
+ */
+function setDataResidency(region) {
+    ensureStateLoaded();
+    dataResidency = region;
+    saveState();
+}
+/**
+ * Get current data residency setting.
+ *
+ * @returns Region code or null.
+ */
+function getDataResidency() {
+    ensureStateLoaded();
+    return dataResidency;
+}
+/**
+ * Configure HTTP settings from Monora config (internal).
+ *
+ * Called by runtime.init() to pass endpoint configuration.
+ */
+function configureHttp(config) {
+    if (!config)
+        return;
+    if (config.endpoints) {
+        if (config.endpoints.us)
+            HTTP_CONFIG.endpoints.us = config.endpoints.us;
+        if (config.endpoints.eu)
+            HTTP_CONFIG.endpoints.eu = config.endpoints.eu;
+    }
+    if (config.apiKeyEnv)
+        HTTP_CONFIG.apiKeyEnv = config.apiKeyEnv;
+    if (config.timeoutSec)
+        HTTP_CONFIG.timeoutSec = config.timeoutSec;
+    if (config.retryAttempts)
+        HTTP_CONFIG.retryAttempts = config.retryAttempts;
+    if (config.backoffBaseSec)
+        HTTP_CONFIG.backoffBaseSec = config.backoffBaseSec;
+}
+function getEndpoint(endpointType) {
+    ensureStateLoaded();
+    const residency = dataResidency || 'us';
+    if (residency === 'none')
+        return null;
+    const baseUrl = HTTP_CONFIG.endpoints[residency] || HTTP_CONFIG.endpoints.us;
+    if (!baseUrl)
+        return null;
+    return `${baseUrl}/${endpointType}`;
+}
+function getApiKey() {
+    return process.env[HTTP_CONFIG.apiKeyEnv] || null;
+}
+async function makeRequest(url, data, timeout, retries) {
+    const apiKey = getApiKey();
+    if (!apiKey)
+        return false;
+    // Convert seconds to milliseconds for setTimeout
+    const effectiveTimeout = (timeout ?? HTTP_CONFIG.timeoutSec) * 1000;
+    const effectiveRetries = retries ?? HTTP_CONFIG.retryAttempts;
+    const payload = JSON.stringify({
+        ...data,
+        sdk_type: 'node',
+        sdk_version: SDK_VERSION,
+    });
+    const parsedUrl = new URL(url);
+    const isHttps = parsedUrl.protocol === 'https:';
+    const requestModule = isHttps ? https : http;
+    const options = {
+        hostname: parsedUrl.hostname,
+        port: parsedUrl.port || (isHttps ? 443 : 80),
+        path: parsedUrl.pathname + parsedUrl.search,
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(payload),
+            apikey: apiKey,
+            Authorization: `Bearer ${apiKey}`,
+            'x-monora-sdk-type': 'node',
+            'x-monora-sdk-version': SDK_VERSION,
+            'x-data-residency': dataResidency || 'us',
+        },
+        timeout: effectiveTimeout,
+    };
+    for (let attempt = 0; attempt <= effectiveRetries; attempt++) {
+        try {
+            const success = await new Promise((resolve) => {
+                const req = requestModule.request(options, (res) => {
+                    let body = '';
+                    res.on('data', (chunk) => {
+                        body += chunk.toString();
+                    });
+                    res.on('end', () => {
+                        if (res.statusCode === 200) {
+                            resolve(true);
+                        }
+                        else if (res.statusCode === 429) {
+                            resolve(false);
+                        }
+                        else {
+                            resolve(false);
+                        }
+                    });
+                });
+                req.on('error', () => resolve(false));
+                req.on('timeout', () => {
+                    req.destroy();
+                    resolve(false);
+                });
+                req.write(payload);
+                req.end();
+            });
+            if (success)
+                return true;
+            if (attempt < effectiveRetries) {
+                // Convert seconds to milliseconds for setTimeout
+                const delay = HTTP_CONFIG.backoffBaseSec * 1000 * Math.pow(2, attempt) + Math.random() * 100;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+        catch {
+            if (attempt < effectiveRetries) {
+                // Convert seconds to milliseconds for setTimeout
+                const delay = HTTP_CONFIG.backoffBaseSec * 1000 * Math.pow(2, attempt) + Math.random() * 100;
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+        }
+    }
+    return false;
+}
+function sendAsync(endpointType, data) {
+    const url = getEndpoint(endpointType);
+    if (!url)
+        return;
+    makeRequest(url, data)
+        .then((success) => {
+        if (!success) {
+            queueForRetry(endpointType, data);
+        }
+    })
+        .catch(() => {
+        queueForRetry(endpointType, data);
+    });
+}
+function queueForRetry(endpointType, data) {
+    if (retryQueue.length < MAX_RETRY_QUEUE_SIZE) {
+        retryQueue.push({
+            endpointType,
+            data,
+            queuedAt: new Date().toISOString(),
+        });
+    }
+    // Start retry timer if not already running
+    if (!retryTimer) {
+        retryTimer = setTimeout(processRetryQueue, 30000);
+        if (retryTimer.unref) {
+            retryTimer.unref(); // Don't block process exit
+        }
+    }
+}
+async function processRetryQueue() {
+    retryTimer = null;
+    while (retryQueue.length > 0) {
+        const item = retryQueue[0];
+        const url = getEndpoint(item.endpointType);
+        if (!url) {
+            retryQueue.shift();
+            continue;
+        }
+        const success = await makeRequest(url, item.data);
+        if (success) {
+            retryQueue.shift();
+        }
+        else {
+            // Stop on first failure to preserve order
+            break;
+        }
+    }
+    // Restart timer if queue still has items
+    if (retryQueue.length > 0) {
+        retryTimer = setTimeout(processRetryQueue, 30000);
+        if (retryTimer.unref) {
+            retryTimer.unref();
+        }
+    }
+}
+/**
+ * Send registration to Monora API (internal).
+ * Includes optional email if provided.
+ */
+function sendRegistration(registration) {
+    if (!sendDataEnabled)
+        return;
+    const data = {
+        install_id: getInstallId(),
+        company: registration.company,
+        role: registration.role,
+        email: registration.email,
+        source: registration.source,
+        use_case: registration.useCase,
+        team_size: registration.teamSize,
+        business_owner: registration.businessOwner,
+        data_categories: registration.dataCategories,
+        tags: registration.tags,
+        registered_at: registration.registeredAt || new Date().toISOString(),
+    };
+    sendAsync('registration', cleanPayload(data));
+}
+/**
+ * Send usage report to Monora API (internal).
+ */
+function sendUsageReport(report) {
+    if (!sendDataEnabled)
+        return;
+    const data = {
+        install_id: report.installId,
+        runtime_version: report.nodeVersion,
+        os_name: report.osName,
+        os_version: report.osVersion,
+        framework: report.framework,
+        environment: report.environment,
+        features_used: report.featuresUsed,
+        reported_at: report.reportedAt || new Date().toISOString(),
+    };
+    sendAsync('usage-report', cleanPayload(data));
+}
+/**
+ * Send a telemetry event (e.g., startup, shutdown, error).
+ *
+ * This is called internally by the SDK to track usage patterns.
+ * Only sends if telemetry is enabled with sendData=true.
+ *
+ * @param options - Event options.
+ */
+function sendTelemetryEvent(options) {
+    ensureStateLoaded();
+    if (!telemetryEnabled || !sendDataEnabled)
+        return;
+    const { eventType, eventData, framework, environment = 'development' } = options;
+    const data = {
+        install_id: getInstallId(),
+        runtime_version: process.version,
+        os_name: os.platform(),
+        os_version: os.release(),
+        framework,
+        environment,
+        features_used: getFeaturesUsed(),
+        event_type: eventType,
+        event_data: eventData || {},
+        timestamp: new Date().toISOString(),
+    };
+    sendAsync('telemetry', cleanPayload(data));
+}
+/**
+ * Set audit metadata for compliance purposes.
+ *
+ * This metadata is included in compliance reports and can be used
+ * to satisfy audit requirements for SOC 2, GDPR, ISO 27001, etc.
+ *
+ * @param metadata - Audit metadata.
+ * @returns AuditMetadata object.
+ *
+ * @example
+ * ```typescript
+ * setAuditMetadata({
+ *   useCaseName: 'Customer Support AI',
+ *   businessOwner: 'Jane Smith',
+ *   dataCategories: ['customer_data', 'PII'],
+ *   riskLevel: 'medium',
+ *   complianceFrameworks: ['SOC2', 'GDPR'],
+ * });
+ * ```
+ */
+function setAuditMetadata(metadata) {
+    ensureStateLoaded();
+    auditMetadata = { ...metadata };
+    saveState();
+    return auditMetadata;
+}
+/**
+ * Get current audit metadata.
+ *
+ * @returns AuditMetadata object or null.
+ */
+function getAuditMetadata() {
+    ensureStateLoaded();
+    return auditMetadata;
+}
+/**
+ * Load the first-run prompt state from disk.
+ */
+function loadFirstRunPromptState() {
+    try {
+        if (!fs.existsSync(FIRST_RUN_PROMPT_PATH)) {
+            return null;
+        }
+        const raw = fs.readFileSync(FIRST_RUN_PROMPT_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save the first-run prompt state to disk.
+ */
+function saveFirstRunPromptState(state) {
+    try {
+        const dir = path.dirname(FIRST_RUN_PROMPT_PATH);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(FIRST_RUN_PROMPT_PATH, JSON.stringify(state, null, 2));
+    }
+    catch {
+        // Silent fail - don't break user's app
+    }
+}
+/**
+ * Check if first-run registration prompt has been shown.
+ *
+ * @returns True if already prompted, false otherwise.
+ */
+function hasShownFirstRunPrompt() {
+    const state = loadFirstRunPromptState();
+    return state !== null && !!state.promptedAt;
+}
+/**
+ * Check if user has registered (either via postinstall or programmatically).
+ *
+ * @returns True if registered, false otherwise.
+ */
+function hasRegistration() {
+    ensureStateLoaded();
+    return currentRegistration !== null;
+}
+/**
+ * Prompt the user to register their project (interactive, optional).
+ *
+ * @param options - Optional context about the environment.
+ * @returns True if registration was completed, false otherwise.
+ */
+async function promptForRegistration(options) {
+    try {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            return false;
+        }
+        if (!options?.force) {
+            if (options?.environment === 'production') {
+                return false;
+            }
+            if (process.env.CI ||
+                process.env.GITHUB_ACTIONS ||
+                process.env.GITLAB_CI ||
+                process.env.MONORA_SKIP_PROMPT) {
+                return false;
+            }
+            if (hasRegistration()) {
+                return false;
+            }
+        }
+        if (options?.silent) {
+            return false;
+        }
+        console.log('');
+        console.log('Monora SDK optional project registration');
+        console.log('This helps us improve the SDK and share best practices.');
+        console.log('Email is stored locally and only sent if telemetry is enabled.');
+        console.log('');
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const ask = (question) => new Promise((resolve) => rl.question(question, (answer) => resolve(answer)));
+        try {
+            const confirm = (await ask('Register this project now? [y/N]: ')).trim().toLowerCase();
+            if (confirm !== 'y' && confirm !== 'yes') {
+                return false;
+            }
+            const company = (await ask('Company (optional): ')).trim() || undefined;
+            const role = (await ask('Role (optional): ')).trim() || undefined;
+            const email = (await ask('Work email (optional): ')).trim() || undefined;
+            const source = (await ask('How did you find Monora? (optional): ')).trim() || undefined;
+            const useCase = (await ask('Primary use case (optional): ')).trim() || undefined;
+            registerProject({
+                company,
+                role,
+                email,
+                source,
+                useCase,
+            });
+            return true;
+        }
+        finally {
+            rl.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Show first-run registration prompt if needed.
+ *
+ * This logs a one-time message suggesting the user run `npx monora init`
+ * to register their project for best practices updates. The message is
+ * only shown once per installation.
+ *
+ * @param options - Optional context about the environment.
+ * @returns True if prompt was shown, false if skipped.
+ */
+function showFirstRunPromptIfNeeded(options) {
+    // Skip in CI environments
+    if (process.env.CI ||
+        process.env.GITHUB_ACTIONS ||
+        process.env.GITLAB_CI ||
+        process.env.MONORA_SKIP_PROMPT) {
+        return false;
+    }
+    // Skip if already prompted
+    if (hasShownFirstRunPrompt()) {
+        return false;
+    }
+    // Skip if already registered
+    if (hasRegistration()) {
+        // Mark as prompted so we don't check again
+        saveFirstRunPromptState({
+            promptedAt: new Date().toISOString(),
+            sdkVersion: SDK_VERSION,
+            environment: options?.environment,
+        });
+        return false;
+    }
+    // Save state first to avoid showing multiple times in parallel inits
+    saveFirstRunPromptState({
+        promptedAt: new Date().toISOString(),
+        sdkVersion: SDK_VERSION,
+        environment: options?.environment,
+    });
+    // Show the prompt (unless silent mode)
+    if (!options?.silent) {
+        console.log('');
+        console.log('\x1b[36m[Monora]\x1b[0m Register your project for best practices updates:');
+        console.log('         Run: \x1b[33mnpx monora init\x1b[0m');
+        console.log('         Or skip this message by setting MONORA_SKIP_PROMPT=1');
+        console.log('');
+    }
+    return true;
+}
+/**
+ * Reset the first-run prompt state (for testing).
+ */
+function resetFirstRunPrompt() {
+    try {
+        if (fs.existsSync(FIRST_RUN_PROMPT_PATH)) {
+            fs.unlinkSync(FIRST_RUN_PROMPT_PATH);
+        }
+    }
+    catch {
+        // Silent fail
+    }
+}