tokens-for-good 0.4.8 → 0.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokens-for-good",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "type": "module",
   "description": "Donate your spare AI tokens to research nonprofits for Fierce Philanthropy",
   "homepage": "https://tokensforgood.ai",

package/src/api-client.js

@@ -1,96 +1,110 @@
-// HTTP client for the Fierce Philanthropy coordination API
-
-const BASE_URL = process.env.FIERCE_API_URL || 'https://tokensforgood.ai/api';
-
-export class ApiClient {
-  constructor(apiKey) {
-    this.apiKey = apiKey;
-    if (!apiKey) {
-      throw new Error('TFG_API_KEY environment variable is required. Get your key at https://tokensforgood.ai/contribute');
-    }
-  }
-
-  async request(method, path, body = null) {
-    const url = `${BASE_URL}${path}`;
-    const options = {
-      method,
-      headers: {
-        'X-TFG-Api-Key': this.apiKey,
-        'Content-Type': 'application/json',
-        'Accept': 'application/json',
-      },
-      signal: AbortSignal.timeout(30000),
-    };
-
-    if (body) {
-      options.body = JSON.stringify(body);
-    }
-
-    const response = await fetch(url, options);
-    const data = await response.json();
-
-    if (!response.ok) {
-      const error = new Error(data.error || data.message || `API error ${response.status}`);
-      error.status = response.status;
-      error.data = data;
-      throw error;
-    }
-
-    return data;
-  }
-
-  async claimOrg(platform = null) {
-    return this.request('POST', '/research/claim', { platform });
-  }
-
-  async submitReport(claimId, reportMarkdown, tokenUsage = null, metrics = null, modelUsed = null, promptVersion = null) {
-    return this.request('POST', '/research/submit', {
-      claim_id: claimId,
-      report_markdown: reportMarkdown,
-      token_usage: tokenUsage,
-      metrics: metrics,
-      model_used: modelUsed,
-      prompt_version: promptVersion,
-    });
-  }
-
-  async releaseClaim(claimId) {
-    return this.request('POST', '/research/release', { claim_id: claimId });
-  }
-
-  async getNextPeerReview() {
-    return this.request('GET', '/research/review/next');
-  }
-
-  async submitPeerReview(claimId, score, notes = null, updatedReport = null) {
-    return this.request('POST', '/research/review/submit', {
-      claim_id: claimId,
-      score,
-      notes,
-      updated_report: updatedReport,
-    });
-  }
-
-  async getStatus() {
-    const response = await fetch(`${BASE_URL}/research/status`, {
-      headers: { 'Accept': 'application/json' },
-      signal: AbortSignal.timeout(15000),
-    });
-    if (!response.ok) {
-      throw new Error(`Status API error ${response.status}`);
-    }
-    return response.json();
-  }
-
-  async getImpact() {
-    return this.request('GET', '/research/impact');
-  }
-
-  async getNextAction() {
-    return this.request('GET', '/research/next-action');
-  }
-
-  async enableSchedule() {
-    return this.request('POST', '/research/enable-schedule');
-  }
-}
+// HTTP client for the Fierce Philanthropy coordination API
+
+const BASE_URL = process.env.FIERCE_API_URL || 'https://tokensforgood.ai/api';
+
+export class ApiClient {
+  constructor(apiKey, { version = null, platform = null, installId = null } = {}) {
+    this.apiKey = apiKey;
+    this.version = version;
+    this.platform = platform;
+    this.installId = installId;
+    if (!apiKey) {
+      throw new Error('TFG_API_KEY environment variable is required. Get your key at https://tokensforgood.ai/contribute');
+    }
+  }
+
+  // Version, platform, and install_id ride along on every request so the
+  // server can attribute traffic by client build, editor, and per-machine
+  // install without inspecting the request body.
+  headers(extra = {}) {
+    const headers = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      ...extra,
+    };
+    if (this.version) headers['X-TFG-Version'] = this.version;
+    if (this.platform) headers['X-TFG-Platform'] = this.platform;
+    if (this.installId) headers['X-TFG-Install-Id'] = this.installId;
+    return headers;
+  }
+
+  async request(method, path, body = null) {
+    const url = `${BASE_URL}${path}`;
+    const options = {
+      method,
+      headers: this.headers({ 'X-TFG-Api-Key': this.apiKey }),
+      signal: AbortSignal.timeout(30000),
+    };
+
+    if (body) {
+      options.body = JSON.stringify(body);
+    }
+
+    const response = await fetch(url, options);
+    const data = await response.json();
+
+    if (!response.ok) {
+      const error = new Error(data.error || data.message || `API error ${response.status}`);
+      error.status = response.status;
+      error.data = data;
+      throw error;
+    }
+
+    return data;
+  }
+
+  async claimOrg(platform = null) {
+    return this.request('POST', '/research/claim', { platform });
+  }
+
+  async submitReport(claimId, reportMarkdown, tokenUsage = null, metrics = null, modelUsed = null, promptVersion = null) {
+    return this.request('POST', '/research/submit', {
+      claim_id: claimId,
+      report_markdown: reportMarkdown,
+      token_usage: tokenUsage,
+      metrics: metrics,
+      model_used: modelUsed,
+      prompt_version: promptVersion,
+    });
+  }
+
+  async releaseClaim(claimId) {
+    return this.request('POST', '/research/release', { claim_id: claimId });
+  }
+
+  async getNextPeerReview() {
+    return this.request('GET', '/research/review/next');
+  }
+
+  async submitPeerReview(claimId, score, notes = null, updatedReport = null) {
+    return this.request('POST', '/research/review/submit', {
+      claim_id: claimId,
+      score,
+      notes,
+      updated_report: updatedReport,
+    });
+  }
+
+  async getStatus() {
+    const response = await fetch(`${BASE_URL}/research/status`, {
+      headers: this.headers(),
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!response.ok) {
+      throw new Error(`Status API error ${response.status}`);
+    }
+    return response.json();
+  }
+
+  async getImpact() {
+    return this.request('GET', '/research/impact');
+  }
+
+  async getNextAction() {
+    return this.request('GET', '/research/next-action');
+  }
+
+  async enableSchedule() {
+    return this.request('POST', '/research/enable-schedule');
+  }
+}

package/src/cli.js

@@ -46,8 +46,9 @@ if (args.includes('-v') || args.includes('--version')) {
   runSessionStartHook();
 } else if (args.includes('--status') || first === 'status') {
   const { ApiClient } = await import('./api-client.js');
+  const { getOrCreateInstallId } = await import('./state.js');
   try {
-    const client = new ApiClient(process.env.TFG_API_KEY || 'public');
+    const client = new ApiClient(process.env.TFG_API_KEY || 'public', { version: pkg.version, installId: getOrCreateInstallId() });
     const status = await client.getStatus();
     const sys = status.system_stats || status;
     console.log('\nTokens for Good - Project Status\n');
@@ -68,8 +69,9 @@ if (args.includes('-v') || args.includes('--version')) {
   }
 } else if (args.includes('--impact') || first === 'impact') {
   const { ApiClient } = await import('./api-client.js');
+  const { getOrCreateInstallId } = await import('./state.js');
   try {
-    const client = new ApiClient(process.env.TFG_API_KEY);
+    const client = new ApiClient(process.env.TFG_API_KEY, { version: pkg.version, installId: getOrCreateInstallId() });
     const result = await client.getImpact();
     const c = result.contributor;
     console.log(`\nYour Impact (@${c.github_handle})\n`);

package/src/init.js

@@ -9,7 +9,7 @@ import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
 import { detectPlatform, cronForSchedule, MAX_RUNS_PER_DAY } from './platform.js';
-import { loadState, saveState } from './state.js';
+import { loadState, saveState, getOrCreateInstallId } from './state.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = join(__dirname, '..');
@@ -130,6 +130,10 @@ export async function runInit() {
     console.log(`✓ ${plans[1].label}`);
   }
 
+  // Generate the install_id at install time so it lines up cleanly with
+  // `installed_at` instead of being lazily created at first MCP call.
+  getOrCreateInstallId();
+
   saveState({
     ...loadState(),
     intended_flow,

package/src/mcp-server.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { ApiClient } from './api-client.js';
 import { detectPlatform, isSchedulable, getAutomationInstructions } from './platform.js';
-import { loadState, updateState, isSnoozed, snoozeDays, hasContributedToday, markContributed, markSetupComplete } from './state.js';
+import { loadState, updateState, isSnoozed, snoozeDays, hasContributedToday, markContributed, markSetupComplete, getOrCreateInstallId } from './state.js';
 import { readFileSync, existsSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
@@ -32,17 +32,18 @@ function notInitialized() {
 }
 
 const apiKey = process.env.TFG_API_KEY;
+const platform = detectPlatform();
+updateState({ platform });
+const installId = getOrCreateInstallId();
+
 let client;
 try {
-  client = new ApiClient(apiKey);
+  client = new ApiClient(apiKey, { version: PKG_VERSION, platform, installId });
 } catch {
   // Will fail on tool calls, but server can still start
   client = null;
 }
 
-const platform = detectPlatform();
-updateState({ platform });
-
 const server = new McpServer({
   name: 'tokens-for-good',
   version: PKG_VERSION,
@@ -83,7 +84,7 @@ How it works:
 
 Research pipeline (per org, all done by your AI):
 - Research the org using web search + web fetch, following the 6-prompt methodology
-- Score using a weighted checklist (100 pts base, 120 max with extra credit)
+- Score using a weighted 6-criterion checklist (out of 120)
 - Verify citations by visiting each URL before submitting
 - Clean up writing style (no AI tells, no filler adjectives, no em dashes)
 
@@ -223,7 +224,7 @@ server.tool('submit_peer_review', 'Submit your peer review score for a report.',
 
 server.tool('research_status', 'See the overall Tokens for Good project progress and leaderboard.', {}, async () => {
   try {
-    const clientForStatus = client || new ApiClient('dummy'); // Status is public
+    const clientForStatus = client || new ApiClient('dummy', { version: PKG_VERSION, platform, installId }); // Status is public
     const result = await clientForStatus.getStatus();
     const sys = result.system_stats || result;
     const queue = result.queue_status || result.queue || {};

package/src/state.js

@@ -2,6 +2,7 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
+import { randomUUID } from 'crypto';
 
 const STATE_DIR = join(homedir(), '.tokens-for-good');
 const STATE_FILE = join(STATE_DIR, 'state.json');
@@ -17,6 +18,7 @@ const DEFAULT_STATE = {
   runs_per_day: null,           // 1-15 when intended_frequency === 'daily', else null
   first_setup_complete: false,  // flipped by mark_setup_complete tool after first scheduled run or first one-off submit
   installed_at: null,           // ISO timestamp when init finished
+  install_id: null,             // stable per-machine UUID sent as X-TFG-Install-Id header
 };
 
 export function loadState() {
@@ -84,3 +86,16 @@ export function isInitialized() {
   const state = loadState();
   return state.intended_flow !== null;
 }
+
+// Lazily generate and persist a stable per-machine install ID the first time
+// it's needed. Sent to the server as X-TFG-Install-Id on every request so
+// distinct installs can be counted separately from API keys (one key, N
+// machines). Existing users get an ID generated on their next session;
+// the server treats first-seen as install/activation.
+export function getOrCreateInstallId() {
+  const state = loadState();
+  if (state.install_id) return state.install_id;
+  const id = randomUUID();
+  updateState({ install_id: id });
+  return id;
+}