@ascendkit/cli 0.1.11 → 0.2.6

package/dist/commands/campaigns.js

@@ -0,0 +1,25 @@
+export async function createCampaign(client, params) {
+    return client.managedPost("/api/v1/campaigns", params);
+}
+export async function listCampaigns(client, status, limit = 200) {
+    const params = new URLSearchParams();
+    if (status)
+        params.set("status", status);
+    params.set("limit", String(limit));
+    return client.managedGet(`/api/v1/campaigns?${params.toString()}`);
+}
+export async function getCampaign(client, campaignId) {
+    return client.managedGet(`/api/v1/campaigns/${campaignId}`);
+}
+export async function updateCampaign(client, campaignId, params) {
+    return client.managedPut(`/api/v1/campaigns/${campaignId}`, params);
+}
+export async function deleteCampaign(client, campaignId) {
+    return client.managedDelete(`/api/v1/campaigns/${campaignId}`);
+}
+export async function previewAudience(client, audienceFilter) {
+    return client.managedPost("/api/v1/campaigns/preview", { audienceFilter });
+}
+export async function getCampaignAnalytics(client, campaignId) {
+    return client.managedGet(`/api/v1/campaigns/${campaignId}/analytics`);
+}

package/dist/commands/import.d.ts

@@ -0,0 +1,75 @@
+import { AscendKitClient } from "../api/client.js";
+export interface ImportUserRecord {
+    sourceId: string;
+    email: string;
+    name?: string;
+    image?: string;
+    emailVerified?: boolean;
+    hadPassword?: boolean;
+    oauthProviders?: Array<{
+        providerId: string;
+        accountId: string;
+    }>;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+    createdAt?: string;
+    lastLoginAt?: string;
+}
+export interface ImportUsersPayload {
+    source: string;
+    users: ImportUserRecord[];
+    authSettings?: {
+        enabledProviders?: string[];
+        oauthClientIds?: Record<string, string>;
+    };
+    dryRun?: boolean;
+}
+export interface ImportResult {
+    imported: number;
+    duplicates: Array<{
+        email: string;
+        sourceId: string;
+    }>;
+    errors: Array<{
+        email: string;
+        sourceId: string;
+        reason: string;
+    }>;
+    warnings: string[];
+}
+export declare function importUsers(client: AscendKitClient, payload: ImportUsersPayload): Promise<ImportResult>;
+export declare function instantiateMigrationJourney(client: AscendKitClient, fromIdentityEmail?: string): Promise<unknown>;
+interface ClerkUser {
+    id: string;
+    email_addresses?: Array<{
+        id: string;
+        email_address: string;
+        verification?: {
+            status: string;
+        };
+    }>;
+    primary_email_address_id?: string;
+    first_name?: string;
+    last_name?: string;
+    image_url?: string;
+    password_enabled?: boolean;
+    external_accounts?: Array<{
+        id: string;
+        provider: string;
+        provider_user_id: string;
+    }>;
+    public_metadata?: Record<string, unknown>;
+    private_metadata?: Record<string, unknown>;
+    created_at?: number;
+    last_sign_in_at?: number;
+    last_active_at?: number;
+}
+export declare function transformClerkUser(clerk: ClerkUser): ImportUserRecord;
+export declare function fetchClerkUsers(apiKey: string, instanceUrl?: string): Promise<ClerkUser[]>;
+export interface ClerkDerivedSettings {
+    hasCredentials: boolean;
+    providers: string[];
+}
+export declare function deriveSettingsFromUsers(users: ImportUserRecord[]): ClerkDerivedSettings;
+export declare function parseClerkExport(filePath: string): ClerkUser[];
+export {};

package/dist/commands/import.js

@@ -0,0 +1,97 @@
+import { readFileSync } from "fs";
+export async function importUsers(client, payload) {
+    return client.managedPost("/api/import/users", payload);
+}
+export async function instantiateMigrationJourney(client, fromIdentityEmail) {
+    return client.managedPost("/api/import/instantiate-migration-journey", {
+        fromIdentityEmail: fromIdentityEmail ?? null,
+    });
+}
+function clerkProviderToAscendKit(provider) {
+    const map = {
+        oauth_google: "google",
+        oauth_github: "github",
+        oauth_linkedin: "linkedin",
+        oauth_linkedin_oidc: "linkedin",
+    };
+    return map[provider] ?? provider.replace(/^oauth_/, "");
+}
+export function transformClerkUser(clerk) {
+    const primaryEmail = clerk.email_addresses?.find((e) => e.id === clerk.primary_email_address_id);
+    const email = primaryEmail?.email_address ?? clerk.email_addresses?.[0]?.email_address ?? "";
+    const emailVerified = primaryEmail?.verification?.status === "verified";
+    const name = [clerk.first_name, clerk.last_name].filter(Boolean).join(" ") || undefined;
+    const oauthProviders = (clerk.external_accounts ?? []).map((ext) => ({
+        providerId: clerkProviderToAscendKit(ext.provider),
+        accountId: ext.provider_user_id,
+    }));
+    // Clerk timestamps are Unix ms
+    const createdAt = clerk.created_at
+        ? new Date(clerk.created_at).toISOString()
+        : undefined;
+    const lastLoginAt = clerk.last_sign_in_at
+        ? new Date(clerk.last_sign_in_at).toISOString()
+        : undefined;
+    return {
+        sourceId: clerk.id,
+        email,
+        name,
+        image: clerk.image_url || undefined,
+        emailVerified,
+        hadPassword: clerk.password_enabled ?? false,
+        oauthProviders,
+        metadata: clerk.public_metadata ?? undefined,
+        createdAt,
+        lastLoginAt,
+    };
+}
+export async function fetchClerkUsers(apiKey, instanceUrl) {
+    const baseUrl = instanceUrl ?? "https://api.clerk.com";
+    const allUsers = [];
+    let offset = 0;
+    const limit = 100;
+    while (true) {
+        const url = `${baseUrl}/v1/users?limit=${limit}&offset=${offset}`;
+        const response = await fetch(url, {
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Clerk API error ${response.status}: ${text}`);
+        }
+        const users = (await response.json());
+        if (users.length === 0)
+            break;
+        allUsers.push(...users);
+        offset += users.length;
+        if (users.length < limit)
+            break;
+    }
+    return allUsers;
+}
+export function deriveSettingsFromUsers(users) {
+    let hasCredentials = false;
+    const providers = new Set();
+    for (const u of users) {
+        if (u.hadPassword)
+            hasCredentials = true;
+        for (const p of u.oauthProviders ?? []) {
+            providers.add(p.providerId);
+        }
+    }
+    return { hasCredentials, providers: [...providers].sort() };
+}
+export function parseClerkExport(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+        return parsed;
+    }
+    if (parsed.users && Array.isArray(parsed.users)) {
+        return parsed.users;
+    }
+    throw new Error("Unrecognized Clerk export format. Expected a JSON array of users or an object with a 'users' key.");
+}

package/dist/commands/journeys.d.ts

@@ -41,6 +41,7 @@ export interface AddNodeParams {
         surveySlug?: string;
         tagName?: string;
         stageName?: string;
+        fromIdentityEmail?: string;
     };
     terminal?: boolean;
 }
@@ -51,6 +52,7 @@ export interface EditNodeParams {
         surveySlug?: string;
         tagName?: string;
         stageName?: string;
+        fromIdentityEmail?: string;
     };
     terminal?: boolean;
 }

package/dist/commands/platform.d.ts

@@ -17,7 +17,7 @@ export interface McpCreateProjectParams {
 }
 export interface McpCreateEnvironmentParams {
     projectId: string;
-    name: string;
+    name?: string;
     description?: string;
     tier: string;
 }
@@ -34,8 +34,24 @@ export declare function mcpListProjects(client: AscendKitClient): Promise<unknow
 export declare function mcpCreateProject(client: AscendKitClient, params: McpCreateProjectParams): Promise<unknown>;
 export declare function mcpListEnvironments(client: AscendKitClient, projectId: string): Promise<unknown>;
 export declare function mcpCreateEnvironment(client: AscendKitClient, params: McpCreateEnvironmentParams): Promise<unknown>;
+export declare function updateEnvironment(projectId: string, envId: string, name?: string, description?: string): Promise<unknown>;
 export declare function promoteEnvironment(environmentId: string, targetTier: string): Promise<unknown>;
+export interface McpUpdateEnvironmentParams {
+    projectId: string;
+    environmentId: string;
+    name?: string;
+    description?: string;
+}
+export declare function mcpUpdateEnvironment(client: AscendKitClient, params: McpUpdateEnvironmentParams): Promise<unknown>;
 export declare function mcpPromoteEnvironment(client: AscendKitClient, params: {
     environmentId: string;
     targetTier: string;
 }): Promise<unknown>;
+export interface McpUpdateEnvironmentVariablesParams {
+    projectId: string;
+    envId: string;
+    variables: Record<string, string>;
+}
+export declare function mcpUpdateEnvironmentVariables(client: AscendKitClient, params: McpUpdateEnvironmentVariablesParams): Promise<unknown>;
+export declare function getEnvironment(projectId: string, envId: string): Promise<Record<string, unknown>>;
+export declare function updateEnvironmentVariables(projectId: string, envId: string, variables: Record<string, string>): Promise<unknown>;

package/dist/commands/platform.js

@@ -184,7 +184,7 @@ async function updateRuntimeEnvFile(filePath, apiUrl, publicKey, secretKey, opti
     const existingPublicKey = readEnvValue(original, "ASCENDKIT_ENV_KEY");
     const existingSecretKey = readEnvValue(original, "ASCENDKIT_SECRET_KEY");
     const existingWebhookSecret = readEnvValue(original, "ASCENDKIT_WEBHOOK_SECRET") ?? "";
-    const resolvedApiUrl = existingApiUrl ?? apiUrl;
+    const resolvedApiUrl = apiUrl;
     const resolvedPublicKey = preserveExistingKeys
         ? (existingPublicKey && existingPublicKey.trim() ? existingPublicKey : publicKey)
         : publicKey;
@@ -535,10 +535,43 @@ export async function mcpListEnvironments(client, projectId) {
 export async function mcpCreateEnvironment(client, params) {
     return client.platformRequest("POST", `/api/platform/projects/${params.projectId}/environments`, { name: params.name, description: params.description ?? "", tier: params.tier });
 }
+export async function updateEnvironment(projectId, envId, name, description) {
+    const auth = requireAuth();
+    const body = {};
+    if (name)
+        body.name = name;
+    if (description !== undefined)
+        body.description = description;
+    return apiRequest(auth.apiUrl, "PATCH", `/api/platform/projects/${projectId}/environments/${envId}`, body, auth.token);
+}
 export async function promoteEnvironment(environmentId, targetTier) {
     const auth = requireAuth();
     return apiRequest(auth.apiUrl, "POST", `/api/platform/environments/${environmentId}/promote`, { targetTier, dryRun: false }, auth.token);
 }
+export async function mcpUpdateEnvironment(client, params) {
+    const body = {};
+    if (params.name)
+        body.name = params.name;
+    if (params.description !== undefined)
+        body.description = params.description;
+    return client.platformRequest("PATCH", `/api/platform/projects/${params.projectId}/environments/${params.environmentId}`, body);
+}
 export async function mcpPromoteEnvironment(client, params) {
     return client.platformRequest("POST", `/api/platform/environments/${params.environmentId}/promote`, { targetTier: params.targetTier, dryRun: false });
 }
+export async function mcpUpdateEnvironmentVariables(client, params) {
+    return client.platformRequest("PATCH", `/api/platform/projects/${params.projectId}/environments/${params.envId}`, { variables: params.variables });
+}
+export async function getEnvironment(projectId, envId) {
+    const auth = requireAuth();
+    const envs = await apiRequest(auth.apiUrl, "GET", `/api/platform/projects/${projectId}/environments`, undefined, auth.token);
+    const env = envs.find(e => e.id === envId);
+    if (!env) {
+        throw new Error(`Environment ${envId} not found in project ${projectId}.`);
+    }
+    return env;
+}
+export async function updateEnvironmentVariables(projectId, envId, variables) {
+    const auth = requireAuth();
+    return apiRequest(auth.apiUrl, "PATCH", `/api/platform/projects/${projectId}/environments/${envId}`, { variables }, auth.token);
+}

package/dist/mcp.js

@@ -10,6 +10,8 @@ import { registerPlatformTools } from "./tools/platform.js";
 import { registerEmailTools } from "./tools/email.js";
 import { registerJourneyTools } from "./tools/journeys.js";
 import { registerWebhookTools } from "./tools/webhooks.js";
+import { registerCampaignTools } from "./tools/campaigns.js";
+import { registerImportTools } from "./tools/import.js";
 import { DEFAULT_API_URL } from "./constants.js";
 const client = new AscendKitClient({
     apiUrl: process.env.ASCENDKIT_API_URL ?? DEFAULT_API_URL,
@@ -34,6 +36,8 @@ registerSurveyTools(server, client);
 registerEmailTools(server, client);
 registerJourneyTools(server, client);
 registerWebhookTools(server, client);
+registerCampaignTools(server, client);
+registerImportTools(server, client);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/auth.js

@@ -35,12 +35,31 @@ export function registerAuthTools(server, client) {
         const data = await auth.updateProviders(client, params.providers);
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     });
-    server.tool("auth_setup_oauth", "Configure OAuth credentials for a provider. Pass clientId and clientSecret to set credentials directly, or omit them to get a portal URL for browser-based entry. Note: credentials in tool args may appear in logs — use the portal URL for sensitive environments.", {
+    server.tool("auth_setup_oauth", "Configure OAuth credentials for a provider. Pass clientId and clientSecret for custom credentials, or useProxy to revert to AscendKit managed credentials. Omit all to get a portal URL for browser-based entry.", {
         provider: z.string().describe('OAuth provider name, e.g. "google", "github"'),
         clientId: z.string().optional().describe("OAuth client ID (to set credentials directly)"),
         clientSecret: z.string().optional().describe("OAuth client secret (to set credentials directly)"),
         callbackUrl: z.string().optional().describe("Auth callback URL for this provider"),
+        useProxy: z.boolean().optional().describe("Clear custom credentials and use AscendKit managed proxy credentials"),
     }, async (params) => {
+        if (params.useProxy && (params.clientId || params.clientSecret)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Cannot use useProxy with custom credentials. Either set useProxy to clear credentials, or provide clientId and clientSecret.",
+                    }],
+                isError: true,
+            };
+        }
+        if (params.useProxy) {
+            const data = await auth.deleteOAuthCredentials(client, params.provider);
+            return {
+                content: [{
+                        type: "text",
+                        text: `Cleared custom OAuth credentials for ${params.provider}. Now using AscendKit managed proxy credentials.\n\n${JSON.stringify(data, null, 2)}`,
+                    }],
+            };
+        }
         if ((params.clientId && !params.clientSecret) || (!params.clientId && params.clientSecret)) {
             return {
                 content: [{
@@ -72,4 +91,22 @@ export function registerAuthTools(server, client) {
         const data = await auth.listUsers(client);
         return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
     });
+    server.tool("auth_delete_user", "Deactivate a user (soft delete). The user record is preserved but marked inactive.", {
+        userId: z.string().describe("User ID (usr_ prefixed)"),
+    }, async (params) => {
+        const data = await auth.deleteUser(client, params.userId);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("auth_bulk_delete_users", "Bulk deactivate users (soft delete). All specified users are marked inactive.", {
+        userIds: z.array(z.string()).min(1).max(100).describe("Array of user IDs (usr_ prefixed)"),
+    }, async (params) => {
+        const data = await auth.bulkDeleteUsers(client, params.userIds);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("auth_reactivate_user", "Reactivate a previously deactivated user.", {
+        userId: z.string().describe("User ID (usr_ prefixed)"),
+    }, async (params) => {
+        const data = await auth.reactivateUser(client, params.userId);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
 }

package/dist/tools/campaigns.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AscendKitClient } from "../api/client.js";
+export declare function registerCampaignTools(server: McpServer, client: AscendKitClient): void;

package/dist/tools/campaigns.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import * as campaigns from "../commands/campaigns.js";
+export function registerCampaignTools(server, client) {
+    server.tool("campaign_create", "Create a new email campaign targeting users that match an audience filter. Campaigns start as drafts; set scheduledAt to schedule for future delivery. Campaign lifecycle: create → preview audience → schedule → sending → sent.", {
+        name: z.string().describe("Campaign name, e.g. 'March Newsletter'"),
+        templateId: z.string().describe("Email template ID (tpl_ prefixed) to use for the campaign"),
+        audienceFilter: z
+            .record(z.unknown())
+            .describe("Filter object to select target users (e.g. { tags: { $in: ['premium'] } }). Allowed fields: createdAt, emailVerified, lastLoginAt, tags, stage, name, email, waitlistStatus, metadata.*"),
+        scheduledAt: z
+            .string()
+            .optional()
+            .describe("ISO 8601 datetime to schedule sending (omit to keep as draft)"),
+        fromIdentityEmail: z
+            .string()
+            .optional()
+            .describe("Verified email identity to use as sender. Falls back to environment default."),
+    }, async (params) => {
+        const data = await campaigns.createCampaign(client, params);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("campaign_list", "List campaigns for the current project. Optionally filter by status: draft, scheduled, sending, sent, failed, or cancelled.", {
+        status: z
+            .enum(["draft", "scheduled", "sending", "sent", "failed", "cancelled"])
+            .optional()
+            .describe("Filter by campaign status"),
+    }, async (params) => {
+        const data = await campaigns.listCampaigns(client, params.status);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("campaign_get", "Get full details of a campaign including its status, template, audience filter, and schedule.", {
+        campaignId: z.string().describe("Campaign ID (cmp_ prefixed)"),
+    }, async (params) => {
+        const data = await campaigns.getCampaign(client, params.campaignId);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("campaign_update", "Update a draft, scheduled, or failed campaign. You can change the name, template, audience filter, or schedule. Only provided fields are updated.", {
+        campaignId: z.string().describe("Campaign ID (cmp_ prefixed)"),
+        name: z.string().optional().describe("New campaign name"),
+        templateId: z.string().optional().describe("New email template ID (tpl_ prefixed)"),
+        audienceFilter: z
+            .record(z.unknown())
+            .optional()
+            .describe("New audience filter object"),
+        scheduledAt: z
+            .string()
+            .optional()
+            .describe("New scheduled send time (ISO 8601 datetime)"),
+        fromIdentityEmail: z
+            .string()
+            .optional()
+            .describe("Verified email identity to use as sender. Falls back to environment default."),
+    }, async (params) => {
+        const { campaignId, ...rest } = params;
+        const data = await campaigns.updateCampaign(client, campaignId, rest);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("campaign_delete", "Delete a draft or failed campaign, or cancel a scheduled/sending campaign. Sent campaigns cannot be deleted.", {
+        campaignId: z.string().describe("Campaign ID (cmp_ prefixed)"),
+    }, async (params) => {
+        const data = await campaigns.deleteCampaign(client, params.campaignId);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("campaign_preview_audience", "Preview how many users match an audience filter before creating or updating a campaign. Returns the count and a sample of matching users.", {
+        audienceFilter: z
+            .record(z.unknown())
+            .describe("Filter object to preview (e.g. { tags: { $in: ['premium'] } }). Allowed fields: createdAt, emailVerified, lastLoginAt, tags, stage, name, email, waitlistStatus, metadata.*"),
+    }, async (params) => {
+        const data = await campaigns.previewAudience(client, params.audienceFilter);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool("campaign_analytics", "Get campaign performance analytics: delivery stats (sent, failed, bounced), engagement metrics (opened, clicked), and calculated rates.", {
+        campaignId: z.string().describe("Campaign ID (cmp_ prefixed)"),
+    }, async (params) => {
+        const data = await campaigns.getCampaignAnalytics(client, params.campaignId);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/import.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AscendKitClient } from "../api/client.js";
+export declare function registerImportTools(server: McpServer, client: AscendKitClient): void;

package/dist/tools/import.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import * as importCmd from "../commands/import.js";
+export function registerImportTools(server, client) {
+    server.tool("auth_import_clerk", "Import users from Clerk into the current AscendKit environment. Fetches all users from the Clerk API, transforms them to AscendKit format, and pushes them to the import endpoint. Tags users by auth type: import:needs-password-reset or import:social-only. Defaults to dry-run — pass execute=true to apply changes.", {
+        clerkApiKey: z
+            .string()
+            .describe("Clerk secret API key (sk_live_... or sk_test_...)"),
+        clerkInstanceUrl: z
+            .string()
+            .optional()
+            .describe("Custom Clerk API URL (default: https://api.clerk.com)"),
+        execute: z
+            .boolean()
+            .optional()
+            .describe("Set to true to apply changes. Default is dry-run (preview only)."),
+        importUsers: z
+            .boolean()
+            .optional()
+            .describe("Import users (default: true)"),
+        importSettings: z
+            .boolean()
+            .optional()
+            .describe("Import auth settings — OAuth provider config (default: true)"),
+    }, async (params) => {
+        try {
+            const dryRun = !(params.execute ?? false);
+            const shouldImportUsers = params.importUsers ?? true;
+            const shouldImportSettings = params.importSettings ?? true;
+            const rawUsers = await importCmd.fetchClerkUsers(params.clerkApiKey, params.clerkInstanceUrl);
+            const users = rawUsers.map(importCmd.transformClerkUser);
+            if (users.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No users found in Clerk." }],
+                };
+            }
+            let totalImported = 0;
+            let totalDuplicates = 0;
+            const allErrors = [];
+            const allWarnings = [];
+            // Import users in batches of 500
+            if (shouldImportUsers) {
+                const batchSize = 500;
+                for (let i = 0; i < users.length; i += batchSize) {
+                    const batch = users.slice(i, i + batchSize);
+                    const result = await importCmd.importUsers(client, {
+                        source: "clerk",
+                        users: batch,
+                        dryRun,
+                    });
+                    totalImported += result.imported;
+                    totalDuplicates += result.duplicates.length;
+                    allErrors.push(...result.errors);
+                    allWarnings.push(...result.warnings);
+                }
+            }
+            // Import auth settings (OAuth provider config)
+            if (shouldImportSettings) {
+                const providers = new Set();
+                for (const u of users) {
+                    for (const p of u.oauthProviders ?? []) {
+                        providers.add(p.providerId);
+                    }
+                }
+                if (providers.size > 0) {
+                    const settingsResult = await importCmd.importUsers(client, {
+                        source: "clerk",
+                        users: [],
+                        authSettings: { enabledProviders: [...providers] },
+                        dryRun,
+                    });
+                    allWarnings.push(...settingsResult.warnings);
+                }
+            }
+            const summary = {
+                fetched: users.length,
+                dryRun,
+                importUsers: shouldImportUsers,
+                importSettings: shouldImportSettings,
+            };
+            if (shouldImportUsers) {
+                summary.imported = totalImported;
+                summary.duplicates = totalDuplicates;
+            }
+            if (allErrors.length > 0)
+                summary.errors = allErrors;
+            if (allWarnings.length > 0)
+                summary.warnings = allWarnings;
+            let text = JSON.stringify(summary, null, 2);
+            if (dryRun) {
+                text += "\n\nThis was a dry run. Pass execute=true to apply changes.";
+            }
+            else if (totalImported > 0) {
+                text += "\n\nTo set up migration emails, use the journey_create_migration tool.";
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Import failed: ${err instanceof Error ? err.message : String(err)}`,
+                    }],
+                isError: true,
+            };
+        }
+    });
+    server.tool("journey_create_migration", "Create pre-built migration email templates and draft journeys for notifying imported users. Creates 5 email templates (announcement, go-live, reminder, password reset, password reset reminder) and 2 journeys: announcement cadence (all users, Day 0/3/7) and password reset cadence (credential users, Day 1/4). Idempotent — skips already-existing templates/journeys.", {
+        fromIdentityEmail: z
+            .string()
+            .optional()
+            .describe("Verified email identity to use as sender for migration emails"),
+    }, async (params) => {
+        const data = await importCmd.instantiateMigrationJourney(client, params.fromIdentityEmail);
+        return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/journeys.js

@@ -14,7 +14,7 @@ export function registerJourneyTools(server, client) {
         nodes: z
             .record(z.record(z.unknown()))
             .optional()
-            .describe("Map of node names to definitions. Each node has 'action' ({type, templateSlug?, surveySlug?, tagName?, stageName?}) and optional 'terminal' (boolean). If omitted, the entry node is auto-created as a 'none' action placeholder."),
+            .describe("Map of node names to definitions. Each node has 'action' ({type, templateSlug?, surveySlug?, tagName?, stageName?, variables?}) and optional 'terminal' (boolean). If omitted, the entry node is auto-created as a 'none' action placeholder."),
         transitions: z
             .array(z.record(z.unknown()))
             .optional()
@@ -138,6 +138,8 @@ export function registerJourneyTools(server, client) {
             surveySlug: z.string().optional().describe("Survey slug to include in email (for send_email)"),
             tagName: z.string().optional().describe("Tag to add (for tag_user)"),
             stageName: z.string().optional().describe("Stage to set (for advance_stage)"),
+            fromIdentityEmail: z.string().optional().describe("Verified email identity to use when this node sends email"),
+            variables: z.record(z.string()).optional().describe("Custom template variables for this node's email (e.g. {loginUrl: 'https://...', resetUrl: 'https://...'})"),
         })
             .optional()
             .describe("Action to execute when a user enters this node. Defaults to {type: 'none'}."),
@@ -161,6 +163,8 @@ export function registerJourneyTools(server, client) {
             surveySlug: z.string().optional().describe("Survey slug to include in email"),
             tagName: z.string().optional().describe("Tag to add"),
             stageName: z.string().optional().describe("Stage to set"),
+            fromIdentityEmail: z.string().optional().describe("Verified email identity to use when this node sends email"),
+            variables: z.record(z.string()).optional().describe("Custom template variables for this node's email (e.g. {loginUrl: 'https://...', resetUrl: 'https://...'})"),
         })
             .optional()
             .describe("New action definition (replaces the entire action)"),