@nordsym/apiclaw 2.1.0 → 2.2.0

package/src/funnel-client.ts

@@ -0,0 +1,168 @@
+/**
+ * APIClaw Funnel — client-side emitter for MCP server.
+ *
+ * Fire-and-forget POST to Convex funnel:recordEvent. Never throws, never
+ * blocks. See convex/funnel.ts for schema and classification rules.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const CONVEX_URL = process.env.CONVEX_URL || "https://adventurous-avocet-799.convex.cloud";
+
+export type FunnelEventName =
+  | "install"
+  | "first_run"
+  | "register_owner"
+  | "verify_code"
+  | "first_call_api_success"
+  // Diagnostics
+  | "register_owner_failed"
+  | "verify_code_failed"
+  | "call_api_blocked"
+  | "call_api_error"
+  | "quota_hit"
+  | "gateway_retry";
+
+export type Classification = "human" | "ci" | "bot" | "internal";
+
+const CI_ENV_KEYS = [
+  "CI",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "CIRCLECI",
+  "BUILDKITE",
+  "JENKINS_URL",
+  "TEAMCITY_VERSION",
+  "TRAVIS",
+  "BITBUCKET_BUILD_NUMBER",
+];
+
+const BOT_UA_MARKERS = [
+  "bot",
+  "crawl",
+  "spider",
+  "scanner",
+  "curl/",
+  "wget/",
+  "httpclient",
+  "python-requests",
+  "go-http-client",
+  "okhttp",
+  "java/",
+  "httrack",
+  "headlesschrome",
+  "phantomjs",
+];
+
+const INTERNAL_EMAIL_DOMAINS = ["nordsym.com", "apiclaw.cloud"];
+const INTERNAL_EMAIL_EXACT = ["gustav@nordsym.com", "gustavnordsync@gmail.com"];
+
+export function classifyLocalSource(input: {
+  userAgent?: string | null;
+  email?: string | null;
+  fingerprint?: string | null;
+  env?: NodeJS.ProcessEnv;
+}): Classification {
+  const email = (input.email || "").toLowerCase().trim();
+  if (email) {
+    if (INTERNAL_EMAIL_EXACT.includes(email)) return "internal";
+    const domain = email.split("@")[1] || "";
+    if (INTERNAL_EMAIL_DOMAINS.includes(domain)) return "internal";
+  }
+  const env = input.env || process.env;
+  for (const key of CI_ENV_KEYS) {
+    const val = env[key];
+    if (val && val !== "false" && val !== "0") return "ci";
+  }
+  const ua = (input.userAgent || "").toLowerCase();
+  if (ua) {
+    for (const m of BOT_UA_MARKERS) {
+      if (ua.includes(m)) return "bot";
+    }
+  }
+  return "human";
+}
+
+// Persistent first-run marker stored alongside the session file.
+const MARKER_DIR = path.join(os.homedir(), ".apiclaw");
+const MARKER_FILE = path.join(MARKER_DIR, "funnel-markers.json");
+
+function readMarkers(): Record<string, number> {
+  try {
+    if (!fs.existsSync(MARKER_FILE)) return {};
+    return JSON.parse(fs.readFileSync(MARKER_FILE, "utf8")) || {};
+  } catch {
+    return {};
+  }
+}
+
+function writeMarkers(m: Record<string, number>): void {
+  try {
+    if (!fs.existsSync(MARKER_DIR)) fs.mkdirSync(MARKER_DIR, { mode: 0o700 });
+    fs.writeFileSync(MARKER_FILE, JSON.stringify(m), { mode: 0o600 });
+  } catch {
+    /* ignore */
+  }
+}
+
+export function hasLocalMarker(key: string): boolean {
+  return !!readMarkers()[key];
+}
+
+export function setLocalMarker(key: string): void {
+  const m = readMarkers();
+  m[key] = Date.now();
+  writeMarkers(m);
+}
+
+export interface EmitArgs {
+  event: FunnelEventName;
+  workspaceId?: string;
+  fingerprint?: string;
+  sessionToken?: string;
+  email?: string;
+  mcpClient?: string;
+  platform?: string;
+  version?: string;
+  dedupeKey?: string;
+  props?: Record<string, unknown>;
+}
+
+export function emitFunnelEvent(args: EmitArgs): void {
+  if (process.env.APICLAW_TELEMETRY === "false") return;
+
+  const classification = classifyLocalSource({
+    email: args.email,
+    fingerprint: args.fingerprint,
+  });
+
+  const payload = {
+    path: "funnel:recordEvent",
+    args: {
+      event: args.event,
+      classification,
+      workspaceId: args.workspaceId,
+      fingerprint: args.fingerprint,
+      sessionToken: args.sessionToken,
+      email: args.email,
+      userAgent: `apiclaw-mcp/${args.version || "unknown"}`,
+      mcpClient: args.mcpClient,
+      platform: args.platform || process.platform,
+      version: args.version,
+      dedupeKey: args.dedupeKey,
+      props: args.props,
+    },
+  };
+
+  // Fire and forget.
+  try {
+    fetch(`${CONVEX_URL}/api/mutation`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    }).catch(() => {});
+  } catch {
+    /* ignore */
+  }
+}

package/src/funnel.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for funnel classification + registration guard + event canon.
+ * Run: npx tsx src/funnel.test.ts
+ */
+import { strict as assert } from 'node:assert';
+import { classifyLocalSource } from './funnel-client.js';
+import {
+  requireVerifiedOwner,
+  FREE_CALL_PATHS,
+  ENFORCED_CALL_PATHS,
+  type WorkspaceContextLike,
+} from './registration-guard.js';
+
+let failed = 0;
+let passed = 0;
+
+function test(name: string, fn: () => void) {
+  try {
+    fn();
+    console.log(`✅ ${name}`);
+    passed++;
+  } catch (e: any) {
+    console.log(`❌ ${name}`);
+    console.log(`   ${e.message || e}`);
+    failed++;
+  }
+}
+
+// ------------------------------------------------------------------
+// Classification
+// ------------------------------------------------------------------
+test('classify: human is default', () => {
+  assert.equal(classifyLocalSource({ env: {} }), 'human');
+});
+
+test('classify: CI env flag → ci', () => {
+  assert.equal(classifyLocalSource({ env: { CI: 'true' } }), 'ci');
+  assert.equal(classifyLocalSource({ env: { GITHUB_ACTIONS: '1' } }), 'ci');
+  assert.equal(classifyLocalSource({ env: { CIRCLECI: 'true' } }), 'ci');
+});
+
+test('classify: CI=false is NOT ci', () => {
+  assert.equal(classifyLocalSource({ env: { CI: 'false' } }), 'human');
+  assert.equal(classifyLocalSource({ env: { CI: '0' } }), 'human');
+});
+
+test('classify: bot UA → bot', () => {
+  assert.equal(classifyLocalSource({ env: {}, userAgent: 'curl/7.88' }), 'bot');
+  assert.equal(
+    classifyLocalSource({ env: {}, userAgent: 'Mozilla/5.0 (compatible; Googlebot/2.1)' }),
+    'bot'
+  );
+  assert.equal(classifyLocalSource({ env: {}, userAgent: 'python-requests/2.31' }), 'bot');
+});
+
+test('classify: internal email domain → internal', () => {
+  assert.equal(
+    classifyLocalSource({ env: {}, email: 'someone@nordsym.com' }),
+    'internal'
+  );
+  assert.equal(
+    classifyLocalSource({ env: {}, email: 'test@apiclaw.cloud' }),
+    'internal'
+  );
+});
+
+test('classify: internal exact email → internal (even with CI set)', () => {
+  assert.equal(
+    classifyLocalSource({
+      env: { CI: 'true' },
+      email: 'gustavnordsync@gmail.com',
+    }),
+    'internal'
+  );
+});
+
+test('classify: precedence internal > ci > bot > human', () => {
+  // internal wins over CI
+  assert.equal(
+    classifyLocalSource({ env: { CI: 'true' }, email: 'x@nordsym.com' }),
+    'internal'
+  );
+  // ci wins over bot
+  assert.equal(
+    classifyLocalSource({ env: { CI: 'true' }, userAgent: 'curl/8' }),
+    'ci'
+  );
+});
+
+// ------------------------------------------------------------------
+// requireVerifiedOwner
+// ------------------------------------------------------------------
+const good: WorkspaceContextLike = {
+  sessionToken: 'tok',
+  workspaceId: 'ws_1',
+  email: 'user@example.com',
+  tier: 'free',
+  status: 'active',
+  usageRemaining: 42,
+  usageCount: 8,
+};
+
+test('guard: no workspace → no_session', () => {
+  const r = requireVerifiedOwner(null);
+  assert.equal(r.ok, false);
+  if (!r.ok) assert.equal(r.reason, 'no_session');
+});
+
+test('guard: workspace without email → pending_verification', () => {
+  const r = requireVerifiedOwner({ ...good, email: '' });
+  assert.equal(r.ok, false);
+  if (!r.ok) assert.equal(r.reason, 'pending_verification');
+});
+
+test('guard: workspace status pending → not_verified', () => {
+  const r = requireVerifiedOwner({ ...good, status: 'pending' });
+  assert.equal(r.ok, false);
+  if (!r.ok) assert.equal(r.reason, 'not_verified');
+});
+
+test('guard: quota exhausted → quota_exceeded', () => {
+  const r = requireVerifiedOwner({ ...good, usageRemaining: 0 });
+  assert.equal(r.ok, false);
+  if (!r.ok) assert.equal(r.reason, 'quota_exceeded');
+});
+
+test('guard: happy path → ok', () => {
+  const r = requireVerifiedOwner(good);
+  assert.equal(r.ok, true);
+  if (r.ok) assert.equal(r.ctx.email, 'user@example.com');
+});
+
+test('guard: unlimited (usageRemaining=-1) → ok', () => {
+  const r = requireVerifiedOwner({ ...good, usageRemaining: -1 });
+  assert.equal(r.ok, true);
+});
+
+// ------------------------------------------------------------------
+// Enforcement matrix coverage
+// ------------------------------------------------------------------
+test('matrix: discover_apis is free', () => {
+  assert.equal(FREE_CALL_PATHS.has('discover_apis'), true);
+  assert.equal(ENFORCED_CALL_PATHS.has('discover_apis'), false);
+});
+
+test('matrix: call_api / capability / resume_chain are enforced', () => {
+  for (const p of ['call_api', 'capability', 'resume_chain']) {
+    assert.equal(ENFORCED_CALL_PATHS.has(p), true, `${p} should be enforced`);
+  }
+});
+
+test('matrix: register_owner + verify_code are free (they BECOME the auth)', () => {
+  assert.equal(FREE_CALL_PATHS.has('register_owner'), true);
+  assert.equal(FREE_CALL_PATHS.has('verify_code'), true);
+});
+
+test('matrix: free and enforced sets are disjoint', () => {
+  for (const p of FREE_CALL_PATHS) {
+    assert.equal(ENFORCED_CALL_PATHS.has(p), false, `${p} is in both sets`);
+  }
+});
+
+// ------------------------------------------------------------------
+// Event canon type surface
+// ------------------------------------------------------------------
+import type { FunnelEventName } from './funnel-client.js';
+
+test('event canon: all 11 approved events are typed', () => {
+  const names: FunnelEventName[] = [
+    'install',
+    'first_run',
+    'register_owner',
+    'verify_code',
+    'first_call_api_success',
+    'register_owner_failed',
+    'verify_code_failed',
+    'call_api_blocked',
+    'call_api_error',
+    'quota_hit',
+    'gateway_retry',
+  ];
+  assert.equal(names.length, 11);
+});
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/src/index.ts

@@ -45,6 +45,8 @@ import {
 } from './confirmation.js';
 import { executeCapability, listCapabilities, hasCapability } from './capability-router.js';
 import { readSession, writeSession, clearSession, getMachineFingerprint, detectMCPClient, SessionData } from './session.js';
+import { requireVerifiedOwner, type WorkspaceContextLike } from './registration-guard.js';
+import { emitFunnelEvent, hasLocalMarker, setLocalMarker } from './funnel-client.js';
 import { ConvexHttpClient } from 'convex/browser';
 import { 
   getOrCreateCustomer, 
@@ -342,6 +344,52 @@ function checkWorkspaceAccess(providerId?: string): { allowed: boolean; error?:
   return { allowed: true, isAnonymous: false };
 }
 
+/**
+ * Single enforcement entry point for every paying call path.
+ * Returns either a verified workspace context or an MCP-formatted block response.
+ */
+function enforceOwner(channel: string):
+  | { ok: true; ctx: WorkspaceContextLike }
+  | { ok: false; response: { content: { type: 'text'; text: string }[]; isError: true } } {
+  const result = requireVerifiedOwner(workspaceContext as WorkspaceContextLike | null);
+  if (result.ok) {
+    return { ok: true, ctx: result.ctx };
+  }
+  // Diagnostic: record why the call was blocked.
+  try {
+    emitFunnelEvent({
+      event: 'call_api_blocked',
+      workspaceId: workspaceContext?.workspaceId,
+      email: workspaceContext?.email,
+      fingerprint: getMachineFingerprint(),
+      mcpClient: detectMCPClient(),
+      platform: process.platform,
+      version: process.env.npm_package_version || 'unknown',
+      props: { reason: result.reason, channel },
+    });
+    if (result.reason === 'quota_exceeded') {
+      emitFunnelEvent({
+        event: 'quota_hit',
+        workspaceId: workspaceContext?.workspaceId,
+        email: workspaceContext?.email,
+        fingerprint: getMachineFingerprint(),
+        version: process.env.npm_package_version || 'unknown',
+        props: { tier: workspaceContext?.tier, limit: workspaceContext?.usageCount },
+      });
+    }
+  } catch { /* non-blocking */ }
+  return {
+    ok: false,
+    response: {
+      content: [{ type: 'text', text: JSON.stringify(result.payload, null, 2) }],
+      isError: true,
+    },
+  };
+}
+
+// Per-process marker: ensure first_call_api_success fires once per server boot.
+let firstCallEmitted = false;
+
 /**
  * Get customer API key from environment variable
  * Convention: {PROVIDER}_API_KEY (e.g., COACCEPT_API_KEY, ELKS_API_KEY)
@@ -1182,23 +1230,10 @@ Docs: https://apiclaw.cloud
 
       case 'call_api': {
         // ============================================
-        // REGISTRATION GATE: require email before any API call
+        // REGISTRATION GATE: requireVerifiedOwner (single source of truth)
         // ============================================
-        if (!workspaceContext) {
-          return {
-            content: [{
-              type: 'text',
-              text: JSON.stringify({
-                status: 'registration_required',
-                error: 'You need to register before making API calls.',
-                message: 'APIClaw requires a free account to use APIs. Ask the user for their email address, then call register_owner({ email: "user@example.com" }). A 6-digit verification code will be sent to their email. Then call verify_code with the code.',
-                action: 'register_owner',
-                free_tier: '50 API calls/month, unlimited discovery -- completely free.',
-              }, null, 2)
-            }],
-            isError: true
-          };
-        }
+        const gate = enforceOwner("mcp:call_api");
+        if (!gate.ok) return gate.response;
 
         const provider = args?.provider as string;
         const action = args?.action as string;
@@ -1229,34 +1264,7 @@ Docs: https://apiclaw.cloud
         // CHAIN EXECUTION MODE
         // ============================================
         if (chain && Array.isArray(chain) && chain.length > 0) {
-          // Check workspace access for chains
-          const access = checkWorkspaceAccess();
-          if (!access.allowed) {
-            // If error is already formatted JSON (from rate limit checks), return as-is
-            if (access.error?.startsWith('{')) {
-              return {
-                content: [{
-                  type: 'text',
-                  text: access.error
-                }],
-                isError: true
-              };
-            }
-            
-            // Otherwise, wrap in standard error format
-            return {
-              content: [{
-                type: 'text',
-                text: JSON.stringify({
-                  status: 'error',
-                  error: access.error,
-                  hint: 'Use register_owner to authenticate your workspace.',
-                }, null, 2)
-              }],
-              isError: true
-            };
-          }
-          
+          // Gate already enforced at top of call_api via enforceOwner().
           try {
             // Construct ChainDefinition from the input
             const chainDefinition: ChainDefinition = {
@@ -1627,6 +1635,39 @@ Docs: https://apiclaw.cloud
           workspaceContext.usageCount = (workspaceContext.usageCount || 0) + 1;
         }
 
+        // Funnel: call_api_error (provider-level failure)
+        if (!result.success && workspaceContext) {
+          emitFunnelEvent({
+            event: 'call_api_error',
+            workspaceId: workspaceContext.workspaceId,
+            email: workspaceContext.email,
+            fingerprint: getMachineFingerprint(),
+            version: process.env.npm_package_version || 'unknown',
+            props: {
+              provider: result.provider || provider,
+              action: result.action || action,
+              errorCode: (result.error || '').slice(0, 80) || 'unknown',
+            },
+          });
+        }
+
+        // Funnel: first_call_api_success (once per workspace, deduped server-side)
+        if (result.success && workspaceContext && !isFreeAPI && !firstCallEmitted) {
+          firstCallEmitted = true;
+          emitFunnelEvent({
+            event: 'first_call_api_success',
+            email: workspaceContext.email,
+            workspaceId: workspaceContext.workspaceId,
+            sessionToken: workspaceContext.sessionToken,
+            fingerprint: getMachineFingerprint(),
+            mcpClient: detectMCPClient(),
+            platform: process.platform,
+            version: process.env.npm_package_version || 'unknown',
+            dedupeKey: `first_call:${workspaceContext.workspaceId}`,
+            props: { provider, action, channel: 'mcp:call_api' },
+          });
+        }
+
         // Build response with signup nudge for unregistered users
         const responseData: Record<string, unknown> = {
           status: result.success ? 'success' : 'error',
@@ -1683,21 +1724,9 @@ Docs: https://apiclaw.cloud
       }
 
       case 'capability': {
-        // Registration gate
-        if (!workspaceContext) {
-          return {
-            content: [{
-              type: 'text',
-              text: JSON.stringify({
-                status: 'registration_required',
-                error: 'You need to register before making API calls.',
-                message: 'Ask the user for their email, then call register_owner({ email: "..." }). A 6-digit code will be sent. Then call verify_code with the code.',
-                action: 'register_owner',
-              }, null, 2)
-            }],
-            isError: true
-          };
-        }
+        // Registration gate: requireVerifiedOwner (single source of truth)
+        const capGate = enforceOwner("mcp:capability");
+        if (!capGate.ok) return capGate.response;
 
         const capabilityId = args?.capability as string;
         const action = args?.action as string;
@@ -1793,6 +1822,14 @@ Docs: https://apiclaw.cloud
         const email = args?.email as string;
 
         if (!email || !email.includes('@')) {
+          emitFunnelEvent({
+            event: 'register_owner_failed',
+            email,
+            fingerprint: getMachineFingerprint(),
+            mcpClient: detectMCPClient(),
+            version: process.env.npm_package_version || 'unknown',
+            props: { reason: 'invalid_email' },
+          });
           return {
             content: [{
               type: 'text',
@@ -1895,12 +1932,30 @@ Docs: https://apiclaw.cloud
 
           if (!emailResponse.ok) {
             const errorData = await emailResponse.text();
+            emitFunnelEvent({
+              event: 'register_owner_failed',
+              email,
+              fingerprint: getMachineFingerprint(),
+              mcpClient: detectMCPClient(),
+              version: process.env.npm_package_version || 'unknown',
+              props: { reason: 'email_send_failed' },
+            });
             throw new Error(`Failed to send verification email: ${errorData}`);
           }
 
           // Store pending email for verify_code
           pendingRegistrationEmail = email;
 
+          // Funnel: register_owner
+          emitFunnelEvent({
+            event: 'register_owner',
+            email,
+            fingerprint: getMachineFingerprint(),
+            mcpClient: detectMCPClient(),
+            platform: process.platform,
+            version: process.env.npm_package_version || 'unknown',
+          });
+
           return {
             content: [{
               type: 'text',
@@ -1966,6 +2021,19 @@ Docs: https://apiclaw.cloud
               await convex.mutation("workspaces:incrementOTPAttempt" as any, { email, code: code.trim() });
             } catch (_) {}
 
+            const reason =
+              result.error === 'code_expired' ? 'expired'
+              : result.error === 'attempts_exceeded' ? 'attempts_exceeded'
+              : 'invalid';
+            emitFunnelEvent({
+              event: 'verify_code_failed',
+              email,
+              fingerprint: getMachineFingerprint(),
+              mcpClient: detectMCPClient(),
+              version: process.env.npm_package_version || 'unknown',
+              props: { reason },
+            });
+
             return {
               content: [{
                 type: 'text',
@@ -2008,6 +2076,20 @@ Docs: https://apiclaw.cloud
 
           pendingRegistrationEmail = null;
 
+          // Funnel: verify_code (dedupe per workspace so re-verifies don't double-count)
+          emitFunnelEvent({
+            event: 'verify_code',
+            email: result.workspace!.email,
+            workspaceId: result.workspace!.id,
+            fingerprint: getMachineFingerprint(),
+            sessionToken: result.sessionToken,
+            mcpClient: detectMCPClient(),
+            platform: process.platform,
+            version: process.env.npm_package_version || 'unknown',
+            dedupeKey: `verify_code:${result.workspace!.id}`,
+            props: { isNewUser: !!result.isNewUser },
+          });
+
           return {
             content: [{
               type: 'text',
@@ -2418,22 +2500,10 @@ Docs: https://apiclaw.cloud
           };
         }
         
-        // Check workspace access
-        const access = checkWorkspaceAccess();
-        if (!access.allowed) {
-          return {
-            content: [{
-              type: 'text',
-              text: JSON.stringify({
-                status: 'error',
-                error: access.error,
-                hint: 'Use register_owner to authenticate your workspace.',
-              }, null, 2)
-            }],
-            isError: true
-          };
-        }
-        
+        // Registration gate: requireVerifiedOwner (single source of truth)
+        const resumeGate = enforceOwner("mcp:resume_chain");
+        if (!resumeGate.ok) return resumeGate.response;
+
         try {
           // Note: The resume_chain function requires the original chain definition
           // In practice, you'd store this or require the caller to provide it
@@ -2556,7 +2626,28 @@ async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   trackStartup();
-  
+
+  // Funnel: first_run (once per fingerprint, persisted across restarts)
+  try {
+    const fp = getMachineFingerprint();
+    const mcpClient = detectMCPClient();
+    const version = process.env.npm_package_version || 'unknown';
+    const dedupeKey = `first_run:${fp}`;
+    if (!hasLocalMarker(dedupeKey)) {
+      emitFunnelEvent({
+        event: 'first_run',
+        fingerprint: fp,
+        mcpClient,
+        platform: process.platform,
+        version,
+        dedupeKey,
+      });
+      setLocalMarker(dedupeKey);
+    }
+  } catch {
+    /* non-blocking */
+  }
+
   // Validate session on startup
   const hasValidSession = await validateSession();