migma 1.8.1 → 1.10.0

package/dist/index.d.ts

@@ -61,9 +61,12 @@ interface RequestOptions {
     body?: Record<string, unknown>;
     query?: Record<string, string | number | boolean | undefined>;
     headers?: Record<string, string>;
+    maxRetries?: number;
 }
 /** Per-call options for write methods (POST/PATCH/DELETE). */
 interface CallOptions {
+    /** Override automatic retries for this call. Use 0 for unsafe writes. */
+    maxRetries?: number;
     /**
      * Optional Idempotency-Key (max 100 chars). Same key + same body within 24h
      * replays the original response; a different body returns 409 IDEMPOTENCY_CONFLICT.
@@ -100,6 +103,64 @@ declare class MigmaClient {
     private sleep;
 }
 
+interface SegmentFieldFilter {
+    key: string;
+    /** Exact/pattern, date, or numeric comparison. Date/number comparisons use one
+     * value; date_between/number_between use two ordered bounds. */
+    mode?: 'is' | 'is_not' | 'starts_with' | 'ends_with' | 'contains' | 'not_contains' | 'date_after' | 'date_before' | 'date_on' | 'date_between' | 'number_gt' | 'number_gte' | 'number_lt' | 'number_lte' | 'number_between';
+    values: string[];
+}
+interface SegmentActivityFilter {
+    action: 'sent' | 'opened' | 'clicked';
+    channel?: 'email';
+    mode: 'within' | 'before' | 'never' | 'between';
+    unit?: 'hours' | 'days';
+    amount?: number;
+    from?: string | Date;
+    to?: string | Date;
+    campaignId?: string;
+}
+interface SegmentFilters {
+    /** Combines this group's conditions and child groups. Defaults to all (AND).
+     * Campaign-scoped activity requires all in its group and every ancestor. */
+    match?: 'all' | 'any';
+    /** Nonempty child groups: at most 10 per group, 3 levels below the root,
+     * and 50 conditions across the entire filter tree. The root may be empty. */
+    groups?: 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;
+    name: string;
+    description: string;
+    filters: SegmentFilters;
+    count: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateSegmentParams {
+    name: string;
+    description?: string;
+    filters?: SegmentFilters;
+    projectId: string;
+}
+interface UpdateSegmentParams {
+    name?: string;
+    description?: string;
+    filters?: SegmentFilters;
+    projectId: string;
+}
+interface ListSegmentsResponse {
+    data: Segment[];
+    count: number;
+}
+
 type ContactStatus = 'subscribed' | 'unsubscribed' | 'bounced' | 'non-subscribed';
 interface Contact {
     id: string;
@@ -209,6 +270,64 @@ interface ChangeStatusParams {
     tags?: string[];
     projectId: string;
 }
+interface CreateContactExportParams {
+    projectId: string;
+    segmentId?: string;
+    /** Same filters used by saved segments; tags are IDs, not names. */
+    filters?: SegmentFilters & {
+        search?: string;
+    };
+}
+interface ContactExportStatus {
+    jobId: string;
+    projectId: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    contactCount: number;
+    fileName: string;
+    createdAt: string;
+    completedAt: string | null;
+    /** Present only after the private CSV has been uploaded. Expires after one hour. */
+    downloadUrl?: string;
+    downloadExpiresAt?: string;
+    error?: string;
+}
+type ContactImportProvider = 'klaviyo' | 'mailchimp' | 'hubspot';
+/** A list or segment in the connected provider account that can be imported. */
+interface ProviderImportSource {
+    id: string;
+    type: 'audience' | 'segment' | 'tag' | 'list';
+    name: string;
+    [key: string]: unknown;
+}
+interface ListProviderImportSourcesParams {
+    provider: ContactImportProvider;
+    projectId: string;
+    /** Only when the brand has several accounts connected for this provider. */
+    connectionId?: string;
+}
+interface ImportFromProviderParams {
+    provider: ContactImportProvider;
+    projectId: string;
+    /** 1 to 25 sources from listProviderImportSources. */
+    sources: Pick<ProviderImportSource, 'id' | 'type' | 'name'>[];
+    /** Default subscribed-only. */
+    consentMode?: 'subscribed-only' | 'include-all';
+    connectionId?: string;
+}
+/** Each import becomes a tag and a segment named after its sources. Poll the import with its id. */
+interface ProviderImportStarted {
+    object: 'contact_import';
+    id: string;
+    status: 'pending';
+    tag: {
+        id: string;
+        name: string;
+    };
+    segment: {
+        id: string;
+        name: string;
+    };
+}
 
 declare class Contacts {
     private readonly client;
@@ -222,6 +341,15 @@ declare class Contacts {
     getBulkImportStatus(jobId: string): Promise<MigmaResult<BulkImportJobStatus>>;
     /** Batch delete contacts by email (up to 1000). Emails with no match come back in `notFound`. */
     bulkDeleteByEmail(params: BatchDeleteContactsParams, options?: CallOptions): Promise<MigmaResult<BatchDeleteResponse>>;
+    /** Queue a filtered CSV export. Poll getExport; do not list every contact to build a CSV. */
+    createExport(params: CreateContactExportParams, options?: CallOptions): Promise<MigmaResult<ContactExportStatus>>;
+    getExport(jobId: string, projectId: string): Promise<MigmaResult<ContactExportStatus>>;
+    /** Lists and segments in the brand's connected Klaviyo, Mailchimp or HubSpot account. A 409 error message includes the link to connect it. */
+    listProviderImportSources(params: ListProviderImportSourcesParams): Promise<MigmaResult<{
+        sources: ProviderImportSource[];
+    }>>;
+    /** Import provider sources as contacts (subscribed only by default). Poll GET /contacts/imports/{id} for counts. */
+    importFromProvider(params: ImportFromProviderParams, options?: CallOptions): Promise<MigmaResult<ProviderImportStarted>>;
     changeStatus(params: ChangeStatusParams, options?: CallOptions): Promise<MigmaResult<{
         success: boolean;
     }>>;
@@ -272,59 +400,6 @@ declare class Tags {
     remove(id: string, projectId: string): Promise<MigmaResult<DeleteResponse>>;
 }
 
-interface SegmentFieldFilter {
-    key: string;
-    /** Exact match (is/is_not) or pattern match (starts_with/ends_with/contains/not_contains,
-     *  compiled to anchored case-insensitive regex). Pattern modes keep a value group
-     *  like "email ends_with .vc" accurate as new contacts arrive. */
-    mode?: 'is' | 'is_not' | 'starts_with' | 'ends_with' | 'contains' | 'not_contains';
-    values: string[];
-}
-interface SegmentActivityFilter {
-    action: 'sent' | 'opened' | 'clicked';
-    channel?: 'email';
-    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;
-    name: string;
-    description: string;
-    filters: SegmentFilters;
-    count: number;
-    createdAt: string;
-    updatedAt: string;
-}
-interface CreateSegmentParams {
-    name: string;
-    description?: string;
-    filters?: SegmentFilters;
-    projectId: string;
-}
-interface UpdateSegmentParams {
-    name?: string;
-    description?: string;
-    filters?: SegmentFilters;
-    projectId: string;
-}
-interface ListSegmentsResponse {
-    data: Segment[];
-    count: number;
-}
-
 declare class Segments {
     private readonly client;
     constructor(client: MigmaClient);
@@ -472,6 +547,38 @@ declare class Sending {
     getBatchStatus(batchId: string): Promise<MigmaResult<BatchStatus>>;
 }
 
+interface ConnectedToolScope {
+    projectId: string;
+    serverId: string;
+    toolName: string;
+}
+interface ListConnectedToolsParams {
+    projectId: string;
+    search?: string;
+    offset?: number;
+    limit?: number;
+}
+interface ConnectedToolSummary {
+    name: string;
+    serverId: string;
+    description: string;
+    requiresApproval: boolean;
+    annotations?: Record<string, unknown>;
+}
+interface ConnectedToolSchema extends ConnectedToolSummary {
+    inputSchema: Record<string, unknown>;
+}
+interface ListConnectedToolsResponse {
+    tools: ConnectedToolSummary[];
+    total: number;
+    nextOffset: number | null;
+    unreachableServers: string[];
+    authRequired: Array<{
+        serverId: string;
+        authUrl: string;
+    }>;
+}
+
 interface Project {
     _id: string;
     name: string;
@@ -620,6 +727,12 @@ declare class Projects {
     references(projectId: string): Promise<MigmaResult<ProjectReferencesResponse>>;
     retryImport(projectId: string): Promise<MigmaResult<RetryImportResponse>>;
     fieldCatalog(projectId: string, params?: FieldCatalogParams): Promise<MigmaResult<FieldCatalogResponse>>;
+    listConnectedTools(params: ListConnectedToolsParams): Promise<MigmaResult<ListConnectedToolsResponse>>;
+    getConnectedTool(params: ConnectedToolScope): Promise<MigmaResult<ConnectedToolSchema>>;
+    /** Never automatically replay external writes; provider outcome can be unknown. */
+    callConnectedTool(params: ConnectedToolScope & {
+        parameters: Record<string, unknown>;
+    }): Promise<MigmaResult<unknown>>;
     /**
      * Import a project and wait for completion.
      * Polls getImportStatus until status is 'active' or 'error'.
@@ -773,6 +886,21 @@ interface EditEmailParams {
     prompt: string;
     label?: string;
 }
+interface EmailEditOperation {
+    editId: string;
+    emailId: string;
+    conversationId: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    stage: string;
+    createdAt: string;
+    updatedAt: string;
+    pollAfterMs: number;
+    error?: string;
+    /** Inspect the saved email before starting another edit after a failure. */
+    changesMayHaveBeenSaved?: boolean;
+    /** Current saved email, included by getEditStatus after completion. */
+    result?: Email;
+}
 interface EmailMetricsSummary {
     totalEmails: number;
     delivered: number;
@@ -875,8 +1003,12 @@ declare class Emails {
     getGenerationStatus(conversationId: string): Promise<MigmaResult<EmailGenerationStatus>>;
     /** Fetch one generated email by email id */
     get(emailId: string): Promise<MigmaResult<Email>>;
-    /** Prompt Migma to edit one generated email */
+    /** Synchronous edit. No automatic retries; use startEdit for long edits. */
     edit(emailId: string, params: EditEmailParams): Promise<MigmaResult<Email>>;
+    /** Queue an edit immediately. Retain an explicit key to recover uncertain submissions. */
+    startEdit(emailId: string, params: EditEmailParams, options?: CallOptions): Promise<MigmaResult<EmailEditOperation>>;
+    /** Poll the exact edit; a completed conversation may belong to an earlier turn. */
+    getEditStatus(emailId: string, editId: string): Promise<MigmaResult<EmailEditOperation>>;
     /**
      * Generate an email and wait for completion.
      * Polls getGenerationStatus until status is 'completed' or 'failed'.
@@ -1182,6 +1314,8 @@ interface Domain {
     status: string;
     isVerified?: boolean;
     dnsRecords?: DnsRecord[];
+    /** Set while a custom domain cannot send yet: a Migma page that starts one-click DNS setup. */
+    connectUrl?: string;
     trackingSettings?: {
         openTracking?: boolean;
         clickTracking?: boolean;
@@ -1386,16 +1520,20 @@ interface CreditStatus {
 type UpgradePlan = 'basic' | 'premium' | 'business' | 'basic_annual' | 'premium_annual' | 'business_annual';
 interface UpgradeLinkParams {
     /**
-     * Target plan for Stripe Checkout. Omit to get a billing portal link
-     * (existing Stripe customers only).
+     * User-chosen plan for new subscription checkout. Omit for an existing
+     * Stripe customer's billing portal. Passing plan for an active subscription
+     * can change it and charge immediately; requires explicit charge approval.
      */
     plan?: UpgradePlan;
 }
 interface UpgradeLink {
-    /** URL the account owner opens in a browser to pay or manage billing. */
+    /** Checkout, invoice, confirmation, or portal URL; not proof of payment. */
     url: string;
+    /** checkout includes an existing plan-change result; portal is the billing portal. */
     kind: 'checkout' | 'portal';
+    /** Present when a new Stripe Checkout session was created. */
     sessionId?: string;
+    /** Migma checkout order id or Stripe invoice id for an existing plan change. */
     orderId?: string;
 }
 
@@ -1405,8 +1543,10 @@ declare class Billing {
     /** Plan and remaining credits for the API key owner. */
     credits(): Promise<MigmaResult<CreditStatus>>;
     /**
-     * Mint a Stripe link the account owner opens in a browser to upgrade or
-     * manage the subscription. Nothing is charged by this call itself.
+     * Create checkout for a user-chosen new plan, or omit plan for the existing
+     * customer's billing portal. Passing plan for an active subscription can
+     * change it and charge prorated payment immediately; obtain charge approval.
+     * The returned URL alone does not confirm payment. Do not retry unknown writes.
      */
     upgradeLink(params?: UpgradeLinkParams): Promise<MigmaResult<UpgradeLink>>;
 }
@@ -1512,6 +1652,13 @@ interface KnowledgeBaseEntry {
     thumbnailUrl?: string;
     screenshotUrl?: string;
     referenceOrigin?: ReferenceOrigin;
+    sourceFileName?: string;
+    /** Preparation runs after save; poll list() for completion. Retry failures by updating the original content. */
+    conversion?: {
+        status: 'pending' | 'complete' | 'failed';
+        revision: string;
+        error?: string;
+    };
 }
 interface KnowledgeBaseListResponse {
     entries: KnowledgeBaseEntry[];
@@ -1520,6 +1667,8 @@ interface KnowledgeBaseListResponse {
 interface AddKnowledgeBaseParams {
     title: string;
     content: string;
+    /** Original upload name, including .html, .eml, or .mjml; at most 255 characters. */
+    sourceFileName?: string;
     /** Set to mark the entry as a design reference generation should match. */
     referenceOrigin?: ReferenceOrigin;
     previewHtml?: string;
@@ -1529,6 +1678,8 @@ interface AddKnowledgeBaseParams {
 interface UpdateKnowledgeBaseParams {
     title?: string;
     content?: string;
+    /** Empty string clears the previous upload name. */
+    sourceFileName?: string;
 }
 
 declare class KnowledgeBase {
@@ -1592,6 +1743,8 @@ interface Campaign {
     replyTo?: string | null;
     recipientType: 'audience' | 'tag';
     recipientId: string;
+    /** Present when the campaign targets more than one segment or list. */
+    recipientIds?: string[];
     topicId?: string | null;
     estimatedRecipients?: number | null;
     providerType: string;
@@ -1599,6 +1752,8 @@ interface Campaign {
     status: CampaignStatus;
     scheduledAt?: string | null;
     scheduledTimezone?: string | null;
+    /** True when the scheduled clock time is used in each contact's own time zone. */
+    localTimeDelivery?: boolean;
     batchId?: string | null;
     sentAt?: string | null;
     completedAt?: string | null;
@@ -1622,6 +1777,8 @@ interface CreateCampaignParams {
     replyTo?: string;
     recipientType: 'audience' | 'tag';
     recipientId: string;
+    /** Full list of segment or list IDs of the same type. When set, this is the selection; recipientId is stored as the first id. Unique people receive one email. Max 20. */
+    recipientIds?: string[];
     topicId?: string;
     providerType?: 'ses' | 'resend' | 'sendgrid' | 'mailgun' | 'migma';
     variables?: Record<string, unknown>;
@@ -1640,6 +1797,13 @@ interface ListCampaignsResponse {
 interface ScheduleCampaignParams {
     scheduledAt: string;
     scheduledTimezone?: string;
+    /**
+     * Send at the clock time of `scheduledAt` in `scheduledTimezone`, in each contact's own time zone (by country).
+     * Requires `scheduledTimezone`. Contacts without a country get it at `scheduledAt`; where that time has passed,
+     * the same time the next day. Not available with A/B tests or batch sending. Omit to keep the campaign's current
+     * setting; `false` turns it off.
+     */
+    localTimeDelivery?: boolean;
 }
 /**
  * Aggregated engagement metrics for a campaign.
@@ -1816,4 +1980,4 @@ declare class Migma {
     constructor(apiKey: string, config?: MigmaConfig);
 }
 
-export { type AddCustomDnsRecordParams, type AddImageParams, type AddKnowledgeBaseParams, type AnalyzeDeliverabilityParams, type AnalyzeLinksParams, type ApiResponse, type BatchDeleteContactsParams, type BatchDeleteResponse, type BatchStatus, type BrandGuidelinesParams, type BrandGuidelinesResponse, type BrandImageStyle, type BulkImportAsyncResponse, type BulkImportContactItem, type BulkImportJobStatus, type BulkImportParams, type BulkImportResponse, type BulkImportSyncResponse, type Campaign, type CampaignLog, type CampaignLogsParams, type CampaignLogsResponse, type CampaignStats, 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 CreateWebhookResponse, type CreditStatus, type CustomDnsRecord, type CustomDnsRecordList, type CustomDnsRecordType, type DeleteResponse, type DeliverabilityResponse, type DesignReferenceItem, type DeviceCategoriesResponse, type DnsRecord, type Domain, type DomainAvailability, type DomainDeleteResponse, type DomainPurchaseCheckout, type DomainPurchaseParams, type DomainPurchaseQuote, type DomainPurchaseSearchParams, type DomainRegistration, type DomainRegistrationStatus, type DomainStream, type DomainVerificationResult, type EditEmailParams, type Email, type EmailFavorite, type EmailGenerationResult, type EmailGenerationStatus, type EmailImage, type EmailLogsParams, type EmailLogsResponse, type EmailMetrics, type EmailMetricsCountry, type EmailMetricsSummary, type EmailMetricsTimePoint, type EmailSendLog, 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 ImportHtmlEmailFile, type ImportHtmlEmailParams, 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 ListWorkspacesResponse, 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 ProjectReferencesResponse, type ProviderType, type ProvisionStreamParams, type RecipientType, type ReferenceOrigin, type RetryImportResponse, type ScheduleCampaignParams, type Segment, type SegmentActivityFilter, type SegmentFieldFilter, type SegmentFilters, type SendEmailParams, type SendEmailResponse, type SendTestEmailParams, type SendTestEmailResponse, type SendingMetrics, type SendingMetricsCounts, type SendingMetricsHistoryEntry, type SendingMetricsParams, type SendingMetricsToday, type SetupDomainParams, type SetupDomainResponse, 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 UpgradeLink, type UpgradeLinkParams, type UpgradePlan, type ValidateAllParams, type ValidateAllResponse, type Webhook, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDetail, type WebhookEvent, type WebhookEventType, type WebhookEventsResponse, type WebhookTestResult, type Workspace, poll };
+export { type AddCustomDnsRecordParams, type AddImageParams, type AddKnowledgeBaseParams, type AnalyzeDeliverabilityParams, type AnalyzeLinksParams, type ApiResponse, type BatchDeleteContactsParams, type BatchDeleteResponse, type BatchStatus, type BrandGuidelinesParams, type BrandGuidelinesResponse, type BrandImageStyle, type BulkImportAsyncResponse, type BulkImportContactItem, type BulkImportJobStatus, type BulkImportParams, type BulkImportResponse, type BulkImportSyncResponse, type Campaign, type CampaignLog, type CampaignLogsParams, type CampaignLogsResponse, type CampaignStats, type CampaignStatus, type ChangeStatusParams, type CheckCompatibilityParams, type CheckSpellingParams, type CheckedLink, type ClientConfig, type CompatibilityResponse, type ConnectedToolSchema, type ConnectedToolScope, type ConnectedToolSummary, type Contact, type ContactExportStatus, type ContactImportProvider, type ContactStatus, type CreateCampaignParams, type CreateContactExportParams, type CreateContactParams, type CreateDomainParams, type CreateManagedDomainParams, type CreatePreviewParams, type CreatePreviewResponse, type CreateSegmentParams, type CreateTagParams, type CreateTopicParams, type CreateWebhookParams, type CreateWebhookResponse, type CreditStatus, type CustomDnsRecord, type CustomDnsRecordList, type CustomDnsRecordType, type DeleteResponse, type DeliverabilityResponse, type DesignReferenceItem, type DeviceCategoriesResponse, type DnsRecord, type Domain, type DomainAvailability, type DomainDeleteResponse, type DomainPurchaseCheckout, type DomainPurchaseParams, type DomainPurchaseQuote, type DomainPurchaseSearchParams, type DomainRegistration, type DomainRegistrationStatus, type DomainStream, type DomainVerificationResult, type EditEmailParams, type Email, type EmailEditOperation, type EmailFavorite, type EmailGenerationResult, type EmailGenerationStatus, type EmailImage, type EmailLogsParams, type EmailLogsResponse, type EmailMetrics, type EmailMetricsCountry, type EmailMetricsSummary, type EmailMetricsTimePoint, type EmailSendLog, 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 ImportFromProviderParams, type ImportHtmlEmailFile, type ImportHtmlEmailParams, type ImportProjectParams, type ImportProjectResponse, type ImportStatusResponse, type KnowledgeBaseEntry, type KnowledgeBaseListResponse, type LinkAnalysisResponse, type ListCampaignsParams, type ListCampaignsResponse, type ListConnectedToolsParams, type ListConnectedToolsResponse, type ListContactsParams, type ListContactsResponse, type ListEmailsEmail, type ListEmailsParams, type ListEmailsResponse, type ListProjectsParams, type ListProjectsResponse, type ListProviderImportSourcesParams, type ListSegmentsResponse, type ListTagsParams, type ListTagsResponse, type ListTopicsParams, type ListTopicsResponse, type ListWebhooksResponse, type ListWorkspacesResponse, 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 ProjectReferencesResponse, type ProviderImportSource, type ProviderImportStarted, type ProviderType, type ProvisionStreamParams, type RecipientType, type ReferenceOrigin, type RetryImportResponse, type ScheduleCampaignParams, type Segment, type SegmentActivityFilter, type SegmentFieldFilter, type SegmentFilters, type SendEmailParams, type SendEmailResponse, type SendTestEmailParams, type SendTestEmailResponse, type SendingMetrics, type SendingMetricsCounts, type SendingMetricsHistoryEntry, type SendingMetricsParams, type SendingMetricsToday, type SetupDomainParams, type SetupDomainResponse, 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 UpgradeLink, type UpgradeLinkParams, type UpgradePlan, type ValidateAllParams, type ValidateAllResponse, type Webhook, type WebhookDeliveriesResponse, type WebhookDelivery, type WebhookDetail, type WebhookEvent, type WebhookEventType, type WebhookEventsResponse, type WebhookTestResult, type Workspace, poll };

package/dist/index.js

@@ -1,5 +1,7 @@
 'use strict';
 
+var crypto = require('crypto');
+
 // src/agent-identity.ts
 var AGENT_ID_PATTERN = /^ai:[a-z0-9][a-z0-9._-]{0,62}$/;
 var HOST_AGENT_ENV = [
@@ -89,7 +91,7 @@ var MigmaClient = class {
   }
   async request(options) {
     const url = this.buildUrl(options.path, options.query);
-    const attempts = this.config.maxRetries + 1;
+    const attempts = (options.maxRetries ?? this.config.maxRetries) + 1;
     let lastError = null;
     for (let attempt = 0; attempt < attempts; attempt++) {
       try {
@@ -98,12 +100,9 @@ var MigmaClient = class {
           headers: { ...this.headers, ...options.headers },
           body: options.body ? JSON.stringify(options.body) : void 0
         });
-        const json = await response.json();
-        if (!response.ok || !json.success) {
-          const error = new MigmaError(
-            json.error || `Request failed with status ${response.status}`,
-            response.status
-          );
+        const json = await readJson(response);
+        if (!response.ok || !json?.success) {
+          const error = new MigmaError(failureMessage(response, json), response.status);
           if (response.status >= 500 || response.status === 429) {
             lastError = error;
             if (attempt < attempts - 1) {
@@ -141,14 +140,11 @@ var MigmaClient = class {
         headers: { ...this.headers, ...options.headers },
         body: options.body ? JSON.stringify(options.body) : void 0
       });
-      const json = await response.json();
-      if (!response.ok || !json.success) {
+      const json = await readJson(response);
+      if (!response.ok || !json?.success) {
         return {
           data: null,
-          error: new MigmaError(
-            json.error || `Request failed with status ${response.status}`,
-            response.status
-          )
+          error: new MigmaError(failureMessage(response, json), response.status)
         };
       }
       return {
@@ -173,16 +169,16 @@ var MigmaClient = class {
     return this.requestWithCount({ method: "GET", path, query });
   }
   async post(path, body, options) {
-    return this.request({ method: "POST", path, body, headers: this.callHeaders(options) });
+    return this.request({ method: "POST", path, body, headers: this.callHeaders(options), maxRetries: options?.maxRetries });
   }
   async patch(path, body, options) {
-    return this.request({ method: "PATCH", path, body, headers: this.callHeaders(options) });
+    return this.request({ method: "PATCH", path, body, headers: this.callHeaders(options), maxRetries: options?.maxRetries });
   }
   async put(path, body) {
     return this.request({ method: "PUT", path, body });
   }
   async delete(path, query, options) {
-    return this.request({ method: "DELETE", path, query, headers: this.callHeaders(options) });
+    return this.request({ method: "DELETE", path, query, headers: this.callHeaders(options), maxRetries: options?.maxRetries });
   }
   callHeaders(options) {
     if (options?.idempotencyKey) {
@@ -213,6 +209,18 @@ var MigmaClient = class {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 };
+async function readJson(response) {
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function failureMessage(response, json) {
+  if (json?.error) return json.error;
+  return json ? `Request failed with status ${response.status}` : `Request failed with status ${response.status}: the server did not return JSON`;
+}
 
 // src/resources/contacts.ts
 var Contacts = class {
@@ -252,6 +260,22 @@ var Contacts = class {
   async bulkDeleteByEmail(params, options) {
     return this.client.post("/contacts/bulk-delete", params, options);
   }
+  /** Queue a filtered CSV export. Poll getExport; do not list every contact to build a CSV. */
+  async createExport(params, options) {
+    return this.client.post("/contacts/exports", params, { ...options, maxRetries: options?.idempotencyKey ? options.maxRetries : 0 });
+  }
+  async getExport(jobId, projectId) {
+    return this.client.get(`/contacts/exports/${encodeURIComponent(jobId)}`, { projectId });
+  }
+  /** Lists and segments in the brand's connected Klaviyo, Mailchimp or HubSpot account. A 409 error message includes the link to connect it. */
+  async listProviderImportSources(params) {
+    const { provider, projectId, connectionId } = params;
+    return this.client.get(`/contacts/imports/providers/${encodeURIComponent(provider)}/sources`, { projectId, connectionId });
+  }
+  /** Import provider sources as contacts (subscribed only by default). Poll GET /contacts/imports/{id} for counts. */
+  async importFromProvider(params, options) {
+    return this.client.post("/contacts/imports/provider", params, { ...options, maxRetries: options?.idempotencyKey ? options.maxRetries : 0 });
+  }
   async changeStatus(params, options) {
     return this.client.post("/contacts/status", params, options);
   }
@@ -454,6 +478,16 @@ var Projects = class {
       }
     );
   }
+  async listConnectedTools(params) {
+    return this.client.get("/connected-tools", { ...params });
+  }
+  async getConnectedTool(params) {
+    return this.client.get("/connected-tools/schema", { ...params });
+  }
+  /** Never automatically replay external writes; provider outcome can be unknown. */
+  async callConnectedTool(params) {
+    return this.client.post("/connected-tools/call", { ...params }, { maxRetries: 0 });
+  }
   /**
    * Import a project and wait for completion.
    * Polls getImportStatus until status is 'active' or 'error'.
@@ -471,8 +505,6 @@ var Projects = class {
     );
   }
 };
-
-// src/resources/emails.ts
 var Emails = class {
   constructor(client) {
     this.client = client;
@@ -514,11 +546,26 @@ var Emails = class {
   async get(emailId) {
     return this.client.get(`/emails/${emailId}`);
   }
-  /** Prompt Migma to edit one generated email */
+  /** Synchronous edit. No automatic retries; use startEdit for long edits. */
   async edit(emailId, params) {
     return this.client.post(
       `/emails/${emailId}/edit`,
-      params
+      params,
+      { maxRetries: 0 }
+    );
+  }
+  /** Queue an edit immediately. Retain an explicit key to recover uncertain submissions. */
+  async startEdit(emailId, params, options) {
+    return this.client.post(
+      `/emails/${encodeURIComponent(emailId)}/edit`,
+      { ...params, async: true },
+      { ...options, idempotencyKey: options?.idempotencyKey || crypto.randomUUID() }
+    );
+  }
+  /** Poll the exact edit; a completed conversation may belong to an earlier turn. */
+  async getEditStatus(emailId, editId) {
+    return this.client.get(
+      `/emails/${encodeURIComponent(emailId)}/edits/${encodeURIComponent(editId)}`
     );
   }
   /**
@@ -821,8 +868,10 @@ var Billing = class {
     return this.client.get("/billing/credits");
   }
   /**
-   * Mint a Stripe link the account owner opens in a browser to upgrade or
-   * manage the subscription. Nothing is charged by this call itself.
+   * Create checkout for a user-chosen new plan, or omit plan for the existing
+   * customer's billing portal. Passing plan for an active subscription can
+   * change it and charge prorated payment immediately; obtain charge approval.
+   * The returned URL alone does not confirm payment. Do not retry unknown writes.
    */
   async upgradeLink(params = {}) {
     return this.client.post("/billing/upgrade-link", params);