Added headers for events and transactionals

Author: danrowden

CONTRIBUTING.md

@@ -13,7 +13,7 @@ Thank you for your interest in contributing to Loops JS SDK. We welcome contribu
 1. Make your changes in your branch.
 2. Follow the coding style and conventions used in the project.
 3. Write clear, concise commit messages.
-4. Test your changes thoroughly.
+4. Test your changes thoroughly. Write or modify existing tests when it makes sense.
 
 ## Submitting a Pull Request
 

README.md

@@ -567,6 +567,15 @@ const resp = await loops.sendEvent({
     plan: "pro",
   },
 });
+
+// Example with Idempotency-Key header
+const resp = await loops.sendEvent({
+  email: "[email protected]",
+  eventName: "signup",
+  headers: {
+    "Idempotency-Key": "550e8400-e29b-41d4-a716-446655440000",
+  },
+});
 ```
 
 #### Response
@@ -619,6 +628,18 @@ const resp = await loops.sendTransactionalEmail({
   },
 });
 
+// Example with Idempotency-Key header
+const resp = await loops.sendTransactionalEmail({
+  transactionalId: "clfq6dinn000yl70fgwwyp82l",
+  email: "[email protected]",
+  dataVariables: {
+    loginUrl: "https://myapp.com/login/",
+  },
+  headers: {
+    "Idempotency-Key": "550e8400-e29b-41d4-a716-446655440000",
+  },
+});
+
 // Please contact us to enable attachments on your account.
 const resp = await loops.sendTransactionalEmail({
   transactionalId: "clfq6dinn000yl70fgwwyp82l",
@@ -733,6 +754,7 @@ const resp = await loops.getTransactionalEmails({ perPage: 15 });
 
 ## Version history
 
+- `v5.0.1` (May 13, 2025) - Added a `headers` parameter for [`sendEvent()`](#sendevent) and [`sendTransactionalEmail()`](#sendtransactionalemail), enabling support for the `Idempotency-Key` header.
 - `v5.0.0` (Apr 29, 2025)
   - Types are now exported so you can use them in your application.
   - `ValidationError` is now thrown when paramters are not added correctly.
@@ -770,6 +792,12 @@ const resp = await loops.getTransactionalEmails({ perPage: 15 });
 
 ---
 
+## Tests
+
+Run tests with `npm run test`.
+
+---
+
 ## Contributing
 
 Bug reports and pull requests are welcome. Please read our [Contributing Guidelines](CONTRIBUTING.md).

src/__tests__/LoopsClient.test.ts

@@ -409,6 +409,69 @@ describe("LoopsClient", () => {
         })
       );
     });
+
+    it("should send event with idempotency key", async () => {
+      const eventData = {
+        email: "[email protected]",
+        eventName: "test_event",
+        headers: {
+          "Idempotency-Key": "unique_key_123",
+        },
+      };
+      const mockResponse = { success: true };
+
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+      const result = await client.sendEvent(eventData);
+
+      expect(result).toEqual(mockResponse);
+
+      // Get the actual fetch call arguments
+      const fetchCall = (fetch as jest.Mock).mock.calls[0];
+      const requestOptions = fetchCall[1];
+
+      // Verify headers using Headers object methods
+      const headers = requestOptions.headers;
+      expect(headers.get("Idempotency-Key")).toBe("unique_key_123");
+
+      // Verify the body doesn't contain idempotency key
+      expect(requestOptions.body).toBe(
+        JSON.stringify({
+          eventName: eventData.eventName,
+          email: eventData.email,
+        })
+      );
+    });
+
+    it("should send event without idempotency key when empty string", async () => {
+      const eventData = {
+        email: "[email protected]",
+        eventName: "test_event",
+        headers: {
+          "Idempotency-Key": "",
+        },
+      };
+      const mockResponse = { success: true };
+
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve(mockResponse),
+      });
+
+      const result = await client.sendEvent(eventData);
+
+      expect(result).toEqual(mockResponse);
+
+      // Get the actual fetch call arguments
+      const fetchCall = (fetch as jest.Mock).mock.calls[0];
+      const requestOptions = fetchCall[1];
+
+      // Verify no header is set
+      expect(requestOptions.headers.get("Idempotency-Key")).toBeNull();
+    });
   });
 
   describe("sendTransactionalEmail", () => {

src/index.ts

@@ -3,6 +3,7 @@ interface QueryOptions {
   method?: "GET" | "POST" | "PUT";
   payload?: Record<string, unknown>;
   params?: Record<string, string>;
+  headers?: Record<string, string>;
 }
 
 interface ApiKeySuccessResponse {
@@ -280,18 +281,28 @@ class LoopsClient {
    * @param {Object} params
    * @param {string} params.path Endpoint path
    * @param {string} params.method HTTP method
+   * @param {Object} params.headers Additional headers to send with the request
    * @param {Object} params.payload Payload for PUT and POST requests
    * @param {Object} params.params URL query parameters
    */
   private async _makeQuery<T>({
     path,
     method = "GET",
+    headers,
     payload,
     params,
   }: QueryOptions): Promise<T> {
-    const headers = new Headers();
-    headers.set("Authorization", `Bearer ${this.apiKey}`);
-    headers.set("Content-Type", "application/json");
+    const h = new Headers();
+    h.set("Authorization", `Bearer ${this.apiKey}`);
+    h.set("Content-Type", "application/json");
+
+    if (headers) {
+      Object.entries(headers).forEach(([key, value]) => {
+        if (value !== "" && value !== undefined && value !== null) {
+          h.set(key, value as string);
+        }
+      });
+    }
 
     const url = new URL(path, this.apiRoot);
     if (params && method === "GET") {
@@ -303,7 +314,7 @@ class LoopsClient {
     try {
       const response = await fetch(url.href, {
         method,
-        headers,
+        headers: h,
         body: payload ? JSON.stringify(payload) : undefined,
       });
 
@@ -525,6 +536,7 @@ class LoopsClient {
    * @param {Object} [params.contactProperties] Properties to update the contact with, including custom properties.
    * @param {Object} [params.eventProperties] Event properties, made available in emails triggered by the event.
    * @param {Object} [params.mailingLists] An object of mailing list IDs and boolean subscription statuses.
+   * @param {Object} [params.headers] Additional headers to send with the request.
    *
    * @see https://loops.so/docs/api-reference/send-event
    *
@@ -537,13 +549,15 @@ class LoopsClient {
     contactProperties,
     eventProperties,
     mailingLists,
+    headers,
   }: {
     email?: string;
     userId?: string;
     eventName: string;
     contactProperties?: ContactProperties;
     eventProperties?: EventProperties;
     mailingLists?: MailingLists;
+    headers?: Record<string, string>;
   }): Promise<EventSuccessResponse> {
     if (!userId && !email)
       throw new ValidationError(
@@ -566,6 +580,7 @@ class LoopsClient {
     return this._makeQuery({
       path: "v1/events/send",
       method: "POST",
+      headers,
       payload,
     });
   }
@@ -579,6 +594,7 @@ class LoopsClient {
    * @param {boolean} [params.addToAudience] Create a contact in your audience using the provided email address (if one doesn't already exist).
    * @param {Object} [params.dataVariables] Data variables as defined by the transational email template.
    * @param {Object[]} [params.attachments] File(s) to be sent along with the email message.
+   * @param {Object} [params.headers] Additional headers to send with the request.
    *
    * @see https://loops.so/docs/api-reference/send-transactional-email
    *
@@ -590,12 +606,14 @@ class LoopsClient {
     addToAudience,
     dataVariables,
     attachments,
+    headers,
   }: {
     transactionalId: string;
     email: string;
     addToAudience?: boolean;
     dataVariables?: TransactionalVariables;
     attachments?: Array<TransactionalAttachment>;
+    headers?: Record<string, string>;
   }): Promise<TransactionalSuccess> {
     const payload = {
       transactionalId,
@@ -607,6 +625,7 @@ class LoopsClient {
     return this._makeQuery({
       path: "v1/transactional",
       method: "POST",
+      headers,
       payload,
     });
   }