fodda-mcp 1.7.0 → 1.30.0

package/dist/tools.js

@@ -1,301 +1,94 @@
-export const MCP_SERVER_VERSION = "1.7.0";
+/**
+ * Tool Metadata — version constants for the Fodda MCP server.
+ *
+ * The actual tool registrations live in toolHandlers.ts.
+ * This file provides version strings used by index.ts and toolHandlers.ts.
+ */
+export const MCP_SERVER_VERSION = "1.30.0";
 export const TOOL_VERSIONS = {
-    list_graphs: "1.0.0",
-    search_graph: "1.2.0",
+    list_graphs: "1.4.0",
+    search_graph: "1.4.0",
     get_neighbors: "1.2.0",
     get_evidence: "1.1.0",
     get_node: "1.0.0",
     get_label_values: "1.2.0",
     psfk_overview: "1.0.0",
     discover_adjacent_trends: "1.0.0",
+    brand_tracker: "1.0.0",
+    get_census_retail_snapshot: "1.0.0",
+    get_census_demographics_snapshot: "1.1.0",
+    get_fred_economic_snapshot: "1.0.0",
+    get_wikipedia_pageviews: "1.0.0",
+    get_worldbank_global_snapshot: "1.1.0",
+    get_fda_ingredient_safety: "1.0.0",
+    get_fda_recalls: "1.0.0",
+    get_clinical_trials: "1.0.0",
+    get_bls_economic_snapshot: "1.0.0",
+    get_bea_spending_snapshot: "1.0.0",
+    get_cdc_health_data: "1.0.0",
+    get_pubmed_research_trends: "1.0.0",
+    get_openalex_research_trends: "1.0.0",
+    search_statistics: "1.0.0",
+    search_insights: "1.0.0",
+    get_wto_trade_snapshot: "1.0.0",
+    get_pew_survey_data: "1.0.0",
+    get_openfoodfacts_snapshot: "1.0.0",
+    get_ridb_recreation_snapshot: "1.0.0",
+    get_osm_commerce_snapshot: "1.0.0",
+    get_google_trends_snapshot: "1.0.0",
+    get_amazon_products_snapshot: "1.0.0",
+    get_oecd_economic_snapshot: "1.0.0",
+    get_cbs_nl_snapshot: "1.0.0",
+    get_ptdata_pt_snapshot: "1.0.0",
+    // v1.28.0 — European expansion
+    get_eurostat_eu_snapshot: "1.0.0",
+    get_ecb_euro_snapshot: "1.0.0",
+    get_boe_uk_snapshot: "1.0.0",
+    get_nordic_pxweb_snapshot: "1.0.0",
+    get_bundesbank_de_snapshot: "1.0.0",
+    get_ine_es_snapshot: "1.0.0",
+    get_insee_fr_snapshot: "1.0.0",
+    get_snb_ch_snapshot: "1.0.0",
+    get_bis_global_snapshot: "1.0.0",
+    // v1.28.0 — Americas expansion
+    get_bcb_br_snapshot: "1.0.0",
+    get_bcrp_pe_snapshot: "1.0.0",
+    get_arg_ar_snapshot: "1.0.0",
+    get_banxico_mx_snapshot: "1.0.0",
+    get_bch_hn_snapshot: "1.0.0",
+    get_boc_ca_snapshot: "1.0.0",
+    get_statcan_ca_snapshot: "1.0.0",
+    get_bcch_cl_snapshot: "1.0.0",
+    get_socrata_us_snapshot: "1.0.0",
+    // v1.28.0 — Asia-Pacific expansion
+    get_abs_au_snapshot: "1.0.0",
+    get_rba_au_snapshot: "1.0.0",
+    get_pdh_pacific_snapshot: "1.0.0",
+    get_bnm_my_snapshot: "1.0.0",
+    get_hkma_hk_snapshot: "1.0.0",
+    get_estat_jp_snapshot: "1.0.0",
+    get_bok_kr_snapshot: "1.0.0",
+    get_bot_th_snapshot: "1.0.0",
+    get_bps_id_snapshot: "1.0.0",
+    get_psa_ph_snapshot: "1.0.0",
+    get_sg_snapshot: "1.0.0",
+    get_cn_china_snapshot: "1.0.0",
+    get_india_in_snapshot: "1.0.0",
+    // v1.28.0 — Middle East & Africa expansion
+    get_qatar_qa_snapshot: "1.0.0",
+    get_bahrain_bh_snapshot: "1.0.0",
+    get_boi_il_snapshot: "1.0.0",
+    get_sarb_za_snapshot: "1.0.0",
+    // Utility tools
+    sign_up_free_account: "1.0.0",
+    send_feedback: "1.0.0",
+    get_my_account: "1.0.0",
+    update_user_profile: "1.0.0",
+    deep_research_topic: "1.0.0",
+    read_url: "1.0.0",
+    list_analysts: "1.0.0",
+    consult_analyst: "1.0.0",
+    toggle_graph_preference: "1.0.0",
+    manage_scheduled_reports: "2.0.0",
 };
-const GRAPH_ID_DESCRIPTION = "Select which curated graph to query. Use list_graphs to discover available options. Common values: 'retail', 'beauty', 'sports', 'psfk', 'sic', 'waldo', 'pew'.";
-const ALL_TOOLS = [
-    {
-        name: "list_graphs",
-        description: "Discover available knowledge graphs and their schemas, including node types, relationship types, and versions. Use this tool first to find valid graphId values for other tools.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                userId: { type: "string", description: "Unique identifier for the user (Required)" },
-            },
-            required: ["userId"],
-        },
-        outputSchema: {
-            type: "object",
-            properties: {
-                graphs: {
-                    type: "array",
-                    description: "Array of available graphs with their schemas",
-                },
-            },
-        },
-        isDeterministic: true,
-    },
-    {
-        name: "search_graph",
-        description: "Search across expert-curated PSFK knowledge graphs (Retail, Beauty, Sports and partner datasets) to retrieve structured trend clusters, signals, and supporting articles relevant to a query. Note: a server-side relevance gate may reduce results for brand/entity-specific queries — results with low semantic scores that don't mention query terms are automatically filtered out.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                graphId: { type: "string", description: GRAPH_ID_DESCRIPTION },
-                query: { type: "string", description: "The search query. Location terms (city/country names like 'London', 'Tokyo') are auto-detected and used to hard-filter results geographically. Geo terms auto-expand (e.g., 'London' also matches 'UK', 'England'). No additional parameters needed for location filtering." },
-                userId: { type: "string", description: "Unique identifier for the user (Required)" },
-                limit: { type: "number", description: "Maximum number of results (default 25, max 50)" },
-                use_semantic: { type: "boolean", description: "Whether to use semantic search (default true)" },
-                filters: {
-                    type: "object",
-                    description: "Optional filters to narrow search results",
-                    properties: {
-                        node_types: {
-                            type: "array",
-                            items: { type: "string" },
-                            description: "Filter by node labels (e.g., ['Trend', 'Article'])"
-                        },
-                    },
-                },
-                include_evidence: { type: "boolean", description: "If true, batch-fetch supporting evidence articles inline with results. Saves a separate get_evidence call per trend. Default: true. Each evidence item includes: sourceUrl, place (geographic location), brandNames, snippet, and publishedAt." },
-            },
-            required: ["graphId", "query", "userId"],
-        },
-        outputSchema: {
-            type: "object",
-            properties: {
-                results: {
-                    type: "array",
-                    description: "Array of matching nodes (trends, articles), each optionally with an 'evidence' array if include_evidence=true. When evidence is included, each evidence item contains: sourceUrl (article link), place (geographic location of the article), brandNames (brands mentioned), snippet (relevant excerpt), and publishedAt (publication date).",
-                },
-                total: { type: "number", description: "Total number of results found" },
-                search_method: { type: "string", description: "Search method used: 'vector', 'keyword', 'hybrid', or 'all_fallback'" },
-                usage: {
-                    type: "object",
-                    description: "Billing/usage metadata",
-                    properties: {
-                        total_billable_units: { type: "number" },
-                    },
-                },
-            },
-        },
-        isDeterministic: false,
-    },
-    {
-        name: "get_neighbors",
-        description: "Explore how a trend, brand, or technology connects to related signals, concepts, and adjacent innovation patterns within the selected graph. Traversal is depth-limited for focused discovery.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                graphId: { type: "string", description: GRAPH_ID_DESCRIPTION },
-                seed_node_ids: { type: "array", items: { type: "string" }, description: "Array of node IDs to start traversal from" },
-                userId: { type: "string", description: "Unique identifier for the user (Required)" },
-                relationship_types: { type: "array", items: { type: "string" }, description: "Filter by relationship types: 'EVIDENCED_BY', 'RELATED_TO', 'SEMANTICALLY_SIMILAR', 'ASSOCIATED_BRAND', 'MENTIONS_BRAND', 'IN_LOCATION'" },
-                direction: { type: "string", enum: ["in", "out"], description: "Traversal direction: 'out' (default) follows outgoing edges, 'in' follows incoming edges" },
-                depth: { type: "number", description: "Traversal depth (default 1, max 2)" },
-                limit: { type: "number", description: "Maximum results (default 50)" },
-            },
-            required: ["graphId", "seed_node_ids", "userId"],
-        },
-        outputSchema: {
-            type: "object",
-            properties: {
-                nodes: {
-                    type: "array",
-                    description: "Array of neighboring nodes",
-                },
-                edges: {
-                    type: "array",
-                    description: "Array of relationships between nodes",
-                },
-                usage: {
-                    type: "object",
-                    properties: {
-                        total_billable_units: { type: "number" },
-                    },
-                },
-            },
-        },
-        isDeterministic: true,
-    },
-    {
-        name: "get_evidence",
-        description: "Retrieve supporting signals, source articles, and structured evidence for a specific trend or concept. Designed for provenance, validation, and strategic briefing.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                graphId: { type: "string", description: GRAPH_ID_DESCRIPTION },
-                for_node_id: { type: "string", description: "The ID of the node (Trend or Article)" },
-                userId: { type: "string", description: "Unique identifier for the user (Required)" },
-                top_k: { type: "number", description: "Number of evidence items to return (default 5)" },
-            },
-            required: ["graphId", "for_node_id", "userId"],
-        },
-        outputSchema: {
-            type: "object",
-            properties: {
-                evidence: {
-                    type: "array",
-                    description: "Array of evidence items with source URLs, titles, snippets, relevance scores, place (geographic location of the article), and brand names",
-                },
-                node_id: { type: "string", description: "The node this evidence supports" },
-                usage: {
-                    type: "object",
-                    properties: {
-                        total_billable_units: { type: "number" },
-                    },
-                },
-            },
-        },
-        isDeterministic: true,
-    },
-    {
-        name: "get_node",
-        description: "Retrieve the full metadata and properties of a specific node within the knowledge graph, including labels and structured attributes.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                graphId: { type: "string", description: GRAPH_ID_DESCRIPTION },
-                nodeId: { type: "string", description: "The ID of the node" },
-                userId: { type: "string", description: "Unique identifier for the user (Required)" },
-            },
-            required: ["graphId", "nodeId", "userId"],
-        },
-        outputSchema: {
-            type: "object",
-            properties: {
-                id: { type: "string", description: "Node ID" },
-                display: { type: "string", description: "Display name of the node" },
-                labels: { type: "array", description: "Array of node labels/types" },
-                properties: { type: "object", description: "Key-value properties of the node" },
-            },
-        },
-        isDeterministic: true,
-    },
-    {
-        name: "get_label_values",
-        description: "Discover available values for a specific category (e.g., Technology, Audience, RetailerType, Brand) to support structured filtering and exploration.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                graphId: { type: "string", description: GRAPH_ID_DESCRIPTION },
-                label: { type: "string", description: "The label to fetch values for (e.g., 'Brand', 'Location', 'Technology', 'Audience', 'RetailerType', 'Trend')" },
-                userId: { type: "string", description: "Unique identifier for the user (Required)" },
-                property: { type: "string", description: "Optional property to return values for. Defaults vary by label (Brand→name, Technology→slug, Audience→slug, Trend→trendName)" },
-            },
-            required: ["graphId", "label", "userId"],
-        },
-        outputSchema: {
-            type: "object",
-            properties: {
-                label: { type: "string", description: "The label queried" },
-                property: { type: "string", description: "The property values were fetched from" },
-                values: { type: "array", description: "Array of valid values for the label" },
-                count: { type: "number", description: "Number of values found" },
-            },
-        },
-        isDeterministic: true,
-    },
-    {
-        name: "psfk_overview",
-        description: "Generate a macro-level overview of a selected PSFK domain (e.g., Retail, Beauty, Sports), summarizing key meta-patterns and structured trend clusters for strategic briefing.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                industry: { type: "string", description: "Filter by industry (e.g. 'Retail', 'Health')" },
-                sector: { type: "string", description: "Filter by sector" },
-                region: { type: "string", description: "Filter by region" },
-                timeframe: { type: "string", description: "Timeframe for the overview" },
-                userId: { type: "string", description: "Unique identifier for the user (Required)" },
-            },
-            required: ["userId"],
-            anyOf: [
-                { required: ["industry"] },
-                { required: ["sector"] }
-            ],
-        },
-        outputSchema: {
-            type: "object",
-            properties: {
-                meta_patterns: {
-                    type: "array",
-                    description: "Up to 3 macro-level pattern objects with trend summaries",
-                },
-                industry: { type: "string", description: "Industry filter applied" },
-                sector: { type: "string", description: "Sector filter applied" },
-                usage: {
-                    type: "object",
-                    properties: {
-                        total_billable_units: { type: "number" },
-                    },
-                },
-            },
-        },
-        isDeterministic: false,
-    },
-    {
-        name: "discover_adjacent_trends",
-        description: "Find trends that are semantically similar to a given trend — useful for discovering 'what else should I be watching?' or expanding a research brief with related signals. Returns trends connected by AI-computed similarity, not editorial curation.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                graphId: {
-                    type: "string",
-                    description: GRAPH_ID_DESCRIPTION
-                },
-                trend_id: {
-                    type: "string",
-                    description: "The trendId of the seed trend to find adjacent possibilities for"
-                },
-                userId: {
-                    type: "string",
-                    description: "Unique identifier for the user (Required)"
-                },
-                min_score: {
-                    type: "number",
-                    description: "Minimum similarity score threshold (0-1). Higher = more similar. Default: 0.80"
-                },
-                limit: {
-                    type: "number",
-                    description: "Maximum number of adjacent trends to return. Default: 10"
-                },
-                include_editorial: {
-                    type: "boolean",
-                    description: "If true, also include trends that are already editorially linked via RELATED_TO. Default: false (shows only AI-discovered connections)"
-                }
-            },
-            required: ["graphId", "trend_id", "userId"]
-        },
-        outputSchema: {
-            type: "object",
-            properties: {
-                adjacent: {
-                    type: "array",
-                    description: "Array of semantically similar trends with similarity scores",
-                },
-                node_id: { type: "string", description: "The seed trend ID queried" },
-                count: { type: "number", description: "Number of adjacent trends returned" },
-                min_score: { type: "number", description: "Minimum similarity threshold applied" },
-                usage: {
-                    type: "object",
-                    properties: {
-                        total_billable_units: { type: "number" },
-                    },
-                },
-            },
-        },
-        isDeterministic: true,
-    },
-];
-const DEFAULT_ENTERPRISE_TOOLS = [
-    "list_graphs",
-    "search_graph",
-    "get_node",
-    "get_evidence",
-    "get_neighbors",
-    "get_label_values",
-    "discover_adjacent_trends"
-];
-const allowedToolsStr = process.env.ALLOWED_TOOLS;
-const allowedTools = allowedToolsStr
-    ? allowedToolsStr.split(',').map(s => s.trim())
-    : DEFAULT_ENTERPRISE_TOOLS;
-export const TOOLS = ALL_TOOLS.filter(tool => allowedTools.includes(tool.name));
 //# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,QAAQ,CAAC;AAE3C,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB,WAAW,EAAE,OAAO;IACpB,YAAY,EAAE,OAAO;IACrB,aAAa,EAAE,OAAO;IACtB,YAAY,EAAE,OAAO;IACrB,QAAQ,EAAE,OAAO;IACjB,gBAAgB,EAAE,OAAO;IACzB,aAAa,EAAE,OAAO;IACtB,wBAAwB,EAAE,OAAO;IACjC,aAAa,EAAE,OAAO;IACtB,0BAA0B,EAAE,OAAO;IACnC,gCAAgC,EAAE,OAAO;IACzC,0BAA0B,EAAE,OAAO;IACnC,uBAAuB,EAAE,OAAO;IAChC,6BAA6B,EAAE,OAAO;IACtC,yBAAyB,EAAE,OAAO;IAClC,eAAe,EAAE,OAAO;IACxB,mBAAmB,EAAE,OAAO;IAC5B,yBAAyB,EAAE,OAAO;IAClC,yBAAyB,EAAE,OAAO;IAClC,mBAAmB,EAAE,OAAO;IAC5B,0BAA0B,EAAE,OAAO;IACnC,4BAA4B,EAAE,OAAO;IACrC,iBAAiB,EAAE,OAAO;IAC1B,eAAe,EAAE,OAAO;IACxB,sBAAsB,EAAE,OAAO;IAC/B,mBAAmB,EAAE,OAAO;IAC5B,0BAA0B,EAAE,OAAO;IACnC,4BAA4B,EAAE,OAAO;IACrC,yBAAyB,EAAE,OAAO;IAClC,0BAA0B,EAAE,OAAO;IACnC,4BAA4B,EAAE,OAAO;IACrC,0BAA0B,EAAE,OAAO;IACnC,mBAAmB,EAAE,OAAO;IAC5B,sBAAsB,EAAE,OAAO;IAC/B,+BAA+B;IAC/B,wBAAwB,EAAE,OAAO;IACjC,qBAAqB,EAAE,OAAO;IAC9B,mBAAmB,EAAE,OAAO;IAC5B,yBAAyB,EAAE,OAAO;IAClC,0BAA0B,EAAE,OAAO;IACnC,mBAAmB,EAAE,OAAO;IAC5B,qBAAqB,EAAE,OAAO;IAC9B,mBAAmB,EAAE,OAAO;IAC5B,uBAAuB,EAAE,OAAO;IAChC,+BAA+B;IAC/B,mBAAmB,EAAE,OAAO;IAC5B,oBAAoB,EAAE,OAAO;IAC7B,mBAAmB,EAAE,OAAO;IAC5B,uBAAuB,EAAE,OAAO;IAChC,mBAAmB,EAAE,OAAO;IAC5B,mBAAmB,EAAE,OAAO;IAC5B,uBAAuB,EAAE,OAAO;IAChC,oBAAoB,EAAE,OAAO;IAC7B,uBAAuB,EAAE,OAAO;IAChC,mCAAmC;IACnC,mBAAmB,EAAE,OAAO;IAC5B,mBAAmB,EAAE,OAAO;IAC5B,wBAAwB,EAAE,OAAO;IACjC,mBAAmB,EAAE,OAAO;IAC5B,oBAAoB,EAAE,OAAO;IAC7B,qBAAqB,EAAE,OAAO;IAC9B,mBAAmB,EAAE,OAAO;IAC5B,mBAAmB,EAAE,OAAO;IAC5B,mBAAmB,EAAE,OAAO;IAC5B,mBAAmB,EAAE,OAAO;IAC5B,eAAe,EAAE,OAAO;IACxB,qBAAqB,EAAE,OAAO;IAC9B,qBAAqB,EAAE,OAAO;IAC9B,2CAA2C;IAC3C,qBAAqB,EAAE,OAAO;IAC9B,uBAAuB,EAAE,OAAO;IAChC,mBAAmB,EAAE,OAAO;IAC5B,oBAAoB,EAAE,OAAO;IAC7B,gBAAgB;IAChB,oBAAoB,EAAE,OAAO;IAC7B,aAAa,EAAE,OAAO;IACtB,cAAc,EAAE,OAAO;IACvB,mBAAmB,EAAE,OAAO;IAC5B,mBAAmB,EAAE,OAAO;IAC5B,QAAQ,EAAE,OAAO;IACjB,aAAa,EAAE,OAAO;IACtB,eAAe,EAAE,OAAO;IACxB,uBAAuB,EAAE,OAAO;IAChC,wBAAwB,EAAE,OAAO;CACpC,CAAC"}

package/dist/trialTracker.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Trial Tracker — Firestore-backed per-user trial token counter.
+ *
+ * Tracks how many API calls each trial user (identified by userId/email)
+ * has made across all sessions. Cloud Run instances are ephemeral, so
+ * in-memory counters reset on cold starts — Firestore provides persistence.
+ *
+ * Does NOT modify the existing trial → Base conversion flow.
+ * Only adds a per-user counting layer that triggers it earlier.
+ *
+ * Split credit model (2026-04-24):
+ *   - 50 search tokens (standard graph queries)
+ *   - 1 free Deep Dive (fast or comprehensive)
+ *   - 2 free Expert Agent turns
+ * Each pool is tracked independently in the Firestore document.
+ */
+export type TrialInteractionType = 'search' | 'deep_dive' | 'expert_agent';
+export interface TrialUsage {
+    count: number;
+    deepDiveUsed: number;
+    expertAgentUsed: number;
+    firstUse: Date;
+    lastUse: Date;
+}
+export interface TrialCheckResult {
+    allowed: boolean;
+    count: number;
+    remaining: number;
+    limit: number;
+    shouldWarn: boolean;
+    /** Which credit pool was checked */
+    pool: TrialInteractionType;
+}
+/**
+ * Get the current trial usage for a user.
+ * If the user's firstUse is older than 30 days, resets all counters.
+ * Returns { count, deepDiveUsed, expertAgentUsed, firstUse, lastUse }.
+ */
+export declare function getTrialUsage(userId: string): Promise<TrialUsage>;
+/**
+ * Increment the trial usage counter for a user.
+ * Called after a successful API call.
+ * Uses a transaction to ensure firstUse is only set on doc creation.
+ *
+ * @param userId - The user identifier (email or fingerprint)
+ * @param cost - Number of tokens to deduct (default: 1 for search)
+ * @param interactionType - Which credit pool to deduct from
+ */
+export declare function incrementTrialUsage(userId: string, cost?: number, interactionType?: TrialInteractionType): Promise<number>;
+/**
+ * Check if a trial user is allowed to make an API call.
+ * Checks the appropriate credit pool based on interactionType.
+ *
+ * @param userId - The user identifier
+ * @param interactionType - Which pool to check: 'search' (50 tokens), 'deep_dive' (1 free), 'expert_agent' (2 free)
+ */
+export declare function checkTrialLimit(userId: string, interactionType?: TrialInteractionType): Promise<TrialCheckResult>;
+//# sourceMappingURL=trialTracker.d.ts.map

package/dist/trialTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trialTracker.d.ts","sourceRoot":"","sources":["../src/trialTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoBH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,WAAW,GAAG,cAAc,CAAC;AAoB3E,MAAM,WAAW,UAAU;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,IAAI,CAAC;IACf,OAAO,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,oCAAoC;IACpC,IAAI,EAAE,oBAAoB,CAAC;CAC9B;AAMD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA4BvE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAU,EAChB,eAAe,GAAE,oBAA+B,GACjD,OAAO,CAAC,MAAM,CAAC,CA2CjB;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACjC,MAAM,EAAE,MAAM,EACd,eAAe,GAAE,oBAA+B,GACjD,OAAO,CAAC,gBAAgB,CAAC,CAqC3B"}

package/dist/trialTracker.js

@@ -0,0 +1,179 @@
+/**
+ * Trial Tracker — Firestore-backed per-user trial token counter.
+ *
+ * Tracks how many API calls each trial user (identified by userId/email)
+ * has made across all sessions. Cloud Run instances are ephemeral, so
+ * in-memory counters reset on cold starts — Firestore provides persistence.
+ *
+ * Does NOT modify the existing trial → Base conversion flow.
+ * Only adds a per-user counting layer that triggers it earlier.
+ *
+ * Split credit model (2026-04-24):
+ *   - 50 search tokens (standard graph queries)
+ *   - 1 free Deep Dive (fast or comprehensive)
+ *   - 2 free Expert Agent turns
+ * Each pool is tracked independently in the Firestore document.
+ */
+import { Firestore } from '@google-cloud/firestore';
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+const PER_USER_TRIAL_LIMIT = 50;
+const DEEP_DIVE_TRIAL_LIMIT = 1; // 1 free Deep Dive per trial user
+const EXPERT_AGENT_TRIAL_LIMIT = 2; // 2 free Expert Agent turns per trial user
+const WARNING_THRESHOLD = 10; // warn when remaining < 10
+const RESET_PERIOD_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const COLLECTION = 'trial-usage';
+// ---------------------------------------------------------------------------
+// Firestore client — uses Application Default Credentials on Cloud Run
+// ---------------------------------------------------------------------------
+let db = null;
+function getDb() {
+    if (!db) {
+        const projectId = process.env.GOOGLE_CLOUD_PROJECT || process.env.GCP_PROJECT;
+        db = new Firestore(projectId ? { projectId } : {});
+    }
+    return db;
+}
+// ---------------------------------------------------------------------------
+// Core functions
+// ---------------------------------------------------------------------------
+/**
+ * Get the current trial usage for a user.
+ * If the user's firstUse is older than 30 days, resets all counters.
+ * Returns { count, deepDiveUsed, expertAgentUsed, firstUse, lastUse }.
+ */
+export async function getTrialUsage(userId) {
+    try {
+        const docRef = getDb().collection(COLLECTION).doc(sanitizeDocId(userId));
+        const snap = await docRef.get();
+        if (!snap.exists) {
+            return { count: 0, deepDiveUsed: 0, expertAgentUsed: 0, firstUse: new Date(), lastUse: new Date() };
+        }
+        const data = snap.data();
+        const firstUse = data['firstUse']?.toDate?.() ?? new Date(data['firstUse']);
+        const lastUse = data['lastUse']?.toDate?.() ?? new Date(data['lastUse']);
+        const count = data['count'] ?? 0;
+        const deepDiveUsed = data['deepDiveUsed'] ?? 0;
+        const expertAgentUsed = data['expertAgentUsed'] ?? 0;
+        // Monthly reset: if firstUse is older than 30 days, reset all counters
+        if (Date.now() - firstUse.getTime() > RESET_PERIOD_MS) {
+            await docRef.set({ count: 0, deepDiveUsed: 0, expertAgentUsed: 0, firstUse: new Date(), lastUse: new Date() });
+            return { count: 0, deepDiveUsed: 0, expertAgentUsed: 0, firstUse: new Date(), lastUse: new Date() };
+        }
+        return { count, deepDiveUsed, expertAgentUsed, firstUse, lastUse };
+    }
+    catch (err) {
+        // If Firestore is unavailable, fail open — let the shared pool handle it
+        console.error(`[trialTracker] Firestore read failed for ${userId}:`, err.message);
+        return { count: 0, deepDiveUsed: 0, expertAgentUsed: 0, firstUse: new Date(), lastUse: new Date() };
+    }
+}
+/**
+ * Increment the trial usage counter for a user.
+ * Called after a successful API call.
+ * Uses a transaction to ensure firstUse is only set on doc creation.
+ *
+ * @param userId - The user identifier (email or fingerprint)
+ * @param cost - Number of tokens to deduct (default: 1 for search)
+ * @param interactionType - Which credit pool to deduct from
+ */
+export async function incrementTrialUsage(userId, cost = 1, interactionType = 'search') {
+    try {
+        const docRef = getDb().collection(COLLECTION).doc(sanitizeDocId(userId));
+        const now = new Date();
+        const newCount = await getDb().runTransaction(async (tx) => {
+            const snap = await tx.get(docRef);
+            if (!snap.exists) {
+                // First ever API call for this user
+                const initial = { count: 0, deepDiveUsed: 0, expertAgentUsed: 0, firstUse: now, lastUse: now };
+                if (interactionType === 'deep_dive') {
+                    initial.deepDiveUsed = 1;
+                }
+                else if (interactionType === 'expert_agent') {
+                    initial.expertAgentUsed = 1;
+                }
+                else {
+                    initial.count = cost;
+                }
+                tx.set(docRef, initial);
+                return interactionType === 'search' ? cost : 0;
+            }
+            const data = snap.data();
+            const updates = { lastUse: now };
+            if (interactionType === 'deep_dive') {
+                updates.deepDiveUsed = (data['deepDiveUsed'] ?? 0) + 1;
+            }
+            else if (interactionType === 'expert_agent') {
+                updates.expertAgentUsed = (data['expertAgentUsed'] ?? 0) + 1;
+            }
+            else {
+                updates.count = (data['count'] ?? 0) + cost;
+            }
+            tx.update(docRef, updates);
+            return updates.count ?? data['count'] ?? 0;
+        });
+        return newCount;
+    }
+    catch (err) {
+        // If Firestore is unavailable, fail open
+        console.error(`[trialTracker] Firestore write failed for ${userId}:`, err.message);
+        return 0;
+    }
+}
+/**
+ * Check if a trial user is allowed to make an API call.
+ * Checks the appropriate credit pool based on interactionType.
+ *
+ * @param userId - The user identifier
+ * @param interactionType - Which pool to check: 'search' (50 tokens), 'deep_dive' (1 free), 'expert_agent' (2 free)
+ */
+export async function checkTrialLimit(userId, interactionType = 'search') {
+    const usage = await getTrialUsage(userId);
+    if (interactionType === 'deep_dive') {
+        const remaining = Math.max(0, DEEP_DIVE_TRIAL_LIMIT - usage.deepDiveUsed);
+        return {
+            allowed: usage.deepDiveUsed < DEEP_DIVE_TRIAL_LIMIT,
+            count: usage.deepDiveUsed,
+            remaining,
+            limit: DEEP_DIVE_TRIAL_LIMIT,
+            shouldWarn: false, // Only 1 credit — no point warning
+            pool: 'deep_dive',
+        };
+    }
+    if (interactionType === 'expert_agent') {
+        const remaining = Math.max(0, EXPERT_AGENT_TRIAL_LIMIT - usage.expertAgentUsed);
+        return {
+            allowed: usage.expertAgentUsed < EXPERT_AGENT_TRIAL_LIMIT,
+            count: usage.expertAgentUsed,
+            remaining,
+            limit: EXPERT_AGENT_TRIAL_LIMIT,
+            shouldWarn: remaining === 1,
+            pool: 'expert_agent',
+        };
+    }
+    // Default: search token pool
+    const remaining = Math.max(0, PER_USER_TRIAL_LIMIT - usage.count);
+    return {
+        allowed: usage.count < PER_USER_TRIAL_LIMIT,
+        count: usage.count,
+        remaining,
+        limit: PER_USER_TRIAL_LIMIT,
+        shouldWarn: remaining > 0 && remaining < WARNING_THRESHOLD,
+        pool: 'search',
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Sanitize a userId for use as a Firestore document ID.
+ * Firestore doc IDs cannot contain '/' and should be reasonable length.
+ */
+function sanitizeDocId(userId) {
+    return userId
+        .replace(/[\/\.+\s]/g, '_') // Replace /, ., +, whitespace with _
+        .replace(/__+/g, '_') // Collapse multiple underscores
+        .substring(0, 200);
+}
+//# sourceMappingURL=trialTracker.js.map