@nordsym/apiclaw 2.1.0 → 2.2.0

package/dist/funnel.test.js

@@ -0,0 +1,145 @@
+/**
+ * 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, } from './registration-guard.js';
+let failed = 0;
+let passed = 0;
+function test(name, fn) {
+    try {
+        fn();
+        console.log(`✅ ${name}`);
+        passed++;
+    }
+    catch (e) {
+        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 = {
+    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`);
+    }
+});
+test('event canon: all 11 approved events are typed', () => {
+    const names = [
+        '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);
+//# sourceMappingURL=funnel.test.js.map

package/dist/funnel.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"funnel.test.js","sourceRoot":"","sources":["../src/funnel.test.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -24,6 +24,8 @@ import { getGateway, isGatewayEnabled } from './gateway-client.js';
 import { requiresConfirmationAsync, createPendingAction, consumePendingAction, generatePreview, validateParams } from './confirmation.js';
 import { executeCapability, listCapabilities, hasCapability } from './capability-router.js';
 import { readSession, writeSession, clearSession, getMachineFingerprint, detectMCPClient } from './session.js';
+import { requireVerifiedOwner } from './registration-guard.js';
+import { emitFunnelEvent, hasLocalMarker, setLocalMarker } from './funnel-client.js';
 import { ConvexHttpClient } from 'convex/browser';
 import { getOrCreateCustomer, createMeteredCheckoutSession, getUsageSummary, METERED_BILLING } from './stripe.js';
 import { estimateCost } from './metered.js';
@@ -245,6 +247,49 @@ function checkWorkspaceAccess(providerId) {
     }
     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) {
+    const result = requireVerifiedOwner(workspaceContext);
+    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)
@@ -1046,23 +1091,11 @@ 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;
                 const action = args?.action;
                 const params = args?.params || {};
@@ -1090,32 +1123,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 = {
@@ -1443,6 +1451,37 @@ Docs: https://apiclaw.cloud
                 if (isGatewayEnabled() && result.success && workspaceContext && !isFreeAPI) {
                     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 = {
                     status: result.success ? 'success' : 'error',
@@ -1494,21 +1533,10 @@ 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;
                 const action = args?.action;
                 const params = args?.params || {};
@@ -1588,6 +1616,14 @@ Docs: https://apiclaw.cloud
             case 'register_owner': {
                 const email = args?.email;
                 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',
@@ -1682,10 +1718,27 @@ 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',
@@ -1741,6 +1794,17 @@ Docs: https://apiclaw.cloud
                             await convex.mutation("workspaces:incrementOTPAttempt", { 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',
@@ -1779,6 +1843,19 @@ Docs: https://apiclaw.cloud
                         status: result.workspace.status,
                     };
                     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',
@@ -2147,21 +2224,10 @@ Docs: https://apiclaw.cloud
                         isError: true
                     };
                 }
-                // 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
@@ -2272,6 +2338,27 @@ 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();
     // Register/update agent identity (fire-and-forget)