migma 1.11.1 → 1.13.0

package/README.md

@@ -116,6 +116,7 @@ const migma = new Migma('mgma_sk_live_...', {
   baseUrl: 'https://api.migma.ai/v1', // default
   maxRetries: 2,                           // retries on 5xx/429
   retryDelay: 1000,                        // base delay between retries
+  agentId: 'ai:claude-code',               // the AI agent behind these calls (default: MIGMA_AGENT_ID, then detected)
 });
 ```
 
@@ -228,10 +229,10 @@ const { data: deletion } = await migma.contacts.bulkDeleteByEmail({
 });
 
 // Import contacts from a CSV file (multipart upload, processed in the background).
-// `file` accepts a Blob/File, a Buffer, or a ReadableStream.
+// `file` accepts a Buffer, Uint8Array, Blob or File. Requires 1.13.0 or later.
 import { readFileSync } from 'node:fs';
 
-const { data: job } = await migma.contacts.imports.create({
+const { data: job } = await migma.contacts.createImport({
   file: readFileSync('./contacts.csv'),
   projectId: 'proj_abc123',
   columnMap: {
@@ -243,10 +244,10 @@ const { data: job } = await migma.contacts.imports.create({
   tags: ['newsletter'],
 });
 
-// Poll for status + counts until the import finishes.
-const { data: status } = await migma.contacts.imports.get(job!.id);
+// Check status and counts. Repeat until the status is completed or failed.
+const { data: status } = await migma.contacts.getImport(job!.id);
 // status.status → 'pending' | 'processing' | 'completed' | 'failed'
-// status.counts → { total, created, updated, skipped, failed }
+// status.counts → { total, created, updated, skipped, failed, non_sendable }
 
 // Safe retries: pass an Idempotency-Key so a retried write never duplicates.
 // Same key + same body within 24h replays the original response.
@@ -698,8 +699,7 @@ await migma.images.updateLogos('proj_abc123', {
 
 | Resource | Methods | Docs |
 |----------|---------|------|
-| `migma.contacts` | `create` `list` `get` `update` `remove` `bulkImport` `getBulkImportStatus` `changeStatus` | [Contacts](https://docs.migma.ai/api-reference/contacts/get-contact) |
-| `migma.contacts.imports` | `create` `get` | [Contact imports](https://docs.migma.ai/api-reference/contacts/get-contact) |
+| `migma.contacts` | `create` `list` `get` `update` `remove` `bulkImport` `getBulkImportStatus` `createImport` `getImport` `changeStatus` | [Contacts](https://docs.migma.ai/api-reference/contacts/get-contact) |
 | `migma.tags` | `create` `list` `get` `update` `remove` | [Tags](https://docs.migma.ai/api-reference/tags/list-tags) |
 | `migma.segments` | `create` `list` `get` `update` `remove` | [Segments](https://docs.migma.ai/api-reference/audiences/list-audiences) |
 | `migma.topics` | `create` `list` `get` `update` `remove` `subscribe` `unsubscribe` | [Topics](https://docs.migma.ai/api-reference/topics/list-topics) |

package/dist/index.d.mts

@@ -53,12 +53,13 @@ interface ClientConfig {
     baseUrl: string;
     maxRetries: number;
     retryDelay: number;
+    agentId?: string;
 }
 type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
 interface RequestOptions {
     method: HttpMethod;
     path: string;
-    body?: Record<string, unknown>;
+    body?: Record<string, unknown> | FormData;
     query?: Record<string, string | number | boolean | undefined>;
     headers?: Record<string, string>;
     maxRetries?: number;
@@ -94,9 +95,12 @@ declare class MigmaClient {
         count: number;
     }>>;
     post<T>(path: string, body?: Record<string, unknown>, options?: CallOptions): Promise<MigmaResult<T>>;
+    postForm<T>(path: string, body: FormData, options?: CallOptions): Promise<MigmaResult<T>>;
     patch<T>(path: string, body?: Record<string, unknown>, options?: CallOptions): Promise<MigmaResult<T>>;
     put<T>(path: string, body?: Record<string, unknown>): Promise<MigmaResult<T>>;
     delete<T>(path: string, query?: Record<string, string | number | boolean | undefined>, options?: CallOptions): Promise<MigmaResult<T>>;
+    /** JSON by default. A form body drops the JSON header so fetch sets the multipart one with its boundary. */
+    private encode;
     private callHeaders;
     private buildUrl;
     private parseRetryAfter;
@@ -296,7 +300,59 @@ interface ContactExportStatus {
     downloadExpiresAt?: string;
     error?: string;
 }
+/** Maps contact fields to CSV header names. Only email is required. */
+interface ContactImportColumnMap {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    name?: string;
+    phone?: string;
+    country?: string;
+    language?: string;
+    /** Custom field key to CSV header name. */
+    customFields?: Record<string, string>;
+}
+interface CreateContactImportParams {
+    /** CSV contents, up to 200MB: a Buffer, Uint8Array, Blob or File. */
+    file: Blob | Uint8Array;
+    /** Name shown for the import. Defaults to the File's name, then contacts.csv. */
+    fileName?: string;
+    projectId: string;
+    columnMap: ContactImportColumnMap;
+    /** Rows whose email already exists: upsert updates them (default), skip leaves them untouched. */
+    onConflict?: 'upsert' | 'skip';
+    /** CSV field delimiter. Default comma. */
+    delimiter?: string;
+    /** Tag names or existing tag IDs for every imported contact. Unknown names create tags. */
+    tags?: string[];
+}
+interface ContactImportStarted {
+    object: 'contact_import';
+    id: string;
+    status: 'processing';
+}
 type ContactImportProvider = 'klaviyo' | 'mailchimp' | 'hubspot';
+/** A CSV or provider import. Provider, tag and segment fields are null for CSV imports. */
+interface ContactImportStatus {
+    object: 'contact_import';
+    id: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    provider: ContactImportProvider | null;
+    tag_id: string | null;
+    segment_id: string | null;
+    counts: {
+        total: number;
+        created: number;
+        updated: number;
+        skipped: number;
+        failed: number;
+        /** Imported contacts who are not subscribed and cannot receive campaigns. */
+        non_sendable: number;
+    };
+    error: string | null;
+    created_at: string;
+    completed_at: string | null;
+}
 /** A list or segment in the connected provider account that can be imported. */
 interface ProviderImportSource {
     id: string;
@@ -319,7 +375,7 @@ interface ImportFromProviderParams {
     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. */
+/** Each import becomes a tag and a segment named after its sources. Poll getImport with its id. */
 interface ProviderImportStarted {
     object: 'contact_import';
     id: string;
@@ -349,11 +405,18 @@ declare class Contacts {
     /** 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>>;
+    /**
+     * Upload a CSV to import in the background. Poll getImport for status and counts.
+     * Never retried automatically: the endpoint has no idempotency key, so a repeat creates a second import.
+     */
+    createImport(params: CreateContactImportParams): Promise<MigmaResult<ContactImportStarted>>;
+    /** Status and counts of a CSV or provider import. */
+    getImport(id: string): Promise<MigmaResult<ContactImportStatus>>;
     /** 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. */
+    /** Import provider sources as contacts (subscribed only by default). Poll getImport for counts. */
     importFromProvider(params: ImportFromProviderParams, options?: CallOptions): Promise<MigmaResult<ProviderImportStarted>>;
     changeStatus(params: ChangeStatusParams, options?: CallOptions): Promise<MigmaResult<{
         success: boolean;
@@ -1969,6 +2032,12 @@ interface MigmaConfig {
     maxRetries?: number;
     /** Base delay between retries in ms. Default: 1000 */
     retryDelay?: number;
+    /**
+     * Names the AI agent behind these calls, sent as `X-Agent-Id`: `ai:<slug>`,
+     * such as `ai:claude-code`. For one process serving several agents. Default:
+     * `MIGMA_AGENT_ID`, then the detected host.
+     */
+    agentId?: string;
 }
 declare class Migma {
     private readonly client;
@@ -1994,4 +2063,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 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 LocalTimePassed, 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 };
+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 ContactImportColumnMap, type ContactImportProvider, type ContactImportStarted, type ContactImportStatus, type ContactStatus, type CreateCampaignParams, type CreateContactExportParams, type CreateContactImportParams, 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 LocalTimePassed, 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.d.ts

@@ -53,12 +53,13 @@ interface ClientConfig {
     baseUrl: string;
     maxRetries: number;
     retryDelay: number;
+    agentId?: string;
 }
 type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
 interface RequestOptions {
     method: HttpMethod;
     path: string;
-    body?: Record<string, unknown>;
+    body?: Record<string, unknown> | FormData;
     query?: Record<string, string | number | boolean | undefined>;
     headers?: Record<string, string>;
     maxRetries?: number;
@@ -94,9 +95,12 @@ declare class MigmaClient {
         count: number;
     }>>;
     post<T>(path: string, body?: Record<string, unknown>, options?: CallOptions): Promise<MigmaResult<T>>;
+    postForm<T>(path: string, body: FormData, options?: CallOptions): Promise<MigmaResult<T>>;
     patch<T>(path: string, body?: Record<string, unknown>, options?: CallOptions): Promise<MigmaResult<T>>;
     put<T>(path: string, body?: Record<string, unknown>): Promise<MigmaResult<T>>;
     delete<T>(path: string, query?: Record<string, string | number | boolean | undefined>, options?: CallOptions): Promise<MigmaResult<T>>;
+    /** JSON by default. A form body drops the JSON header so fetch sets the multipart one with its boundary. */
+    private encode;
     private callHeaders;
     private buildUrl;
     private parseRetryAfter;
@@ -296,7 +300,59 @@ interface ContactExportStatus {
     downloadExpiresAt?: string;
     error?: string;
 }
+/** Maps contact fields to CSV header names. Only email is required. */
+interface ContactImportColumnMap {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    name?: string;
+    phone?: string;
+    country?: string;
+    language?: string;
+    /** Custom field key to CSV header name. */
+    customFields?: Record<string, string>;
+}
+interface CreateContactImportParams {
+    /** CSV contents, up to 200MB: a Buffer, Uint8Array, Blob or File. */
+    file: Blob | Uint8Array;
+    /** Name shown for the import. Defaults to the File's name, then contacts.csv. */
+    fileName?: string;
+    projectId: string;
+    columnMap: ContactImportColumnMap;
+    /** Rows whose email already exists: upsert updates them (default), skip leaves them untouched. */
+    onConflict?: 'upsert' | 'skip';
+    /** CSV field delimiter. Default comma. */
+    delimiter?: string;
+    /** Tag names or existing tag IDs for every imported contact. Unknown names create tags. */
+    tags?: string[];
+}
+interface ContactImportStarted {
+    object: 'contact_import';
+    id: string;
+    status: 'processing';
+}
 type ContactImportProvider = 'klaviyo' | 'mailchimp' | 'hubspot';
+/** A CSV or provider import. Provider, tag and segment fields are null for CSV imports. */
+interface ContactImportStatus {
+    object: 'contact_import';
+    id: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    provider: ContactImportProvider | null;
+    tag_id: string | null;
+    segment_id: string | null;
+    counts: {
+        total: number;
+        created: number;
+        updated: number;
+        skipped: number;
+        failed: number;
+        /** Imported contacts who are not subscribed and cannot receive campaigns. */
+        non_sendable: number;
+    };
+    error: string | null;
+    created_at: string;
+    completed_at: string | null;
+}
 /** A list or segment in the connected provider account that can be imported. */
 interface ProviderImportSource {
     id: string;
@@ -319,7 +375,7 @@ interface ImportFromProviderParams {
     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. */
+/** Each import becomes a tag and a segment named after its sources. Poll getImport with its id. */
 interface ProviderImportStarted {
     object: 'contact_import';
     id: string;
@@ -349,11 +405,18 @@ declare class Contacts {
     /** 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>>;
+    /**
+     * Upload a CSV to import in the background. Poll getImport for status and counts.
+     * Never retried automatically: the endpoint has no idempotency key, so a repeat creates a second import.
+     */
+    createImport(params: CreateContactImportParams): Promise<MigmaResult<ContactImportStarted>>;
+    /** Status and counts of a CSV or provider import. */
+    getImport(id: string): Promise<MigmaResult<ContactImportStatus>>;
     /** 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. */
+    /** Import provider sources as contacts (subscribed only by default). Poll getImport for counts. */
     importFromProvider(params: ImportFromProviderParams, options?: CallOptions): Promise<MigmaResult<ProviderImportStarted>>;
     changeStatus(params: ChangeStatusParams, options?: CallOptions): Promise<MigmaResult<{
         success: boolean;
@@ -1969,6 +2032,12 @@ interface MigmaConfig {
     maxRetries?: number;
     /** Base delay between retries in ms. Default: 1000 */
     retryDelay?: number;
+    /**
+     * Names the AI agent behind these calls, sent as `X-Agent-Id`: `ai:<slug>`,
+     * such as `ai:claude-code`. For one process serving several agents. Default:
+     * `MIGMA_AGENT_ID`, then the detected host.
+     */
+    agentId?: string;
 }
 declare class Migma {
     private readonly client;
@@ -1994,4 +2063,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 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 LocalTimePassed, 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 };
+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 ContactImportColumnMap, type ContactImportProvider, type ContactImportStarted, type ContactImportStatus, type ContactStatus, type CreateCampaignParams, type CreateContactExportParams, type CreateContactImportParams, 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 LocalTimePassed, 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

@@ -9,10 +9,16 @@ var HOST_AGENT_ENV = [
   { env: "CURSOR_TRACE_ID", id: "ai:cursor" },
   { env: "CODEX_HOME", id: "ai:codex" }
 ];
-function detectAgentId() {
+function validAgentId(value) {
+  const id = (value || "").trim().toLowerCase();
+  return AGENT_ID_PATTERN.test(id) ? id : null;
+}
+function detectAgentId(configured) {
+  const configuredId = validAgentId(configured);
+  if (configuredId) return configuredId;
   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;
+  const explicit = validAgentId(process.env.MIGMA_AGENT_ID);
+  if (explicit) return explicit;
   for (const { env, id } of HOST_AGENT_ENV) {
     if (process.env[env]) return id;
   }
@@ -84,7 +90,7 @@ var MigmaClient = class {
       "Content-Type": "application/json",
       "User-Agent": "migma-node/1.0.0"
     };
-    const agentId = detectAgentId();
+    const agentId = detectAgentId(config.agentId);
     if (agentId) {
       this.headers["X-Agent-Id"] = agentId;
     }
@@ -97,8 +103,7 @@ var MigmaClient = class {
       try {
         const response = await fetch(url, {
           method: options.method,
-          headers: { ...this.headers, ...options.headers },
-          body: options.body ? JSON.stringify(options.body) : void 0
+          ...this.encode(options)
         });
         const json = await readJson(response);
         if (!response.ok || !json?.success) {
@@ -171,6 +176,9 @@ var MigmaClient = class {
   async post(path, body, options) {
     return this.request({ method: "POST", path, body, headers: this.callHeaders(options), maxRetries: options?.maxRetries });
   }
+  async postForm(path, body, 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), maxRetries: options?.maxRetries });
   }
@@ -180,6 +188,15 @@ var MigmaClient = class {
   async delete(path, query, options) {
     return this.request({ method: "DELETE", path, query, headers: this.callHeaders(options), maxRetries: options?.maxRetries });
   }
+  /** JSON by default. A form body drops the JSON header so fetch sets the multipart one with its boundary. */
+  encode(options) {
+    const headers = { ...this.headers, ...options.headers };
+    if (options.body instanceof FormData) {
+      delete headers["Content-Type"];
+      return { headers, body: options.body };
+    }
+    return { headers, body: options.body ? JSON.stringify(options.body) : void 0 };
+  }
   callHeaders(options) {
     if (options?.idempotencyKey) {
       return { "Idempotency-Key": options.idempotencyKey };
@@ -267,12 +284,35 @@ var Contacts = class {
   async getExport(jobId, projectId) {
     return this.client.get(`/contacts/exports/${encodeURIComponent(jobId)}`, { projectId });
   }
+  /**
+   * Upload a CSV to import in the background. Poll getImport for status and counts.
+   * Never retried automatically: the endpoint has no idempotency key, so a repeat creates a second import.
+   */
+  async createImport(params) {
+    const { file, fileName, projectId, columnMap, onConflict, delimiter, tags } = params;
+    const form = new FormData();
+    form.append(
+      "file",
+      file instanceof Blob ? file : new Blob([file], { type: "text/csv" }),
+      fileName ?? file.name ?? "contacts.csv"
+    );
+    form.append("projectId", projectId);
+    form.append("columnMap", JSON.stringify(columnMap));
+    if (onConflict) form.append("onConflict", onConflict);
+    if (delimiter) form.append("delimiter", delimiter);
+    if (tags?.length) form.append("tags", JSON.stringify(tags));
+    return this.client.postForm("/contacts/imports", form, { maxRetries: 0 });
+  }
+  /** Status and counts of a CSV or provider import. */
+  async getImport(id) {
+    return this.client.get(`/contacts/imports/${encodeURIComponent(id)}`);
+  }
   /** 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. */
+  /** Import provider sources as contacts (subscribed only by default). Poll getImport for counts. */
   async importFromProvider(params, options) {
     return this.client.post("/contacts/imports/provider", params, { ...options, maxRetries: options?.idempotencyKey ? options.maxRetries : 0 });
   }
@@ -1085,7 +1125,8 @@ var Migma = class {
     this.client = new MigmaClient(apiKey, {
       baseUrl: config?.baseUrl ?? "https://api.migma.ai/v1",
       maxRetries: config?.maxRetries ?? 2,
-      retryDelay: config?.retryDelay ?? 1e3
+      retryDelay: config?.retryDelay ?? 1e3,
+      agentId: config?.agentId
     });
     this.contacts = new Contacts(this.client);
     this.tags = new Tags(this.client);