@ascendkit/cli 0.1.10

package/dist/utils/journey-format.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Human-readable formatting for journey data.
+ * Used by MCP tools to present journey definitions and analytics conversationally.
+ */
+interface JourneyData {
+    id: string;
+    name: string;
+    description?: string;
+    status: string;
+    entryEvent: string;
+    entryNode: string;
+    reEntryPolicy?: string;
+    nodes: Record<string, {
+        action?: {
+            type?: string;
+        };
+        terminal?: boolean;
+    }>;
+    transitions?: Array<{
+        from?: string;
+        from_?: string;
+        to?: string;
+        trigger?: {
+            type?: string;
+            event?: string;
+            delay?: string;
+        };
+        priority?: number;
+    }>;
+    stats?: {
+        totalEnrolled?: number;
+        currentlyActive?: number;
+        completed?: number;
+    };
+    version?: number;
+    warnings?: string[];
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface AnalyticsData {
+    journey: {
+        id: string;
+        name: string;
+        status: string;
+    };
+    nodes: Array<{
+        name: string;
+        action: string;
+        terminal: boolean;
+        userCount: number;
+        medianTimeHours: number;
+    }>;
+    transitions: Array<{
+        from: string;
+        to: string;
+        type: string;
+        event?: string;
+        delay?: string;
+        userCount: number;
+    }>;
+    terminalDistribution: Array<{
+        node: string;
+        count: number;
+    }>;
+    totals: {
+        enrolled: number;
+        active: number;
+        completed: number;
+        failed: number;
+        exited?: number;
+    };
+}
+export declare function formatJourneyWithGuidance(journey: JourneyData): string;
+export declare function formatJourneyList(data: {
+    journeys: JourneyData[];
+    total: number;
+}): string;
+interface NodeListItem {
+    name: string;
+    action: {
+        type?: string;
+        templateSlug?: string;
+        surveySlug?: string;
+        tagName?: string;
+        stageName?: string;
+    };
+    terminal: boolean;
+    isEntryNode: boolean;
+    outgoingTransitions: number;
+    incomingTransitions: number;
+}
+interface TransitionListItem {
+    name: string;
+    from: string;
+    to: string;
+    trigger: {
+        type?: string;
+        event?: string;
+        delay?: string;
+    };
+    priority?: number;
+}
+export declare function formatNodeList(data: {
+    nodes: NodeListItem[];
+}): string;
+export declare function formatSingleNode(data: JourneyData, action: string, nodeName: string): string;
+export declare function formatTransitionList(data: {
+    transitions: TransitionListItem[];
+}): string;
+export declare function formatSingleTransition(data: JourneyData, action: string, transitionName: string): string;
+export declare function formatJourneyAnalytics(data: AnalyticsData): string;
+export {};

package/dist/utils/journey-format.js

@@ -0,0 +1,200 @@
+/**
+ * Human-readable formatting for journey data.
+ * Used by MCP tools to present journey definitions and analytics conversationally.
+ */
+const STATUS_ICONS = {
+    draft: "draft",
+    active: "active",
+    paused: "paused",
+    archived: "archived",
+};
+function nodeCount(journey) {
+    return Object.keys(journey.nodes || {}).length;
+}
+function transitionCount(journey) {
+    return (journey.transitions || []).length;
+}
+export function formatJourneyWithGuidance(journey) {
+    const nodes = nodeCount(journey);
+    const transitions = transitionCount(journey);
+    const stats = journey.stats;
+    const lines = [
+        `Journey: ${journey.name} (${journey.id})`,
+        `Status: ${STATUS_ICONS[journey.status] || journey.status} | Nodes: ${nodes} | Transitions: ${transitions} | Entry: ${journey.entryEvent}`,
+    ];
+    if (stats && stats.totalEnrolled) {
+        lines.push(`Stats: ${stats.totalEnrolled} enrolled, ${stats.currentlyActive ?? 0} active, ${stats.completed ?? 0} completed`);
+    }
+    if (journey.description) {
+        lines.push(`Description: ${journey.description}`);
+    }
+    // Graph summary
+    lines.push("");
+    lines.push("Nodes:");
+    for (const [name, node] of Object.entries(journey.nodes || {})) {
+        const action = node.action?.type || "none";
+        const terminal = node.terminal ? " (terminal)" : "";
+        const isEntry = name === journey.entryNode ? " [entry]" : "";
+        lines.push(`  ${name}: ${action}${terminal}${isEntry}`);
+    }
+    if (journey.transitions && journey.transitions.length > 0) {
+        lines.push("");
+        lines.push("Transitions:");
+        for (const t of journey.transitions) {
+            const from = t.from || t.from_;
+            const trigger = t.trigger;
+            let desc;
+            if (trigger?.type === "timer") {
+                desc = `timer (${trigger.delay || "?"})`;
+            }
+            else {
+                desc = trigger?.event || "event";
+            }
+            lines.push(`  ${from} → ${t.to} [${desc}]`);
+        }
+    }
+    // Warnings
+    if (journey.warnings && journey.warnings.length > 0) {
+        lines.push("");
+        lines.push("Warnings:");
+        for (const w of journey.warnings) {
+            lines.push(`  ! ${w}`);
+        }
+    }
+    // Next steps
+    const hints = [];
+    if (journey.status === "draft") {
+        hints.push("Journey is in draft. Use journey_activate to start enrolling users.");
+    }
+    else if (journey.status === "active") {
+        hints.push("Journey is active and enrolling users. Use journey_analytics to see user flow.");
+    }
+    else if (journey.status === "paused") {
+        hints.push("Journey is paused. Actions are queued. Use journey_activate to resume.");
+    }
+    else if (journey.status === "archived") {
+        hints.push("Journey is archived. No further enrollment or transitions.");
+    }
+    if (hints.length > 0) {
+        lines.push("");
+        lines.push("Next steps:");
+        for (const hint of hints) {
+            lines.push(`  → ${hint}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatJourneyList(data) {
+    const { journeys, total } = data;
+    if (!journeys || journeys.length === 0) {
+        return "No journeys found. Use journey_create to design a user lifecycle journey.";
+    }
+    const lines = [`${total} journey(s):\n`];
+    for (const j of journeys) {
+        const nodes = nodeCount(j);
+        const stats = j.stats;
+        const enrolled = stats?.totalEnrolled ?? 0;
+        const active = stats?.currentlyActive ?? 0;
+        let readiness;
+        if (j.status === "draft") {
+            readiness = "draft";
+        }
+        else if (j.status === "active") {
+            readiness = `active — ${active} active / ${enrolled} enrolled`;
+        }
+        else {
+            readiness = j.status;
+        }
+        lines.push(`  ${j.id} | ${j.name} — ${nodes} nodes — ${readiness}`);
+    }
+    return lines.join("\n");
+}
+function formatActionLabel(action) {
+    const type = action?.type || "none";
+    if (type === "send_email") {
+        const parts = [`send_email (${action.templateSlug || "?"})`];
+        if (action.surveySlug)
+            parts.push(`+ survey: ${action.surveySlug}`);
+        return parts.join(" ");
+    }
+    if (type === "tag_user")
+        return `tag_user (${action.tagName || "?"})`;
+    if (type === "advance_stage")
+        return `advance_stage (${action.stageName || "?"})`;
+    return type;
+}
+function formatTriggerLabel(trigger) {
+    if (trigger?.type === "timer")
+        return `after ${trigger.delay || "?"}`;
+    return `on ${trigger?.event || "event"}`;
+}
+export function formatNodeList(data) {
+    const nodes = data.nodes || [];
+    if (nodes.length === 0) {
+        return "No nodes. Use journey_add_node to add the first node.";
+    }
+    const lines = [`${nodes.length} node(s):\n`];
+    for (const n of nodes) {
+        const entry = n.isEntryNode ? " [entry]" : "";
+        const terminal = n.terminal ? " (terminal)" : "";
+        const action = formatActionLabel(n.action);
+        const edges = `${n.outgoingTransitions} out / ${n.incomingTransitions} in`;
+        lines.push(`  ${n.name}: ${action}${terminal}${entry}`);
+        lines.push(`    transitions: ${edges}`);
+    }
+    return lines.join("\n");
+}
+export function formatSingleNode(data, action, nodeName) {
+    return `${action} node '${nodeName}'.\n\n${formatJourneyWithGuidance(data)}`;
+}
+export function formatTransitionList(data) {
+    const transitions = data.transitions || [];
+    if (transitions.length === 0) {
+        return "No transitions. Use journey_add_transition to connect nodes.";
+    }
+    const lines = [`${transitions.length} transition(s):\n`];
+    for (const t of transitions) {
+        const trigger = formatTriggerLabel(t.trigger);
+        const priority = t.priority != null ? ` [priority: ${t.priority}]` : "";
+        lines.push(`  ${t.name}: ${t.from} → ${t.to} — ${trigger}${priority}`);
+    }
+    return lines.join("\n");
+}
+export function formatSingleTransition(data, action, transitionName) {
+    return `${action} transition '${transitionName}'.\n\n${formatJourneyWithGuidance(data)}`;
+}
+export function formatJourneyAnalytics(data) {
+    const { journey, nodes, transitions, terminalDistribution, totals } = data;
+    const lines = [
+        `Analytics: ${journey.name} (${journey.id})`,
+        `Status: ${journey.status}`,
+        "",
+        `Totals: ${totals.enrolled} enrolled, ${totals.active} active, ${totals.completed} completed, ${totals.failed} failed`,
+        "",
+    ];
+    // Node breakdown
+    lines.push("Nodes:");
+    for (const n of nodes) {
+        const terminal = n.terminal ? " (terminal)" : "";
+        const time = n.medianTimeHours > 0 ? ` — median ${n.medianTimeHours}h` : "";
+        lines.push(`  ${n.name}: ${n.userCount} active users${terminal}${time}`);
+    }
+    // Transition breakdown
+    if (transitions.length > 0) {
+        lines.push("");
+        lines.push("Transitions:");
+        for (const t of transitions) {
+            const trigger = t.type === "timer" ? `timer (${t.delay || "?"})` : (t.event || "event");
+            lines.push(`  ${t.from} → ${t.to} [${trigger}]: ${t.userCount} users`);
+        }
+    }
+    // Terminal distribution
+    if (terminalDistribution.length > 0) {
+        lines.push("");
+        lines.push("Completed users ended at:");
+        for (const td of terminalDistribution) {
+            lines.push(`  ${td.node}: ${td.count}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/utils/survey-format.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Human-readable formatting for survey questions.
+ * Used by MCP tools to present question data in a conversational format.
+ */
+interface QuestionData {
+    name: string;
+    type: string;
+    title: string;
+    isRequired: boolean;
+    position: number;
+    choices?: string[];
+    rateMin?: number;
+    rateMax?: number;
+    minRateDescription?: string;
+    maxRateDescription?: string;
+    inputType?: string;
+    visibleIf?: string;
+    requiredIf?: string;
+}
+export declare function formatQuestionList(questions: QuestionData[]): string;
+export declare function formatSingleQuestion(q: QuestionData, action: string): string;
+interface SurveyData {
+    id: string;
+    name: string;
+    type: string;
+    status: string;
+    definition?: {
+        pages?: Array<{
+            elements?: unknown[];
+        }>;
+    };
+    stats?: {
+        responseCount?: number;
+        completionRate?: number;
+    };
+    createdAt?: string;
+    updatedAt?: string;
+}
+/**
+ * Format a survey with contextual guidance and next-step suggestions.
+ * Used by create, get, and update tools to guide the developer through
+ * the survey lifecycle: create → add questions → activate → distribute.
+ */
+export declare function formatSurveyWithGuidance(survey: SurveyData): string;
+/**
+ * Format a survey list with readiness status.
+ */
+export declare function formatSurveyList(surveyList: SurveyData[]): string;
+/**
+ * Format distribution results with guidance.
+ */
+export declare function formatDistributionResult(invitations: Array<{
+    id: string;
+    userId: string;
+    token: string;
+    status: string;
+    isNew?: boolean;
+    link?: string;
+}>): string;
+export {};

package/dist/utils/survey-format.js

@@ -0,0 +1,164 @@
+/**
+ * Human-readable formatting for survey questions.
+ * Used by MCP tools to present question data in a conversational format.
+ */
+const TYPE_LABELS = {
+    text: "Short text",
+    comment: "Long text",
+    radiogroup: "Single choice",
+    checkbox: "Multiple choice",
+    rating: "Rating scale",
+    boolean: "Yes/No",
+    dropdown: "Dropdown",
+    ranking: "Ranking",
+};
+function getTypeDisplay(q) {
+    if (q.type === "rating" && q.rateMin === 0 && q.rateMax === 10) {
+        return "NPS (0-10)";
+    }
+    if (q.type === "rating" && q.rateMin != null && q.rateMax != null) {
+        return `Rating (${q.rateMin}-${q.rateMax})`;
+    }
+    if (q.type === "text" && q.inputType === "date") {
+        return "Date";
+    }
+    return TYPE_LABELS[q.type] || q.type;
+}
+export function formatQuestionList(questions) {
+    if (!questions || questions.length === 0) {
+        return "This survey has no questions yet.";
+    }
+    const lines = [`${questions.length} question(s):\n`];
+    for (const q of questions) {
+        const num = q.position + 1;
+        const required = q.isRequired ? " (required)" : "";
+        const typeDisplay = getTypeDisplay(q);
+        lines.push(`  ${num}. [${typeDisplay}]${required} ${q.title}`);
+        lines.push(`     name: ${q.name}`);
+        if (q.choices && q.choices.length > 0) {
+            lines.push(`     choices: ${q.choices.join(", ")}`);
+        }
+        if (q.minRateDescription || q.maxRateDescription) {
+            const parts = [];
+            if (q.minRateDescription)
+                parts.push(`min: "${q.minRateDescription}"`);
+            if (q.maxRateDescription)
+                parts.push(`max: "${q.maxRateDescription}"`);
+            lines.push(`     labels: ${parts.join(", ")}`);
+        }
+        if (q.visibleIf) {
+            lines.push(`     show if: ${q.visibleIf}`);
+        }
+        if (q.requiredIf) {
+            lines.push(`     required if: ${q.requiredIf}`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatSingleQuestion(q, action) {
+    const formatted = formatQuestionList([{ ...q, position: 0 }]);
+    return `${action} question:\n\n${formatted}`;
+}
+function countQuestions(definition) {
+    if (!definition?.pages)
+        return 0;
+    return definition.pages.reduce((sum, page) => sum + (page.elements?.length ?? 0), 0);
+}
+/**
+ * Format a survey with contextual guidance and next-step suggestions.
+ * Used by create, get, and update tools to guide the developer through
+ * the survey lifecycle: create → add questions → activate → distribute.
+ */
+export function formatSurveyWithGuidance(survey) {
+    const questionCount = countQuestions(survey.definition);
+    const responseCount = survey.stats?.responseCount ?? 0;
+    const typeLabel = survey.type === "nps"
+        ? "NPS"
+        : survey.type === "csat"
+            ? "CSAT"
+            : "Custom";
+    const lines = [
+        `Survey: ${survey.name} (${survey.id})`,
+        `Type: ${typeLabel} | Status: ${survey.status} | Questions: ${questionCount} | Responses: ${responseCount}`,
+    ];
+    // Next steps based on current state
+    const hints = [];
+    if (questionCount === 0) {
+        hints.push("This survey has no questions yet. Use survey_add_question to add questions, or survey_list_questions to see supported question types.");
+    }
+    else if (survey.status === "draft") {
+        hints.push(`Survey has ${questionCount} question(s) and is in draft. Use survey_update with status 'active' to activate it for distribution.`);
+        hints.push("Use survey_list_questions to review the questions before activating.");
+    }
+    else if (survey.status === "active" && responseCount === 0) {
+        hints.push("Survey is active and ready to distribute. Use survey_distribute with a list of user IDs to create personalized tracking links.");
+    }
+    else if (survey.status === "active" && responseCount > 0) {
+        hints.push("Survey is collecting responses. Use survey_analytics to see the distribution funnel and results.");
+    }
+    else if (survey.status === "paused") {
+        hints.push("Survey is paused. Use survey_update with status 'active' to resume collection.");
+    }
+    if (hints.length > 0) {
+        lines.push("");
+        lines.push("Next steps:");
+        for (const hint of hints) {
+            lines.push(`  → ${hint}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Format a survey list with readiness status.
+ */
+export function formatSurveyList(surveyList) {
+    if (!surveyList || surveyList.length === 0) {
+        return "No surveys found. Use survey_create to create one (try type 'nps' or 'csat' for quick presets).";
+    }
+    const lines = [`${surveyList.length} survey(s):\n`];
+    for (const s of surveyList) {
+        const qCount = countQuestions(s.definition);
+        const responses = s.stats?.responseCount ?? 0;
+        const typeLabel = s.type === "nps" ? "NPS" : s.type === "csat" ? "CSAT" : "Custom";
+        // Readiness indicator
+        let readiness;
+        if (qCount === 0) {
+            readiness = "needs questions";
+        }
+        else if (s.status === "draft") {
+            readiness = "draft — ready to activate";
+        }
+        else if (s.status === "active" && responses === 0) {
+            readiness = "active — ready to distribute";
+        }
+        else if (s.status === "active") {
+            readiness = `active — ${responses} response(s)`;
+        }
+        else {
+            readiness = s.status;
+        }
+        lines.push(`  ${s.id} | ${s.name} [${typeLabel}] — ${qCount} questions — ${readiness}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Format distribution results with guidance.
+ */
+export function formatDistributionResult(invitations) {
+    if (!invitations || invitations.length === 0) {
+        return "No invitations created.";
+    }
+    const newCount = invitations.filter((i) => i.isNew === true).length;
+    const existingCount = invitations.length - newCount;
+    const lines = [
+        `Created ${newCount} personalized survey link(s).`,
+    ];
+    if (existingCount > 0) {
+        lines.push(`${existingCount} user(s) already had invitations (skipped).`);
+    }
+    lines.push("");
+    lines.push("Each link is unique and trackable (sent → opened → submitted).");
+    lines.push("Include these links in email campaigns or journey-triggered messages.");
+    lines.push("Use survey_analytics to monitor the distribution funnel.");
+    return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ascendkit/cli",
+  "version": "0.1.10",
+  "description": "AscendKit CLI and MCP server",
+  "author": "ascendkit.dev",
+  "license": "MIT",
+  "homepage": "https://ascendkit.dev",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["ascendkit", "cli", "mcp", "model-context-protocol", "b2b", "saas"],
+  "type": "module",
+  "main": "dist/cli.js",
+  "files": [
+    "dist/",
+    "README.md",
+    "!dist/releases/**"
+  ],
+  "bin": {
+    "ascendkit": "dist/cli.js",
+    "ascendkit-mcp": "dist/mcp.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "release:local": "./scripts/release-local.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}