saasfunnels 0.1.0-beta.0 → 0.2.1

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,258 @@
+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 defaultRoots: string[];
+export declare const ignoredSegments: Set<string>;
+export declare const sensitivePathPattern: RegExp;
+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.2.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.2.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[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saasfunnels",
-  "version": "0.1.0-beta.0",
+  "version": "0.2.1",
   "private": false,
   "description": "SaaSFunnels CLI and local stdio MCP server",
   "author": "SaaSFunnels",
@@ -24,20 +24,26 @@
   "bin": {
     "saasfunnels": "dist/saasfunnels.js"
   },
+  "exports": {
+    "./library": {
+      "types": "./dist/types/library.d.ts",
+      "import": "./dist/library.js"
+    }
+  },
   "engines": {
     "node": ">=22"
   },
   "files": [
     "LICENSE",
     "README.md",
-    "dist/saasfunnels.js"
+    "dist"
   ],
   "license": "MIT",
   "publishConfig": {
     "access": "public",
-    "provenance": false,
+    "provenance": true,
     "registry": "https://registry.npmjs.org/",
-    "tag": "beta"
+    "tag": "latest"
   },
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -51,7 +57,8 @@
     "verify:metadata": "node scripts/verify-package-metadata.mjs",
     "verify:pack": "node scripts/verify-pack.mjs",
     "verify:installed": "node scripts/smoke-installed-package.mjs",
-    "release:verify": "npm run typecheck && npm test && npm run security:secrets && npm run security:audit && npm run verify:metadata && npm run verify:pack && npm run verify:installed"
+    "release:verify": "npm run typecheck && npm test && npm run security:secrets && npm run security:audit && npm run verify:metadata && npm run verify:pack && npm run verify:installed",
+    "eval": "node eval/run.mjs"
   },
   "devDependencies": {
     "@npmcli/package-json": "7.0.5",