@heymantle/core-api-client 0.1.4 → 0.1.6

package/dist/index.d.mts

@@ -758,39 +758,70 @@ interface Deal {
     currentAmount?: number;
     acquisitionChannel?: string;
     acquisitionSource?: string;
-    firstInteractionAt?: string;
-    closingAt?: string;
-    closedAt?: string;
-    stage?: string;
-    step?: number;
-    dealFlowId?: string;
-    dealStageId?: string;
-    customerId?: string;
-    domain?: string;
-    shopifyDomain?: string;
-    companyId?: string;
-    appId?: string;
-    planId?: string;
-    ownerIds?: string[];
-    contactIds?: string[];
     notes?: string;
-    affiliateId?: string;
-    partnershipId?: string;
-    archived?: boolean;
+    firstInteractionAt?: string | null;
+    closingAt?: string | null;
+    closedAt?: string | null;
+    archivedAt?: string | null;
     createdAt: string;
     updatedAt: string;
+    dealStage?: {
+        id: string;
+        name: string;
+        stage?: string;
+        weight?: number;
+    } | null;
+    dealFlow?: {
+        id: string;
+        name: string;
+    } | null;
     customer?: {
         id: string;
         name?: string;
-    };
-    dealFlow?: {
+        email?: string;
+        domain?: string;
+        shopifyDomain?: string;
+    } | null;
+    app?: {
         id: string;
         name: string;
-    };
-    dealStage?: {
+    } | null;
+    plan?: {
         id: string;
         name: string;
-    };
+    } | null;
+    affiliate?: {
+        id: string;
+        name?: string;
+    } | null;
+    partnership?: {
+        id: string;
+        name?: string;
+        displayName?: string;
+    } | null;
+    acquirer?: {
+        id: string;
+        name?: string;
+        email?: string;
+    } | null;
+    owners?: Array<{
+        id: string;
+        userId: string;
+        user?: {
+            id: string;
+            name?: string;
+            email?: string;
+        } | null;
+    }>;
+    contacts?: Array<{
+        id: string;
+        contactId: string;
+        contact?: {
+            id: string;
+            name?: string;
+            email?: string;
+        } | null;
+    }>;
 }
 /**
  * Parameters for listing deals
@@ -822,34 +853,147 @@ interface DealListParams extends ListParams {
 interface DealListResponse extends PaginatedResponse {
     deals: Deal[];
 }
+/**
+ * Inline customer data for deal creation/update.
+ * Matches existing customers by domain or shopifyDomain.
+ * If no match found, creates a new customer.
+ */
+interface DealCustomerInput {
+    /** The name of the customer */
+    name?: string;
+    /** The email of the customer */
+    email?: string;
+    /** The domain of the customer (used for matching existing customers) */
+    domain?: string;
+    /** The Shopify domain of the customer (used for matching existing customers) */
+    shopifyDomain?: string;
+    /** The Shopify shop ID */
+    shopifyShopId?: string;
+    /** Tags to associate with the customer */
+    tags?: string[];
+    /** Custom fields for the customer */
+    customFields?: Record<string, unknown>;
+    /** The country code of the customer */
+    countryCode?: string;
+    /** The preferred currency of the customer */
+    preferredCurrency?: string;
+    /** Description of the customer */
+    description?: string;
+}
+/**
+ * Inline contact data for deal creation/update.
+ * Matches existing contacts by email.
+ * Contacts are linked to both the customer and the deal.
+ */
+interface DealContactInput {
+    /** The email of the contact (required, used for matching existing contacts) */
+    email: string;
+    /** The name of the contact */
+    name?: string;
+    /** The phone number of the contact */
+    phone?: string;
+    /** The job title of the contact */
+    jobTitle?: string;
+    /** The label for the contact relationship (e.g., "primary", "technical") */
+    label?: string;
+    /** Notes about the contact */
+    notes?: string;
+    /** Tags for the contact */
+    tags?: string[];
+}
 /**
  * Parameters for creating a deal
+ *
+ * **Customer Linking Options** (use only one approach):
+ * - `customerId` - Link to an existing customer by ID
+ * - `customer` - Create/update a customer inline (matches by domain or shopifyDomain)
+ * - `domain`/`shopifyDomain` alone - Find or create a customer by domain
+ *
+ * Note: `domain` and `shopifyDomain` can be provided alongside `customerId` or `customer`
+ * to update the customer's domain fields if they are not already set.
+ *
+ * **Contact Linking Options** (use only one approach):
+ * - `contactIds` - Link to existing contacts by their IDs
+ * - `contacts` - Create/update contacts inline (matches by email)
  */
 interface DealCreateParams {
+    /** The name of the deal */
     name: string;
+    /** The monetary value of the deal */
     amount?: number;
+    /** The currency code for the deal amount (e.g., 'USD', 'EUR') */
     amountCurrencyCode?: string;
+    /** The channel through which the deal was acquired */
     acquisitionChannel?: string;
+    /** The specific source of the deal acquisition */
     acquisitionSource?: string;
+    /** The timestamp of the first interaction with the prospect */
     firstInteractionAt?: string;
+    /** The expected closing date for the deal */
     closingAt?: string;
+    /** The actual closing date for the deal */
     closedAt?: string;
+    /** The ID of the deal flow */
     dealFlowId?: string;
+    /** The ID of the deal stage within the flow */
     dealStageId?: string;
+    /**
+     * Link to an existing customer by ID.
+     * Cannot be used together with `customer` object.
+     */
     customerId?: string;
+    /**
+     * Create or update a customer inline.
+     * Matches existing customers by `domain` or `shopifyDomain`.
+     * Cannot be used together with `customerId`.
+     */
+    customer?: DealCustomerInput;
+    /**
+     * The domain of the customer (e.g., 'acme.com').
+     * URLs are automatically normalized (protocol and path stripped).
+     * Used to find/create a customer if no `customerId` or `customer` provided,
+     * or to update the customer's domain if not already set.
+     */
     domain?: string;
+    /**
+     * The Shopify domain of the customer (e.g., 'acme.myshopify.com').
+     * URLs are automatically normalized (protocol and path stripped).
+     * Used to find/create a customer if no `customerId` or `customer` provided,
+     * or to update the customer's shopifyDomain if not already set.
+     */
     shopifyDomain?: string;
+    /** The ID of the company to associate with the deal */
     companyId?: string;
+    /** The ID of the app to associate with the deal */
     appId?: string;
+    /** The ID of the plan to associate with the deal */
     planId?: string;
+    /** Array of user IDs to assign as deal owners */
     ownerIds?: string[];
+    /**
+     * Link to existing contacts by their IDs.
+     * Cannot be used together with `contacts` array.
+     */
     contactIds?: string[];
+    /**
+     * Create or update contacts inline.
+     * Matches existing contacts by email.
+     * Contacts are automatically linked to both the customer and the deal.
+     * Cannot be used together with `contactIds`.
+     */
+    contacts?: DealContactInput[];
+    /** Additional notes about the deal */
     notes?: string;
+    /** The ID of the affiliate to associate with the deal */
     affiliateId?: string;
+    /** The ID of the partnership to associate with the deal */
     partnershipId?: string;
 }
 /**
  * Parameters for updating a deal
+ *
+ * All fields are optional. See {@link DealCreateParams} for detailed documentation
+ * on customer and contact linking options.
  */
 interface DealUpdateParams extends Partial<DealCreateParams> {
 }
@@ -2200,12 +2344,76 @@ declare class DealsResource extends BaseResource {
     }>;
     /**
      * Create a new deal
+     *
+     * **Linking a Customer:**
+     * There are three ways to associate a customer with a deal (use only one):
+     *
+     * 1. `customerId` - Link to an existing customer by ID
+     * 2. `customer` - Create or update a customer inline. Matches existing customers
+     *    by `domain` or `shopifyDomain`. If no match, creates a new customer.
+     * 3. `domain` and/or `shopifyDomain` - Find an existing customer by domain,
+     *    or create a minimal customer record if not found.
+     *
+     * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
+     * they will be used to update the customer's domain fields only if not already set.
+     *
+     * **Linking Contacts:**
+     * There are two ways to associate contacts with a deal (use only one):
+     *
+     * 1. `contactIds` - Link to existing contacts by their IDs
+     * 2. `contacts` - Create or update contacts inline. Matches existing contacts
+     *    by email. Contacts are automatically linked to both the customer and the deal.
+     *
+     * @example
+     * // Using an existing customer
+     * await client.deals.create({ name: 'Deal', customerId: 'cust_123', dealFlowId: '...', dealStageId: '...' });
+     *
+     * // Creating a customer inline
+     * await client.deals.create({
+     *   name: 'Deal',
+     *   customer: { name: 'Acme Corp', domain: 'acme.com', email: 'info@acme.com' },
+     *   contacts: [{ email: 'john@acme.com', name: 'John Doe', jobTitle: 'CEO' }],
+     *   dealFlowId: '...',
+     *   dealStageId: '...',
+     * });
+     *
+     * // Using domain to find/create customer
+     * await client.deals.create({ name: 'Deal', shopifyDomain: 'acme.myshopify.com', dealFlowId: '...', dealStageId: '...' });
      */
     create(data: DealCreateParams): Promise<{
         deal: Deal;
     }>;
     /**
      * Update an existing deal
+     *
+     * **Updating Customer Association:**
+     * There are three ways to change or update the customer (use only one):
+     *
+     * 1. `customerId` - Change to a different existing customer
+     * 2. `customer` - Update the linked customer inline, or create/link a new one.
+     *    Matches existing customers by `domain` or `shopifyDomain`.
+     * 3. `domain` and/or `shopifyDomain` - Find a different customer by domain,
+     *    or create a minimal customer record if not found.
+     *
+     * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
+     * they will be used to update the customer's domain fields only if not already set.
+     *
+     * **Updating Contacts:**
+     * There are two ways to update contacts (use only one):
+     *
+     * 1. `contactIds` - Replace deal contacts with the specified contact IDs
+     * 2. `contacts` - Create or update contacts inline. Matches existing contacts
+     *    by email. Contacts are automatically linked to both the customer and the deal.
+     *
+     * @example
+     * // Update customer's domain if not set
+     * await client.deals.update('deal_123', { customerId: 'cust_456', domain: 'newdomain.com' });
+     *
+     * // Update customer and contacts inline
+     * await client.deals.update('deal_123', {
+     *   customer: { name: 'Updated Name', domain: 'acme.com' },
+     *   contacts: [{ email: 'new@acme.com', name: 'New Contact' }],
+     * });
      */
     update(dealId: string, data: DealUpdateParams): Promise<{
         deal: Deal;
@@ -3176,4 +3384,4 @@ interface AuthRefreshOptions {
  */
 declare function createAuthRefreshMiddleware(options: AuthRefreshOptions): Middleware;
 
-export { type AccountOwner, type AccountOwnersListResponse, type Affiliate, type AffiliateCommission, type AffiliateCommissionListParams, type AffiliateCommissionListResponse, AffiliateCommissionsResource, type AffiliateListParams, type AffiliateListResponse, type AffiliatePayout, type AffiliatePayoutListParams, type AffiliatePayoutListResponse, AffiliatePayoutsResource, type AffiliateProgram, type AffiliateProgramCreateParams, type AffiliateProgramUpdateParams, AffiliateProgramsResource, type AffiliateReferral, type AffiliateReferralListParams, type AffiliateReferralListResponse, AffiliateReferralsResource, type AffiliateUpdateParams, AffiliatesResource, type Agent, type AgentListResponse, AgentsResource, type App, type AppEvent, type AppEventListParams, type AppEventListResponse, type AppInstallation, type AppInstallationParams, type AppListParams, AppsResource, type AuthRefreshOptions, BaseResource, type Channel, type ChannelCreateParams, type ChannelListParams, ChannelsResource, type Charge, type ChargeListParams, type ChargeListResponse, ChargesResource, CompaniesResource, type Company, type CompanyCreateParams, type CompanyListParams, type CompanyListResponse, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactEntity, type ContactListParams, type ContactListResponse, type ContactUpdateParams, ContactsResource, type CustomField, type CustomFieldCreateParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerEntity, type CustomerListParams, type CustomerListResponse, type CustomerRetrieveParams, type CustomerSegment, type CustomerSegmentListParams, type CustomerSegmentListResponse, CustomerSegmentsResource, type CustomerUpdateParams, CustomersResource, type DateRangeType, type Deal, DealActivitiesResource, type DealActivity, type DealActivityCreateParams, type DealActivityUpdateParams, type DealCreateParams, type DealFlow, type DealFlowCreateParams, type DealFlowUpdateParams, DealFlowsResource, type DealListParams, type DealListResponse, type DealStage, type DealUpdateParams, DealsResource, type DeleteResponse, type DocCollection, type DocCollectionCreateParams, type DocCollectionUpdateParams, type DocGroup, type DocGroupCreateParams, type DocGroupUpdateParams, type DocPage, type DocPageCreateParams, type DocPageListParams, type DocPageListResponse, type DocPageStatus, type DocPageUpdateParams, type DocTreeNode, type DocTreeResponse, DocsResource, EntitiesResource, type EntitiesSearchParams, type EntitiesSearchResponse, type Entity, type EntityType, type Feature, type FeatureCreateParams, type FeatureUpdateParams, type Flow, type FlowCreateParams, type FlowListParams, type FlowListResponse, type FlowStatus, type FlowUpdateParams, FlowsResource, type HttpMethod, type ListParams, MantleAPIError, MantleAuthenticationError, MantleCoreClient, type MantleCoreClientConfig, MantleNotFoundError, MantlePermissionError, MantleRateLimitError, MantleValidationError, MeResource, type MeResponse, type MessageAttachment, type MetricDataPoint, type MetricType, type MetricsBaseParams, type MetricsGetParams, MetricsResource, type MetricsResponse, type Middleware, type MiddlewareContext, MiddlewareManager, type MiddlewareOptions, type MiddlewareRequest, type MiddlewareResponse, type NextFunction, type Organization, OrganizationResource, type PaginatedResponse, type Plan, type PlanCreateParams, type PlanFeature, type PlanListParams, type PlanListResponse, type PlanUpdateParams, type PlanUsageCharge, type RequestOptions, type Review, type ReviewCreateParams, type ReviewUpdateParams, type SocialProfile, type SocialProfileType, type Subscription, type SubscriptionListParams, type SubscriptionListResponse, SubscriptionsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskListResponse, type TaskPriority, type TaskStatus, type TaskUpdateParams, TasksResource, type Ticket, type TicketContactData, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TicketMessage, type TicketMessageCreateParams, type TicketMessageUpdateParams, type TicketUpdateParams, TicketsResource, type TimelineEvent, type TimelineListParams, type TimelineListResponse, type Transaction, type TransactionListParams, type TransactionListResponse, TransactionsResource, type UsageEvent, type UsageEventCreateData, type UsageEventCreateParams, type UsageEventCreateResponse, type UsageEventListParams, type UsageEventListResponse, type UsageEventMetricsParams, UsageEventsResource, type UsageMetric, type UsageMetricCreateParams, type UsageMetricParams, type UsageMetricUpdateParams, type User, type UserListParams, type UserListResponse, UsersResource, type Webhook, type WebhookCreateParams, type WebhookFilter, type WebhookListResponse, type WebhookTopic, type WebhookUpdateParams, WebhooksResource, createAuthRefreshMiddleware };
+export { type AccountOwner, type AccountOwnersListResponse, type Affiliate, type AffiliateCommission, type AffiliateCommissionListParams, type AffiliateCommissionListResponse, AffiliateCommissionsResource, type AffiliateListParams, type AffiliateListResponse, type AffiliatePayout, type AffiliatePayoutListParams, type AffiliatePayoutListResponse, AffiliatePayoutsResource, type AffiliateProgram, type AffiliateProgramCreateParams, type AffiliateProgramUpdateParams, AffiliateProgramsResource, type AffiliateReferral, type AffiliateReferralListParams, type AffiliateReferralListResponse, AffiliateReferralsResource, type AffiliateUpdateParams, AffiliatesResource, type Agent, type AgentListResponse, AgentsResource, type App, type AppEvent, type AppEventListParams, type AppEventListResponse, type AppInstallation, type AppInstallationParams, type AppListParams, AppsResource, type AuthRefreshOptions, BaseResource, type Channel, type ChannelCreateParams, type ChannelListParams, ChannelsResource, type Charge, type ChargeListParams, type ChargeListResponse, ChargesResource, CompaniesResource, type Company, type CompanyCreateParams, type CompanyListParams, type CompanyListResponse, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactEntity, type ContactListParams, type ContactListResponse, type ContactUpdateParams, ContactsResource, type CustomField, type CustomFieldCreateParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerEntity, type CustomerListParams, type CustomerListResponse, type CustomerRetrieveParams, type CustomerSegment, type CustomerSegmentListParams, type CustomerSegmentListResponse, CustomerSegmentsResource, type CustomerUpdateParams, CustomersResource, type DateRangeType, type Deal, DealActivitiesResource, type DealActivity, type DealActivityCreateParams, type DealActivityUpdateParams, type DealContactInput, type DealCreateParams, type DealCustomerInput, type DealFlow, type DealFlowCreateParams, type DealFlowUpdateParams, DealFlowsResource, type DealListParams, type DealListResponse, type DealStage, type DealUpdateParams, DealsResource, type DeleteResponse, type DocCollection, type DocCollectionCreateParams, type DocCollectionUpdateParams, type DocGroup, type DocGroupCreateParams, type DocGroupUpdateParams, type DocPage, type DocPageCreateParams, type DocPageListParams, type DocPageListResponse, type DocPageStatus, type DocPageUpdateParams, type DocTreeNode, type DocTreeResponse, DocsResource, EntitiesResource, type EntitiesSearchParams, type EntitiesSearchResponse, type Entity, type EntityType, type Feature, type FeatureCreateParams, type FeatureUpdateParams, type Flow, type FlowCreateParams, type FlowListParams, type FlowListResponse, type FlowStatus, type FlowUpdateParams, FlowsResource, type HttpMethod, type ListParams, MantleAPIError, MantleAuthenticationError, MantleCoreClient, type MantleCoreClientConfig, MantleNotFoundError, MantlePermissionError, MantleRateLimitError, MantleValidationError, MeResource, type MeResponse, type MessageAttachment, type MetricDataPoint, type MetricType, type MetricsBaseParams, type MetricsGetParams, MetricsResource, type MetricsResponse, type Middleware, type MiddlewareContext, MiddlewareManager, type MiddlewareOptions, type MiddlewareRequest, type MiddlewareResponse, type NextFunction, type Organization, OrganizationResource, type PaginatedResponse, type Plan, type PlanCreateParams, type PlanFeature, type PlanListParams, type PlanListResponse, type PlanUpdateParams, type PlanUsageCharge, type RequestOptions, type Review, type ReviewCreateParams, type ReviewUpdateParams, type SocialProfile, type SocialProfileType, type Subscription, type SubscriptionListParams, type SubscriptionListResponse, SubscriptionsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskListResponse, type TaskPriority, type TaskStatus, type TaskUpdateParams, TasksResource, type Ticket, type TicketContactData, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TicketMessage, type TicketMessageCreateParams, type TicketMessageUpdateParams, type TicketUpdateParams, TicketsResource, type TimelineEvent, type TimelineListParams, type TimelineListResponse, type Transaction, type TransactionListParams, type TransactionListResponse, TransactionsResource, type UsageEvent, type UsageEventCreateData, type UsageEventCreateParams, type UsageEventCreateResponse, type UsageEventListParams, type UsageEventListResponse, type UsageEventMetricsParams, UsageEventsResource, type UsageMetric, type UsageMetricCreateParams, type UsageMetricParams, type UsageMetricUpdateParams, type User, type UserListParams, type UserListResponse, UsersResource, type Webhook, type WebhookCreateParams, type WebhookFilter, type WebhookListResponse, type WebhookTopic, type WebhookUpdateParams, WebhooksResource, createAuthRefreshMiddleware };

package/dist/index.d.ts

@@ -758,39 +758,70 @@ interface Deal {
     currentAmount?: number;
     acquisitionChannel?: string;
     acquisitionSource?: string;
-    firstInteractionAt?: string;
-    closingAt?: string;
-    closedAt?: string;
-    stage?: string;
-    step?: number;
-    dealFlowId?: string;
-    dealStageId?: string;
-    customerId?: string;
-    domain?: string;
-    shopifyDomain?: string;
-    companyId?: string;
-    appId?: string;
-    planId?: string;
-    ownerIds?: string[];
-    contactIds?: string[];
     notes?: string;
-    affiliateId?: string;
-    partnershipId?: string;
-    archived?: boolean;
+    firstInteractionAt?: string | null;
+    closingAt?: string | null;
+    closedAt?: string | null;
+    archivedAt?: string | null;
     createdAt: string;
     updatedAt: string;
+    dealStage?: {
+        id: string;
+        name: string;
+        stage?: string;
+        weight?: number;
+    } | null;
+    dealFlow?: {
+        id: string;
+        name: string;
+    } | null;
     customer?: {
         id: string;
         name?: string;
-    };
-    dealFlow?: {
+        email?: string;
+        domain?: string;
+        shopifyDomain?: string;
+    } | null;
+    app?: {
         id: string;
         name: string;
-    };
-    dealStage?: {
+    } | null;
+    plan?: {
         id: string;
         name: string;
-    };
+    } | null;
+    affiliate?: {
+        id: string;
+        name?: string;
+    } | null;
+    partnership?: {
+        id: string;
+        name?: string;
+        displayName?: string;
+    } | null;
+    acquirer?: {
+        id: string;
+        name?: string;
+        email?: string;
+    } | null;
+    owners?: Array<{
+        id: string;
+        userId: string;
+        user?: {
+            id: string;
+            name?: string;
+            email?: string;
+        } | null;
+    }>;
+    contacts?: Array<{
+        id: string;
+        contactId: string;
+        contact?: {
+            id: string;
+            name?: string;
+            email?: string;
+        } | null;
+    }>;
 }
 /**
  * Parameters for listing deals
@@ -822,34 +853,147 @@ interface DealListParams extends ListParams {
 interface DealListResponse extends PaginatedResponse {
     deals: Deal[];
 }
+/**
+ * Inline customer data for deal creation/update.
+ * Matches existing customers by domain or shopifyDomain.
+ * If no match found, creates a new customer.
+ */
+interface DealCustomerInput {
+    /** The name of the customer */
+    name?: string;
+    /** The email of the customer */
+    email?: string;
+    /** The domain of the customer (used for matching existing customers) */
+    domain?: string;
+    /** The Shopify domain of the customer (used for matching existing customers) */
+    shopifyDomain?: string;
+    /** The Shopify shop ID */
+    shopifyShopId?: string;
+    /** Tags to associate with the customer */
+    tags?: string[];
+    /** Custom fields for the customer */
+    customFields?: Record<string, unknown>;
+    /** The country code of the customer */
+    countryCode?: string;
+    /** The preferred currency of the customer */
+    preferredCurrency?: string;
+    /** Description of the customer */
+    description?: string;
+}
+/**
+ * Inline contact data for deal creation/update.
+ * Matches existing contacts by email.
+ * Contacts are linked to both the customer and the deal.
+ */
+interface DealContactInput {
+    /** The email of the contact (required, used for matching existing contacts) */
+    email: string;
+    /** The name of the contact */
+    name?: string;
+    /** The phone number of the contact */
+    phone?: string;
+    /** The job title of the contact */
+    jobTitle?: string;
+    /** The label for the contact relationship (e.g., "primary", "technical") */
+    label?: string;
+    /** Notes about the contact */
+    notes?: string;
+    /** Tags for the contact */
+    tags?: string[];
+}
 /**
  * Parameters for creating a deal
+ *
+ * **Customer Linking Options** (use only one approach):
+ * - `customerId` - Link to an existing customer by ID
+ * - `customer` - Create/update a customer inline (matches by domain or shopifyDomain)
+ * - `domain`/`shopifyDomain` alone - Find or create a customer by domain
+ *
+ * Note: `domain` and `shopifyDomain` can be provided alongside `customerId` or `customer`
+ * to update the customer's domain fields if they are not already set.
+ *
+ * **Contact Linking Options** (use only one approach):
+ * - `contactIds` - Link to existing contacts by their IDs
+ * - `contacts` - Create/update contacts inline (matches by email)
  */
 interface DealCreateParams {
+    /** The name of the deal */
     name: string;
+    /** The monetary value of the deal */
     amount?: number;
+    /** The currency code for the deal amount (e.g., 'USD', 'EUR') */
     amountCurrencyCode?: string;
+    /** The channel through which the deal was acquired */
     acquisitionChannel?: string;
+    /** The specific source of the deal acquisition */
     acquisitionSource?: string;
+    /** The timestamp of the first interaction with the prospect */
     firstInteractionAt?: string;
+    /** The expected closing date for the deal */
     closingAt?: string;
+    /** The actual closing date for the deal */
     closedAt?: string;
+    /** The ID of the deal flow */
     dealFlowId?: string;
+    /** The ID of the deal stage within the flow */
     dealStageId?: string;
+    /**
+     * Link to an existing customer by ID.
+     * Cannot be used together with `customer` object.
+     */
     customerId?: string;
+    /**
+     * Create or update a customer inline.
+     * Matches existing customers by `domain` or `shopifyDomain`.
+     * Cannot be used together with `customerId`.
+     */
+    customer?: DealCustomerInput;
+    /**
+     * The domain of the customer (e.g., 'acme.com').
+     * URLs are automatically normalized (protocol and path stripped).
+     * Used to find/create a customer if no `customerId` or `customer` provided,
+     * or to update the customer's domain if not already set.
+     */
     domain?: string;
+    /**
+     * The Shopify domain of the customer (e.g., 'acme.myshopify.com').
+     * URLs are automatically normalized (protocol and path stripped).
+     * Used to find/create a customer if no `customerId` or `customer` provided,
+     * or to update the customer's shopifyDomain if not already set.
+     */
     shopifyDomain?: string;
+    /** The ID of the company to associate with the deal */
     companyId?: string;
+    /** The ID of the app to associate with the deal */
     appId?: string;
+    /** The ID of the plan to associate with the deal */
     planId?: string;
+    /** Array of user IDs to assign as deal owners */
     ownerIds?: string[];
+    /**
+     * Link to existing contacts by their IDs.
+     * Cannot be used together with `contacts` array.
+     */
     contactIds?: string[];
+    /**
+     * Create or update contacts inline.
+     * Matches existing contacts by email.
+     * Contacts are automatically linked to both the customer and the deal.
+     * Cannot be used together with `contactIds`.
+     */
+    contacts?: DealContactInput[];
+    /** Additional notes about the deal */
     notes?: string;
+    /** The ID of the affiliate to associate with the deal */
     affiliateId?: string;
+    /** The ID of the partnership to associate with the deal */
     partnershipId?: string;
 }
 /**
  * Parameters for updating a deal
+ *
+ * All fields are optional. See {@link DealCreateParams} for detailed documentation
+ * on customer and contact linking options.
  */
 interface DealUpdateParams extends Partial<DealCreateParams> {
 }
@@ -2200,12 +2344,76 @@ declare class DealsResource extends BaseResource {
     }>;
     /**
      * Create a new deal
+     *
+     * **Linking a Customer:**
+     * There are three ways to associate a customer with a deal (use only one):
+     *
+     * 1. `customerId` - Link to an existing customer by ID
+     * 2. `customer` - Create or update a customer inline. Matches existing customers
+     *    by `domain` or `shopifyDomain`. If no match, creates a new customer.
+     * 3. `domain` and/or `shopifyDomain` - Find an existing customer by domain,
+     *    or create a minimal customer record if not found.
+     *
+     * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
+     * they will be used to update the customer's domain fields only if not already set.
+     *
+     * **Linking Contacts:**
+     * There are two ways to associate contacts with a deal (use only one):
+     *
+     * 1. `contactIds` - Link to existing contacts by their IDs
+     * 2. `contacts` - Create or update contacts inline. Matches existing contacts
+     *    by email. Contacts are automatically linked to both the customer and the deal.
+     *
+     * @example
+     * // Using an existing customer
+     * await client.deals.create({ name: 'Deal', customerId: 'cust_123', dealFlowId: '...', dealStageId: '...' });
+     *
+     * // Creating a customer inline
+     * await client.deals.create({
+     *   name: 'Deal',
+     *   customer: { name: 'Acme Corp', domain: 'acme.com', email: 'info@acme.com' },
+     *   contacts: [{ email: 'john@acme.com', name: 'John Doe', jobTitle: 'CEO' }],
+     *   dealFlowId: '...',
+     *   dealStageId: '...',
+     * });
+     *
+     * // Using domain to find/create customer
+     * await client.deals.create({ name: 'Deal', shopifyDomain: 'acme.myshopify.com', dealFlowId: '...', dealStageId: '...' });
      */
     create(data: DealCreateParams): Promise<{
         deal: Deal;
     }>;
     /**
      * Update an existing deal
+     *
+     * **Updating Customer Association:**
+     * There are three ways to change or update the customer (use only one):
+     *
+     * 1. `customerId` - Change to a different existing customer
+     * 2. `customer` - Update the linked customer inline, or create/link a new one.
+     *    Matches existing customers by `domain` or `shopifyDomain`.
+     * 3. `domain` and/or `shopifyDomain` - Find a different customer by domain,
+     *    or create a minimal customer record if not found.
+     *
+     * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
+     * they will be used to update the customer's domain fields only if not already set.
+     *
+     * **Updating Contacts:**
+     * There are two ways to update contacts (use only one):
+     *
+     * 1. `contactIds` - Replace deal contacts with the specified contact IDs
+     * 2. `contacts` - Create or update contacts inline. Matches existing contacts
+     *    by email. Contacts are automatically linked to both the customer and the deal.
+     *
+     * @example
+     * // Update customer's domain if not set
+     * await client.deals.update('deal_123', { customerId: 'cust_456', domain: 'newdomain.com' });
+     *
+     * // Update customer and contacts inline
+     * await client.deals.update('deal_123', {
+     *   customer: { name: 'Updated Name', domain: 'acme.com' },
+     *   contacts: [{ email: 'new@acme.com', name: 'New Contact' }],
+     * });
      */
     update(dealId: string, data: DealUpdateParams): Promise<{
         deal: Deal;
@@ -3176,4 +3384,4 @@ interface AuthRefreshOptions {
  */
 declare function createAuthRefreshMiddleware(options: AuthRefreshOptions): Middleware;
 
-export { type AccountOwner, type AccountOwnersListResponse, type Affiliate, type AffiliateCommission, type AffiliateCommissionListParams, type AffiliateCommissionListResponse, AffiliateCommissionsResource, type AffiliateListParams, type AffiliateListResponse, type AffiliatePayout, type AffiliatePayoutListParams, type AffiliatePayoutListResponse, AffiliatePayoutsResource, type AffiliateProgram, type AffiliateProgramCreateParams, type AffiliateProgramUpdateParams, AffiliateProgramsResource, type AffiliateReferral, type AffiliateReferralListParams, type AffiliateReferralListResponse, AffiliateReferralsResource, type AffiliateUpdateParams, AffiliatesResource, type Agent, type AgentListResponse, AgentsResource, type App, type AppEvent, type AppEventListParams, type AppEventListResponse, type AppInstallation, type AppInstallationParams, type AppListParams, AppsResource, type AuthRefreshOptions, BaseResource, type Channel, type ChannelCreateParams, type ChannelListParams, ChannelsResource, type Charge, type ChargeListParams, type ChargeListResponse, ChargesResource, CompaniesResource, type Company, type CompanyCreateParams, type CompanyListParams, type CompanyListResponse, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactEntity, type ContactListParams, type ContactListResponse, type ContactUpdateParams, ContactsResource, type CustomField, type CustomFieldCreateParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerEntity, type CustomerListParams, type CustomerListResponse, type CustomerRetrieveParams, type CustomerSegment, type CustomerSegmentListParams, type CustomerSegmentListResponse, CustomerSegmentsResource, type CustomerUpdateParams, CustomersResource, type DateRangeType, type Deal, DealActivitiesResource, type DealActivity, type DealActivityCreateParams, type DealActivityUpdateParams, type DealCreateParams, type DealFlow, type DealFlowCreateParams, type DealFlowUpdateParams, DealFlowsResource, type DealListParams, type DealListResponse, type DealStage, type DealUpdateParams, DealsResource, type DeleteResponse, type DocCollection, type DocCollectionCreateParams, type DocCollectionUpdateParams, type DocGroup, type DocGroupCreateParams, type DocGroupUpdateParams, type DocPage, type DocPageCreateParams, type DocPageListParams, type DocPageListResponse, type DocPageStatus, type DocPageUpdateParams, type DocTreeNode, type DocTreeResponse, DocsResource, EntitiesResource, type EntitiesSearchParams, type EntitiesSearchResponse, type Entity, type EntityType, type Feature, type FeatureCreateParams, type FeatureUpdateParams, type Flow, type FlowCreateParams, type FlowListParams, type FlowListResponse, type FlowStatus, type FlowUpdateParams, FlowsResource, type HttpMethod, type ListParams, MantleAPIError, MantleAuthenticationError, MantleCoreClient, type MantleCoreClientConfig, MantleNotFoundError, MantlePermissionError, MantleRateLimitError, MantleValidationError, MeResource, type MeResponse, type MessageAttachment, type MetricDataPoint, type MetricType, type MetricsBaseParams, type MetricsGetParams, MetricsResource, type MetricsResponse, type Middleware, type MiddlewareContext, MiddlewareManager, type MiddlewareOptions, type MiddlewareRequest, type MiddlewareResponse, type NextFunction, type Organization, OrganizationResource, type PaginatedResponse, type Plan, type PlanCreateParams, type PlanFeature, type PlanListParams, type PlanListResponse, type PlanUpdateParams, type PlanUsageCharge, type RequestOptions, type Review, type ReviewCreateParams, type ReviewUpdateParams, type SocialProfile, type SocialProfileType, type Subscription, type SubscriptionListParams, type SubscriptionListResponse, SubscriptionsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskListResponse, type TaskPriority, type TaskStatus, type TaskUpdateParams, TasksResource, type Ticket, type TicketContactData, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TicketMessage, type TicketMessageCreateParams, type TicketMessageUpdateParams, type TicketUpdateParams, TicketsResource, type TimelineEvent, type TimelineListParams, type TimelineListResponse, type Transaction, type TransactionListParams, type TransactionListResponse, TransactionsResource, type UsageEvent, type UsageEventCreateData, type UsageEventCreateParams, type UsageEventCreateResponse, type UsageEventListParams, type UsageEventListResponse, type UsageEventMetricsParams, UsageEventsResource, type UsageMetric, type UsageMetricCreateParams, type UsageMetricParams, type UsageMetricUpdateParams, type User, type UserListParams, type UserListResponse, UsersResource, type Webhook, type WebhookCreateParams, type WebhookFilter, type WebhookListResponse, type WebhookTopic, type WebhookUpdateParams, WebhooksResource, createAuthRefreshMiddleware };
+export { type AccountOwner, type AccountOwnersListResponse, type Affiliate, type AffiliateCommission, type AffiliateCommissionListParams, type AffiliateCommissionListResponse, AffiliateCommissionsResource, type AffiliateListParams, type AffiliateListResponse, type AffiliatePayout, type AffiliatePayoutListParams, type AffiliatePayoutListResponse, AffiliatePayoutsResource, type AffiliateProgram, type AffiliateProgramCreateParams, type AffiliateProgramUpdateParams, AffiliateProgramsResource, type AffiliateReferral, type AffiliateReferralListParams, type AffiliateReferralListResponse, AffiliateReferralsResource, type AffiliateUpdateParams, AffiliatesResource, type Agent, type AgentListResponse, AgentsResource, type App, type AppEvent, type AppEventListParams, type AppEventListResponse, type AppInstallation, type AppInstallationParams, type AppListParams, AppsResource, type AuthRefreshOptions, BaseResource, type Channel, type ChannelCreateParams, type ChannelListParams, ChannelsResource, type Charge, type ChargeListParams, type ChargeListResponse, ChargesResource, CompaniesResource, type Company, type CompanyCreateParams, type CompanyListParams, type CompanyListResponse, type CompanyUpdateParams, type Contact, type ContactCreateParams, type ContactEntity, type ContactListParams, type ContactListResponse, type ContactUpdateParams, ContactsResource, type CustomField, type CustomFieldCreateParams, type CustomFieldUpdateParams, type Customer, type CustomerCreateParams, type CustomerEntity, type CustomerListParams, type CustomerListResponse, type CustomerRetrieveParams, type CustomerSegment, type CustomerSegmentListParams, type CustomerSegmentListResponse, CustomerSegmentsResource, type CustomerUpdateParams, CustomersResource, type DateRangeType, type Deal, DealActivitiesResource, type DealActivity, type DealActivityCreateParams, type DealActivityUpdateParams, type DealContactInput, type DealCreateParams, type DealCustomerInput, type DealFlow, type DealFlowCreateParams, type DealFlowUpdateParams, DealFlowsResource, type DealListParams, type DealListResponse, type DealStage, type DealUpdateParams, DealsResource, type DeleteResponse, type DocCollection, type DocCollectionCreateParams, type DocCollectionUpdateParams, type DocGroup, type DocGroupCreateParams, type DocGroupUpdateParams, type DocPage, type DocPageCreateParams, type DocPageListParams, type DocPageListResponse, type DocPageStatus, type DocPageUpdateParams, type DocTreeNode, type DocTreeResponse, DocsResource, EntitiesResource, type EntitiesSearchParams, type EntitiesSearchResponse, type Entity, type EntityType, type Feature, type FeatureCreateParams, type FeatureUpdateParams, type Flow, type FlowCreateParams, type FlowListParams, type FlowListResponse, type FlowStatus, type FlowUpdateParams, FlowsResource, type HttpMethod, type ListParams, MantleAPIError, MantleAuthenticationError, MantleCoreClient, type MantleCoreClientConfig, MantleNotFoundError, MantlePermissionError, MantleRateLimitError, MantleValidationError, MeResource, type MeResponse, type MessageAttachment, type MetricDataPoint, type MetricType, type MetricsBaseParams, type MetricsGetParams, MetricsResource, type MetricsResponse, type Middleware, type MiddlewareContext, MiddlewareManager, type MiddlewareOptions, type MiddlewareRequest, type MiddlewareResponse, type NextFunction, type Organization, OrganizationResource, type PaginatedResponse, type Plan, type PlanCreateParams, type PlanFeature, type PlanListParams, type PlanListResponse, type PlanUpdateParams, type PlanUsageCharge, type RequestOptions, type Review, type ReviewCreateParams, type ReviewUpdateParams, type SocialProfile, type SocialProfileType, type Subscription, type SubscriptionListParams, type SubscriptionListResponse, SubscriptionsResource, type Task, type TaskCreateParams, type TaskListParams, type TaskListResponse, type TaskPriority, type TaskStatus, type TaskUpdateParams, TasksResource, type Ticket, type TicketContactData, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TicketMessage, type TicketMessageCreateParams, type TicketMessageUpdateParams, type TicketUpdateParams, TicketsResource, type TimelineEvent, type TimelineListParams, type TimelineListResponse, type Transaction, type TransactionListParams, type TransactionListResponse, TransactionsResource, type UsageEvent, type UsageEventCreateData, type UsageEventCreateParams, type UsageEventCreateResponse, type UsageEventListParams, type UsageEventListResponse, type UsageEventMetricsParams, UsageEventsResource, type UsageMetric, type UsageMetricCreateParams, type UsageMetricParams, type UsageMetricUpdateParams, type User, type UserListParams, type UserListResponse, UsersResource, type Webhook, type WebhookCreateParams, type WebhookFilter, type WebhookListResponse, type WebhookTopic, type WebhookUpdateParams, WebhooksResource, createAuthRefreshMiddleware };

package/dist/index.js

@@ -766,12 +766,76 @@ var DealsResource = class extends BaseResource {
   }
   /**
    * Create a new deal
+   *
+   * **Linking a Customer:**
+   * There are three ways to associate a customer with a deal (use only one):
+   *
+   * 1. `customerId` - Link to an existing customer by ID
+   * 2. `customer` - Create or update a customer inline. Matches existing customers
+   *    by `domain` or `shopifyDomain`. If no match, creates a new customer.
+   * 3. `domain` and/or `shopifyDomain` - Find an existing customer by domain,
+   *    or create a minimal customer record if not found.
+   *
+   * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
+   * they will be used to update the customer's domain fields only if not already set.
+   *
+   * **Linking Contacts:**
+   * There are two ways to associate contacts with a deal (use only one):
+   *
+   * 1. `contactIds` - Link to existing contacts by their IDs
+   * 2. `contacts` - Create or update contacts inline. Matches existing contacts
+   *    by email. Contacts are automatically linked to both the customer and the deal.
+   *
+   * @example
+   * // Using an existing customer
+   * await client.deals.create({ name: 'Deal', customerId: 'cust_123', dealFlowId: '...', dealStageId: '...' });
+   *
+   * // Creating a customer inline
+   * await client.deals.create({
+   *   name: 'Deal',
+   *   customer: { name: 'Acme Corp', domain: 'acme.com', email: 'info@acme.com' },
+   *   contacts: [{ email: 'john@acme.com', name: 'John Doe', jobTitle: 'CEO' }],
+   *   dealFlowId: '...',
+   *   dealStageId: '...',
+   * });
+   *
+   * // Using domain to find/create customer
+   * await client.deals.create({ name: 'Deal', shopifyDomain: 'acme.myshopify.com', dealFlowId: '...', dealStageId: '...' });
    */
   async create(data) {
     return this.post("/deals", data);
   }
   /**
    * Update an existing deal
+   *
+   * **Updating Customer Association:**
+   * There are three ways to change or update the customer (use only one):
+   *
+   * 1. `customerId` - Change to a different existing customer
+   * 2. `customer` - Update the linked customer inline, or create/link a new one.
+   *    Matches existing customers by `domain` or `shopifyDomain`.
+   * 3. `domain` and/or `shopifyDomain` - Find a different customer by domain,
+   *    or create a minimal customer record if not found.
+   *
+   * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
+   * they will be used to update the customer's domain fields only if not already set.
+   *
+   * **Updating Contacts:**
+   * There are two ways to update contacts (use only one):
+   *
+   * 1. `contactIds` - Replace deal contacts with the specified contact IDs
+   * 2. `contacts` - Create or update contacts inline. Matches existing contacts
+   *    by email. Contacts are automatically linked to both the customer and the deal.
+   *
+   * @example
+   * // Update customer's domain if not set
+   * await client.deals.update('deal_123', { customerId: 'cust_456', domain: 'newdomain.com' });
+   *
+   * // Update customer and contacts inline
+   * await client.deals.update('deal_123', {
+   *   customer: { name: 'Updated Name', domain: 'acme.com' },
+   *   contacts: [{ email: 'new@acme.com', name: 'New Contact' }],
+   * });
    */
   async update(dealId, data) {
     return this.put(`/deals/${dealId}`, data);

package/dist/index.mjs

@@ -702,12 +702,76 @@ var DealsResource = class extends BaseResource {
   }
   /**
    * Create a new deal
+   *
+   * **Linking a Customer:**
+   * There are three ways to associate a customer with a deal (use only one):
+   *
+   * 1. `customerId` - Link to an existing customer by ID
+   * 2. `customer` - Create or update a customer inline. Matches existing customers
+   *    by `domain` or `shopifyDomain`. If no match, creates a new customer.
+   * 3. `domain` and/or `shopifyDomain` - Find an existing customer by domain,
+   *    or create a minimal customer record if not found.
+   *
+   * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
+   * they will be used to update the customer's domain fields only if not already set.
+   *
+   * **Linking Contacts:**
+   * There are two ways to associate contacts with a deal (use only one):
+   *
+   * 1. `contactIds` - Link to existing contacts by their IDs
+   * 2. `contacts` - Create or update contacts inline. Matches existing contacts
+   *    by email. Contacts are automatically linked to both the customer and the deal.
+   *
+   * @example
+   * // Using an existing customer
+   * await client.deals.create({ name: 'Deal', customerId: 'cust_123', dealFlowId: '...', dealStageId: '...' });
+   *
+   * // Creating a customer inline
+   * await client.deals.create({
+   *   name: 'Deal',
+   *   customer: { name: 'Acme Corp', domain: 'acme.com', email: 'info@acme.com' },
+   *   contacts: [{ email: 'john@acme.com', name: 'John Doe', jobTitle: 'CEO' }],
+   *   dealFlowId: '...',
+   *   dealStageId: '...',
+   * });
+   *
+   * // Using domain to find/create customer
+   * await client.deals.create({ name: 'Deal', shopifyDomain: 'acme.myshopify.com', dealFlowId: '...', dealStageId: '...' });
    */
   async create(data) {
     return this.post("/deals", data);
   }
   /**
    * Update an existing deal
+   *
+   * **Updating Customer Association:**
+   * There are three ways to change or update the customer (use only one):
+   *
+   * 1. `customerId` - Change to a different existing customer
+   * 2. `customer` - Update the linked customer inline, or create/link a new one.
+   *    Matches existing customers by `domain` or `shopifyDomain`.
+   * 3. `domain` and/or `shopifyDomain` - Find a different customer by domain,
+   *    or create a minimal customer record if not found.
+   *
+   * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
+   * they will be used to update the customer's domain fields only if not already set.
+   *
+   * **Updating Contacts:**
+   * There are two ways to update contacts (use only one):
+   *
+   * 1. `contactIds` - Replace deal contacts with the specified contact IDs
+   * 2. `contacts` - Create or update contacts inline. Matches existing contacts
+   *    by email. Contacts are automatically linked to both the customer and the deal.
+   *
+   * @example
+   * // Update customer's domain if not set
+   * await client.deals.update('deal_123', { customerId: 'cust_456', domain: 'newdomain.com' });
+   *
+   * // Update customer and contacts inline
+   * await client.deals.update('deal_123', {
+   *   customer: { name: 'Updated Name', domain: 'acme.com' },
+   *   contacts: [{ email: 'new@acme.com', name: 'New Contact' }],
+   * });
    */
   async update(dealId, data) {
     return this.put(`/deals/${dealId}`, data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heymantle/core-api-client",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "TypeScript SDK for the Mantle Core API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",