migma 1.3.0 → 1.3.1

package/README.md

@@ -63,7 +63,7 @@ const { data: email } = await migma.emails.generateAndWait({
   prompt: 'Create a summer sale email with 30% off everything',
 });
 
-// 3. Send it — conversationId resolves the template and project automatically
+// 3. Send it — conversationId works for single-email conversations
 await migma.sending.send({
   recipientType: 'email',
   recipientEmail: 'sarah@example.com',
@@ -72,6 +72,9 @@ await migma.sending.send({
   subject: email.result.subject,
   conversationId: email.conversationId,
 });
+
+// For multi-slot emails or series, use the selected slot's artifactId instead.
+// Copy it from Publish -> Send via API in the app.
 ```
 
 [Full OpenClaw tutorial](https://docs.migma.ai/tutorials/send-emails-from-openclaw)
@@ -220,7 +223,7 @@ const { data: result } = await migma.contacts.bulkImport({
 Send to a single recipient, segment, tag, or full audience.
 
 ```typescript
-// Send using a conversationId (template + project resolved automatically)
+// Send a single-email conversation by conversationId
 await migma.sending.send({
   recipientType: 'email',
   recipientEmail: 'user@example.com',
@@ -230,6 +233,18 @@ await migma.sending.send({
   conversationId: 'conv_abc123',
 });
 
+// For a multi-slot conversation or series, send one slot by artifactId.
+// In the app, open the focused slot and use Publish -> Send via API to copy it.
+await migma.sending.send({
+  recipientType: 'email',
+  recipientEmail: 'user@example.com',
+  from: 'hello@yourdomain.com',
+  fromName: 'Your Company',
+  subject: 'Welcome!',
+  artifactId: 'artifact_abc123',
+  conversationId: 'conv_abc123',
+});
+
 // Send to a segment
 await migma.sending.send({
   recipientType: 'segment',
@@ -248,8 +263,7 @@ await migma.sending.send({
   from: 'noreply@yourdomain.com',
   fromName: 'Your Company',
   subject: 'Your subscription renews tomorrow',
-  template: '<html>Your plan renews on March 1.</html>',
-  projectId: 'proj_abc123',
+  artifactId: 'artifact_abc123',
   transactional: true,
 });
 ```

package/dist/index.d.mts

@@ -353,13 +353,22 @@ interface SendEmailParams {
     replyTo?: string;
     bcc?: string[];
     subject: string;
-    /** Email template HTML. Required unless conversationId is provided. */
+    /** Email template source. Required unless conversationId or artifactId is provided. */
     template?: string;
     variables?: Record<string, unknown>;
     providerType?: ProviderType;
-    /** Required unless conversationId is provided. */
+    /** Required unless conversationId or artifactId is provided. */
     projectId?: string;
-    /** When provided, template and projectId are resolved automatically from the conversation. */
+    /**
+     * Slot-precise email artifact id. Use this for a selected email inside a
+     * multi-slot conversation or series. Resolves template, projectId, and parent
+     * conversation automatically.
+     */
+    artifactId?: string;
+    /**
+     * Conversation id. Works for single-email conversations. For multi-slot
+     * conversations, also provide artifactId so API knows which email to send.
+     */
     conversationId?: string;
     /** Defaults to true for single sends, false for batch sends. Set explicitly to override. Transactional emails bypass subscription status and topic filters, and omit List-Unsubscribe headers. */
     transactional?: boolean;
@@ -1177,6 +1186,336 @@ declare class Campaigns {
     unarchive(id: string): Promise<MigmaResult<Campaign>>;
 }
 
+/**
+ * Design v2 — SDK types for the `/v1/flows/*` and `/v1/emails/*` REST surface
+ * shipped in P5 of the design-v2 plan.
+ *
+ * Mongo ObjectIds and Dates serialize to JSON strings on the wire, so every
+ * id and timestamp on this surface is `string`. These types intentionally do
+ * not import from the backend — the SDK is versioned independently and must
+ * not take a peer dep on the backend package.
+ */
+type FlowStatus = 'draft' | 'generating' | 'ready' | 'archived';
+type EmailStatus = 'pending' | 'streaming' | 'ready' | 'failed' | 'sent';
+type ImageGenMode = 'auto' | 'manual' | 'off';
+type EmailVariableSource = 'persona' | 'manual' | 'system';
+type EmailEditKind = 'chat' | 'visual' | 'tool';
+type ImageJobStatus = 'queued' | 'running' | 'succeeded' | 'failed';
+interface FlowToolPolicy {
+    localization: boolean;
+    validate: boolean;
+    imageGen: ImageGenMode;
+    mcpEnabled: {
+        shopify: boolean;
+        notion: boolean;
+    };
+}
+interface FlowReferenceSelection {
+    selected: string[];
+    autoIncluded: string[];
+}
+interface FlowMeta {
+    creditsSpent: number;
+    tokensIn: number;
+    tokensOut: number;
+    model: string;
+}
+interface Flow {
+    _id: string;
+    userId: string;
+    projectId: string;
+    title: string;
+    goal: string;
+    status: FlowStatus;
+    emailIds: string[];
+    references: FlowReferenceSelection;
+    agentSessionId: string | null;
+    toolPolicy: FlowToolPolicy;
+    meta: FlowMeta;
+    createdAt: string;
+    updatedAt: string;
+    archivedAt?: string;
+}
+interface ListFlowsParams {
+    projectId?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface ListFlowsResponse {
+    items: Flow[];
+    nextCursor: string | null;
+}
+interface CreateFlowParams {
+    projectId: string;
+    title?: string;
+    description?: string;
+}
+interface FlowPatch {
+    title?: string;
+    description?: string;
+    status?: FlowStatus;
+    toolPolicy?: Partial<FlowToolPolicy>;
+    references?: {
+        selected?: string[];
+        autoIncluded?: string[];
+    };
+}
+interface DeleteFlowResponse {
+    archived: true;
+}
+interface EmailVariable {
+    name: string;
+    defaultValue: string;
+    source: EmailVariableSource;
+    required?: boolean;
+}
+interface EmailAsset {
+    url: string;
+    type: string;
+    alt?: string;
+    w?: number;
+    h?: number;
+    sourceTool?: string;
+    replicateId?: string;
+}
+interface EmailEdit {
+    at: string;
+    kind: EmailEditKind;
+    summary: string;
+    astPatch: Record<string, unknown>;
+}
+interface ImageJob {
+    jobId: string;
+    status: ImageJobStatus;
+    prompt: string;
+    replicateUrl?: string;
+    finalUrl?: string;
+}
+interface EmailExport {
+    at: string;
+    format: string;
+    platform?: string;
+    url?: string;
+}
+interface EmailSend {
+    lastSentAt?: string;
+    recipients: number;
+    esp?: string;
+}
+interface EmailDesign {
+    _id: string;
+    flowId: string | null;
+    userId: string;
+    projectId: string;
+    index: number;
+    title: string;
+    subject: string;
+    preheader: string;
+    /**
+     * Internal-only on the backend, but exposed through the REST surface for
+     * SDK consumers. Treat as canonical source of truth for the email content.
+     */
+    zinnSource: string;
+    ast: Record<string, unknown>;
+    html: string;
+    htmlPartial: string | null;
+    text: string;
+    markdown: string;
+    assets: EmailAsset[];
+    compatibility: Record<string, unknown>;
+    warnings: string[];
+    status: EmailStatus;
+    agentSessionId: string | null;
+    edits: EmailEdit[];
+    imageJobs: ImageJob[];
+    exports: EmailExport[];
+    send: EmailSend;
+    variables: EmailVariable[];
+    firstCompileAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Response envelope from `GET /v1/emails/:id`. Mirrors the backend
+ * `EmailWithHistory` shape so callers don't have to make a second call to
+ * `history()` for the most recent edit.
+ */
+interface EmailWithHistory {
+    email: EmailDesign;
+    history: {
+        count: number;
+        latest: EmailEdit | null;
+    };
+}
+interface EmailDesignPatch {
+    title?: string;
+    subject?: string;
+    preheader?: string;
+    zinnSource?: string;
+    status?: EmailStatus;
+}
+interface UpdateEmailParams {
+    /** Apply a structured patch to email fields (synchronous). */
+    patch?: EmailDesignPatch;
+    /**
+     * Natural-language instruction routed to the design agent (async). Mutually
+     * exclusive with `patch`. The SDK does NOT enforce the exclusion — pass one
+     * or the other; passing both makes `instruction` win at the controller.
+     */
+    instruction?: string;
+}
+interface EmailRevisionRef {
+    blobId: string;
+    by: 'user' | 'agent';
+    summary: string;
+    at: string;
+}
+/**
+ * One revision returned from `GET /v1/emails/:id/history`. Carries the same
+ * payload as `EmailEdit` for now — the backend writes both `flow_emails.edits`
+ * (ring buffer, capped at 50) and the design-history store, and the history
+ * endpoint reads from the latter. Defined separately so the wire shape can
+ * diverge from `edits[]` without a SDK break.
+ */
+type EmailRevision = EmailEdit;
+/**
+ * Synchronous result of `PATCH /v1/emails/:id` with a `patch` body.
+ */
+interface UpdateEmailPatchResult {
+    mode: 'patch';
+    email: EmailDesign;
+    revision: EmailRevisionRef | null;
+}
+/**
+ * Async-accepted result of `PATCH /v1/emails/:id` with an `instruction` body.
+ * The HTTP layer returns 202 Accepted; the SDK surfaces `status: 202` in the
+ * body for symmetry with the spec, even though the SDK does not expose raw
+ * HTTP status codes elsewhere.
+ *
+ * **`sessionId` is a P2 stub.** Until the agent runtime from P2 wires up,
+ * the controller returns `stub_p2_<emailId>_<timestamp>` instead of a real
+ * session id. Consumers detecting `sessionId.startsWith('stub_p2_')` should
+ * display a "pending" indicator and not open an SSE stream until P2 ships.
+ */
+interface UpdateEmailInstructionResult {
+    mode: 'instruction';
+    accepted: true;
+    status: 202;
+    sessionId: string;
+}
+type EmailUpdateResult = UpdateEmailPatchResult | UpdateEmailInstructionResult;
+interface CompileEmailParams {
+    vars?: Record<string, unknown>;
+}
+interface CompileEmailWarning {
+    code: string;
+    line: number;
+    message: string;
+}
+interface CompileEmailResult {
+    html: string;
+    ms: number;
+    warnings: ReadonlyArray<CompileEmailWarning>;
+}
+interface DeleteEmailResponse {
+    archived: true;
+}
+
+/**
+ * Wraps `/v1/flows/*` — the design-v2 flow CRUD surface (P5).
+ *
+ * Mounted on `client.design.flows`. Internally the wire path is `/flows/...`
+ * (the SDK's base URL already includes the `/v1` prefix).
+ */
+declare class FlowsResource {
+    private readonly client;
+    constructor(client: MigmaClient);
+    /** List non-archived flows for the authenticated user. */
+    list(params?: ListFlowsParams): Promise<MigmaResult<ListFlowsResponse>>;
+    /** Fetch a single flow by id. */
+    get(flowId: string): Promise<MigmaResult<Flow>>;
+    /** Create a new flow under a project. */
+    create(params: CreateFlowParams): Promise<MigmaResult<Flow>>;
+    /** Patch a flow (partial fields). */
+    update(flowId: string, patch: FlowPatch): Promise<MigmaResult<Flow>>;
+    /**
+     * Soft-delete a flow. The backend marks `status: 'archived'` so existing
+     * email/history references stay resolvable.
+     */
+    delete(flowId: string): Promise<MigmaResult<DeleteFlowResponse>>;
+    /** List the emails that belong to a flow, ordered by `index` ascending. */
+    listEmails(flowId: string): Promise<MigmaResult<EmailDesign[]>>;
+}
+
+/**
+ * Wraps `/v1/emails/*` — the design-v2 single-email surface (P5).
+ *
+ * Mounted on `client.design.emails`. Distinct from the legacy `client.emails`
+ * resource (which targets `/projects/emails/*` for the generation flow);
+ * design v2 owns the `/emails/:id` namespace.
+ */
+declare class EmailsResource {
+    private readonly client;
+    constructor(client: MigmaClient);
+    /**
+     * Fetch a single email plus a thin history summary (count + latest edit).
+     * Mirrors the backend `EmailWithHistory` shape so the common UI case
+     * (header chip showing last-edit metadata) avoids a second round trip.
+     */
+    get(emailId: string): Promise<MigmaResult<EmailWithHistory>>;
+    /**
+     * Update an email. Two mutually exclusive modes:
+     *
+     * - `patch`: structured field update (title / subject / preheader /
+     *   zinnSource / status). Returns the updated email plus the recorded
+     *   revision (when `zinnSource` changed).
+     *
+     * - `instruction`: natural-language edit routed to the design agent.
+     *   Returns `{ mode: 'instruction', accepted: true, status: 202, sessionId }`.
+     *
+     *   **`sessionId` is a P2 stub.** Until the agent runtime ships, the
+     *   controller returns `stub_p2_<emailId>_<timestamp>`. Consumers that
+     *   detect `sessionId.startsWith('stub_p2_')` should render a "pending"
+     *   indicator and not open an SSE stream until P2 lands. The contract
+     *   (mode/accepted/status/sessionId) will not change when P2 wires real
+     *   sessions — only the id format will.
+     */
+    update(emailId: string, body: UpdateEmailParams): Promise<MigmaResult<EmailUpdateResult>>;
+    /**
+     * Soft-delete an email. The backend flips `status: 'failed'` so revert and
+     * history endpoints still resolve. The response is `{ archived: true }`
+     * for symmetry with `FlowsResource.delete`.
+     */
+    delete(emailId: string): Promise<MigmaResult<DeleteEmailResponse>>;
+    /** Compile an email's zinn source to HTML, optionally supplying merge vars. */
+    compile(emailId: string, opts?: CompileEmailParams): Promise<MigmaResult<CompileEmailResult>>;
+    /** List the email's full edit history (capped server-side). */
+    history(emailId: string): Promise<MigmaResult<EmailRevision[]>>;
+    /**
+     * Revert an email to a prior revision. Re-compiles and returns the fresh
+     * `CompileEmailResult`; the server also writes a new history entry tagged
+     * "Reverted to <blobId>".
+     */
+    revert(emailId: string, rev: string): Promise<MigmaResult<CompileEmailResult>>;
+}
+
+/**
+ * Namespace wrapper exposing the design-v2 surface (P5) under `client.design`.
+ *
+ * Sub-resources are instantiated eagerly — same pattern as every other
+ * resource on the `Migma` client, keeps the public surface side-effect-free
+ * at module-load time and avoids per-call allocation.
+ *
+ * Naming: internally the wire path is `/v1/flows/*` (matches DB + REST), but
+ * the user-facing SDK surface is `client.design.flows` / `client.design.emails`
+ * so call sites read naturally for design tooling.
+ */
+declare class DesignResource {
+    readonly flows: FlowsResource;
+    readonly emails: EmailsResource;
+    constructor(client: MigmaClient);
+}
+
 interface MigmaConfig {
     /** API base URL. Default: 'https://api.migma.ai/v1' */
     baseUrl?: string;
@@ -1202,7 +1541,8 @@ declare class Migma {
     readonly knowledgeBase: KnowledgeBase;
     readonly images: Images;
     readonly campaigns: Campaigns;
+    readonly design: DesignResource;
     constructor(apiKey: string, config?: MigmaConfig);
 }
 
-export { type AddImageParams, type AddKnowledgeBaseParams, type AnalyzeDeliverabilityParams, type AnalyzeLinksParams, type ApiResponse, type BatchStatus, type BulkImportAsyncResponse, type BulkImportContactItem, type BulkImportJobStatus, type BulkImportParams, type BulkImportResponse, type BulkImportSyncResponse, type Campaign, type CampaignStatus, type ChangeStatusParams, type CheckCompatibilityParams, type CheckSpellingParams, type CheckedLink, type ClientConfig, type CompatibilityResponse, type Contact, type ContactStatus, type CreateCampaignParams, type CreateContactParams, type CreateDomainParams, type CreateManagedDomainParams, type CreatePreviewParams, type CreatePreviewResponse, type CreateSegmentParams, type CreateTagParams, type CreateTopicParams, type CreateWebhookParams, type DeleteResponse, type DeliverabilityResponse, type DeviceCategoriesResponse, type DnsRecord, type Domain, type DomainAvailability, type DomainDeleteResponse, type DomainVerificationResult, type EmailGenerationResult, type EmailGenerationStatus, type EmailImage, type ExportFile, type ExportFormat, type ExportFormatsResponse, type ExportResult, type ExportStatusResponse, type FieldCatalogEntry, type FieldCatalogParams, type FieldCatalogResponse, type FieldCatalogValueType, type GenerateEmailParams, type GenerateEmailResponse, type GetDevicePreviewResponse, type GetPreviewResponse, type GetPreviewStatusResponse, type GetSupportedDevicesResponse, type HubspotExportParams, type ImportProjectParams, type ImportProjectResponse, type ImportStatusResponse, type KnowledgeBaseEntry, type KnowledgeBaseListResponse, type LinkAnalysisResponse, type ListCampaignsParams, type ListCampaignsResponse, type ListContactsParams, type ListContactsResponse, type ListEmailsEmail, type ListEmailsParams, type ListEmailsResponse, type ListProjectsParams, type ListProjectsResponse, type ListSegmentsResponse, type ListTagsParams, type ListTagsResponse, type ListTopicsParams, type ListTopicsResponse, type ListWebhooksResponse, type LogosResponse, type MessageResponse, Migma, MigmaClient, type MigmaConfig, MigmaError, MigmaErrorCode, type MigmaResult, type PollingOptions, type PreviewDevice, type PreviewDeviceCategory, type PreviewDeviceStatus, type PreviewMetadata, type PreviewStatus, type Project, type ProjectImage, type ProviderType, type RecipientType, type RetryImportResponse, type ScheduleCampaignParams, type Segment, type SegmentFilters, type SendEmailParams, type SendEmailResponse, type SendTestEmailParams, type SendTestEmailResponse, type SpellingResponse, type SupportedDevice, type Tag, type Topic, type TopicSubscriptionParams, type TopicSubscriptionResponse, type UpdateContactParams, type UpdateDomainParams, type UpdateImageParams, type UpdateKnowledgeBaseParams, type UpdateLogosParams, type UpdateSegmentParams, type UpdateTagParams, type UpdateTopicParams, type UpdateWebhookParams, type ValidateAllParams, type ValidateAllResponse, type Webhook, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDetail, type WebhookEvent, type WebhookEventType, type WebhookEventsResponse, type WebhookTestResult, poll };
+export { type AddImageParams, type AddKnowledgeBaseParams, type AnalyzeDeliverabilityParams, type AnalyzeLinksParams, type ApiResponse, type BatchStatus, type BulkImportAsyncResponse, type BulkImportContactItem, type BulkImportJobStatus, type BulkImportParams, type BulkImportResponse, type BulkImportSyncResponse, type Campaign, type CampaignStatus, type ChangeStatusParams, type CheckCompatibilityParams, type CheckSpellingParams, type CheckedLink, type ClientConfig, type CompatibilityResponse, type CompileEmailParams, type CompileEmailResult, type CompileEmailWarning, type Contact, type ContactStatus, type CreateCampaignParams, type CreateContactParams, type CreateDomainParams, type CreateFlowParams, type CreateManagedDomainParams, type CreatePreviewParams, type CreatePreviewResponse, type CreateSegmentParams, type CreateTagParams, type CreateTopicParams, type CreateWebhookParams, type DeleteEmailResponse, type DeleteFlowResponse, type DeleteResponse, type DeliverabilityResponse, DesignResource, type DeviceCategoriesResponse, type DnsRecord, type Domain, type DomainAvailability, type DomainDeleteResponse, type DomainVerificationResult, type EmailAsset, type EmailDesign, type EmailDesignPatch, type EmailEdit, type EmailEditKind, type EmailExport, type EmailGenerationResult, type EmailGenerationStatus, type EmailImage, type EmailRevision, type EmailRevisionRef, type EmailSend, type EmailStatus, type EmailUpdateResult, type EmailVariable, type EmailVariableSource, type EmailWithHistory, EmailsResource, type ExportFile, type ExportFormat, type ExportFormatsResponse, type ExportResult, type ExportStatusResponse, type FieldCatalogEntry, type FieldCatalogParams, type FieldCatalogResponse, type FieldCatalogValueType, type Flow, type FlowMeta, type FlowPatch, type FlowReferenceSelection, type FlowStatus, type FlowToolPolicy, FlowsResource, type GenerateEmailParams, type GenerateEmailResponse, type GetDevicePreviewResponse, type GetPreviewResponse, type GetPreviewStatusResponse, type GetSupportedDevicesResponse, type HubspotExportParams, type ImageGenMode, type ImageJob, type ImageJobStatus, type ImportProjectParams, type ImportProjectResponse, type ImportStatusResponse, type KnowledgeBaseEntry, type KnowledgeBaseListResponse, type LinkAnalysisResponse, type ListCampaignsParams, type ListCampaignsResponse, type ListContactsParams, type ListContactsResponse, type ListEmailsEmail, type ListEmailsParams, type ListEmailsResponse, type ListFlowsParams, type ListFlowsResponse, type ListProjectsParams, type ListProjectsResponse, type ListSegmentsResponse, type ListTagsParams, type ListTagsResponse, type ListTopicsParams, type ListTopicsResponse, type ListWebhooksResponse, type LogosResponse, type MessageResponse, Migma, MigmaClient, type MigmaConfig, MigmaError, MigmaErrorCode, type MigmaResult, type PollingOptions, type PreviewDevice, type PreviewDeviceCategory, type PreviewDeviceStatus, type PreviewMetadata, type PreviewStatus, type Project, type ProjectImage, type ProviderType, type RecipientType, type RetryImportResponse, type ScheduleCampaignParams, type Segment, type SegmentFilters, type SendEmailParams, type SendEmailResponse, type SendTestEmailParams, type SendTestEmailResponse, type SpellingResponse, type SupportedDevice, type Tag, type Topic, type TopicSubscriptionParams, type TopicSubscriptionResponse, type UpdateContactParams, type UpdateDomainParams, type UpdateEmailInstructionResult, type UpdateEmailParams, type UpdateEmailPatchResult, type UpdateImageParams, type UpdateKnowledgeBaseParams, type UpdateLogosParams, type UpdateSegmentParams, type UpdateTagParams, type UpdateTopicParams, type UpdateWebhookParams, type ValidateAllParams, type ValidateAllResponse, type Webhook, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDetail, type WebhookEvent, type WebhookEventType, type WebhookEventsResponse, type WebhookTestResult, poll };