@unsent/sdk 1.0.0 → 1.0.2

package/README.md

@@ -38,7 +38,7 @@ bun add @unsent/sdk
 ```typescript
 import { unsent } from "@unsent/sdk";
 
-const client = new unsent("us_12345");
+const client = new unsent("un_xxxx");
 ```
 
 ### Environment Variables
@@ -60,8 +60,8 @@ const { data, error } = await client.emails.send({
   to: "hello@acme.com",
   from: "hello@company.com",
   subject: "unsent email",
-  html: "<p>unsent is the best open source product to send emails</p>",
-  text: "unsent is the best open source product to send emails",
+  html: "<p>unsent is the best email service provider to send emails</p>",
+  text: "unsent is the best email service provider to send emails",
 });
 
 if (error) {
@@ -143,6 +143,60 @@ if (error) {
 }
 ```
 
+#### Idempotency Keys
+
+Safely retry email sends with an idempotency key to prevent duplicate sends. This is especially useful for critical emails like signup confirmations or password resets.
+
+```typescript
+// Safely retry sends with an idempotency key
+const { data, error } = await client.emails.send(
+  {
+    to: "hello@acme.com",
+    from: "hello@company.com",
+    subject: "unsent email",
+    html: "<p>unsent is the best open source product to send emails</p>",
+  },
+  { idempotencyKey: "signup-123" },
+);
+
+if (error) {
+  console.error("Error:", error);
+} else {
+  console.log("Email sent! ID:", data.id);
+}
+```
+
+Idempotency keys also work for batch sends:
+
+```typescript
+// Works for bulk sends too
+const { data, error } = await client.emails.batch(
+  [
+    {
+      to: "a@example.com",
+      from: "hello@company.com",
+      subject: "Welcome",
+      html: "<p>Hello A</p>",
+    },
+    {
+      to: "b@example.com",
+      from: "hello@company.com",
+      subject: "Welcome",
+      html: "<p>Hello B</p>",
+    },
+  ],
+  { idempotencyKey: "bulk-welcome-1" },
+);
+
+if (error) {
+  console.error("Error:", error);
+} else {
+  console.log(`Sent ${data.length} emails`);
+}
+```
+
+> **Note:** Reusing the same idempotency key with a different payload will return HTTP 409 (Conflict). This ensures that retries are safe and prevents accidental duplicate sends with modified content.
+
 ### Managing Emails
 
 #### Get Email Details
@@ -249,7 +303,7 @@ Create and manage email campaigns:
 ```typescript
 import { unsent } from "@unsent/sdk";
 
-const client = new unsent("us_12345");
+const client = new unsent("un_xxxx");
 
 // Create a campaign
 const campaign = await client.campaigns.create({
@@ -336,7 +390,7 @@ The SDK is fully typed with TypeScript:
 ```typescript
 import { unsent } from "@unsent/sdk";
 
-const client = new unsent("us_12345");
+const client = new unsent("un_xxxx");
 
 // Full type inference and autocomplete
 const result = await client.emails.send({

package/dist/index.d.mts

@@ -1312,6 +1312,12 @@ type BatchEmailPayload = paths["/v1/emails/batch"]["post"]["requestBody"]["conte
  * Successful response schema for batch email send.
  */
 type BatchEmailResponseSuccess = paths["/v1/emails/batch"]["post"]["responses"]["200"]["content"]["application/json"];
+/**
+ * Options for email requests.
+ */
+type EmailRequestOptions = {
+    idempotencyKey?: string;
+};
 /**
  * Response structure for the batch method.
  */
@@ -1322,15 +1328,15 @@ type BatchEmailResponse = {
 declare class Emails {
     private readonly unsent;
     constructor(unsent: unsent);
-    send(payload: SendEmailPayload): Promise<CreateEmailResponse>;
-    create(payload: SendEmailPayload): Promise<CreateEmailResponse>;
+    send(payload: SendEmailPayload, options?: EmailRequestOptions): Promise<CreateEmailResponse>;
+    create(payload: SendEmailPayload, options?: EmailRequestOptions): Promise<CreateEmailResponse>;
     /**
      * Send up to 100 emails in a single request.
      *
      * @param payload An array of email payloads. Max 100 emails.
      * @returns A promise that resolves to the list of created email IDs or an error.
      */
-    batch(payload: BatchEmailPayload): Promise<BatchEmailResponse>;
+    batch(payload: BatchEmailPayload, options?: EmailRequestOptions): Promise<BatchEmailResponse>;
     get(id: string): Promise<GetEmailResponse>;
     update(id: string, payload: UpdateEmailPayload): Promise<UpdateEmailResponse>;
     cancel(id: string): Promise<CancelEmailResponse>;
@@ -1419,7 +1425,9 @@ declare class unsent {
         data: T | null;
         error: ErrorResponse | null;
     }>;
-    post<T>(path: string, body: unknown): Promise<{
+    post<T>(path: string, body: unknown, options?: {
+        headers?: Record<string, string>;
+    }): Promise<{
         data: T | null;
         error: ErrorResponse | null;
     }>;

package/dist/index.d.ts

@@ -1312,6 +1312,12 @@ type BatchEmailPayload = paths["/v1/emails/batch"]["post"]["requestBody"]["conte
  * Successful response schema for batch email send.
  */
 type BatchEmailResponseSuccess = paths["/v1/emails/batch"]["post"]["responses"]["200"]["content"]["application/json"];
+/**
+ * Options for email requests.
+ */
+type EmailRequestOptions = {
+    idempotencyKey?: string;
+};
 /**
  * Response structure for the batch method.
  */
@@ -1322,15 +1328,15 @@ type BatchEmailResponse = {
 declare class Emails {
     private readonly unsent;
     constructor(unsent: unsent);
-    send(payload: SendEmailPayload): Promise<CreateEmailResponse>;
-    create(payload: SendEmailPayload): Promise<CreateEmailResponse>;
+    send(payload: SendEmailPayload, options?: EmailRequestOptions): Promise<CreateEmailResponse>;
+    create(payload: SendEmailPayload, options?: EmailRequestOptions): Promise<CreateEmailResponse>;
     /**
      * Send up to 100 emails in a single request.
      *
      * @param payload An array of email payloads. Max 100 emails.
      * @returns A promise that resolves to the list of created email IDs or an error.
      */
-    batch(payload: BatchEmailPayload): Promise<BatchEmailResponse>;
+    batch(payload: BatchEmailPayload, options?: EmailRequestOptions): Promise<BatchEmailResponse>;
     get(id: string): Promise<GetEmailResponse>;
     update(id: string, payload: UpdateEmailPayload): Promise<UpdateEmailResponse>;
     cancel(id: string): Promise<CancelEmailResponse>;
@@ -1419,7 +1425,9 @@ declare class unsent {
         data: T | null;
         error: ErrorResponse | null;
     }>;
-    post<T>(path: string, body: unknown): Promise<{
+    post<T>(path: string, body: unknown, options?: {
+        headers?: Record<string, string>;
+    }): Promise<{
         data: T | null;
         error: ErrorResponse | null;
     }>;

package/dist/index.js

@@ -73,17 +73,18 @@ var Emails = class {
     this.unsent = unsent2;
     this.unsent = unsent2;
   }
-  async send(payload) {
-    return this.create(payload);
+  async send(payload, options) {
+    return this.create(payload, options);
   }
-  async create(payload) {
+  async create(payload, options) {
     if (payload.react) {
       payload.html = await (0, import_render.render)(payload.react);
       delete payload.react;
     }
     const data = await this.unsent.post(
       "/emails",
-      payload
+      payload,
+      options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : void 0
     );
     return data;
   }
@@ -93,10 +94,11 @@ var Emails = class {
    * @param payload An array of email payloads. Max 100 emails.
    * @returns A promise that resolves to the list of created email IDs or an error.
    */
-  async batch(payload) {
+  async batch(payload, options) {
     const response = await this.unsent.post(
       "/emails/batch",
-      payload
+      payload,
+      options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : void 0
     );
     return {
       data: response.data ? response.data.data : null,
@@ -220,12 +222,12 @@ var unsent = class {
       }
       if (!this.key) {
         throw new Error(
-          'Missing API key. Pass it to the constructor `new unsent("us_123")`'
+          'Missing API key. Pass it to the constructor `new unsent("un_xxxx")`'
         );
       }
     }
     if (url) {
-      this.url = `${url}/api/v1`;
+      this.url = `${url}/v1`;
     }
     this.headers = new Headers({
       Authorization: `Bearer ${this.key}`,
@@ -239,7 +241,8 @@ var unsent = class {
   campaigns = new Campaigns(this);
   url = baseUrl;
   async fetchRequest(path, options = {}) {
-    const response = await fetch(`${this.url}${path}`, options);
+    const fullUrl = `${this.url}${path}`;
+    const response = await fetch(fullUrl, options);
     const defaultError = {
       code: "INTERNAL_SERVER_ERROR",
       message: response.statusText
@@ -261,13 +264,32 @@ var unsent = class {
         return { data: null, error: defaultError };
       }
     }
-    const data = await response.json();
-    return { data, error: null };
+    try {
+      const data = await response.json();
+      return { data, error: null };
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("JSON")) {
+        return {
+          data: null,
+          error: {
+            code: "INTERNAL_SERVER_ERROR",
+            message: "Invalid JSON response from server"
+          }
+        };
+      }
+      throw err;
+    }
   }
-  async post(path, body) {
+  async post(path, body, options) {
+    const headers = new Headers(this.headers);
+    if (options?.headers) {
+      Object.entries(options.headers).forEach(([key, value]) => {
+        headers.set(key, value);
+      });
+    }
     const requestOptions = {
       method: "POST",
-      headers: this.headers,
+      headers,
       body: JSON.stringify(body)
     };
     return this.fetchRequest(path, requestOptions);

package/dist/index.mjs

@@ -46,17 +46,18 @@ var Emails = class {
     this.unsent = unsent2;
     this.unsent = unsent2;
   }
-  async send(payload) {
-    return this.create(payload);
+  async send(payload, options) {
+    return this.create(payload, options);
   }
-  async create(payload) {
+  async create(payload, options) {
     if (payload.react) {
       payload.html = await render(payload.react);
       delete payload.react;
     }
     const data = await this.unsent.post(
       "/emails",
-      payload
+      payload,
+      options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : void 0
     );
     return data;
   }
@@ -66,10 +67,11 @@ var Emails = class {
    * @param payload An array of email payloads. Max 100 emails.
    * @returns A promise that resolves to the list of created email IDs or an error.
    */
-  async batch(payload) {
+  async batch(payload, options) {
     const response = await this.unsent.post(
       "/emails/batch",
-      payload
+      payload,
+      options?.idempotencyKey ? { headers: { "Idempotency-Key": options.idempotencyKey } } : void 0
     );
     return {
       data: response.data ? response.data.data : null,
@@ -193,12 +195,12 @@ var unsent = class {
       }
       if (!this.key) {
         throw new Error(
-          'Missing API key. Pass it to the constructor `new unsent("us_123")`'
+          'Missing API key. Pass it to the constructor `new unsent("un_xxxx")`'
         );
       }
     }
     if (url) {
-      this.url = `${url}/api/v1`;
+      this.url = `${url}/v1`;
     }
     this.headers = new Headers({
       Authorization: `Bearer ${this.key}`,
@@ -212,7 +214,8 @@ var unsent = class {
   campaigns = new Campaigns(this);
   url = baseUrl;
   async fetchRequest(path, options = {}) {
-    const response = await fetch(`${this.url}${path}`, options);
+    const fullUrl = `${this.url}${path}`;
+    const response = await fetch(fullUrl, options);
     const defaultError = {
       code: "INTERNAL_SERVER_ERROR",
       message: response.statusText
@@ -234,13 +237,32 @@ var unsent = class {
         return { data: null, error: defaultError };
       }
     }
-    const data = await response.json();
-    return { data, error: null };
+    try {
+      const data = await response.json();
+      return { data, error: null };
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("JSON")) {
+        return {
+          data: null,
+          error: {
+            code: "INTERNAL_SERVER_ERROR",
+            message: "Invalid JSON response from server"
+          }
+        };
+      }
+      throw err;
+    }
   }
-  async post(path, body) {
+  async post(path, body, options) {
+    const headers = new Headers(this.headers);
+    if (options?.headers) {
+      Object.entries(options.headers).forEach(([key, value]) => {
+        headers.set(key, value);
+      });
+    }
     const requestOptions = {
       method: "POST",
-      headers: this.headers,
+      headers,
       body: JSON.stringify(body)
     };
     return this.fetchRequest(path, requestOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unsent/sdk",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "TypeScript SDK for the Unsent API - Send transactional emails with ease",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -31,7 +31,7 @@
     "@types/node": "^24.7.0",
     "@types/react": "^19.1.2",
     "openapi-typescript": "^7.6.1",
-    "tsup": "^8.4.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "@unsent/typescript-config": "0.0.0"
   },