saasfunnels 0.2.2 → 0.3.0

package/README.md

@@ -37,9 +37,9 @@ saasfunnels plans handoff --integration-id <id> \
 prices. Files that reference a Stripe price are reported as evidence; files that
 only look commercial by name and content are reported separately as guesses.
 Nothing leaves the machine until `.saasfunnels/plan-sources.json` lists the files
-and `plans handoff --send` is run, because plan mapping receives file contents
-rather than the `file:line` references a feature manifest sends. Commit that file
-so the approved set is reviewable.
+and `plans handoff --send` is run. The CLI extracts normalized mapping evidence
+locally; source contents stay on your machine. Commit the approval file so the
+approved set is reviewable.
 
 ### GitHub Action
 
@@ -75,6 +75,10 @@ The application imports the exact versioned MCP registry through the server-side
 
 In hosted OAuth, `list_workspaces` discovers accessible workspace names and IDs. Live read, inspect, and plan tools accept an optional `workspace_id`. The hosted application must select the sole accessible workspace automatically, require an explicit ID when several are accessible, recheck authorization for every call, and include the selected workspace name and ID in each live response. The application passes the selection through to its developer API as the `workspace_id` query parameter. Local stdio API-key tools do not expose workspace selection; their key stays pinned to its workspace.
 
+For Funnel discovery, hosted MCP offers `list_funnels` and `get_funnel_state`. `list_funnels` returns at most 50 summaries per page; follow `page.hasMore` with the next `offset` to cover the workspace. The app returns the selected workspace and evaluation time with each read. `get_funnel_state` reports the current lifecycle and publication readiness for one Funnel. These reads do not include Funnel definitions, customer data, or Results. Signals remain supporting evidence and enrollment inputs.
+
+For performance, `get_portfolio_results` and `get_funnel_results` use a 7d, 30d, 90d, or 12m reporting window (30d by default). Portfolio rows are paged at 50 Funnels and cover at most the first 100; check `page.has_more` and `funnels_truncated` before claiming complete coverage. Stage counts and revenue rows retain their distinct attribution, value basis, and currency. `list_opportunities` and `list_leads` return at most 50 records per page with `page.total_count` and `page.has_more`; `get_opportunity` and `get_lead` return one bounded record. Opportunity reads omit private evidence and money; Lead reads omit personal identity and raw responses. These six reads require hosted OAuth, an accessible selected workspace, and the app's `funnels.view` role check.
+
 ## Development
 
 ```bash
@@ -87,3 +91,13 @@ The package allowlist is enforced as `LICENSE`, `README.md`, `package.json`, the
 Documentation: https://docs.saasfunnels.ai/developer-tools/saasfunnels-cli
 
 Support: support@saasfunnels.ai
+
+### Guided application discovery
+
+Use `saasfunnels setup run` from the application repository after creating app credentials in Setup. Load `SAASFUNNELS_API_KEY` from **Developer setup access** into the local process environment. Its scopes are `developer:read` and `features:write`; it is not a browser or payment-administration key.
+
+The command asks before uploading structured discovery proposals. `--send` provides explicit non-interactive approval. It coordinates features, pricing extraction, and plan branches, reports progress, and waits for the Stripe catalog. Run `saasfunnels setup run --resume` after an interruption. Existing accepted stages and customer review decisions are preserved.
+
+If extraction is unsupported, review a `.saasfunnels/setup-pricing.json` file with `{ "plans": [{ "key": "pro", "name": "Pro", "features": { "export": true }, "prices": [{ "key": "price_ACTUAL_ID" }] }] }`, then resume. Use real identifiers from the connected merchant. Raw source files are never uploaded by guided setup or the pricing handoff.
+
+The command does not implement arbitrary payment code, approve feature access, or verify transactions. Complete **Review and verify** in Setup after deploying the runtime and payment integration. Requires the server's guided setup API release.

package/dist/library.js

@@ -1,4 +1,4 @@
-import { createRequire as __saasfunnelsCreateRequire } from "node:module"; const require = __saasfunnelsCreateRequire(import.meta.url);
+import { createRequire as __saasfunnelsCreateRequire } from "node:module"; const require = __saasfunnelsCreateRequire(import.meta.url); const __filename = new URL(import.meta.url).pathname; const __dirname = require("node:path").dirname(__filename);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -24151,6 +24151,10 @@ var registry2 = Object.freeze({
     "local_mcp",
     "api_key"
   ]),
+  "funnel.workspace.read": capability("funnel.workspace.read", "read", [
+    "in_app",
+    "hosted_mcp"
+  ]),
   "setup.test_event.send": capability("setup.test_event.send", "external_write", [
     "local_cli",
     "local_mcp",
@@ -24260,7 +24264,7 @@ function validateFeatureCatalogManifest(value) {
 
 // src/identity.ts
 var SAASFUNNELS_CLI_NAME = "saasfunnels";
-var SAASFUNNELS_CLI_VERSION = "0.2.2";
+var SAASFUNNELS_CLI_VERSION = "0.3.0";
 var SAASFUNNELS_PRODUCT_NAME = "SaaSFunnels";
 var SAASFUNNELS_DEFAULT_API_BASE_URL = "https://app.saasfunnels.ai";
 var SAASFUNNELS_ENV = Object.freeze({
@@ -24297,11 +24301,19 @@ var saasFunnelsMcpToolCapabilityIds = {
   apply_funnel_entry: "funnel.entry.apply",
   generate_direct_api_handoff: "developer.handoff.generate",
   get_integration_health: "developer.workspace.read",
+  get_funnel_results: "funnel.workspace.read",
+  get_funnel_state: "funnel.workspace.read",
+  get_lead: "funnel.workspace.read",
+  get_opportunity: "funnel.workspace.read",
+  get_portfolio_results: "funnel.workspace.read",
   get_signal_payload_preview: "developer.workspace.read",
   get_workspace_readiness: "developer.workspace.read",
   list_workspaces: "developer.workspace.read",
   inspect_funnel_entry: "funnel.entry.inspect",
+  list_funnels: "funnel.workspace.read",
+  list_leads: "funnel.workspace.read",
   list_mapping_gaps: "developer.workspace.read",
+  list_opportunities: "funnel.workspace.read",
   list_recent_signals: "developer.workspace.read",
   simulate_account_funnel_fit: "account.funnel_fit.simulate",
   propose_funnel_entry_installation: "funnel.entry.plan",
@@ -24380,6 +24392,42 @@ function stringArg(args, name) {
   const value = args[name];
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
+var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+var resultsWindows = ["7d", "30d", "90d", "12m"];
+var attributionRoles = ["direct", "influenced", "observed"];
+var opportunityStates = ["detected", "open", "eligible", "queued", "presented", "engaged", "action_pending", "converted", "dismissed", "suppressed", "expired", "failed"];
+var leadStates = ["new", "working", "qualified", "converted", "disqualified", "withdrawn", "deleted"];
+function uuidArg(args, name, required2 = false) {
+  const value = args[name];
+  if (value === void 0 && !required2) return void 0;
+  const parsed = stringArg(args, name);
+  if (!parsed || !uuidPattern.test(parsed)) {
+    throw new McpProtocolError(-32602, `${name} must be a UUID.`);
+  }
+  return parsed;
+}
+function integerArg(args, name, fallback, max) {
+  const value = args[name] ?? fallback;
+  if (!Number.isInteger(value) || Number(value) < (name === "limit" ? 1 : 0) || Number(value) > max) {
+    throw new McpProtocolError(-32602, `${name} must be an integer from ${name === "limit" ? 1 : 0} to ${max}.`);
+  }
+  return Number(value);
+}
+function optionalFilterArg(args, name) {
+  if (args[name] === void 0) return void 0;
+  const value = stringArg(args, name);
+  if (!value || value.length > 80) {
+    throw new McpProtocolError(-32602, `${name} must be a non-empty string of at most 80 characters.`);
+  }
+  return value;
+}
+function resultsWindowArg(args) {
+  const value = args.window ?? "30d";
+  if (typeof value !== "string" || !resultsWindows.includes(value)) {
+    throw new McpProtocolError(-32602, "window must be 7d, 30d, 90d, or 12m.");
+  }
+  return value;
+}
 function sourceArg(args) {
   const source = stringArg(args, "source") ?? "direct";
   if (!sourceNames.has(source)) {
@@ -24671,11 +24719,19 @@ function emptyLiveInputSchema() {
 }
 var hostedWorkspaceToolNames = /* @__PURE__ */ new Set([
   "get_integration_health",
+  "get_funnel_results",
+  "get_funnel_state",
+  "get_lead",
+  "get_opportunity",
+  "get_portfolio_results",
   "get_workspace_readiness",
   "list_mapping_gaps",
   "list_recent_signals",
   "get_signal_payload_preview",
   "inspect_funnel_entry",
+  "list_funnels",
+  "list_leads",
+  "list_opportunities",
   "propose_funnel_entry_installation",
   "get_account_strategy",
   "simulate_account_funnel_fit"
@@ -24879,6 +24935,136 @@ function saasFunnelsMcpToolDefinitions({
     }
   ];
   if (includeHostedAccountTools) {
+    const readAnnotations = {
+      idempotentHint: true,
+      openWorldHint: true,
+      readOnlyHint: true
+    };
+    const windowSchema = { default: "30d", enum: resultsWindows, type: "string" };
+    const uuidSchema = { format: "uuid", type: "string" };
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read bounded portfolio Results for one workspace and reporting window (30d by default). Funnel rows are paged within the first 100; stage counts, acquisition aggregates, and revenue value bases stay distinct. Check page.has_more and funnels_truncated for coverage.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          attribution_role: { enum: attributionRoles, type: "string" },
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          objective: { enum: ["convert", "grow", "save"], type: "string" },
+          offset: { type: "integer", minimum: 0, maximum: 100 },
+          window: windowSchema
+        },
+        type: "object"
+      },
+      name: "get_portfolio_results",
+      title: "Get Portfolio Results"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one Funnel's Results for a reporting window, including stage counts, configured acquisition aggregates, maturity, warnings, and separate revenue rows. Bounded arrays carry truncation flags.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { funnel_id: uuidSchema, window: windowSchema },
+        required: ["funnel_id"],
+        type: "object"
+      },
+      name: "get_funnel_results",
+      title: "Get Funnel Results"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "List up to 50 Opportunities in one workspace, optionally filtered by Funnel or lifecycle state. Returns exact total count and page.has_more; no raw evidence or monetary values.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0, maximum: 25e4 },
+          state: { enum: opportunityStates, type: "string" }
+        },
+        type: "object"
+      },
+      name: "list_opportunities",
+      title: "List Opportunities"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one Opportunity's bounded Funnel, account, lifecycle, delivery, and outcome summary in the selected workspace. No private evidence or monetary values.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { opportunity_id: uuidSchema },
+        required: ["opportunity_id"],
+        type: "object"
+      },
+      name: "get_opportunity",
+      title: "Get Opportunity"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "List up to 50 generated Leads in one workspace with source Funnel, lifecycle, delivery, and capture counts. Returns exact total count and page.has_more; no personal identity or raw responses.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: uuidSchema,
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0, maximum: 25e4 },
+          state: { enum: leadStates, type: "string" }
+        },
+        type: "object"
+      },
+      name: "list_leads",
+      title: "List Leads"
+    });
+    tools.push({
+      annotations: readAnnotations,
+      description: "Read one generated Lead's bounded source, lifecycle, delivery, capture, and verified outcome summary in the selected workspace. No personal identity or raw responses.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: { lead_id: uuidSchema },
+        required: ["lead_id"],
+        type: "object"
+      },
+      name: "get_lead",
+      title: "Get Lead"
+    });
+    tools.push({
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true
+      },
+      description: "List one selected workspace's Funnels with lifecycle, draft, and publication state. Results include evaluation time, total count, and pagination; use offset to read more pages. No Funnel definitions or customer data.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          include_archived: { type: "boolean" },
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          offset: { type: "integer", minimum: 0 }
+        },
+        type: "object"
+      },
+      name: "list_funnels",
+      title: "List Funnels"
+    });
+    tools.push({
+      annotations: {
+        idempotentHint: true,
+        openWorldHint: true,
+        readOnlyHint: true
+      },
+      description: "Read one Funnel's current lifecycle, draft and published revisions, and server-derived publication readiness in the selected workspace. No definitions or private evidence.",
+      inputSchema: {
+        additionalProperties: false,
+        properties: {
+          funnel_id: { type: "string", format: "uuid" }
+        },
+        required: ["funnel_id"],
+        type: "object"
+      },
+      name: "get_funnel_state",
+      title: "Get Funnel State"
+    });
     tools.push({
       annotations: {
         idempotentHint: true,
@@ -25210,7 +25396,7 @@ async function callSaaSFunnelsMcpTool(name, args, options = {}) {
         "workspace_id is available only with hosted OAuth; an API key is pinned to its workspace."
       );
     }
-    if ((name === "get_account_strategy" || name === "simulate_account_funnel_fit" || name === "list_workspaces") && !options.hostedMode) {
+    if ((name === "get_account_strategy" || name === "get_funnel_results" || name === "get_funnel_state" || name === "get_lead" || name === "get_opportunity" || name === "get_portfolio_results" || name === "list_funnels" || name === "list_leads" || name === "list_opportunities" || name === "simulate_account_funnel_fit" || name === "list_workspaces") && !options.hostedMode) {
       throw new McpToolExecutionError(
         "This tool requires hosted OAuth.",
         {
@@ -25261,6 +25447,102 @@ async function callSaaSFunnelsMcpTool(name, args, options = {}) {
       return structuredToolResult(
         await developerGet("/api/developer-tools/workspaces", {}, options)
       );
+    if (name === "list_funnels") {
+      const limit = args.limit ?? 25;
+      const offset = args.offset ?? 0;
+      if (!Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 50 || !Number.isInteger(offset) || Number(offset) < 0 || Number(offset) > 25e4 || args.include_archived !== void 0 && typeof args.include_archived !== "boolean") {
+        throw new McpProtocolError(
+          -32602,
+          "limit must be 1\u201350, offset must be 0\u2013250000, and include_archived must be boolean."
+        );
+      }
+      const query = new URLSearchParams({
+        include_archived: String(args.include_archived === true),
+        limit: String(limit),
+        offset: String(offset)
+      });
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/funnels?${query}`, args, options)
+      );
+    }
+    if (name === "get_funnel_state") {
+      const funnelId = uuidArg(args, "funnel_id", true);
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/funnels/${encodeURIComponent(funnelId)}`,
+          args,
+          options
+        )
+      );
+    }
+    if (name === "get_portfolio_results") {
+      const query = new URLSearchParams({
+        window: resultsWindowArg(args),
+        limit: String(integerArg(args, "limit", 50, 50)),
+        offset: String(integerArg(args, "offset", 0, 100))
+      });
+      const funnelId = uuidArg(args, "funnel_id");
+      if (funnelId) query.set("funnel_id", funnelId);
+      const objective = optionalFilterArg(args, "objective");
+      if (objective) {
+        if (!["convert", "grow", "save"].includes(objective)) {
+          throw new McpProtocolError(-32602, "objective must be convert, grow, or save.");
+        }
+        query.set("objective", objective);
+      }
+      const attributionRole = optionalFilterArg(args, "attribution_role");
+      if (attributionRole) {
+        if (!attributionRoles.includes(attributionRole)) {
+          throw new McpProtocolError(-32602, "attribution_role must be direct, influenced, or observed.");
+        }
+        query.set("attribution_role", attributionRole);
+      }
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/results?${query}`, args, options)
+      );
+    }
+    if (name === "get_funnel_results") {
+      const funnelId = uuidArg(args, "funnel_id", true);
+      const query = new URLSearchParams({ window: resultsWindowArg(args) });
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/funnels/${encodeURIComponent(funnelId)}/results?${query}`,
+          args,
+          options
+        )
+      );
+    }
+    if (name === "list_opportunities" || name === "list_leads") {
+      const query = new URLSearchParams({
+        limit: String(integerArg(args, "limit", 25, 50)),
+        offset: String(integerArg(args, "offset", 0, 25e4))
+      });
+      const funnelId = uuidArg(args, "funnel_id");
+      if (funnelId) query.set("funnel_id", funnelId);
+      const state = optionalFilterArg(args, "state");
+      if (state) {
+        const allowed = name === "list_leads" ? leadStates : opportunityStates;
+        if (!allowed.includes(state)) {
+          throw new McpProtocolError(-32602, `state is not a supported ${name === "list_leads" ? "Lead" : "Opportunity"} state.`);
+        }
+        query.set("state", state);
+      }
+      const resource = name === "list_leads" ? "leads" : "opportunities";
+      return structuredToolResult(
+        await developerGet(`/api/developer-tools/${resource}?${query}`, args, options)
+      );
+    }
+    if (name === "get_opportunity" || name === "get_lead") {
+      const resource = name === "get_lead" ? "leads" : "opportunities";
+      const id = uuidArg(args, name === "get_lead" ? "lead_id" : "opportunity_id", true);
+      return structuredToolResult(
+        await developerGet(
+          `/api/developer-tools/${resource}/${encodeURIComponent(id)}`,
+          args,
+          options
+        )
+      );
+    }
     if (name === "get_workspace_readiness")
       return structuredToolResult(
         await developerGet(