saasfunnels 0.1.0-beta.0 → 0.2.0

package/dist/saasfunnels.js

@@ -23992,13 +23992,24 @@ var featureInstrumentationBindingSchema = external_exports.object({
   ),
   symbol: external_exports.string().min(1).max(240)
 }).strict();
+var featureInstrumentationManifestProducers = ["cli", "github_action", "github_app"];
+var featureInstrumentationScanRoles = ["series", "candidate"];
 var featureInstrumentationManifestSchema = external_exports.object({
   bindings: external_exports.array(featureInstrumentationBindingSchema).max(1e4),
+  discoveryRoots: external_exports.array(
+    external_exports.string().min(1).max(200).refine(
+      (value) => !value.startsWith("/") && !value.includes(".."),
+      "Discovery roots must be relative and contained."
+    )
+  ).max(50),
   environment: external_exports.enum(funnelFeatureEnvironments),
   manifestFingerprint: fingerprint2,
   manifestVersion: external_exports.string().min(1).max(80),
+  producer: external_exports.enum(featureInstrumentationManifestProducers),
+  repositoryKey: external_exports.string().min(1).max(200),
   repositoryRevision: external_exports.string().min(1).max(160),
-  schemaVersion: external_exports.literal(1),
+  scanRole: external_exports.enum(featureInstrumentationScanRoles),
+  schemaVersion: external_exports.literal(2),
   sdkVersions: external_exports.array(external_exports.string().max(40).regex(/^\d+\.\d+\.\d+$/)).max(10).default([]),
   validatedAt: timestamp2,
   validationState: external_exports.enum(["valid", "failed"])
@@ -24739,11 +24750,15 @@ function buildFeatureInstrumentationHandoff(input) {
         symbol: evidence.symbol
       }))
     ),
+    discoveryRoots: [...new Set(input.discoveryRoots ?? [])].sort(),
     environment: input.manifest.environment,
     manifestFingerprint,
     manifestVersion: manifestFingerprint.slice(0, 16),
+    producer: input.producer ?? "cli",
+    repositoryKey: input.repositoryKey,
     repositoryRevision: input.repositoryRevision,
-    schemaVersion: 1,
+    scanRole: input.scanRole ?? "series",
+    schemaVersion: 2,
     sdkVersions: [...new Set(input.sdkVersions ?? [])].sort(),
     validatedAt: input.validatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
     validationState: "valid"
@@ -24786,7 +24801,7 @@ Applied reviewed edits. Change record: ${result3.changeRecordPath}` : result3.id
 
 // src/identity.ts
 var SAASFUNNELS_CLI_NAME = "saasfunnels";
-var SAASFUNNELS_CLI_VERSION = "0.1.0-beta.0";
+var SAASFUNNELS_CLI_VERSION = "0.1.0-beta.1";
 var SAASFUNNELS_PRODUCT_NAME = "SaaSFunnels";
 var SAASFUNNELS_DEFAULT_API_BASE_URL = "https://app.saasfunnels.ai";
 var SAASFUNNELS_ENV = Object.freeze({
@@ -24817,6 +24832,73 @@ function saasFunnelsPublicText(value) {
   ).replaceAll("prevenueFeatureKeys", "saasFunnelsFeatureKeys").replaceAll("PrevenueFeatureKey", "SaaSFunnelsFeatureKey").replaceAll("SaaSFunnels", SAASFUNNELS_PRODUCT_NAME);
 }
 
+// src/check-summary.ts
+var kindHeadings = {
+  added: "New Feature bindings",
+  moved: "Moved bindings",
+  removed: "Removed bindings",
+  renamed: "Renamed bindings"
+};
+var rejectionReasons = {
+  binding_duplicate: "duplicate evidence for one location",
+  binding_fingerprint_invalid: "malformed fingerprint",
+  binding_kind_unknown: "unrecognised binding kind",
+  binding_path_unsafe: "unsafe or sensitive file path",
+  binding_shape_invalid: "malformed binding"
+};
+function formatFeatureDriftCheckSummary(input) {
+  const lines = [];
+  const removed = input.drift.filter((entry) => entry.kind === "removed");
+  const breaking = removed.filter(
+    (entry) => entry.featureKey && (input.targetedFeatureKeys ?? []).includes(entry.featureKey)
+  );
+  if (breaking.length) {
+    lines.push("### Live Funnels target Features this change removes");
+    for (const entry of breaking) {
+      lines.push(`- \`${entry.featureKey}\`${entry.location ? ` \u2014 ${entry.location}` : ""}`);
+    }
+    lines.push("");
+  }
+  if (!input.drift.length) {
+    lines.push("No Feature binding changes.");
+  } else {
+    for (const kind of ["removed", "renamed", "moved", "added"]) {
+      const entries = input.drift.filter((entry) => entry.kind === kind);
+      if (!entries.length) continue;
+      lines.push(`### ${kindHeadings[kind]}`);
+      for (const entry of entries) {
+        lines.push(
+          `- \`${entry.featureKey ?? "unknown"}\`${entry.location ? ` \u2014 ${entry.location}` : ""}`
+        );
+      }
+      lines.push("");
+    }
+  }
+  if (input.proposedFeatureKeys?.length) {
+    lines.push("### Found in code, not in your catalog");
+    for (const featureKey of input.proposedFeatureKeys) {
+      lines.push(`- \`${featureKey}\``);
+    }
+    lines.push("");
+  }
+  if (input.rejectedBindings?.length) {
+    lines.push("### Evidence that could not be recorded");
+    for (const rejection of input.rejectedBindings) {
+      lines.push(
+        `- \`${rejection.featureKey ?? "unknown"}\` \u2014 ${rejectionReasons[rejection.reason] ?? rejection.reason}`
+      );
+    }
+    lines.push("");
+  }
+  return {
+    // Never fail the build: a false positive blocking a merge queue is the
+    // fastest way to get uninstalled.
+    conclusion: "neutral",
+    summary: lines.join("\n").trim(),
+    title: breaking.length ? `${breaking.length} Feature${breaking.length === 1 ? "" : "s"} targeted by live Funnels removed` : input.drift.length ? `${input.drift.length} Feature binding change${input.drift.length === 1 ? "" : "s"}` : "No Feature binding changes"
+  };
+}
+
 // src/mcp.ts
 import { createInterface } from "node:readline";
 
@@ -26173,7 +26255,7 @@ Usage:
   ${SAASFUNNELS_CLI_NAME} events send-test [--file <file>] [--json]
   ${SAASFUNNELS_CLI_NAME} features setup [--root <paths>] [--exclude <paths>] [--accept <ids|all>] [--reject <ids>] [--map <id=key>] [--manifest-only] [--apply] [--json]
   ${SAASFUNNELS_CLI_NAME} features check --feature <key> --account-id <uuid> [--environment test] [--json]
-  ${SAASFUNNELS_CLI_NAME} features handoff [--file <path>] --repository-revision <revision> [--send] [--json]
+  ${SAASFUNNELS_CLI_NAME} features handoff [--file <path>] --repository-revision <revision> --repository-key <key> [--discovery-roots <paths>] [--scan-role series|candidate] [--producer cli|github_action|github_app] [--send] [--json]
   ${SAASFUNNELS_CLI_NAME} catalog discover [feature setup options]
   ${SAASFUNNELS_CLI_NAME} catalog validate [file] [--json]
   ${SAASFUNNELS_CLI_NAME} catalog diff [feature setup options]
@@ -26396,6 +26478,27 @@ async function commandFeatures(args, flags, options) {
         "Missing --repository-revision for the structured Feature handoff.\n"
       );
     }
+    const repositoryKey = flagString(flags, "repository-key");
+    if (!repositoryKey) {
+      return result(
+        2,
+        "",
+        "Missing --repository-key for the structured Feature handoff.\n"
+      );
+    }
+    const scanRole = flagString(flags, "scan-role") ?? "series";
+    if (scanRole !== "series" && scanRole !== "candidate") {
+      return result(2, "", "Use --scan-role series or --scan-role candidate.\n");
+    }
+    const producer = flagString(flags, "producer") ?? "cli";
+    if (producer !== "cli" && producer !== "github_action" && producer !== "github_app") {
+      return result(
+        2,
+        "",
+        "Use --producer cli, --producer github_action, or --producer github_app.\n"
+      );
+    }
+    const discoveryRoots = (flagString(flags, "discovery-roots") ?? "").split(",").map((root) => root.trim()).filter(Boolean);
     const source = await filesystem(options).readFile(
       resolve2(cwd(options), path),
       "utf8"
@@ -26422,8 +26525,12 @@ ${validation.errors.map((error51) => `- ${error51}`).join("\n")}
     } catch {
     }
     const handoff = buildFeatureInstrumentationHandoff({
+      discoveryRoots,
       manifest: validation.manifest,
+      producer,
+      repositoryKey,
       repositoryRevision,
+      scanRole,
       sdkVersions
     });
     if (hasFlag(flags, "send")) {
@@ -26434,8 +26541,9 @@ ${validation.errors.map((error51) => `- ${error51}`).join("\n")}
           "",
           "Missing SAASFUNNELS_API_KEY with features:write scope for --send.\n"
         );
+      const endpoint = scanRole === "candidate" ? "/api/developer-tools/features/instrumentation/preview" : "/api/developer-tools/features/instrumentation";
       const response = await (options.fetch ?? fetch)(
-        `${apiBaseUrl2(options, flags)}/api/developer-tools/features/instrumentation`,
+        `${apiBaseUrl2(options, flags)}${endpoint}`,
         {
           body: JSON.stringify(handoff),
           headers: {
@@ -26446,7 +26554,14 @@ ${validation.errors.map((error51) => `- ${error51}`).join("\n")}
         }
       );
       const body = await response.json();
-      return jsonMode(flags) ? jsonResult(response.ok ? 0 : 1, body) : response.ok ? result(
+      const reported = response.ok ? {
+        ...body,
+        checkSummary: formatFeatureDriftCheckSummary({
+          drift: body?.data?.drift ?? [],
+          rejectedBindings: body?.data?.rejectedBindings ?? []
+        })
+      } : body;
+      return jsonMode(flags) ? jsonResult(response.ok ? 0 : 1, reported) : response.ok ? result(
         0,
         "Feature instrumentation handoff accepted. Open the Features review link returned by SaaSFunnels.\n"
       ) : result(1, "", "Feature instrumentation handoff was rejected.\n");

package/dist/types/capabilities.d.ts

@@ -0,0 +1,14 @@
+export type AgentCapabilityId = "account.funnel_fit.simulate" | "account.strategy.read" | "developer.event.validate" | "developer.feature_manifest.validate" | "developer.handoff.generate" | "developer.workspace.read" | "funnel.entry.apply" | "funnel.entry.evidence.submit" | "funnel.entry.inspect" | "funnel.entry.plan" | "funnel.entry.test" | "setup.test_event.send";
+type AgentExecutionBoundary = "api_key" | "hosted_mcp" | "in_app" | "local_cli" | "local_mcp" | "scheduled_agent";
+type AgentOperationClass = "external_write" | "plan" | "prepare" | "read" | "reversible_write" | "simulate" | "validate";
+type Capability = {
+    boundaries: AgentExecutionBoundary[];
+    enabled: true;
+    id: AgentCapabilityId;
+    operationClass: AgentOperationClass;
+};
+export declare function getAgentCapability(id: AgentCapabilityId): Capability;
+export declare function agentCapabilityAllowedAtBoundary(id: AgentCapabilityId, boundary: AgentExecutionBoundary, { mutationsEnabled }?: {
+    mutationsEnabled?: boolean;
+}): boolean;
+export {};

package/dist/types/check-summary.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Renders a drift response as a GitHub check summary.
+ *
+ * Lives in the CLI package rather than the Action because this is the only part
+ * of the Action carrying logic worth testing; the Action itself is a thin
+ * wrapper around `features handoff` plus this formatter.
+ */
+export type FeatureDriftEntry = {
+    featureKey: string | null;
+    kind: "added" | "moved" | "removed" | "renamed";
+    location: string | null;
+};
+export type FeatureDriftRejection = {
+    featureKey: string | null;
+    reason: string;
+};
+export declare function formatFeatureDriftCheckSummary(input: {
+    drift: FeatureDriftEntry[];
+    proposedFeatureKeys?: string[];
+    rejectedBindings?: FeatureDriftRejection[];
+    targetedFeatureKeys?: string[];
+}): {
+    conclusion: "neutral";
+    summary: string;
+    title: string;
+};

package/dist/types/feature-setup.d.ts

@@ -0,0 +1,255 @@
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { z } from "zod";
+declare const featureBindingKinds: readonly ["server_enforcement", "browser_presentation", "usage_reporter", "funnel_trigger", "discovery"];
+export declare const featureCatalogManifestSchema: z.ZodObject<{
+    environment: z.ZodEnum<{
+        test: "test";
+        production: "production";
+    }>;
+    features: z.ZodArray<z.ZodObject<{
+        accessModel: z.ZodEnum<{
+            boolean: "boolean";
+            limit: "limit";
+        }>;
+        aliases: z.ZodArray<z.ZodString>;
+        description: z.ZodString;
+        evidence: z.ZodArray<z.ZodObject<{
+            bindingIdentityFingerprint: z.ZodString;
+            bindingKind: z.ZodEnum<{
+                server_enforcement: "server_enforcement";
+                browser_presentation: "browser_presentation";
+                usage_reporter: "usage_reporter";
+                funnel_trigger: "funnel_trigger";
+                discovery: "discovery";
+            }>;
+            confidenceBasisPoints: z.ZodNumber;
+            file: z.ZodString;
+            fingerprint: z.ZodString;
+            line: z.ZodNumber;
+            rationale: z.ZodString;
+            symbol: z.ZodString;
+        }, z.core.$strict>>;
+        key: z.ZodString;
+        name: z.ZodString;
+        unit: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    generatedBy: z.ZodLiteral<"saasfunnels features setup">;
+    schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strict>;
+export type FeatureCatalogManifest = z.infer<typeof featureCatalogManifestSchema>;
+export type FeatureCandidate = {
+    accessModel: "boolean" | "limit";
+    bindingIdentityFingerprint: string;
+    bindingKind: (typeof featureBindingKinds)[number];
+    confidenceBasisPoints: number;
+    file: string;
+    fingerprint: string;
+    id: string;
+    line: number;
+    name: string;
+    rationale: string;
+    suggestedKey: string;
+    symbol: string;
+    unit: string | null;
+};
+export type FeatureSetupEdit = {
+    afterHash: string;
+    beforeHash: string | null;
+    diff: string;
+    id: string;
+    kind: "generated_constants" | "manifest";
+    path: string;
+    selected: boolean;
+};
+export type FeatureSetupInput = {
+    accept?: string[];
+    accountId?: string;
+    apiBaseUrl: string;
+    apply: boolean;
+    cwd: string;
+    environment: "test" | "production";
+    exclude?: string[];
+    fetch?: typeof fetch;
+    include?: string[];
+    manifestOnly: boolean;
+    mappings?: Record<string, string>;
+    prompt?: (message: string) => Promise<string>;
+    reject?: string[];
+    serverKey?: string;
+};
+export type FeatureRuntimeCheckResult = {
+    decision?: {
+        allowed: boolean;
+        reasonCode: string;
+        source: string;
+        value: unknown;
+    };
+    featureKey?: string;
+    reason?: string;
+    state: "failed" | "passed" | "skipped";
+};
+export type FeatureSetupResult = {
+    applied: boolean;
+    candidates: FeatureCandidate[];
+    changeRecordPath?: string;
+    edits: FeatureSetupEdit[];
+    environment: "test" | "production";
+    framework: {
+        framework: "nextjs" | "unsupported";
+        packageManager: "bun" | "npm" | "pnpm" | "unknown" | "yarn";
+        saasFunnelsPackages: string[];
+        roots: string[];
+    };
+    idempotent: boolean;
+    instructions: Array<{
+        featureKey: string;
+        file: string;
+        line: number;
+        message: string;
+        symbol: string;
+    }>;
+    manifest: FeatureCatalogManifest;
+    manifestPath: string;
+    ok: boolean;
+    reviewUrl: string;
+    runtimeCheck: {
+        featureKey?: string;
+        reason?: string;
+        state: "failed" | "passed" | "skipped";
+    };
+    scannedFileCount: number;
+    validation: {
+        errors: string[];
+        ok: boolean;
+    };
+};
+declare function readable(path: string): Promise<string | null>;
+type FeatureSetupAtomicIo = {
+    mkdir: typeof mkdir;
+    read: typeof readable;
+    rename: typeof rename;
+    remove: typeof rm;
+    write: typeof writeFile;
+};
+export declare function applyFeatureSetupChangesAtomically(cwd: string, changes: Array<{
+    contents: string;
+    path: string;
+}>, io?: FeatureSetupAtomicIo): Promise<void>;
+export declare function validateFeatureCatalogManifest(value: unknown): {
+    errors: never[];
+    manifest: {
+        environment: "test" | "production";
+        features: {
+            accessModel: "boolean" | "limit";
+            aliases: string[];
+            description: string;
+            evidence: {
+                bindingIdentityFingerprint: string;
+                bindingKind: "server_enforcement" | "browser_presentation" | "usage_reporter" | "funnel_trigger" | "discovery";
+                confidenceBasisPoints: number;
+                file: string;
+                fingerprint: string;
+                line: number;
+                rationale: string;
+                symbol: string;
+            }[];
+            key: string;
+            name: string;
+            unit: string | null;
+        }[];
+        generatedBy: "saasfunnels features setup";
+        schemaVersion: 1;
+    };
+    ok: true;
+} | {
+    errors: string[];
+    manifest: null;
+    ok: false;
+};
+export declare function readFeatureCatalogManifest(path: string): Promise<{
+    errors: never[];
+    manifest: {
+        environment: "test" | "production";
+        features: {
+            accessModel: "boolean" | "limit";
+            aliases: string[];
+            description: string;
+            evidence: {
+                bindingIdentityFingerprint: string;
+                bindingKind: "server_enforcement" | "browser_presentation" | "usage_reporter" | "funnel_trigger" | "discovery";
+                confidenceBasisPoints: number;
+                file: string;
+                fingerprint: string;
+                line: number;
+                rationale: string;
+                symbol: string;
+            }[];
+            key: string;
+            name: string;
+            unit: string | null;
+        }[];
+        generatedBy: "saasfunnels features setup";
+        schemaVersion: 1;
+    };
+    ok: true;
+} | {
+    errors: string[];
+    manifest: null;
+    ok: false;
+}>;
+export declare function isFeatureKey(value: string): boolean;
+export declare function runFeatureRuntimeCheck(input: {
+    accountId?: string;
+    apiBaseUrl: string;
+    featureKey?: string;
+    fetch?: typeof fetch;
+    serverKey?: string;
+}): Promise<FeatureRuntimeCheckResult>;
+export declare function runFeatureSetup(input: FeatureSetupInput): Promise<FeatureSetupResult>;
+export declare function parseFeatureMappings(values: string[]): {
+    [k: string]: string;
+};
+export declare function parseFeatureManifestSource(source: string): {
+    errors: never[];
+    manifest: {
+        environment: "test" | "production";
+        features: {
+            accessModel: "boolean" | "limit";
+            aliases: string[];
+            description: string;
+            evidence: {
+                bindingIdentityFingerprint: string;
+                bindingKind: "server_enforcement" | "browser_presentation" | "usage_reporter" | "funnel_trigger" | "discovery";
+                confidenceBasisPoints: number;
+                file: string;
+                fingerprint: string;
+                line: number;
+                rationale: string;
+                symbol: string;
+            }[];
+            key: string;
+            name: string;
+            unit: string | null;
+        }[];
+        generatedBy: "saasfunnels features setup";
+        schemaVersion: 1;
+    };
+    ok: true;
+} | {
+    errors: string[];
+    manifest: null;
+    ok: false;
+};
+export declare function buildFeatureInstrumentationHandoff(input: {
+    discoveryRoots?: readonly string[];
+    manifest: FeatureCatalogManifest;
+    producer?: "cli" | "github_action" | "github_app";
+    repositoryKey: string;
+    repositoryRevision: string;
+    scanRole?: "series" | "candidate";
+    sdkVersions?: readonly string[];
+    validatedAt?: string;
+}): unknown;
+export declare function featureSdkVersionsFromPackageJson(value: unknown): string[];
+export declare function featureSetupSummary(result: FeatureSetupResult): string;
+export {};

package/dist/types/identity.d.ts

@@ -0,0 +1,14 @@
+export declare const SAASFUNNELS_CLI_NAME = "saasfunnels";
+export declare const SAASFUNNELS_CLI_VERSION = "0.1.0-beta.1";
+export declare const SAASFUNNELS_PRODUCT_NAME = "SaaSFunnels";
+export declare const SAASFUNNELS_DEFAULT_API_BASE_URL = "https://app.saasfunnels.ai";
+export declare const SAASFUNNELS_ENV: Readonly<{
+    apiBaseUrl: string[];
+    apiKey: string[];
+    funnelsServerKey: string[];
+    ingestApiKey: string[];
+    mcpEnableFunnelWrites: string[];
+    mcpEnableFunnelTests: string[];
+    mcpEnableSendTestEvent: string[];
+}>;
+export declare function saasFunnelsPublicText(value: string): string;

package/dist/types/library.d.ts

@@ -0,0 +1,3 @@
+export { formatFeatureDriftCheckSummary, type FeatureDriftEntry, type FeatureDriftRejection, } from "./check-summary.js";
+export { callSaaSFunnelsMcpTool, handleSaaSFunnelsMcpMessage, hostedSaaSFunnelsMcpToolDefinitions, readSaaSFunnelsMcpResource, saasFunnelsMcpCapabilityForTool, saasFunnelsMcpResources, saasFunnelsMcpToolCapabilityIds, saasFunnelsMcpToolDefinitions, SAASFUNNELS_MCP_PROTOCOL_VERSION, SAASFUNNELS_MCP_SERVER_VERSION, serveSaaSFunnelsMcp, type SaaSFunnelsMcpJsonObject, type SaaSFunnelsMcpOptions, type SaaSFunnelsMcpResourceDefinition, type SaaSFunnelsMcpToolDefinition, type SaaSFunnelsMcpToolName, } from "./mcp.js";
+export { SAASFUNNELS_CLI_NAME, SAASFUNNELS_CLI_VERSION, SAASFUNNELS_DEFAULT_API_BASE_URL, SAASFUNNELS_ENV, SAASFUNNELS_PRODUCT_NAME, } from "./identity.js";

package/dist/types/mcp.d.ts

@@ -0,0 +1,91 @@
+import { type AgentCapabilityId } from "./capabilities.js";
+type McpEnv = Record<string, string | undefined>;
+export type SaaSFunnelsMcpJsonObject = Record<string, unknown>;
+type JsonObject = SaaSFunnelsMcpJsonObject;
+type JsonRpcId = number | string | null;
+type JsonRpcResponse = {
+    error?: {
+        code: number;
+        data?: unknown;
+        message: string;
+    };
+    id: JsonRpcId;
+    jsonrpc: "2.0";
+    result?: unknown;
+};
+export type SaaSFunnelsMcpToolDefinition = {
+    annotations?: Record<string, unknown>;
+    description: string;
+    inputSchema: JsonObject;
+    name: string;
+    outputSchema?: JsonObject;
+    title: string;
+};
+type McpToolDefinition = SaaSFunnelsMcpToolDefinition;
+export type SaaSFunnelsMcpResourceDefinition = {
+    description: string;
+    mimeType: string;
+    name: string;
+    title: string;
+    uri: string;
+};
+type McpResourceDefinition = SaaSFunnelsMcpResourceDefinition;
+export declare const saasFunnelsMcpToolCapabilityIds: {
+    readonly get_account_strategy: "account.strategy.read";
+    readonly apply_funnel_entry: "funnel.entry.apply";
+    readonly generate_direct_api_handoff: "developer.handoff.generate";
+    readonly get_integration_health: "developer.workspace.read";
+    readonly get_signal_payload_preview: "developer.workspace.read";
+    readonly get_workspace_readiness: "developer.workspace.read";
+    readonly inspect_funnel_entry: "funnel.entry.inspect";
+    readonly list_mapping_gaps: "developer.workspace.read";
+    readonly list_recent_signals: "developer.workspace.read";
+    readonly simulate_account_funnel_fit: "account.funnel_fit.simulate";
+    readonly propose_funnel_entry_installation: "funnel.entry.plan";
+    readonly run_funnel_binding_test: "funnel.entry.test";
+    readonly send_test_event: "setup.test_event.send";
+    readonly submit_funnel_entry_evidence: "funnel.entry.evidence.submit";
+    readonly validate_event_payload: "developer.event.validate";
+    readonly validate_feature_catalog_manifest: "developer.feature_manifest.validate";
+};
+export type SaaSFunnelsMcpToolName = keyof typeof saasFunnelsMcpToolCapabilityIds;
+export declare function saasFunnelsMcpCapabilityForTool(name: string): {
+    boundaries: ("api_key" | "hosted_mcp" | "in_app" | "local_cli" | "local_mcp" | "scheduled_agent")[];
+    enabled: true;
+    id: AgentCapabilityId;
+    operationClass: "external_write" | "plan" | "prepare" | "read" | "reversible_write" | "simulate" | "validate";
+} | null;
+export type SaaSFunnelsMcpOptions = {
+    apiBaseUrlOverride?: string;
+    allowFunnelWrites?: boolean;
+    allowFunnelTests?: boolean;
+    allowTestWrites?: boolean;
+    authorizationHeader?: string;
+    env?: McpEnv;
+    fetch?: typeof fetch;
+    hostedMode?: boolean;
+    input?: NodeJS.ReadableStream;
+    output?: Pick<NodeJS.WritableStream, "write">;
+};
+declare const mcpProtocolVersion = "2025-06-18";
+declare const mcpServerVersion = "0.1.0-beta.1";
+export declare function saasFunnelsMcpResources(): McpResourceDefinition[];
+export declare function readSaaSFunnelsMcpResource(uri: string, options?: SaaSFunnelsMcpOptions): string;
+export declare function saasFunnelsMcpToolDefinitions({ allowFunnelTests, allowFunnelWrites, allowTestWrites, includeHostedAccountTools, }?: {
+    allowFunnelTests?: boolean;
+    allowFunnelWrites?: boolean;
+    allowTestWrites?: boolean;
+    includeHostedAccountTools?: boolean;
+}): McpToolDefinition[];
+export declare function hostedSaaSFunnelsMcpToolDefinitions(): SaaSFunnelsMcpToolDefinition[];
+export declare function callSaaSFunnelsMcpTool(name: string, args: JsonObject, options?: SaaSFunnelsMcpOptions): Promise<{
+    content: {
+        text: string;
+        type: string;
+    }[];
+    isError: boolean;
+    structuredContent: SaaSFunnelsMcpJsonObject;
+}>;
+export declare function handleSaaSFunnelsMcpMessage(message: unknown, options?: SaaSFunnelsMcpOptions): Promise<JsonRpcResponse | undefined>;
+export declare function serveSaaSFunnelsMcp(options?: SaaSFunnelsMcpOptions): Promise<void>;
+export { mcpProtocolVersion as SAASFUNNELS_MCP_PROTOCOL_VERSION, mcpServerVersion as SAASFUNNELS_MCP_SERVER_VERSION, };

package/dist/types/runtime-contracts.d.ts

@@ -0,0 +1,73 @@
+export type DeveloperToolEventSource = "direct" | "posthog" | "segment";
+
+export type DeveloperToolValidationIssue = {
+  code: string;
+  message: string;
+  path?: string;
+  severity: "error" | "info" | "warning";
+};
+
+export type DeveloperToolSourceContract = {
+  auth_summary: string;
+  docs_url: string;
+  endpoint: string;
+  key: DeveloperToolEventSource;
+  name: string;
+  recommended_allowlist: string[];
+  required_fields: string[];
+  sample_payload: Record<string, unknown>;
+  scope: string;
+  setup_steps: string[];
+};
+
+export const DEVELOPER_TOOLS_CONTRACT_SCHEMA_VERSION: string;
+export const developerToolEventSources: readonly DeveloperToolEventSource[];
+export const eventKinds: readonly string[];
+export const eventSentimentSources: readonly string[];
+export const eventSentiments: readonly string[];
+export const semanticEventTypes: readonly string[];
+export const signalFamilyContracts: readonly Array<{
+  description: string;
+  label: string;
+  optionalSemanticTypes: string[];
+  requiredSemanticTypes: string[];
+  signalFamilyKey: string;
+}>;
+
+export const featureInstrumentationManifestSchema: import("zod").ZodTypeAny;
+
+export function getDeveloperToolAgentHandoffArtifacts(input: {
+  endpoint: string;
+  eventPlan?: unknown;
+}): Record<
+  "claude-code" | "codex" | "cursor" | "markdown",
+  {
+    file_contents: string;
+    install_command?: string;
+    label: string;
+    prompt: string;
+    target: string;
+    target_path: string;
+    version: string;
+  }
+>;
+
+export function getDeveloperToolSourceContract(
+  source: DeveloperToolEventSource,
+): DeveloperToolSourceContract;
+
+export function validateDeveloperToolEventPayload(input: {
+  payload: unknown;
+  source: DeveloperToolEventSource;
+}): {
+  errors: DeveloperToolValidationIssue[];
+  idempotency: Record<string, unknown>;
+  mapping_hints: Record<string, unknown>;
+  normalized_event?: Record<string, unknown>;
+  ok: boolean;
+  redaction: Record<string, unknown>;
+  revenue_relevant?: boolean;
+  schema_version: string;
+  source: DeveloperToolEventSource;
+  warnings: DeveloperToolValidationIssue[];
+};