@heymantle/core-api-client 0.1.5 → 0.1.7

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.5",
+  "version": "0.1.7",
   "description": "TypeScript SDK for the Mantle Core API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",