@heymantle/core-api-client 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -758,39 +758,70 @@ interface Deal {
758
758
  currentAmount?: number;
759
759
  acquisitionChannel?: string;
760
760
  acquisitionSource?: string;
761
- firstInteractionAt?: string;
762
- closingAt?: string;
763
- closedAt?: string;
764
- stage?: string;
765
- step?: number;
766
- dealFlowId?: string;
767
- dealStageId?: string;
768
- customerId?: string;
769
- domain?: string;
770
- shopifyDomain?: string;
771
- companyId?: string;
772
- appId?: string;
773
- planId?: string;
774
- ownerIds?: string[];
775
- contactIds?: string[];
776
761
  notes?: string;
777
- affiliateId?: string;
778
- partnershipId?: string;
779
- archived?: boolean;
762
+ firstInteractionAt?: string | null;
763
+ closingAt?: string | null;
764
+ closedAt?: string | null;
765
+ archivedAt?: string | null;
780
766
  createdAt: string;
781
767
  updatedAt: string;
768
+ dealStage?: {
769
+ id: string;
770
+ name: string;
771
+ stage?: string;
772
+ weight?: number;
773
+ } | null;
774
+ dealFlow?: {
775
+ id: string;
776
+ name: string;
777
+ } | null;
782
778
  customer?: {
783
779
  id: string;
784
780
  name?: string;
785
- };
786
- dealFlow?: {
781
+ email?: string;
782
+ domain?: string;
783
+ shopifyDomain?: string;
784
+ } | null;
785
+ app?: {
787
786
  id: string;
788
787
  name: string;
789
- };
790
- dealStage?: {
788
+ } | null;
789
+ plan?: {
791
790
  id: string;
792
791
  name: string;
793
- };
792
+ } | null;
793
+ affiliate?: {
794
+ id: string;
795
+ name?: string;
796
+ } | null;
797
+ partnership?: {
798
+ id: string;
799
+ name?: string;
800
+ displayName?: string;
801
+ } | null;
802
+ acquirer?: {
803
+ id: string;
804
+ name?: string;
805
+ email?: string;
806
+ } | null;
807
+ owners?: Array<{
808
+ id: string;
809
+ userId: string;
810
+ user?: {
811
+ id: string;
812
+ name?: string;
813
+ email?: string;
814
+ } | null;
815
+ }>;
816
+ contacts?: Array<{
817
+ id: string;
818
+ contactId: string;
819
+ contact?: {
820
+ id: string;
821
+ name?: string;
822
+ email?: string;
823
+ } | null;
824
+ }>;
794
825
  }
795
826
  /**
796
827
  * Parameters for listing deals
@@ -872,44 +903,97 @@ interface DealContactInput {
872
903
  }
873
904
  /**
874
905
  * Parameters for creating a deal
906
+ *
907
+ * **Customer Linking Options** (use only one approach):
908
+ * - `customerId` - Link to an existing customer by ID
909
+ * - `customer` - Create/update a customer inline (matches by domain or shopifyDomain)
910
+ * - `domain`/`shopifyDomain` alone - Find or create a customer by domain
911
+ *
912
+ * Note: `domain` and `shopifyDomain` can be provided alongside `customerId` or `customer`
913
+ * to update the customer's domain fields if they are not already set.
914
+ *
915
+ * **Contact Linking Options** (use only one approach):
916
+ * - `contactIds` - Link to existing contacts by their IDs
917
+ * - `contacts` - Create/update contacts inline (matches by email)
875
918
  */
876
919
  interface DealCreateParams {
920
+ /** The name of the deal */
877
921
  name: string;
922
+ /** The monetary value of the deal */
878
923
  amount?: number;
924
+ /** The currency code for the deal amount (e.g., 'USD', 'EUR') */
879
925
  amountCurrencyCode?: string;
926
+ /** The channel through which the deal was acquired */
880
927
  acquisitionChannel?: string;
928
+ /** The specific source of the deal acquisition */
881
929
  acquisitionSource?: string;
930
+ /** The timestamp of the first interaction with the prospect */
882
931
  firstInteractionAt?: string;
932
+ /** The expected closing date for the deal */
883
933
  closingAt?: string;
934
+ /** The actual closing date for the deal */
884
935
  closedAt?: string;
936
+ /** The ID of the deal flow */
885
937
  dealFlowId?: string;
938
+ /** The ID of the deal stage within the flow */
886
939
  dealStageId?: string;
887
- /** The ID of an existing customer (alternative to customer object) */
940
+ /**
941
+ * Link to an existing customer by ID.
942
+ * Cannot be used together with `customer` object.
943
+ */
888
944
  customerId?: string;
889
945
  /**
890
- * Create or update a customer inline (alternative to customerId).
891
- * Matches existing customers by domain or shopifyDomain.
946
+ * Create or update a customer inline.
947
+ * Matches existing customers by `domain` or `shopifyDomain`.
948
+ * Cannot be used together with `customerId`.
892
949
  */
893
950
  customer?: DealCustomerInput;
951
+ /**
952
+ * The domain of the customer (e.g., 'acme.com').
953
+ * URLs are automatically normalized (protocol and path stripped).
954
+ * Used to find/create a customer if no `customerId` or `customer` provided,
955
+ * or to update the customer's domain if not already set.
956
+ */
894
957
  domain?: string;
958
+ /**
959
+ * The Shopify domain of the customer (e.g., 'acme.myshopify.com').
960
+ * URLs are automatically normalized (protocol and path stripped).
961
+ * Used to find/create a customer if no `customerId` or `customer` provided,
962
+ * or to update the customer's shopifyDomain if not already set.
963
+ */
895
964
  shopifyDomain?: string;
965
+ /** The ID of the company to associate with the deal */
896
966
  companyId?: string;
967
+ /** The ID of the app to associate with the deal */
897
968
  appId?: string;
969
+ /** The ID of the plan to associate with the deal */
898
970
  planId?: string;
971
+ /** Array of user IDs to assign as deal owners */
899
972
  ownerIds?: string[];
900
- /** Array of existing contact IDs (alternative to contacts array) */
973
+ /**
974
+ * Link to existing contacts by their IDs.
975
+ * Cannot be used together with `contacts` array.
976
+ */
901
977
  contactIds?: string[];
902
978
  /**
903
- * Create or update contacts inline (alternative to contactIds).
904
- * Matches existing contacts by email. Contacts are linked to both the customer and the deal.
979
+ * Create or update contacts inline.
980
+ * Matches existing contacts by email.
981
+ * Contacts are automatically linked to both the customer and the deal.
982
+ * Cannot be used together with `contactIds`.
905
983
  */
906
984
  contacts?: DealContactInput[];
985
+ /** Additional notes about the deal */
907
986
  notes?: string;
987
+ /** The ID of the affiliate to associate with the deal */
908
988
  affiliateId?: string;
989
+ /** The ID of the partnership to associate with the deal */
909
990
  partnershipId?: string;
910
991
  }
911
992
  /**
912
993
  * Parameters for updating a deal
994
+ *
995
+ * All fields are optional. See {@link DealCreateParams} for detailed documentation
996
+ * on customer and contact linking options.
913
997
  */
914
998
  interface DealUpdateParams extends Partial<DealCreateParams> {
915
999
  }
@@ -2260,12 +2344,76 @@ declare class DealsResource extends BaseResource {
2260
2344
  }>;
2261
2345
  /**
2262
2346
  * Create a new deal
2347
+ *
2348
+ * **Linking a Customer:**
2349
+ * There are three ways to associate a customer with a deal (use only one):
2350
+ *
2351
+ * 1. `customerId` - Link to an existing customer by ID
2352
+ * 2. `customer` - Create or update a customer inline. Matches existing customers
2353
+ * by `domain` or `shopifyDomain`. If no match, creates a new customer.
2354
+ * 3. `domain` and/or `shopifyDomain` - Find an existing customer by domain,
2355
+ * or create a minimal customer record if not found.
2356
+ *
2357
+ * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
2358
+ * they will be used to update the customer's domain fields only if not already set.
2359
+ *
2360
+ * **Linking Contacts:**
2361
+ * There are two ways to associate contacts with a deal (use only one):
2362
+ *
2363
+ * 1. `contactIds` - Link to existing contacts by their IDs
2364
+ * 2. `contacts` - Create or update contacts inline. Matches existing contacts
2365
+ * by email. Contacts are automatically linked to both the customer and the deal.
2366
+ *
2367
+ * @example
2368
+ * // Using an existing customer
2369
+ * await client.deals.create({ name: 'Deal', customerId: 'cust_123', dealFlowId: '...', dealStageId: '...' });
2370
+ *
2371
+ * // Creating a customer inline
2372
+ * await client.deals.create({
2373
+ * name: 'Deal',
2374
+ * customer: { name: 'Acme Corp', domain: 'acme.com', email: 'info@acme.com' },
2375
+ * contacts: [{ email: 'john@acme.com', name: 'John Doe', jobTitle: 'CEO' }],
2376
+ * dealFlowId: '...',
2377
+ * dealStageId: '...',
2378
+ * });
2379
+ *
2380
+ * // Using domain to find/create customer
2381
+ * await client.deals.create({ name: 'Deal', shopifyDomain: 'acme.myshopify.com', dealFlowId: '...', dealStageId: '...' });
2263
2382
  */
2264
2383
  create(data: DealCreateParams): Promise<{
2265
2384
  deal: Deal;
2266
2385
  }>;
2267
2386
  /**
2268
2387
  * Update an existing deal
2388
+ *
2389
+ * **Updating Customer Association:**
2390
+ * There are three ways to change or update the customer (use only one):
2391
+ *
2392
+ * 1. `customerId` - Change to a different existing customer
2393
+ * 2. `customer` - Update the linked customer inline, or create/link a new one.
2394
+ * Matches existing customers by `domain` or `shopifyDomain`.
2395
+ * 3. `domain` and/or `shopifyDomain` - Find a different customer by domain,
2396
+ * or create a minimal customer record if not found.
2397
+ *
2398
+ * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
2399
+ * they will be used to update the customer's domain fields only if not already set.
2400
+ *
2401
+ * **Updating Contacts:**
2402
+ * There are two ways to update contacts (use only one):
2403
+ *
2404
+ * 1. `contactIds` - Replace deal contacts with the specified contact IDs
2405
+ * 2. `contacts` - Create or update contacts inline. Matches existing contacts
2406
+ * by email. Contacts are automatically linked to both the customer and the deal.
2407
+ *
2408
+ * @example
2409
+ * // Update customer's domain if not set
2410
+ * await client.deals.update('deal_123', { customerId: 'cust_456', domain: 'newdomain.com' });
2411
+ *
2412
+ * // Update customer and contacts inline
2413
+ * await client.deals.update('deal_123', {
2414
+ * customer: { name: 'Updated Name', domain: 'acme.com' },
2415
+ * contacts: [{ email: 'new@acme.com', name: 'New Contact' }],
2416
+ * });
2269
2417
  */
2270
2418
  update(dealId: string, data: DealUpdateParams): Promise<{
2271
2419
  deal: Deal;
package/dist/index.d.ts CHANGED
@@ -758,39 +758,70 @@ interface Deal {
758
758
  currentAmount?: number;
759
759
  acquisitionChannel?: string;
760
760
  acquisitionSource?: string;
761
- firstInteractionAt?: string;
762
- closingAt?: string;
763
- closedAt?: string;
764
- stage?: string;
765
- step?: number;
766
- dealFlowId?: string;
767
- dealStageId?: string;
768
- customerId?: string;
769
- domain?: string;
770
- shopifyDomain?: string;
771
- companyId?: string;
772
- appId?: string;
773
- planId?: string;
774
- ownerIds?: string[];
775
- contactIds?: string[];
776
761
  notes?: string;
777
- affiliateId?: string;
778
- partnershipId?: string;
779
- archived?: boolean;
762
+ firstInteractionAt?: string | null;
763
+ closingAt?: string | null;
764
+ closedAt?: string | null;
765
+ archivedAt?: string | null;
780
766
  createdAt: string;
781
767
  updatedAt: string;
768
+ dealStage?: {
769
+ id: string;
770
+ name: string;
771
+ stage?: string;
772
+ weight?: number;
773
+ } | null;
774
+ dealFlow?: {
775
+ id: string;
776
+ name: string;
777
+ } | null;
782
778
  customer?: {
783
779
  id: string;
784
780
  name?: string;
785
- };
786
- dealFlow?: {
781
+ email?: string;
782
+ domain?: string;
783
+ shopifyDomain?: string;
784
+ } | null;
785
+ app?: {
787
786
  id: string;
788
787
  name: string;
789
- };
790
- dealStage?: {
788
+ } | null;
789
+ plan?: {
791
790
  id: string;
792
791
  name: string;
793
- };
792
+ } | null;
793
+ affiliate?: {
794
+ id: string;
795
+ name?: string;
796
+ } | null;
797
+ partnership?: {
798
+ id: string;
799
+ name?: string;
800
+ displayName?: string;
801
+ } | null;
802
+ acquirer?: {
803
+ id: string;
804
+ name?: string;
805
+ email?: string;
806
+ } | null;
807
+ owners?: Array<{
808
+ id: string;
809
+ userId: string;
810
+ user?: {
811
+ id: string;
812
+ name?: string;
813
+ email?: string;
814
+ } | null;
815
+ }>;
816
+ contacts?: Array<{
817
+ id: string;
818
+ contactId: string;
819
+ contact?: {
820
+ id: string;
821
+ name?: string;
822
+ email?: string;
823
+ } | null;
824
+ }>;
794
825
  }
795
826
  /**
796
827
  * Parameters for listing deals
@@ -872,44 +903,97 @@ interface DealContactInput {
872
903
  }
873
904
  /**
874
905
  * Parameters for creating a deal
906
+ *
907
+ * **Customer Linking Options** (use only one approach):
908
+ * - `customerId` - Link to an existing customer by ID
909
+ * - `customer` - Create/update a customer inline (matches by domain or shopifyDomain)
910
+ * - `domain`/`shopifyDomain` alone - Find or create a customer by domain
911
+ *
912
+ * Note: `domain` and `shopifyDomain` can be provided alongside `customerId` or `customer`
913
+ * to update the customer's domain fields if they are not already set.
914
+ *
915
+ * **Contact Linking Options** (use only one approach):
916
+ * - `contactIds` - Link to existing contacts by their IDs
917
+ * - `contacts` - Create/update contacts inline (matches by email)
875
918
  */
876
919
  interface DealCreateParams {
920
+ /** The name of the deal */
877
921
  name: string;
922
+ /** The monetary value of the deal */
878
923
  amount?: number;
924
+ /** The currency code for the deal amount (e.g., 'USD', 'EUR') */
879
925
  amountCurrencyCode?: string;
926
+ /** The channel through which the deal was acquired */
880
927
  acquisitionChannel?: string;
928
+ /** The specific source of the deal acquisition */
881
929
  acquisitionSource?: string;
930
+ /** The timestamp of the first interaction with the prospect */
882
931
  firstInteractionAt?: string;
932
+ /** The expected closing date for the deal */
883
933
  closingAt?: string;
934
+ /** The actual closing date for the deal */
884
935
  closedAt?: string;
936
+ /** The ID of the deal flow */
885
937
  dealFlowId?: string;
938
+ /** The ID of the deal stage within the flow */
886
939
  dealStageId?: string;
887
- /** The ID of an existing customer (alternative to customer object) */
940
+ /**
941
+ * Link to an existing customer by ID.
942
+ * Cannot be used together with `customer` object.
943
+ */
888
944
  customerId?: string;
889
945
  /**
890
- * Create or update a customer inline (alternative to customerId).
891
- * Matches existing customers by domain or shopifyDomain.
946
+ * Create or update a customer inline.
947
+ * Matches existing customers by `domain` or `shopifyDomain`.
948
+ * Cannot be used together with `customerId`.
892
949
  */
893
950
  customer?: DealCustomerInput;
951
+ /**
952
+ * The domain of the customer (e.g., 'acme.com').
953
+ * URLs are automatically normalized (protocol and path stripped).
954
+ * Used to find/create a customer if no `customerId` or `customer` provided,
955
+ * or to update the customer's domain if not already set.
956
+ */
894
957
  domain?: string;
958
+ /**
959
+ * The Shopify domain of the customer (e.g., 'acme.myshopify.com').
960
+ * URLs are automatically normalized (protocol and path stripped).
961
+ * Used to find/create a customer if no `customerId` or `customer` provided,
962
+ * or to update the customer's shopifyDomain if not already set.
963
+ */
895
964
  shopifyDomain?: string;
965
+ /** The ID of the company to associate with the deal */
896
966
  companyId?: string;
967
+ /** The ID of the app to associate with the deal */
897
968
  appId?: string;
969
+ /** The ID of the plan to associate with the deal */
898
970
  planId?: string;
971
+ /** Array of user IDs to assign as deal owners */
899
972
  ownerIds?: string[];
900
- /** Array of existing contact IDs (alternative to contacts array) */
973
+ /**
974
+ * Link to existing contacts by their IDs.
975
+ * Cannot be used together with `contacts` array.
976
+ */
901
977
  contactIds?: string[];
902
978
  /**
903
- * Create or update contacts inline (alternative to contactIds).
904
- * Matches existing contacts by email. Contacts are linked to both the customer and the deal.
979
+ * Create or update contacts inline.
980
+ * Matches existing contacts by email.
981
+ * Contacts are automatically linked to both the customer and the deal.
982
+ * Cannot be used together with `contactIds`.
905
983
  */
906
984
  contacts?: DealContactInput[];
985
+ /** Additional notes about the deal */
907
986
  notes?: string;
987
+ /** The ID of the affiliate to associate with the deal */
908
988
  affiliateId?: string;
989
+ /** The ID of the partnership to associate with the deal */
909
990
  partnershipId?: string;
910
991
  }
911
992
  /**
912
993
  * Parameters for updating a deal
994
+ *
995
+ * All fields are optional. See {@link DealCreateParams} for detailed documentation
996
+ * on customer and contact linking options.
913
997
  */
914
998
  interface DealUpdateParams extends Partial<DealCreateParams> {
915
999
  }
@@ -2260,12 +2344,76 @@ declare class DealsResource extends BaseResource {
2260
2344
  }>;
2261
2345
  /**
2262
2346
  * Create a new deal
2347
+ *
2348
+ * **Linking a Customer:**
2349
+ * There are three ways to associate a customer with a deal (use only one):
2350
+ *
2351
+ * 1. `customerId` - Link to an existing customer by ID
2352
+ * 2. `customer` - Create or update a customer inline. Matches existing customers
2353
+ * by `domain` or `shopifyDomain`. If no match, creates a new customer.
2354
+ * 3. `domain` and/or `shopifyDomain` - Find an existing customer by domain,
2355
+ * or create a minimal customer record if not found.
2356
+ *
2357
+ * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
2358
+ * they will be used to update the customer's domain fields only if not already set.
2359
+ *
2360
+ * **Linking Contacts:**
2361
+ * There are two ways to associate contacts with a deal (use only one):
2362
+ *
2363
+ * 1. `contactIds` - Link to existing contacts by their IDs
2364
+ * 2. `contacts` - Create or update contacts inline. Matches existing contacts
2365
+ * by email. Contacts are automatically linked to both the customer and the deal.
2366
+ *
2367
+ * @example
2368
+ * // Using an existing customer
2369
+ * await client.deals.create({ name: 'Deal', customerId: 'cust_123', dealFlowId: '...', dealStageId: '...' });
2370
+ *
2371
+ * // Creating a customer inline
2372
+ * await client.deals.create({
2373
+ * name: 'Deal',
2374
+ * customer: { name: 'Acme Corp', domain: 'acme.com', email: 'info@acme.com' },
2375
+ * contacts: [{ email: 'john@acme.com', name: 'John Doe', jobTitle: 'CEO' }],
2376
+ * dealFlowId: '...',
2377
+ * dealStageId: '...',
2378
+ * });
2379
+ *
2380
+ * // Using domain to find/create customer
2381
+ * await client.deals.create({ name: 'Deal', shopifyDomain: 'acme.myshopify.com', dealFlowId: '...', dealStageId: '...' });
2263
2382
  */
2264
2383
  create(data: DealCreateParams): Promise<{
2265
2384
  deal: Deal;
2266
2385
  }>;
2267
2386
  /**
2268
2387
  * Update an existing deal
2388
+ *
2389
+ * **Updating Customer Association:**
2390
+ * There are three ways to change or update the customer (use only one):
2391
+ *
2392
+ * 1. `customerId` - Change to a different existing customer
2393
+ * 2. `customer` - Update the linked customer inline, or create/link a new one.
2394
+ * Matches existing customers by `domain` or `shopifyDomain`.
2395
+ * 3. `domain` and/or `shopifyDomain` - Find a different customer by domain,
2396
+ * or create a minimal customer record if not found.
2397
+ *
2398
+ * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
2399
+ * they will be used to update the customer's domain fields only if not already set.
2400
+ *
2401
+ * **Updating Contacts:**
2402
+ * There are two ways to update contacts (use only one):
2403
+ *
2404
+ * 1. `contactIds` - Replace deal contacts with the specified contact IDs
2405
+ * 2. `contacts` - Create or update contacts inline. Matches existing contacts
2406
+ * by email. Contacts are automatically linked to both the customer and the deal.
2407
+ *
2408
+ * @example
2409
+ * // Update customer's domain if not set
2410
+ * await client.deals.update('deal_123', { customerId: 'cust_456', domain: 'newdomain.com' });
2411
+ *
2412
+ * // Update customer and contacts inline
2413
+ * await client.deals.update('deal_123', {
2414
+ * customer: { name: 'Updated Name', domain: 'acme.com' },
2415
+ * contacts: [{ email: 'new@acme.com', name: 'New Contact' }],
2416
+ * });
2269
2417
  */
2270
2418
  update(dealId: string, data: DealUpdateParams): Promise<{
2271
2419
  deal: Deal;
package/dist/index.js CHANGED
@@ -766,12 +766,76 @@ var DealsResource = class extends BaseResource {
766
766
  }
767
767
  /**
768
768
  * Create a new deal
769
+ *
770
+ * **Linking a Customer:**
771
+ * There are three ways to associate a customer with a deal (use only one):
772
+ *
773
+ * 1. `customerId` - Link to an existing customer by ID
774
+ * 2. `customer` - Create or update a customer inline. Matches existing customers
775
+ * by `domain` or `shopifyDomain`. If no match, creates a new customer.
776
+ * 3. `domain` and/or `shopifyDomain` - Find an existing customer by domain,
777
+ * or create a minimal customer record if not found.
778
+ *
779
+ * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
780
+ * they will be used to update the customer's domain fields only if not already set.
781
+ *
782
+ * **Linking Contacts:**
783
+ * There are two ways to associate contacts with a deal (use only one):
784
+ *
785
+ * 1. `contactIds` - Link to existing contacts by their IDs
786
+ * 2. `contacts` - Create or update contacts inline. Matches existing contacts
787
+ * by email. Contacts are automatically linked to both the customer and the deal.
788
+ *
789
+ * @example
790
+ * // Using an existing customer
791
+ * await client.deals.create({ name: 'Deal', customerId: 'cust_123', dealFlowId: '...', dealStageId: '...' });
792
+ *
793
+ * // Creating a customer inline
794
+ * await client.deals.create({
795
+ * name: 'Deal',
796
+ * customer: { name: 'Acme Corp', domain: 'acme.com', email: 'info@acme.com' },
797
+ * contacts: [{ email: 'john@acme.com', name: 'John Doe', jobTitle: 'CEO' }],
798
+ * dealFlowId: '...',
799
+ * dealStageId: '...',
800
+ * });
801
+ *
802
+ * // Using domain to find/create customer
803
+ * await client.deals.create({ name: 'Deal', shopifyDomain: 'acme.myshopify.com', dealFlowId: '...', dealStageId: '...' });
769
804
  */
770
805
  async create(data) {
771
806
  return this.post("/deals", data);
772
807
  }
773
808
  /**
774
809
  * Update an existing deal
810
+ *
811
+ * **Updating Customer Association:**
812
+ * There are three ways to change or update the customer (use only one):
813
+ *
814
+ * 1. `customerId` - Change to a different existing customer
815
+ * 2. `customer` - Update the linked customer inline, or create/link a new one.
816
+ * Matches existing customers by `domain` or `shopifyDomain`.
817
+ * 3. `domain` and/or `shopifyDomain` - Find a different customer by domain,
818
+ * or create a minimal customer record if not found.
819
+ *
820
+ * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
821
+ * they will be used to update the customer's domain fields only if not already set.
822
+ *
823
+ * **Updating Contacts:**
824
+ * There are two ways to update contacts (use only one):
825
+ *
826
+ * 1. `contactIds` - Replace deal contacts with the specified contact IDs
827
+ * 2. `contacts` - Create or update contacts inline. Matches existing contacts
828
+ * by email. Contacts are automatically linked to both the customer and the deal.
829
+ *
830
+ * @example
831
+ * // Update customer's domain if not set
832
+ * await client.deals.update('deal_123', { customerId: 'cust_456', domain: 'newdomain.com' });
833
+ *
834
+ * // Update customer and contacts inline
835
+ * await client.deals.update('deal_123', {
836
+ * customer: { name: 'Updated Name', domain: 'acme.com' },
837
+ * contacts: [{ email: 'new@acme.com', name: 'New Contact' }],
838
+ * });
775
839
  */
776
840
  async update(dealId, data) {
777
841
  return this.put(`/deals/${dealId}`, data);
package/dist/index.mjs CHANGED
@@ -702,12 +702,76 @@ var DealsResource = class extends BaseResource {
702
702
  }
703
703
  /**
704
704
  * Create a new deal
705
+ *
706
+ * **Linking a Customer:**
707
+ * There are three ways to associate a customer with a deal (use only one):
708
+ *
709
+ * 1. `customerId` - Link to an existing customer by ID
710
+ * 2. `customer` - Create or update a customer inline. Matches existing customers
711
+ * by `domain` or `shopifyDomain`. If no match, creates a new customer.
712
+ * 3. `domain` and/or `shopifyDomain` - Find an existing customer by domain,
713
+ * or create a minimal customer record if not found.
714
+ *
715
+ * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
716
+ * they will be used to update the customer's domain fields only if not already set.
717
+ *
718
+ * **Linking Contacts:**
719
+ * There are two ways to associate contacts with a deal (use only one):
720
+ *
721
+ * 1. `contactIds` - Link to existing contacts by their IDs
722
+ * 2. `contacts` - Create or update contacts inline. Matches existing contacts
723
+ * by email. Contacts are automatically linked to both the customer and the deal.
724
+ *
725
+ * @example
726
+ * // Using an existing customer
727
+ * await client.deals.create({ name: 'Deal', customerId: 'cust_123', dealFlowId: '...', dealStageId: '...' });
728
+ *
729
+ * // Creating a customer inline
730
+ * await client.deals.create({
731
+ * name: 'Deal',
732
+ * customer: { name: 'Acme Corp', domain: 'acme.com', email: 'info@acme.com' },
733
+ * contacts: [{ email: 'john@acme.com', name: 'John Doe', jobTitle: 'CEO' }],
734
+ * dealFlowId: '...',
735
+ * dealStageId: '...',
736
+ * });
737
+ *
738
+ * // Using domain to find/create customer
739
+ * await client.deals.create({ name: 'Deal', shopifyDomain: 'acme.myshopify.com', dealFlowId: '...', dealStageId: '...' });
705
740
  */
706
741
  async create(data) {
707
742
  return this.post("/deals", data);
708
743
  }
709
744
  /**
710
745
  * Update an existing deal
746
+ *
747
+ * **Updating Customer Association:**
748
+ * There are three ways to change or update the customer (use only one):
749
+ *
750
+ * 1. `customerId` - Change to a different existing customer
751
+ * 2. `customer` - Update the linked customer inline, or create/link a new one.
752
+ * Matches existing customers by `domain` or `shopifyDomain`.
753
+ * 3. `domain` and/or `shopifyDomain` - Find a different customer by domain,
754
+ * or create a minimal customer record if not found.
755
+ *
756
+ * If `domain` or `shopifyDomain` are provided alongside `customerId` or `customer`,
757
+ * they will be used to update the customer's domain fields only if not already set.
758
+ *
759
+ * **Updating Contacts:**
760
+ * There are two ways to update contacts (use only one):
761
+ *
762
+ * 1. `contactIds` - Replace deal contacts with the specified contact IDs
763
+ * 2. `contacts` - Create or update contacts inline. Matches existing contacts
764
+ * by email. Contacts are automatically linked to both the customer and the deal.
765
+ *
766
+ * @example
767
+ * // Update customer's domain if not set
768
+ * await client.deals.update('deal_123', { customerId: 'cust_456', domain: 'newdomain.com' });
769
+ *
770
+ * // Update customer and contacts inline
771
+ * await client.deals.update('deal_123', {
772
+ * customer: { name: 'Updated Name', domain: 'acme.com' },
773
+ * contacts: [{ email: 'new@acme.com', name: 'New Contact' }],
774
+ * });
711
775
  */
712
776
  async update(dealId, data) {
713
777
  return this.put(`/deals/${dealId}`, data);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@heymantle/core-api-client",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
4
4
  "description": "TypeScript SDK for the Mantle Core API",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",