@hyperstar/mcp 0.1.6 → 0.1.10

package/README.md

@@ -7,7 +7,7 @@ CLI login.
 
 ## Install
 
-After `@hyperstar/mcp` is published to npm:
+Run the MCP server directly from npm:
 
 ```sh
 npx -y --package @hyperstar/mcp hyperstar-mcp
@@ -22,6 +22,13 @@ Because the package exposes multiple binaries, use the explicit
 `--package @hyperstar/mcp hyperstar-mcp` form instead of bare
 `npx -y @hyperstar/mcp` in MCP client configs.
 
+If a client spawns through an environment that loses npm's temporary `.bin`
+path, use the equivalent `npm exec` form:
+
+```sh
+npm exec --yes --package @hyperstar/mcp -- hyperstar-mcp
+```
+
 For a one-off browser login without a global install:
 
 ```sh
@@ -30,16 +37,16 @@ npx -y --package @hyperstar/mcp hyperstar workspaces list --json
 npx -y --package @hyperstar/mcp hyperstar workspaces use org_123
 ```
 
-Before the first npm publish, dev e2e should use a local pack:
+For unreleased local package testing, pack from the package directory and use
+the filename printed by `npm pack`:
 
 ```sh
 cd projects/hyperstar-mcp
-npm pack --dry-run
-npm pack
-npx -y --package ./hyperstar-mcp-0.1.0.tgz hyperstar-mcp
-npx -y --package ./hyperstar-mcp-0.1.0.tgz hyperstar login
-npx -y --package ./hyperstar-mcp-0.1.0.tgz hyperstar workspaces list --json
-npx -y --package ./hyperstar-mcp-0.1.0.tgz hyperstar workspaces use org_123
+TARBALL=$(npm pack --silent)
+npx -y --package "./$TARBALL" hyperstar-mcp
+npx -y --package "./$TARBALL" hyperstar login
+npx -y --package "./$TARBALL" hyperstar workspaces list --json
+npx -y --package "./$TARBALL" hyperstar workspaces use org_123
 ```
 
 The first public scoped publish must use public access. This package sets
@@ -48,8 +55,9 @@ credentials are configured.
 
 ## MCP client config
 
-Service-account auth is the simplest non-interactive setup. Configure the MCP
-server with a Hyperstar Product API base URL and service-account API key:
+Service-account auth is the simplest non-interactive setup. For production,
+configure only the service-account API key and use the package's default
+Hyperstar Product API base URL:
 
 ```json
 {
@@ -58,7 +66,6 @@ server with a Hyperstar Product API base URL and service-account API key:
       "command": "npx",
       "args": ["-y", "--package", "@hyperstar/mcp", "hyperstar-mcp"],
       "env": {
-        "HYPERSTAR_API_BASE_URL": "https://api.hyperstar.example",
         "HYPERSTAR_API_KEY": "hstar_test_public-prefix.secret"
       }
     }
@@ -78,11 +85,7 @@ login state created by the `hyperstar` CLI:
   "mcpServers": {
     "hyperstar": {
       "command": "npx",
-      "args": ["-y", "--package", "@hyperstar/mcp", "hyperstar-mcp"],
-      "env": {
-        "HYPERSTAR_API_BASE_URL": "https://autopilot.dev.hyper-star.org",
-        "HYPERSTAR_APP_BASE_URL": "https://app.dev.hyper-star.org"
-      }
+      "args": ["-y", "--package", "@hyperstar/mcp", "hyperstar-mcp"]
     }
   }
 }
@@ -94,13 +97,15 @@ a workspace with `hyperstar workspaces use <organization_id>` or use the MCP
 `list_workspaces` and `select_workspace` tools. Service-account mode is already
 workspace-scoped, so `get_hyperstar_workflow_guide` omits `select_workspace`
 when `HYPERSTAR_API_KEY` is used. For non-production login, set matching
-`HYPERSTAR_API_BASE_URL` and `HYPERSTAR_APP_BASE_URL`; the CLI maps the standard
-dev API origin to the dev app automatically, while custom API origins must
-provide an explicit app base URL. `HYPERSTAR_API_KEY` takes precedence over local
-CLI auth when both are present.
+`HYPERSTAR_API_BASE_URL` and `HYPERSTAR_APP_BASE_URL` explicitly.
+`HYPERSTAR_API_KEY` takes precedence over local CLI auth when both are present.
 
 ## Tools
 
+Agents should start by reading `get_hyperstar_workflow_guide` or the MCP
+resources/prompts listed below. Tool responses include `agent_guidance` and,
+where the next step is deterministic, `next_tool` and `next_arguments`.
+
 - `hyperstar_whoami`
 - `list_workspaces`
 - `select_workspace`
@@ -119,6 +124,22 @@ CLI auth when both are present.
 - `update_inbox_thread_state`
 - `send_inbox_reply`
 
+## Resources and prompts
+
+The server exposes static workflow guides as MCP resources:
+
+- `hyperstar://guide/headless-workflow`
+- `hyperstar://guide/search-to-campaign`
+- `hyperstar://guide/bulk-email-safety`
+- `hyperstar://guide/inbox`
+
+It also exposes matching prompts:
+
+- `hyperstar_headless_workflow`
+- `hyperstar_search_to_campaign`
+- `hyperstar_bulk_email_safety`
+- `hyperstar_inbox_workflow`
+
 ## Development
 
 ```sh
@@ -144,11 +165,23 @@ Search creators:
 }
 ```
 
+Common search filters are supplied as a structured JSON object. Useful fields
+include `follower_range` as `{ "min": 1000, "max": 100000 }`,
+`avg_engagement_rate`, `avg_views`, `has_email`, `email_contactability`,
+`is_verified`, `has_tiktok_shop`, `creator_gender`, `creator_language`,
+`category_1`, Instagram `category_name`, `gmv`, and `gpm`; `gmv` and `gpm` are
+TikTok-only. Put broad niches and countries in `query` / `region` unless a
+named structured filter applies. Use `sort_by` for `relevance`,
+`follower_count`, `engagement_rate`, `avg_views`, `views_growth_rate`, `gmv`, or
+`gpm`.
+
 Search tools return compact creator summaries by default so agents do not load
 full profile payloads into context. Use `get_search_results` with
 `detail_level: "full"` only when a page of raw creator rows is explicitly
 needed. Bulk actions such as `save_search_results_to_campaign` use `search_id`
-server-side and do not require the agent to materialize every creator.
+server-side and do not require the agent to materialize every creator. The
+search response includes `agent_guidance` and `next_tools` so an unfamiliar
+agent can continue without knowing the UI flow.
 
 List or create a campaign before saving creators:
 
@@ -186,9 +219,32 @@ Save search results to a campaign roster:
 }
 ```
 
+Check recipient readiness before any bulk send:
+
+```json
+{
+  "tool": "check_bulk_email_readiness",
+  "arguments": {
+    "campaign_id": 123,
+    "recipient_target": {
+      "type": "ids",
+      "campaign_creator_ids": [7, 8]
+    }
+  }
+}
+```
+
+For filtered campaign roster sends, use `recipient_target.type: "selection"`
+and pass `campaign_creator_selection`. The selection must include at least one
+narrowing filter such as `workflow_filter: "email_not_sent"`, `platform`,
+`source_type`, `search`, or `has_video`; empty selections,
+`workflow_filter: "all"` by itself, and exclusions-only selections are
+rejected.
+
 Start a bulk email job. This performs a real send. The response includes the
 queued job fields plus `next_tool: "get_bulk_email_job"` and `next_arguments`
-so agents know how to check progress:
+so agents know how to check progress. Only call this after readiness has passed
+and the user has authorized the send:
 
 ```json
 {
@@ -197,8 +253,12 @@ so agents know how to check progress:
     "campaign_id": 123,
     "subject": "Partnership idea",
     "body_text": "Hi, we would like to introduce our new campaign.",
-    "campaign_creator_ids": [7, 8],
-    "idempotency_key": "campaign-123-intro-2026-07-09"
+    "recipient_target": {
+      "type": "ids",
+      "campaign_creator_ids": [7, 8]
+    },
+    "idempotency_key": "campaign-123-intro-2026-07-09",
+    "send_confirmation": "user_authorized"
   }
 }
 ```

package/dist/auth/cli-auth-client.js

@@ -211,4 +211,3 @@ export function tokenPairToAuthState(tokenPair, options) {
             }),
     };
 }
-//# sourceMappingURL=cli-auth-client.js.map

package/dist/auth/cli-auth-state.js

@@ -173,4 +173,3 @@ function isAlreadyExistsError(error) {
         "code" in error &&
         error.code === "EEXIST");
 }
-//# sourceMappingURL=cli-auth-state.js.map

package/dist/auth/local-callback.js

@@ -87,4 +87,3 @@ async function closeServer(server) {
         });
     });
 }
-//# sourceMappingURL=local-callback.js.map

package/dist/auth/pkce.js

@@ -11,4 +11,3 @@ export function createPkcePair() {
 export function createState() {
     return randomBytes(32).toString("base64url");
 }
-//# sourceMappingURL=pkce.js.map

package/dist/bulk-email-guidance.js

@@ -33,4 +33,3 @@ function numberValue(value) {
         ? value
         : undefined;
 }
-//# sourceMappingURL=bulk-email-guidance.js.map

package/dist/bulk-email-inputs.d.ts

@@ -0,0 +1,254 @@
+import { z } from "zod";
+export declare const EmailSubjectSchema: z.ZodString;
+export declare const IdempotencyKeySchema: z.ZodString;
+declare const CampaignCreatorSelectionSchema: z.ZodObject<{
+    workflow_filter: z.ZodOptional<z.ZodEnum<{
+        all: "all";
+        email: "email";
+        email_not_sent: "email_not_sent";
+        email_sent: "email_sent";
+        replied: "replied";
+        negotiating: "negotiating";
+        rejected_hold: "rejected_hold";
+        rejected: "rejected";
+        hold: "hold";
+        contract: "contract";
+        contracted: "contracted";
+        content: "content";
+        draft: "draft";
+        final_approved: "final_approved";
+        posted: "posted";
+    }>>;
+    outreach_stage: z.ZodOptional<z.ZodString>;
+    platform: z.ZodOptional<z.ZodEnum<{
+        tiktok: "tiktok";
+        instagram: "instagram";
+    }>>;
+    country: z.ZodOptional<z.ZodString>;
+    has_video: z.ZodOptional<z.ZodBoolean>;
+    source_type: z.ZodOptional<z.ZodEnum<{
+        saved_list: "saved_list";
+        file_upload: "file_upload";
+        manual_add: "manual_add";
+        form_submission: "form_submission";
+        discovery_search: "discovery_search";
+    }>>;
+    search: z.ZodOptional<z.ZodString>;
+    excluded_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strict>;
+export type CampaignCreatorSelectionInput = z.infer<typeof CampaignCreatorSelectionSchema>;
+export declare const CheckBulkEmailReadinessInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    campaign_id: z.ZodNumber;
+    campaign_creator_ids: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    campaign_id: z.ZodNumber;
+    campaign_creator_selection: z.ZodObject<{
+        workflow_filter: z.ZodOptional<z.ZodEnum<{
+            all: "all";
+            email: "email";
+            email_not_sent: "email_not_sent";
+            email_sent: "email_sent";
+            replied: "replied";
+            negotiating: "negotiating";
+            rejected_hold: "rejected_hold";
+            rejected: "rejected";
+            hold: "hold";
+            contract: "contract";
+            contracted: "contracted";
+            content: "content";
+            draft: "draft";
+            final_approved: "final_approved";
+            posted: "posted";
+        }>>;
+        outreach_stage: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodEnum<{
+            tiktok: "tiktok";
+            instagram: "instagram";
+        }>>;
+        country: z.ZodOptional<z.ZodString>;
+        has_video: z.ZodOptional<z.ZodBoolean>;
+        source_type: z.ZodOptional<z.ZodEnum<{
+            saved_list: "saved_list";
+            file_upload: "file_upload";
+            manual_add: "manual_add";
+            form_submission: "form_submission";
+            discovery_search: "discovery_search";
+        }>>;
+        search: z.ZodOptional<z.ZodString>;
+        excluded_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strict>;
+}, z.core.$strict>]>;
+export declare const CheckBulkEmailReadinessDiscoveryInputSchema: z.ZodObject<{
+    campaign_id: z.ZodNumber;
+    recipient_target: z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"ids">;
+        campaign_creator_ids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"selection">;
+        campaign_creator_selection: z.ZodObject<{
+            workflow_filter: z.ZodOptional<z.ZodEnum<{
+                all: "all";
+                email: "email";
+                email_not_sent: "email_not_sent";
+                email_sent: "email_sent";
+                replied: "replied";
+                negotiating: "negotiating";
+                rejected_hold: "rejected_hold";
+                rejected: "rejected";
+                hold: "hold";
+                contract: "contract";
+                contracted: "contracted";
+                content: "content";
+                draft: "draft";
+                final_approved: "final_approved";
+                posted: "posted";
+            }>>;
+            outreach_stage: z.ZodOptional<z.ZodString>;
+            platform: z.ZodOptional<z.ZodEnum<{
+                tiktok: "tiktok";
+                instagram: "instagram";
+            }>>;
+            country: z.ZodOptional<z.ZodString>;
+            has_video: z.ZodOptional<z.ZodBoolean>;
+            source_type: z.ZodOptional<z.ZodEnum<{
+                saved_list: "saved_list";
+                file_upload: "file_upload";
+                manual_add: "manual_add";
+                form_submission: "form_submission";
+                discovery_search: "discovery_search";
+            }>>;
+            search: z.ZodOptional<z.ZodString>;
+            excluded_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export declare const StartBulkEmailInputSchema: z.ZodUnion<readonly [z.ZodObject<{
+    campaign_id: z.ZodNumber;
+    subject: z.ZodString;
+    body_text: z.ZodString;
+    from_email: z.ZodOptional<z.ZodString>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    form_id: z.ZodOptional<z.ZodNumber>;
+    form_language: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        ko: "ko";
+        jp: "jp";
+    }>>;
+    idempotency_key: z.ZodString;
+    send_confirmation: z.ZodLiteral<"user_authorized">;
+    campaign_creator_ids: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    campaign_id: z.ZodNumber;
+    subject: z.ZodString;
+    body_text: z.ZodString;
+    from_email: z.ZodOptional<z.ZodString>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    form_id: z.ZodOptional<z.ZodNumber>;
+    form_language: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        ko: "ko";
+        jp: "jp";
+    }>>;
+    idempotency_key: z.ZodString;
+    send_confirmation: z.ZodLiteral<"user_authorized">;
+    campaign_creator_selection: z.ZodObject<{
+        workflow_filter: z.ZodOptional<z.ZodEnum<{
+            all: "all";
+            email: "email";
+            email_not_sent: "email_not_sent";
+            email_sent: "email_sent";
+            replied: "replied";
+            negotiating: "negotiating";
+            rejected_hold: "rejected_hold";
+            rejected: "rejected";
+            hold: "hold";
+            contract: "contract";
+            contracted: "contracted";
+            content: "content";
+            draft: "draft";
+            final_approved: "final_approved";
+            posted: "posted";
+        }>>;
+        outreach_stage: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodEnum<{
+            tiktok: "tiktok";
+            instagram: "instagram";
+        }>>;
+        country: z.ZodOptional<z.ZodString>;
+        has_video: z.ZodOptional<z.ZodBoolean>;
+        source_type: z.ZodOptional<z.ZodEnum<{
+            saved_list: "saved_list";
+            file_upload: "file_upload";
+            manual_add: "manual_add";
+            form_submission: "form_submission";
+            discovery_search: "discovery_search";
+        }>>;
+        search: z.ZodOptional<z.ZodString>;
+        excluded_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strict>;
+}, z.core.$strict>]>;
+export declare const StartBulkEmailDiscoveryInputSchema: z.ZodObject<{
+    campaign_id: z.ZodNumber;
+    subject: z.ZodString;
+    body_text: z.ZodString;
+    from_email: z.ZodOptional<z.ZodString>;
+    attachments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    form_id: z.ZodOptional<z.ZodNumber>;
+    form_language: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        ko: "ko";
+        jp: "jp";
+    }>>;
+    idempotency_key: z.ZodString;
+    send_confirmation: z.ZodLiteral<"user_authorized">;
+    recipient_target: z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"ids">;
+        campaign_creator_ids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"selection">;
+        campaign_creator_selection: z.ZodObject<{
+            workflow_filter: z.ZodOptional<z.ZodEnum<{
+                all: "all";
+                email: "email";
+                email_not_sent: "email_not_sent";
+                email_sent: "email_sent";
+                replied: "replied";
+                negotiating: "negotiating";
+                rejected_hold: "rejected_hold";
+                rejected: "rejected";
+                hold: "hold";
+                contract: "contract";
+                contracted: "contracted";
+                content: "content";
+                draft: "draft";
+                final_approved: "final_approved";
+                posted: "posted";
+            }>>;
+            outreach_stage: z.ZodOptional<z.ZodString>;
+            platform: z.ZodOptional<z.ZodEnum<{
+                tiktok: "tiktok";
+                instagram: "instagram";
+            }>>;
+            country: z.ZodOptional<z.ZodString>;
+            has_video: z.ZodOptional<z.ZodBoolean>;
+            source_type: z.ZodOptional<z.ZodEnum<{
+                saved_list: "saved_list";
+                file_upload: "file_upload";
+                manual_add: "manual_add";
+                form_submission: "form_submission";
+                discovery_search: "discovery_search";
+            }>>;
+            search: z.ZodOptional<z.ZodString>;
+            excluded_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export type CheckBulkEmailReadinessInput = z.infer<typeof CheckBulkEmailReadinessInputSchema>;
+export type StartBulkEmailInput = z.infer<typeof StartBulkEmailInputSchema>;
+type CheckBulkEmailReadinessDiscoveryInput = z.infer<typeof CheckBulkEmailReadinessDiscoveryInputSchema>;
+type StartBulkEmailDiscoveryInput = z.infer<typeof StartBulkEmailDiscoveryInputSchema>;
+/** Convert the MCP-discoverable recipient target into the Product API shape. */
+export declare function normalizeCheckBulkEmailReadinessInput(input: CheckBulkEmailReadinessDiscoveryInput): CheckBulkEmailReadinessInput;
+/** Convert the MCP-discoverable send target into the Product API shape. */
+export declare function normalizeStartBulkEmailInput(input: StartBulkEmailDiscoveryInput): StartBulkEmailInput;
+export {};

package/dist/bulk-email-inputs.js

@@ -0,0 +1,168 @@
+import { z } from "zod";
+export const EmailSubjectSchema = z.string().trim().min(1).max(500);
+const HeaderValueSchema = z
+    .string()
+    .trim()
+    .regex(/^[\x21-\x7e]+$/, {
+    message: "value contains unsupported header characters",
+});
+export const IdempotencyKeySchema = HeaderValueSchema.min(1).max(128);
+const SendConfirmationSchema = z.literal("user_authorized");
+const CampaignCreatorWorkflowFilterSchema = z.enum([
+    "all",
+    "email",
+    "email_not_sent",
+    "email_sent",
+    "replied",
+    "negotiating",
+    "rejected_hold",
+    "rejected",
+    "hold",
+    "contract",
+    "contracted",
+    "content",
+    "draft",
+    "final_approved",
+    "posted",
+]);
+const PositiveIdListSchema = z.array(z.number().int().positive()).min(1);
+const CampaignCreatorSelectionSchema = z
+    .object({
+    workflow_filter: CampaignCreatorWorkflowFilterSchema.optional(),
+    outreach_stage: z.string().trim().min(1).optional(),
+    platform: z.enum(["tiktok", "instagram"]).optional(),
+    country: z.string().trim().min(1).optional(),
+    has_video: z.boolean().optional(),
+    source_type: z
+        .enum([
+        "saved_list",
+        "file_upload",
+        "manual_add",
+        "form_submission",
+        "discovery_search",
+    ])
+        .optional(),
+    search: z.string().trim().min(1).optional(),
+    excluded_ids: z.array(z.number().int().positive()).optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const hasNarrowingFilter = (value.workflow_filter !== undefined &&
+        value.workflow_filter !== "all") ||
+        value.outreach_stage !== undefined ||
+        value.platform !== undefined ||
+        value.country !== undefined ||
+        value.has_video !== undefined ||
+        value.source_type !== undefined ||
+        value.search !== undefined;
+    if (!hasNarrowingFilter) {
+        context.addIssue({
+            code: "custom",
+            message: "campaign_creator_selection must include a narrowing filter; use campaign_creator_ids for exact rows",
+        });
+    }
+});
+const CampaignRecipientIdsTargetSchema = z
+    .object({
+    campaign_creator_ids: PositiveIdListSchema,
+})
+    .strict();
+const CampaignRecipientSelectionTargetSchema = z
+    .object({
+    campaign_creator_selection: CampaignCreatorSelectionSchema,
+})
+    .strict();
+const CampaignRecipientTargetSchema = z.union([
+    z
+        .object({
+        type: z.literal("ids"),
+        campaign_creator_ids: PositiveIdListSchema.describe("Exact campaign creator row IDs selected from list_campaign_creators."),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("selection"),
+        campaign_creator_selection: CampaignCreatorSelectionSchema.describe("Narrowed campaign roster selection, such as workflow_filter: email_not_sent."),
+    })
+        .strict(),
+]);
+function validateFormLanguage(value, context) {
+    if (value.form_language !== undefined && value.form_id === undefined) {
+        context.addIssue({
+            code: "custom",
+            message: "form_id is required when form_language is provided",
+            path: ["form_id"],
+        });
+    }
+}
+const CheckBulkEmailReadinessBaseSchema = z.object({
+    campaign_id: z.number().int().positive(),
+});
+export const CheckBulkEmailReadinessInputSchema = z.union([
+    CheckBulkEmailReadinessBaseSchema.merge(CampaignRecipientIdsTargetSchema),
+    CheckBulkEmailReadinessBaseSchema.merge(CampaignRecipientSelectionTargetSchema),
+]);
+export const CheckBulkEmailReadinessDiscoveryInputSchema = CheckBulkEmailReadinessBaseSchema.extend({
+    recipient_target: CampaignRecipientTargetSchema,
+}).strict();
+const StartBulkEmailBaseSchema = z
+    .object({
+    campaign_id: z.number().int().positive(),
+    subject: EmailSubjectSchema,
+    body_text: z.string().trim().min(1),
+    from_email: z.string().trim().min(1).optional(),
+    attachments: z.array(z.string().trim().min(1)).optional(),
+    form_id: z.number().int().positive().optional(),
+    form_language: z.enum(["en", "ko", "jp"]).optional(),
+    idempotency_key: IdempotencyKeySchema,
+    send_confirmation: SendConfirmationSchema,
+})
+    .strict();
+export const StartBulkEmailInputSchema = z
+    .union([
+    StartBulkEmailBaseSchema.merge(CampaignRecipientIdsTargetSchema),
+    StartBulkEmailBaseSchema.merge(CampaignRecipientSelectionTargetSchema),
+])
+    .superRefine(validateFormLanguage);
+export const StartBulkEmailDiscoveryInputSchema = StartBulkEmailBaseSchema.extend({
+    recipient_target: CampaignRecipientTargetSchema,
+})
+    .strict()
+    .superRefine(validateFormLanguage);
+/** Convert the MCP-discoverable recipient target into the Product API shape. */
+export function normalizeCheckBulkEmailReadinessInput(input) {
+    if (input.recipient_target.type === "ids") {
+        return {
+            campaign_id: input.campaign_id,
+            campaign_creator_ids: input.recipient_target.campaign_creator_ids,
+        };
+    }
+    return {
+        campaign_id: input.campaign_id,
+        campaign_creator_selection: input.recipient_target.campaign_creator_selection,
+    };
+}
+/** Convert the MCP-discoverable send target into the Product API shape. */
+export function normalizeStartBulkEmailInput(input) {
+    const base = {
+        campaign_id: input.campaign_id,
+        subject: input.subject,
+        body_text: input.body_text,
+        from_email: input.from_email,
+        attachments: input.attachments,
+        form_id: input.form_id,
+        form_language: input.form_language,
+        idempotency_key: input.idempotency_key,
+        send_confirmation: input.send_confirmation,
+    };
+    if (input.recipient_target.type === "ids") {
+        return {
+            ...base,
+            campaign_creator_ids: input.recipient_target.campaign_creator_ids,
+        };
+    }
+    return {
+        ...base,
+        campaign_creator_selection: input.recipient_target.campaign_creator_selection,
+    };
+}

package/dist/bulk-email-tool-body.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject } from "./http.js";
+import type { CheckBulkEmailReadinessInput, StartBulkEmailInput } from "./tool-inputs.js";
+/** Build the campaign bulk-email readiness request body. */
+export declare function readinessRequestBody(input: CheckBulkEmailReadinessInput): JsonObject;
+/** Build the campaign bulk-email job request body. */
+export declare function startBulkEmailRequestBody(input: StartBulkEmailInput): JsonObject;