zupost 0.1.0 → 0.2.0

package/README.md

@@ -29,36 +29,53 @@ const zupost = new Zupost('your-api-key');
 
 ### Send an Email
 
+Zupost is **template first**: design your emails in the Zupost dashboard and send them by `templateId`, passing in dynamic `variables`. This is the recommended approach for almost all use cases — content stays out of your codebase, can be edited without a deploy, and benefits from Zupost's rendering pipeline.
+
+For ad-hoc or dynamically generated content, you can alternatively pass raw `html`, `markdown`, or a `react` component as a fallback.
+
 ```typescript
-// Send with HTML content
-const { emailId } = await zupost.emails.send({
+// Recommended: send with a template
+const { id } = await zupost.emails.send({
 	from: 'sender@example.com',
 	to: 'recipient@example.com',
-	subject: 'Hello World',
-	html: '<h1>Hello!</h1>',
+	templateId: 'welcome-template',
+	variables: { name: 'John' },
 });
 
-// Send to multiple recipients
+// Send to multiple recipients with a template
 await zupost.emails.send({
 	from: 'sender@example.com',
 	to: ['user1@example.com', 'user2@example.com'],
-	subject: 'Team Update',
-	markdown: '# Hello Team\n\nThis is a **markdown** email.',
+	templateId: 'team-update',
+	variables: { teamName: 'Engineering' },
+});
+```
+
+#### Fallback: inline content
+
+When a template is not a good fit, you can pass raw content instead. Exactly one of `html`, `markdown`, or `react` is required in that case.
+
+```typescript
+// Inline HTML
+await zupost.emails.send({
+	from: 'sender@example.com',
+	to: 'recipient@example.com',
+	subject: 'Hello World',
+	html: '<h1>Hello!</h1>',
 });
 
-// Send with a template
+// Inline markdown
 await zupost.emails.send({
 	from: 'sender@example.com',
 	to: 'recipient@example.com',
-	subject: 'Welcome!',
-	templateId: 'welcome-template',
-	variables: { name: 'John' },
+	subject: 'Team Update',
+	markdown: '# Hello Team\n\nThis is a **markdown** email.',
 });
 ```
 
-### Send with React Email
+### Send with React Email (fallback)
 
-Zupost supports [React Email](https://react.email) components out of the box.
+As an alternative to templates, Zupost supports [React Email](https://react.email) components out of the box.
 
 ```bash
 npm install @react-email/components

package/dist/index.d.mts

@@ -1,8 +1,26 @@
 import { Options } from '@react-email/render';
 import { ReactNode } from 'react';
 
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * @internal
+ * Internal HTTP client for the Zupost API. Not part of the public API surface.
+ */
+declare class HttpClient {
+    #private;
+    constructor(apiKey: string, baseUrl: string, userAgent: string);
+    request<T = unknown>(path: string, method: HttpMethod, body?: unknown): Promise<T>;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body: unknown): Promise<T>;
+}
+
 /**
  * Options for sending an email.
+ *
+ * Zupost is template first: the recommended way to send is by providing a
+ * `templateId` (managed in the Zupost dashboard) together with `variables`.
+ * `html`, `markdown`, and `react` are supported as fallbacks for ad-hoc or
+ * dynamically generated content. Exactly one content source is required.
  */
 interface SendEmailOptions {
     /**
@@ -33,23 +51,28 @@ interface SendEmailOptions {
      */
     bcc?: string | string[];
     /**
-     * ID of the email template to use.
+     * ID of the email template to use. Preferred way of sending: content and
+     * subject are managed in the Zupost dashboard and can be changed without a
+     * deploy. Combine with `variables` for interpolation.
      */
     templateId?: string;
     /**
-     * Variables for template interpolation.
+     * Variables for template interpolation. Used together with `templateId`.
      */
     variables?: Record<string, string>;
     /**
-     * Markdown content for the email.
+     * Markdown content for the email. Fallback to `templateId` — use for ad-hoc
+     * or dynamically generated content.
      */
     markdown?: string;
     /**
-     * HTML content for the email.
+     * HTML content for the email. Fallback to `templateId` — use for ad-hoc or
+     * dynamically generated content.
      */
     html?: string;
     /**
-     * React component for the email.
+     * React component for the email. Fallback to `templateId` — use for ad-hoc
+     * or dynamically generated content rendered via React Email.
      */
     react?: ReactNode;
     /**
@@ -99,36 +122,40 @@ interface SendEmailResponse {
  * Emails API for sending transactional emails.
  */
 declare class Emails {
-    private readonly zupost;
-    constructor(zupost: Zupost);
+    private readonly http;
+    constructor(http: HttpClient);
     /**
-     * Send an email using template, markdown or HTML content.
+     * Send an email.
+     *
+     * Zupost is template first: prefer sending by `templateId` with `variables`
+     * so your content lives in the Zupost dashboard and can be edited without a
+     * deploy. Inline `html`, `markdown`, or `react` content is supported as a
+     * fallback for ad-hoc or dynamically generated emails.
      *
      * @param options - Email options including recipient, sender, and content.
-     * @returns A promise that resolves to the email response containing emailId.
+     * @returns A promise that resolves to the email response containing the email id.
      *
      * @example
      * ```typescript
      * const zupost = new Zupost('your-api-key');
      *
-     * // Send with HTML content
-     * const { emailId } = await zupost.emails.send({
+     * // Recommended: send with a template
+     * const { id } = await zupost.emails.send({
      *   from: 'sender@example.com',
      *   to: 'recipient@example.com',
-     *   subject: 'Hello World',
-     *   html: '<h1>Hello!</h1>',
+     *   templateId: 'welcome-template',
+     *   variables: { name: 'John' },
      * });
      *
-     * // Send with a template
+     * // Fallback: inline HTML
      * await zupost.emails.send({
      *   from: 'sender@example.com',
-     *   to: ['user1@example.com', 'user2@example.com'],
-     *   subject: 'Welcome!',
-     *   templateId: 'welcome-template',
-     *   variables: { name: 'John' },
+     *   to: 'recipient@example.com',
+     *   subject: 'Hello World',
+     *   html: '<h1>Hello!</h1>',
      * });
      *
-     * // Send with markdown
+     * // Fallback: inline markdown
      * await zupost.emails.send({
      *   from: 'sender@example.com',
      *   to: 'recipient@example.com',
@@ -168,8 +195,8 @@ interface SendCampaignResponse {
  * Campaigns API for sending email campaigns to audiences.
  */
 declare class Campaigns {
-    private readonly zupost;
-    constructor(zupost: Zupost);
+    private readonly http;
+    constructor(http: HttpClient);
     /**
      * Send a campaign to selected audiences.
      *
@@ -199,8 +226,7 @@ interface ZupostOptions {
     baseUrl?: string;
 }
 declare class Zupost {
-    private readonly headers;
-    private readonly baseUrl;
+    #private;
     /**
      * Emails API for sending transactional emails.
      */
@@ -210,21 +236,27 @@ declare class Zupost {
      */
     readonly campaigns: Campaigns;
     constructor(apiKey: string, options?: ZupostOptions);
-    /**
-     * @internal
-     * Makes a request to the Zupost API.
-     */
-    request<T = unknown>(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown): Promise<T>;
-    /**
-     * @internal
-     * Makes a GET request to the Zupost API.
-     */
-    get<T = unknown>(path: string): Promise<T>;
-    /**
-     * @internal
-     * Makes a POST request to the Zupost API.
-     */
-    post<T = unknown>(path: string, body: unknown): Promise<T>;
 }
 
-export { type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, Zupost, type ZupostOptions };
+/**
+ * Error thrown when the Zupost API returns a non-2xx response.
+ */
+declare class ZupostError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    readonly requestId?: string;
+    readonly code?: string;
+    constructor(args: {
+        message: string;
+        status: number;
+        statusText: string;
+        body: string;
+        requestId?: string;
+        code?: string;
+    });
+    /** @internal */
+    static fromResponse(response: Response): Promise<ZupostError>;
+}
+
+export { type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, Zupost, ZupostError, type ZupostOptions };

package/dist/index.d.ts

@@ -1,8 +1,26 @@
 import { Options } from '@react-email/render';
 import { ReactNode } from 'react';
 
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+/**
+ * @internal
+ * Internal HTTP client for the Zupost API. Not part of the public API surface.
+ */
+declare class HttpClient {
+    #private;
+    constructor(apiKey: string, baseUrl: string, userAgent: string);
+    request<T = unknown>(path: string, method: HttpMethod, body?: unknown): Promise<T>;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body: unknown): Promise<T>;
+}
+
 /**
  * Options for sending an email.
+ *
+ * Zupost is template first: the recommended way to send is by providing a
+ * `templateId` (managed in the Zupost dashboard) together with `variables`.
+ * `html`, `markdown`, and `react` are supported as fallbacks for ad-hoc or
+ * dynamically generated content. Exactly one content source is required.
  */
 interface SendEmailOptions {
     /**
@@ -33,23 +51,28 @@ interface SendEmailOptions {
      */
     bcc?: string | string[];
     /**
-     * ID of the email template to use.
+     * ID of the email template to use. Preferred way of sending: content and
+     * subject are managed in the Zupost dashboard and can be changed without a
+     * deploy. Combine with `variables` for interpolation.
      */
     templateId?: string;
     /**
-     * Variables for template interpolation.
+     * Variables for template interpolation. Used together with `templateId`.
      */
     variables?: Record<string, string>;
     /**
-     * Markdown content for the email.
+     * Markdown content for the email. Fallback to `templateId` — use for ad-hoc
+     * or dynamically generated content.
      */
     markdown?: string;
     /**
-     * HTML content for the email.
+     * HTML content for the email. Fallback to `templateId` — use for ad-hoc or
+     * dynamically generated content.
      */
     html?: string;
     /**
-     * React component for the email.
+     * React component for the email. Fallback to `templateId` — use for ad-hoc
+     * or dynamically generated content rendered via React Email.
      */
     react?: ReactNode;
     /**
@@ -99,36 +122,40 @@ interface SendEmailResponse {
  * Emails API for sending transactional emails.
  */
 declare class Emails {
-    private readonly zupost;
-    constructor(zupost: Zupost);
+    private readonly http;
+    constructor(http: HttpClient);
     /**
-     * Send an email using template, markdown or HTML content.
+     * Send an email.
+     *
+     * Zupost is template first: prefer sending by `templateId` with `variables`
+     * so your content lives in the Zupost dashboard and can be edited without a
+     * deploy. Inline `html`, `markdown`, or `react` content is supported as a
+     * fallback for ad-hoc or dynamically generated emails.
      *
      * @param options - Email options including recipient, sender, and content.
-     * @returns A promise that resolves to the email response containing emailId.
+     * @returns A promise that resolves to the email response containing the email id.
      *
      * @example
      * ```typescript
      * const zupost = new Zupost('your-api-key');
      *
-     * // Send with HTML content
-     * const { emailId } = await zupost.emails.send({
+     * // Recommended: send with a template
+     * const { id } = await zupost.emails.send({
      *   from: 'sender@example.com',
      *   to: 'recipient@example.com',
-     *   subject: 'Hello World',
-     *   html: '<h1>Hello!</h1>',
+     *   templateId: 'welcome-template',
+     *   variables: { name: 'John' },
      * });
      *
-     * // Send with a template
+     * // Fallback: inline HTML
      * await zupost.emails.send({
      *   from: 'sender@example.com',
-     *   to: ['user1@example.com', 'user2@example.com'],
-     *   subject: 'Welcome!',
-     *   templateId: 'welcome-template',
-     *   variables: { name: 'John' },
+     *   to: 'recipient@example.com',
+     *   subject: 'Hello World',
+     *   html: '<h1>Hello!</h1>',
      * });
      *
-     * // Send with markdown
+     * // Fallback: inline markdown
      * await zupost.emails.send({
      *   from: 'sender@example.com',
      *   to: 'recipient@example.com',
@@ -168,8 +195,8 @@ interface SendCampaignResponse {
  * Campaigns API for sending email campaigns to audiences.
  */
 declare class Campaigns {
-    private readonly zupost;
-    constructor(zupost: Zupost);
+    private readonly http;
+    constructor(http: HttpClient);
     /**
      * Send a campaign to selected audiences.
      *
@@ -199,8 +226,7 @@ interface ZupostOptions {
     baseUrl?: string;
 }
 declare class Zupost {
-    private readonly headers;
-    private readonly baseUrl;
+    #private;
     /**
      * Emails API for sending transactional emails.
      */
@@ -210,21 +236,27 @@ declare class Zupost {
      */
     readonly campaigns: Campaigns;
     constructor(apiKey: string, options?: ZupostOptions);
-    /**
-     * @internal
-     * Makes a request to the Zupost API.
-     */
-    request<T = unknown>(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown): Promise<T>;
-    /**
-     * @internal
-     * Makes a GET request to the Zupost API.
-     */
-    get<T = unknown>(path: string): Promise<T>;
-    /**
-     * @internal
-     * Makes a POST request to the Zupost API.
-     */
-    post<T = unknown>(path: string, body: unknown): Promise<T>;
 }
 
-export { type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, Zupost, type ZupostOptions };
+/**
+ * Error thrown when the Zupost API returns a non-2xx response.
+ */
+declare class ZupostError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    readonly requestId?: string;
+    readonly code?: string;
+    constructor(args: {
+        message: string;
+        status: number;
+        statusText: string;
+        body: string;
+        requestId?: string;
+        code?: string;
+    });
+    /** @internal */
+    static fromResponse(response: Response): Promise<ZupostError>;
+}
+
+export { type SendCampaignOptions, type SendCampaignResponse, type SendEmailOptions, type SendEmailResponse, Zupost, ZupostError, type ZupostOptions };