@unsent/sdk 0.25.5 → 1.0.1

package/README.md

@@ -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
@@ -400,3 +454,9 @@ if (result.data) {
 ## License
 
 MIT
+
+## Support
+
+- [Documentation](https://docs.unsent.dev)
+- [GitHub Issues](https://github.com/souravsspace/unsent-typescript/issues)
+- [Discord Community](https://discord.gg/unsent)

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,
@@ -206,9 +208,9 @@ var Campaigns = class {
 };
 
 // src/unsent.ts
-var defaultBaseUrl = "https://app.unsent.dev";
-var baseUrl = `${process?.env?.UNSENT_BASE_URL ?? process?.env?.UNSENT_BASE_URL ?? defaultBaseUrl}/api/v1`;
-function isunsentErrorResponse(error) {
+var defaultBaseUrl = "https://api.unsent.dev";
+var baseUrl = `${process?.env?.UNSENT_BASE_URL ?? process?.env?.UNSENT_BASE_URL ?? defaultBaseUrl}/v1`;
+function isUnsentErrorResponse(error) {
   return error.error.code !== void 0;
 }
 var unsent = class {
@@ -216,7 +218,7 @@ var unsent = class {
     this.key = key;
     if (!key) {
       if (typeof process !== "undefined" && process.env) {
-        this.key = process.env.unsent_API_KEY ?? process.env.UNSENT_API_KEY;
+        this.key = process.env.UNSENT_API_KEY ?? process.env.UNSENT_API_KEY;
       }
       if (!this.key) {
         throw new Error(
@@ -247,7 +249,7 @@ var unsent = class {
     if (!response.ok) {
       try {
         const resp = await response.json();
-        if (isunsentErrorResponse(resp)) {
+        if (isUnsentErrorResponse(resp)) {
           return { data: null, error: resp };
         }
         return { data: null, error: resp.error };
@@ -264,10 +266,16 @@ var unsent = class {
     const data = await response.json();
     return { data, error: null };
   }
-  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,
@@ -179,9 +181,9 @@ var Campaigns = class {
 };
 
 // src/unsent.ts
-var defaultBaseUrl = "https://app.unsent.dev";
-var baseUrl = `${process?.env?.UNSENT_BASE_URL ?? process?.env?.UNSENT_BASE_URL ?? defaultBaseUrl}/api/v1`;
-function isunsentErrorResponse(error) {
+var defaultBaseUrl = "https://api.unsent.dev";
+var baseUrl = `${process?.env?.UNSENT_BASE_URL ?? process?.env?.UNSENT_BASE_URL ?? defaultBaseUrl}/v1`;
+function isUnsentErrorResponse(error) {
   return error.error.code !== void 0;
 }
 var unsent = class {
@@ -189,7 +191,7 @@ var unsent = class {
     this.key = key;
     if (!key) {
       if (typeof process !== "undefined" && process.env) {
-        this.key = process.env.unsent_API_KEY ?? process.env.UNSENT_API_KEY;
+        this.key = process.env.UNSENT_API_KEY ?? process.env.UNSENT_API_KEY;
       }
       if (!this.key) {
         throw new Error(
@@ -220,7 +222,7 @@ var unsent = class {
     if (!response.ok) {
       try {
         const resp = await response.json();
-        if (isunsentErrorResponse(resp)) {
+        if (isUnsentErrorResponse(resp)) {
           return { data: null, error: resp };
         }
         return { data: null, error: resp.error };
@@ -237,10 +239,16 @@ var unsent = class {
     const data = await response.json();
     return { data, error: null };
   }
-  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,20 +1,39 @@
 {
   "name": "@unsent/sdk",
-  "version": "0.25.5",
-  "description": "",
+  "version": "1.0.1",
+  "description": "TypeScript SDK for the Unsent API - Send transactional emails with ease",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "keywords": [],
-  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/souravsspace/unsent-typescript.git"
+  },
+  "homepage": "https://unsent.dev",
+  "bugs": {
+    "url": "https://github.com/souravsspace/unsent-typescript/issues"
+  },
+  "keywords": [
+    "unsent",
+    "email",
+    "transactional-email",
+    "api",
+    "sdk",
+    "typescript",
+    "react-email"
+  ],
+  "author": "sourav",
   "license": "MIT",
+  "files": [
+    "dist"
+  ],
   "devDependencies": {
     "@types/node": "^24.7.0",
     "@types/react": "^19.1.2",
     "openapi-typescript": "^7.6.1",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
-    "@workspace/typescript-config": "0.0.0"
+    "@unsent/typescript-config": "0.0.0"
   },
   "dependencies": {
     "@react-email/render": "^1.0.6",