zupost 0.0.0 → 0.1.0

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.
Files changed (7) hide show
  1. package/LICENSE +9 -0
  2. package/README.md +119 -0
  3. package/dist/index.d.mts +202 -29
  4. package/dist/index.d.ts +202 -29
  5. package/dist/index.js +531 -171
  6. package/dist/index.mjs +531 -171
  7. package/package.json +17 -8
package/LICENSE ADDED
@@ -0,0 +1,9 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Zupost
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,119 @@
1
+ <img src="./.github/banner.png">
2
+
3
+ <br />
4
+
5
+ <div align="center"><strong>Node SDK</strong></div>
6
+ <div align="center">Use your favorite mail provider Zupost, seamless with our node SDK. </div>
7
+
8
+ <br />
9
+
10
+ ## Introduction
11
+
12
+ Zupost is a mail provider that allows you to send emails easily and efficiently. This SDK allows you to integrate Zupost easily into your Node.js applications.
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ npm install zupost
18
+ ```
19
+
20
+ ## Usage Examples
21
+
22
+ ### Initialize the Client
23
+
24
+ ```typescript
25
+ import { Zupost } from 'zupost';
26
+
27
+ const zupost = new Zupost('your-api-key');
28
+ ```
29
+
30
+ ### Send an Email
31
+
32
+ ```typescript
33
+ // Send with HTML content
34
+ const { emailId } = await zupost.emails.send({
35
+ from: 'sender@example.com',
36
+ to: 'recipient@example.com',
37
+ subject: 'Hello World',
38
+ html: '<h1>Hello!</h1>',
39
+ });
40
+
41
+ // Send to multiple recipients
42
+ await zupost.emails.send({
43
+ from: 'sender@example.com',
44
+ to: ['user1@example.com', 'user2@example.com'],
45
+ subject: 'Team Update',
46
+ markdown: '# Hello Team\n\nThis is a **markdown** email.',
47
+ });
48
+
49
+ // Send with a template
50
+ await zupost.emails.send({
51
+ from: 'sender@example.com',
52
+ to: 'recipient@example.com',
53
+ subject: 'Welcome!',
54
+ templateId: 'welcome-template',
55
+ variables: { name: 'John' },
56
+ });
57
+ ```
58
+
59
+ ### Send with React Email
60
+
61
+ Zupost supports [React Email](https://react.email) components out of the box.
62
+
63
+ ```bash
64
+ npm install @react-email/components
65
+ ```
66
+
67
+ ```tsx
68
+ import { Zupost } from 'zupost';
69
+ import { Html, Head, Body, Container, Text } from '@react-email/components';
70
+
71
+ const WelcomeEmail = ({ name }: { name: string }) => (
72
+ <Html>
73
+ <Head />
74
+ <Body>
75
+ <Container>
76
+ <Text>Hello {name}!</Text>
77
+ <Text>Welcome to our platform.</Text>
78
+ </Container>
79
+ </Body>
80
+ </Html>
81
+ );
82
+
83
+ const zupost = new Zupost('your-api-key');
84
+
85
+ await zupost.emails.send({
86
+ from: 'sender@example.com',
87
+ to: 'recipient@example.com',
88
+ subject: 'Welcome!',
89
+ react: <WelcomeEmail name="John" />,
90
+ });
91
+ ```
92
+
93
+ ### Send a Campaign
94
+
95
+ ```typescript
96
+ const { success, message } = await zupost.campaigns.send({
97
+ campaignId: 'campaign_123',
98
+ });
99
+
100
+ if (success) {
101
+ console.log('Campaign sent:', message);
102
+ }
103
+ ```
104
+
105
+ ### Configuration Options
106
+
107
+ ```typescript
108
+ const zupost = new Zupost('your-api-key', {
109
+ baseUrl: 'https://custom-api.zupost.com', // Optional: custom API URL
110
+ });
111
+ ```
112
+
113
+ ## Contributing
114
+
115
+ We welcome contributions! Please open an issue or submit a pull request.
116
+
117
+ ## License
118
+
119
+ This SDK is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
package/dist/index.d.mts CHANGED
@@ -1,57 +1,230 @@
1
- interface CreateEmailContent {
1
+ import { Options } from '@react-email/render';
2
+ import { ReactNode } from 'react';
3
+
4
+ /**
5
+ * Options for sending an email.
6
+ */
7
+ interface SendEmailOptions {
2
8
  /**
3
- * HTML content of the email body.
9
+ * Sender email address.
10
+ * @example "sender@example.com"
4
11
  */
5
- html: string;
12
+ from: string;
6
13
  /**
7
- * Plain text content of the email body.
14
+ * Recipient email address(es).
15
+ * @example "recipient@example.com" or ["a@example.com", "b@example.com"]
8
16
  */
9
- text: string;
10
- }
11
- interface CreateEmailOptions {
17
+ to: string | string[];
12
18
  /**
13
- * Email address of the recipient. Use an array for multiple recipients (up to 50).
19
+ * Email subject.
20
+ * @example "Hello World"
14
21
  */
15
- to: string | string[];
22
+ subject?: string;
16
23
  /**
17
- * Email address of the sender. To add a display name, use: "Name <email@domain.com>".
24
+ * Reply-to email address(es).
18
25
  */
19
- from: string;
26
+ replyTo?: string | string[];
20
27
  /**
21
- * BCC recipient(s). Use a string or an array for multiple addresses.
28
+ * CC recipient(s).
29
+ */
30
+ cc?: string | string[];
31
+ /**
32
+ * BCC recipient(s).
22
33
  */
23
34
  bcc?: string | string[];
24
35
  /**
25
- * CC recipient(s). Use a string or an array for multiple addresses.
36
+ * ID of the email template to use.
26
37
  */
27
- cc?: string | string[];
38
+ templateId?: string;
28
39
  /**
29
- * Additional custom headers for the email.
40
+ * Variables for template interpolation.
30
41
  */
31
- headers?: Record<string, string>;
42
+ variables?: Record<string, string>;
32
43
  /**
33
- * Reply-to address(es). Use a string or an array for multiple addresses.
44
+ * Markdown content for the email.
34
45
  */
35
- replyTo?: string | string[];
46
+ markdown?: string;
47
+ /**
48
+ * HTML content for the email.
49
+ */
50
+ html?: string;
51
+ /**
52
+ * React component for the email.
53
+ */
54
+ react?: ReactNode;
36
55
  /**
37
- * Subject line of the email.
56
+ * Options for the React email renderer.
38
57
  */
39
- subject: string;
58
+ reactOptions?: Options;
40
59
  /**
41
- * Schedule the email for future delivery (ISO 8601 format, e.g., 2024-08-05T11:52:01.858Z).
60
+ * Plain text content for the email.
42
61
  */
43
- scheduledAt?: string;
62
+ text?: string;
63
+ /**
64
+ * Attachments for the email. Each attachment must be an object with the following properties:
65
+ *
66
+ * @property filename - The name of the file as it will appear in the email (e.g., "document.pdf").
67
+ * @property content - The file content as a Base64-encoded string (e.g., "JVBERi0xLjQKJ...").
68
+ *
69
+ * @example
70
+ * attachments: [
71
+ * {
72
+ * filename: "example.pdf",
73
+ * content: "JVBERi0xLjQKJ..."
74
+ * },
75
+ * {
76
+ * filename: "image.png",
77
+ * content: "iVBORw0KGgoAAAANSUhEUg..."
78
+ * }
79
+ * ]
80
+ */
81
+ attachments?: Array<{
82
+ /** The name of the file as it will appear in the email (e.g., "document.pdf"). */
83
+ filename: string;
84
+ /** The file content as a Base64-encoded string (e.g., "JVBERi0xLjQKJ..."). */
85
+ content: string;
86
+ }>;
87
+ }
88
+ /**
89
+ * Response from sending an email.
90
+ */
91
+ interface SendEmailResponse {
92
+ /**
93
+ * Unique identifier of the sent email.
94
+ */
95
+ id: string;
96
+ }
97
+
98
+ /**
99
+ * Emails API for sending transactional emails.
100
+ */
101
+ declare class Emails {
102
+ private readonly zupost;
103
+ constructor(zupost: Zupost);
104
+ /**
105
+ * Send an email using template, markdown or HTML content.
106
+ *
107
+ * @param options - Email options including recipient, sender, and content.
108
+ * @returns A promise that resolves to the email response containing emailId.
109
+ *
110
+ * @example
111
+ * ```typescript
112
+ * const zupost = new Zupost('your-api-key');
113
+ *
114
+ * // Send with HTML content
115
+ * const { emailId } = await zupost.emails.send({
116
+ * from: 'sender@example.com',
117
+ * to: 'recipient@example.com',
118
+ * subject: 'Hello World',
119
+ * html: '<h1>Hello!</h1>',
120
+ * });
121
+ *
122
+ * // Send with a template
123
+ * await zupost.emails.send({
124
+ * from: 'sender@example.com',
125
+ * to: ['user1@example.com', 'user2@example.com'],
126
+ * subject: 'Welcome!',
127
+ * templateId: 'welcome-template',
128
+ * variables: { name: 'John' },
129
+ * });
130
+ *
131
+ * // Send with markdown
132
+ * await zupost.emails.send({
133
+ * from: 'sender@example.com',
134
+ * to: 'recipient@example.com',
135
+ * subject: 'Newsletter',
136
+ * markdown: '# Hello\n\nThis is **markdown** content.',
137
+ * });
138
+ * ```
139
+ */
140
+ send(options: SendEmailOptions): Promise<SendEmailResponse>;
44
141
  }
45
142
 
143
+ /**
144
+ * Options for sending a campaign.
145
+ */
146
+ interface SendCampaignOptions {
147
+ /**
148
+ * ID of the campaign to send.
149
+ * @example "campaign_123"
150
+ */
151
+ campaignId: string;
152
+ }
153
+ /**
154
+ * Response from sending a campaign.
155
+ */
156
+ interface SendCampaignResponse {
157
+ /**
158
+ * Whether the campaign was successfully initiated.
159
+ */
160
+ success: boolean;
161
+ /**
162
+ * A message regarding the campaign status.
163
+ */
164
+ message: string;
165
+ }
166
+
167
+ /**
168
+ * Campaigns API for sending email campaigns to audiences.
169
+ */
170
+ declare class Campaigns {
171
+ private readonly zupost;
172
+ constructor(zupost: Zupost);
173
+ /**
174
+ * Send a campaign to selected audiences.
175
+ *
176
+ * @param options - Campaign options including the campaign ID.
177
+ * @returns A promise that resolves to the campaign response.
178
+ *
179
+ * @example
180
+ * ```typescript
181
+ * const zupost = new Zupost('your-api-key');
182
+ *
183
+ * const { success, message } = await zupost.campaigns.send({
184
+ * campaignId: 'campaign_123',
185
+ * });
186
+ *
187
+ * if (success) {
188
+ * console.log('Campaign sent:', message);
189
+ * }
190
+ * ```
191
+ */
192
+ send(options: SendCampaignOptions): Promise<SendCampaignResponse>;
193
+ }
194
+
195
+ interface ZupostOptions {
196
+ /**
197
+ * Custom API URL. Defaults to 'https://api.zupost.com'.
198
+ */
199
+ baseUrl?: string;
200
+ }
46
201
  declare class Zupost {
47
- readonly apiKey: string;
48
- readonly apiUrl?: string | undefined;
49
202
  private readonly headers;
50
203
  private readonly baseUrl;
51
- constructor(apiKey: string, apiUrl?: string | undefined);
52
- request(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: BodyInit): Promise<unknown>;
53
- get(path: string): Promise<unknown>;
54
- post(path: string, body: BodyInit): Promise<unknown>;
204
+ /**
205
+ * Emails API for sending transactional emails.
206
+ */
207
+ readonly emails: Emails;
208
+ /**
209
+ * Campaigns API for sending email campaigns to audiences.
210
+ */
211
+ readonly campaigns: Campaigns;
212
+ constructor(apiKey: string, options?: ZupostOptions);
213
+ /**
214
+ * @internal
215
+ * Makes a request to the Zupost API.
216
+ */
217
+ request<T = unknown>(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown): Promise<T>;
218
+ /**
219
+ * @internal
220
+ * Makes a GET request to the Zupost API.
221
+ */
222
+ get<T = unknown>(path: string): Promise<T>;
223
+ /**
224
+ * @internal
225
+ * Makes a POST request to the Zupost API.
226
+ */
227
+ post<T = unknown>(path: string, body: unknown): Promise<T>;
55
228
  }
56
229
 
57
- export { type CreateEmailContent, type CreateEmailOptions, Zupost };
230
+ export { type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, Zupost, type ZupostOptions };
package/dist/index.d.ts CHANGED
@@ -1,57 +1,230 @@
1
- interface CreateEmailContent {
1
+ import { Options } from '@react-email/render';
2
+ import { ReactNode } from 'react';
3
+
4
+ /**
5
+ * Options for sending an email.
6
+ */
7
+ interface SendEmailOptions {
2
8
  /**
3
- * HTML content of the email body.
9
+ * Sender email address.
10
+ * @example "sender@example.com"
4
11
  */
5
- html: string;
12
+ from: string;
6
13
  /**
7
- * Plain text content of the email body.
14
+ * Recipient email address(es).
15
+ * @example "recipient@example.com" or ["a@example.com", "b@example.com"]
8
16
  */
9
- text: string;
10
- }
11
- interface CreateEmailOptions {
17
+ to: string | string[];
12
18
  /**
13
- * Email address of the recipient. Use an array for multiple recipients (up to 50).
19
+ * Email subject.
20
+ * @example "Hello World"
14
21
  */
15
- to: string | string[];
22
+ subject?: string;
16
23
  /**
17
- * Email address of the sender. To add a display name, use: "Name <email@domain.com>".
24
+ * Reply-to email address(es).
18
25
  */
19
- from: string;
26
+ replyTo?: string | string[];
20
27
  /**
21
- * BCC recipient(s). Use a string or an array for multiple addresses.
28
+ * CC recipient(s).
29
+ */
30
+ cc?: string | string[];
31
+ /**
32
+ * BCC recipient(s).
22
33
  */
23
34
  bcc?: string | string[];
24
35
  /**
25
- * CC recipient(s). Use a string or an array for multiple addresses.
36
+ * ID of the email template to use.
26
37
  */
27
- cc?: string | string[];
38
+ templateId?: string;
28
39
  /**
29
- * Additional custom headers for the email.
40
+ * Variables for template interpolation.
30
41
  */
31
- headers?: Record<string, string>;
42
+ variables?: Record<string, string>;
32
43
  /**
33
- * Reply-to address(es). Use a string or an array for multiple addresses.
44
+ * Markdown content for the email.
34
45
  */
35
- replyTo?: string | string[];
46
+ markdown?: string;
47
+ /**
48
+ * HTML content for the email.
49
+ */
50
+ html?: string;
51
+ /**
52
+ * React component for the email.
53
+ */
54
+ react?: ReactNode;
36
55
  /**
37
- * Subject line of the email.
56
+ * Options for the React email renderer.
38
57
  */
39
- subject: string;
58
+ reactOptions?: Options;
40
59
  /**
41
- * Schedule the email for future delivery (ISO 8601 format, e.g., 2024-08-05T11:52:01.858Z).
60
+ * Plain text content for the email.
42
61
  */
43
- scheduledAt?: string;
62
+ text?: string;
63
+ /**
64
+ * Attachments for the email. Each attachment must be an object with the following properties:
65
+ *
66
+ * @property filename - The name of the file as it will appear in the email (e.g., "document.pdf").
67
+ * @property content - The file content as a Base64-encoded string (e.g., "JVBERi0xLjQKJ...").
68
+ *
69
+ * @example
70
+ * attachments: [
71
+ * {
72
+ * filename: "example.pdf",
73
+ * content: "JVBERi0xLjQKJ..."
74
+ * },
75
+ * {
76
+ * filename: "image.png",
77
+ * content: "iVBORw0KGgoAAAANSUhEUg..."
78
+ * }
79
+ * ]
80
+ */
81
+ attachments?: Array<{
82
+ /** The name of the file as it will appear in the email (e.g., "document.pdf"). */
83
+ filename: string;
84
+ /** The file content as a Base64-encoded string (e.g., "JVBERi0xLjQKJ..."). */
85
+ content: string;
86
+ }>;
87
+ }
88
+ /**
89
+ * Response from sending an email.
90
+ */
91
+ interface SendEmailResponse {
92
+ /**
93
+ * Unique identifier of the sent email.
94
+ */
95
+ id: string;
96
+ }
97
+
98
+ /**
99
+ * Emails API for sending transactional emails.
100
+ */
101
+ declare class Emails {
102
+ private readonly zupost;
103
+ constructor(zupost: Zupost);
104
+ /**
105
+ * Send an email using template, markdown or HTML content.
106
+ *
107
+ * @param options - Email options including recipient, sender, and content.
108
+ * @returns A promise that resolves to the email response containing emailId.
109
+ *
110
+ * @example
111
+ * ```typescript
112
+ * const zupost = new Zupost('your-api-key');
113
+ *
114
+ * // Send with HTML content
115
+ * const { emailId } = await zupost.emails.send({
116
+ * from: 'sender@example.com',
117
+ * to: 'recipient@example.com',
118
+ * subject: 'Hello World',
119
+ * html: '<h1>Hello!</h1>',
120
+ * });
121
+ *
122
+ * // Send with a template
123
+ * await zupost.emails.send({
124
+ * from: 'sender@example.com',
125
+ * to: ['user1@example.com', 'user2@example.com'],
126
+ * subject: 'Welcome!',
127
+ * templateId: 'welcome-template',
128
+ * variables: { name: 'John' },
129
+ * });
130
+ *
131
+ * // Send with markdown
132
+ * await zupost.emails.send({
133
+ * from: 'sender@example.com',
134
+ * to: 'recipient@example.com',
135
+ * subject: 'Newsletter',
136
+ * markdown: '# Hello\n\nThis is **markdown** content.',
137
+ * });
138
+ * ```
139
+ */
140
+ send(options: SendEmailOptions): Promise<SendEmailResponse>;
44
141
  }
45
142
 
143
+ /**
144
+ * Options for sending a campaign.
145
+ */
146
+ interface SendCampaignOptions {
147
+ /**
148
+ * ID of the campaign to send.
149
+ * @example "campaign_123"
150
+ */
151
+ campaignId: string;
152
+ }
153
+ /**
154
+ * Response from sending a campaign.
155
+ */
156
+ interface SendCampaignResponse {
157
+ /**
158
+ * Whether the campaign was successfully initiated.
159
+ */
160
+ success: boolean;
161
+ /**
162
+ * A message regarding the campaign status.
163
+ */
164
+ message: string;
165
+ }
166
+
167
+ /**
168
+ * Campaigns API for sending email campaigns to audiences.
169
+ */
170
+ declare class Campaigns {
171
+ private readonly zupost;
172
+ constructor(zupost: Zupost);
173
+ /**
174
+ * Send a campaign to selected audiences.
175
+ *
176
+ * @param options - Campaign options including the campaign ID.
177
+ * @returns A promise that resolves to the campaign response.
178
+ *
179
+ * @example
180
+ * ```typescript
181
+ * const zupost = new Zupost('your-api-key');
182
+ *
183
+ * const { success, message } = await zupost.campaigns.send({
184
+ * campaignId: 'campaign_123',
185
+ * });
186
+ *
187
+ * if (success) {
188
+ * console.log('Campaign sent:', message);
189
+ * }
190
+ * ```
191
+ */
192
+ send(options: SendCampaignOptions): Promise<SendCampaignResponse>;
193
+ }
194
+
195
+ interface ZupostOptions {
196
+ /**
197
+ * Custom API URL. Defaults to 'https://api.zupost.com'.
198
+ */
199
+ baseUrl?: string;
200
+ }
46
201
  declare class Zupost {
47
- readonly apiKey: string;
48
- readonly apiUrl?: string | undefined;
49
202
  private readonly headers;
50
203
  private readonly baseUrl;
51
- constructor(apiKey: string, apiUrl?: string | undefined);
52
- request(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: BodyInit): Promise<unknown>;
53
- get(path: string): Promise<unknown>;
54
- post(path: string, body: BodyInit): Promise<unknown>;
204
+ /**
205
+ * Emails API for sending transactional emails.
206
+ */
207
+ readonly emails: Emails;
208
+ /**
209
+ * Campaigns API for sending email campaigns to audiences.
210
+ */
211
+ readonly campaigns: Campaigns;
212
+ constructor(apiKey: string, options?: ZupostOptions);
213
+ /**
214
+ * @internal
215
+ * Makes a request to the Zupost API.
216
+ */
217
+ request<T = unknown>(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown): Promise<T>;
218
+ /**
219
+ * @internal
220
+ * Makes a GET request to the Zupost API.
221
+ */
222
+ get<T = unknown>(path: string): Promise<T>;
223
+ /**
224
+ * @internal
225
+ * Makes a POST request to the Zupost API.
226
+ */
227
+ post<T = unknown>(path: string, body: unknown): Promise<T>;
55
228
  }
56
229
 
57
- export { type CreateEmailContent, type CreateEmailOptions, Zupost };
230
+ export { type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, Zupost, type ZupostOptions };