migma 1.3.2 → 1.3.3

package/dist/index.d.ts

@@ -64,6 +64,7 @@ interface RequestOptions {
 declare class MigmaClient {
     private readonly apiKey;
     private readonly config;
+    private readonly headers;
     constructor(apiKey: string, config: ClientConfig);
     request<T>(options: RequestOptions): Promise<MigmaResult<T>>;
     /**
@@ -94,6 +95,7 @@ interface Contact {
     email: string;
     firstName?: string;
     lastName?: string;
+    phone?: string;
     country?: string;
     language?: string;
     tags: string[];
@@ -107,6 +109,7 @@ interface CreateContactParams {
     email: string;
     firstName?: string;
     lastName?: string;
+    phone?: string;
     /** ISO 3166-1 alpha-2 country code (e.g., US, CA, GB) */
     country?: string;
     /** Language code in ISO 639-1 or BCP 47 format (e.g., en, en-US) */
@@ -118,6 +121,7 @@ interface CreateContactParams {
 interface UpdateContactParams {
     firstName?: string;
     lastName?: string;
+    phone?: string | null;
     country?: string;
     language?: string;
     tags?: string[];
@@ -141,6 +145,7 @@ interface BulkImportContactItem {
     email: string;
     firstName?: string;
     lastName?: string;
+    phone?: string;
     country?: string;
     language?: string;
     tags?: string[];
@@ -241,10 +246,28 @@ declare class Tags {
     remove(id: string, projectId: string): Promise<MigmaResult<DeleteResponse>>;
 }
 
+interface SegmentFieldFilter {
+    key: string;
+    mode?: 'is' | 'is_not';
+    values: string[];
+}
+interface SegmentActivityFilter {
+    action: 'sent' | 'opened' | 'clicked';
+    mode: 'within' | 'before' | 'never' | 'between';
+    unit?: 'hours' | 'days';
+    amount?: number;
+    from?: string | Date;
+    to?: string | Date;
+    campaignId?: string;
+}
 interface SegmentFilters {
     tags?: string[];
+    excludeTags?: string[];
     status?: 'subscribed' | 'unsubscribed' | 'non-subscribed' | 'bounced';
+    validationStatus?: 'valid' | 'invalid' | 'risky' | 'unknown';
     customFields?: Record<string, string[]>;
+    fields?: SegmentFieldFilter[];
+    activity?: SegmentActivityFilter[];
 }
 interface Segment {
     id: string;
@@ -352,21 +375,19 @@ interface SendEmailParams {
     replyTo?: string;
     bcc?: string[];
     subject: string;
-    /** Email template source. Required unless conversationId or artifactId is provided. */
-    template?: string;
     variables?: Record<string, unknown>;
     providerType?: ProviderType;
-    /** Required unless conversationId or artifactId is provided. */
+    /** Optional when emailId or conversationId can resolve project automatically. */
     projectId?: string;
     /**
-     * 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.
+     * Generated email id from result.emails[].emailId. Use this for selected
+     * emails inside multi-slot conversations or series. Resolves template,
+     * projectId, and parent conversation automatically.
      */
-    artifactId?: string;
+    emailId?: string;
     /**
      * Conversation id. Works for single-email conversations. For multi-slot
-     * conversations, also provide artifactId so API knows which email to send.
+     * conversations, use emailId 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. */
@@ -476,6 +497,24 @@ interface RetryImportResponse {
     status: string;
     message: string;
 }
+interface FieldCatalogParams {
+    segmentId?: string;
+    tag?: string;
+}
+type FieldCatalogEntryType = 'string' | 'number' | 'boolean' | 'date' | 'url' | 'unknown';
+interface FieldCatalogEntry {
+    key: string;
+    label: string;
+    type: FieldCatalogEntryType;
+    fillRate: number;
+    sample: string[];
+    auto: boolean;
+}
+interface FieldCatalogResponse {
+    entries: FieldCatalogEntry[];
+    totalSubscribers: number;
+    computedAt: string;
+}
 
 interface PollingOptions {
     /** Polling interval in ms. Default: 2000 */
@@ -502,6 +541,7 @@ declare class Projects {
     import(params: ImportProjectParams): Promise<MigmaResult<ImportProjectResponse>>;
     getImportStatus(projectId: string): Promise<MigmaResult<ImportStatusResponse>>;
     retryImport(projectId: string): Promise<MigmaResult<RetryImportResponse>>;
+    fieldCatalog(projectId: string, params?: FieldCatalogParams): Promise<MigmaResult<FieldCatalogResponse>>;
     /**
      * Import a project and wait for completion.
      * Polls getImportStatus until status is 'active' or 'error'.
@@ -539,8 +579,7 @@ interface EmailGenerationResult {
     subject: string;
     previewText: string;
     html: string;
-    source?: string;
-    emails: GeneratedEmailArtifact[];
+    emails: GeneratedEmail[];
     seriesPlan?: {
         name?: string;
         count?: number;
@@ -555,10 +594,10 @@ interface EmailGenerationResult {
         colors: string[];
     };
     languages: string[];
-    templateVariables?: unknown[];
 }
-interface GeneratedEmailArtifact {
-    artifactId: string | null;
+interface GeneratedEmail {
+    id: string | null;
+    emailId: string | null;
     conversationId: string;
     messageId: string | null;
     slotIdx: number;
@@ -566,11 +605,10 @@ interface GeneratedEmailArtifact {
     subject: string;
     preheader: string;
     html: string;
-    source?: string;
     sendOffsetDays?: number;
     status: 'ready' | 'processing' | 'failed';
+    screenshotUrl?: string | null;
     thumbnailUrl?: string | null;
-    templateVariables?: unknown[];
 }
 interface EmailGenerationStatus {
     conversationId: string;
@@ -607,50 +645,38 @@ interface ListEmailsResponse {
     };
 }
 interface SendTestEmailParams {
-    conversationId: string;
+    emailId?: string;
+    conversationId?: string;
     to: string;
 }
 interface SendTestEmailResponse {
     messageId: string;
+    emailId?: string;
     conversationId: string;
     sentTo: string;
     sentAt: string;
     subject: string;
 }
-interface EmailArtifact {
-    artifactId: string;
+interface Email {
+    id: string;
+    emailId: string;
     conversationId: string;
     messageId: string | null;
     slotIdx: number;
     slotUuid: string | null;
     status: string;
-    engine: 'zinn' | 'react-email';
     subject: string;
     preheader: string;
     html: string;
-    source?: string;
-    templateVariables: unknown[];
+    screenshotUrl: string | null;
     warnings: string[];
     thumbnailUrl: string | null;
     updatedAt: string;
 }
-interface UpdateEmailArtifactParams {
-    source: string;
-    vars?: Record<string, unknown>;
-    lang?: string;
+interface EditEmailParams {
+    prompt: string;
     label?: string;
 }
-interface CompileEmailArtifactParams {
-    source?: string;
-    vars?: Record<string, unknown>;
-    lang?: string;
-}
-interface CompileEmailArtifactResponse {
-    artifactId: string;
-    html: string;
-    warnings: string[];
-    metadata?: Record<string, unknown>;
-}
 
 declare class Emails {
     private readonly client;
@@ -661,12 +687,10 @@ declare class Emails {
     generate(params: GenerateEmailParams): Promise<MigmaResult<GenerateEmailResponse>>;
     /** Check email generation status */
     getGenerationStatus(conversationId: string): Promise<MigmaResult<EmailGenerationStatus>>;
-    /** Fetch one generated email by artifact id */
-    get(artifactId: string): Promise<MigmaResult<EmailArtifact>>;
-    /** Replace one generated email's Migma Email source and persist compiled HTML */
-    update(artifactId: string, params: UpdateEmailArtifactParams): Promise<MigmaResult<EmailArtifact>>;
-    /** Compile an email artifact's source without persisting */
-    compile(artifactId: string, params?: CompileEmailArtifactParams): Promise<MigmaResult<CompileEmailArtifactResponse>>;
+    /** Fetch one generated email by email id */
+    get(emailId: string): Promise<MigmaResult<Email>>;
+    /** Prompt Migma to edit one generated email */
+    edit(emailId: string, params: EditEmailParams): Promise<MigmaResult<Email>>;
     /**
      * Generate an email and wait for completion.
      * Polls getGenerationStatus until status is 'completed' or 'failed'.
@@ -1160,6 +1184,7 @@ interface Campaign {
     projectId: string;
     name: string;
     conversationId: string;
+    emailId?: string | null;
     subject: string;
     preheaderText?: string | null;
     from: string;
@@ -1178,6 +1203,8 @@ interface Campaign {
     sentAt?: string | null;
     completedAt?: string | null;
     error?: string | null;
+    archived?: boolean;
+    archivedAt?: string | null;
     triggeredBy?: 'manual' | 'api' | 'automation';
     createdAt: string;
     updatedAt: string;
@@ -1186,6 +1213,8 @@ interface CreateCampaignParams {
     projectId: string;
     name: string;
     conversationId: string;
+    /** Generated email ID from result.emails[].emailId. Recommended for series slots. */
+    emailId?: string;
     subject?: string;
     preheaderText?: string;
     from: string;
@@ -1202,6 +1231,7 @@ interface ListCampaignsParams {
     status?: CampaignStatus;
     page?: number;
     limit?: number;
+    archived?: boolean;
 }
 interface ListCampaignsResponse {
     campaigns: Campaign[];
@@ -1221,6 +1251,8 @@ declare class Campaigns {
     send(id: string): Promise<MigmaResult<Campaign>>;
     schedule(id: string, params: ScheduleCampaignParams): Promise<MigmaResult<Campaign>>;
     cancel(id: string): Promise<MigmaResult<Campaign>>;
+    archive(id: string): Promise<MigmaResult<Campaign>>;
+    unarchive(id: string): Promise<MigmaResult<Campaign>>;
 }
 
 interface MigmaConfig {
@@ -1251,4 +1283,4 @@ declare class Migma {
     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 CompileEmailArtifactParams, type CompileEmailArtifactResponse, 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 EmailArtifact, type EmailGenerationResult, type EmailGenerationStatus, type EmailImage, type ExportFile, type ExportFormat, type ExportFormatsResponse, type ExportResult, type ExportStatusResponse, type GenerateEmailParams, type GenerateEmailResponse, type GeneratedEmailArtifact, 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 UpdateEmailArtifactParams, 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 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 EditEmailParams, type Email, type EmailGenerationResult, type EmailGenerationStatus, type EmailImage, type ExportFile, type ExportFormat, type ExportFormatsResponse, type ExportResult, type ExportStatusResponse, type FieldCatalogEntry, type FieldCatalogEntryType, type FieldCatalogParams, type FieldCatalogResponse, type GenerateEmailParams, type GenerateEmailResponse, type GeneratedEmail, 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 SegmentActivityFilter, type SegmentFieldFilter, 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 };

package/dist/index.js

@@ -1,5 +1,22 @@
 'use strict';
 
+// src/agent-identity.ts
+var AGENT_ID_PATTERN = /^ai:[a-z0-9][a-z0-9._-]{0,62}$/;
+var HOST_AGENT_ENV = [
+  { env: "CLAUDECODE", id: "ai:claude-code" },
+  { env: "CURSOR_TRACE_ID", id: "ai:cursor" },
+  { env: "CODEX_HOME", id: "ai:codex" }
+];
+function detectAgentId() {
+  if (typeof process === "undefined" || !process.env) return null;
+  const explicit = (process.env.MIGMA_AGENT_ID || "").trim().toLowerCase();
+  if (AGENT_ID_PATTERN.test(explicit)) return explicit;
+  for (const { env, id } of HOST_AGENT_ENV) {
+    if (process.env[env]) return id;
+  }
+  return null;
+}
+
 // src/errors.ts
 var MigmaErrorCode = /* @__PURE__ */ ((MigmaErrorCode2) => {
   MigmaErrorCode2["VALIDATION_ERROR"] = "validation_error";
@@ -56,9 +73,19 @@ var MigmaError = class _MigmaError extends Error {
 var MigmaClient = class {
   apiKey;
   config;
+  headers;
   constructor(apiKey, config) {
     this.apiKey = apiKey;
     this.config = config;
+    this.headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      "User-Agent": "migma-node/1.0.0"
+    };
+    const agentId = detectAgentId();
+    if (agentId) {
+      this.headers["X-Agent-Id"] = agentId;
+    }
   }
   async request(options) {
     const url = this.buildUrl(options.path, options.query);
@@ -68,11 +95,7 @@ var MigmaClient = class {
       try {
         const response = await fetch(url, {
           method: options.method,
-          headers: {
-            Authorization: `Bearer ${this.apiKey}`,
-            "Content-Type": "application/json",
-            "User-Agent": "migma-node/1.0.0"
-          },
+          headers: this.headers,
           body: options.body ? JSON.stringify(options.body) : void 0
         });
         const json = await response.json();
@@ -115,11 +138,7 @@ var MigmaClient = class {
     try {
       const response = await fetch(url, {
         method: options.method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          "User-Agent": "migma-node/1.0.0"
-        },
+        headers: this.headers,
         body: options.body ? JSON.stringify(options.body) : void 0
       });
       const json = await response.json();
@@ -404,6 +423,15 @@ var Projects = class {
       `/projects/import/${projectId}/retry`
     );
   }
+  async fieldCatalog(projectId, params) {
+    return this.client.get(
+      `/projects/${projectId}/field-catalog`,
+      {
+        segmentId: params?.segmentId,
+        tag: params?.tag
+      }
+    );
+  }
   /**
    * Import a project and wait for completion.
    * Polls getImportStatus until status is 'active' or 'error'.
@@ -451,22 +479,15 @@ var Emails = class {
       `/projects/emails/${conversationId}/status`
     );
   }
-  /** Fetch one generated email by artifact id */
-  async get(artifactId) {
-    return this.client.get(`/emails/${artifactId}`);
+  /** Fetch one generated email by email id */
+  async get(emailId) {
+    return this.client.get(`/emails/${emailId}`);
   }
-  /** Replace one generated email's Migma Email source and persist compiled HTML */
-  async update(artifactId, params) {
-    return this.client.patch(
-      `/emails/${artifactId}`,
-      params
-    );
-  }
-  /** Compile an email artifact's source without persisting */
-  async compile(artifactId, params) {
+  /** Prompt Migma to edit one generated email */
+  async edit(emailId, params) {
     return this.client.post(
-      `/emails/${artifactId}/compile`,
-      params || {}
+      `/emails/${emailId}/edit`,
+      params
     );
   }
   /**
@@ -760,12 +781,13 @@ var Campaigns = class {
     this.client = client;
   }
   async list(params) {
-    const { projectId, status, page, limit } = params;
+    const { projectId, status, page, limit, archived } = params;
     return this.client.get("/campaigns", {
       projectId,
       status,
       page,
-      limit
+      limit,
+      archived
     });
   }
   async create(params) {
@@ -783,6 +805,12 @@ var Campaigns = class {
   async cancel(id) {
     return this.client.post(`/campaigns/${id}/cancel`);
   }
+  async archive(id) {
+    return this.client.post(`/campaigns/${id}/archive`);
+  }
+  async unarchive(id) {
+    return this.client.post(`/campaigns/${id}/unarchive`);
+  }
 };
 
 // src/migma.ts