@zyphr-dev/node-sdk 0.1.22 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zyphr-dev/node-sdk",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Official Zyphr SDK for Node.js, React, and React Native",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -28,6 +28,9 @@
     "build": "tsup",
     "lint": "tsc --noEmit",
     "test": "echo 'No tests yet for generated SDK'",
+    "examples:typecheck": "tsc --noEmit -p examples/tsconfig.json",
+    "readme:check": "node ../scripts/verify-readme-methods.mjs",
+    "verify": "yarn lint && yarn examples:typecheck && yarn readme:check",
     "clean": "rm -rf dist"
   },
   "devDependencies": {

package/src/.openapi-generator/FILES

@@ -66,6 +66,7 @@ src/models/AuthUser.ts
 src/models/AuthUserResponse.ts
 src/models/AuthUserResponseData.ts
 src/models/BatchPublishWaaSEvents201Response.ts
+src/models/BatchRecipient.ts
 src/models/BulkRetryWebhookDeliveriesRequest.ts
 src/models/BulkUpsertAuthEmailTemplatesRequest.ts
 src/models/BulkUpsertAuthEmailTemplatesResponse.ts

package/src/errors.ts

@@ -82,6 +82,26 @@ export class ZyphrNotFoundError extends ZyphrError {
   }
 }
 
+/**
+ * Thrown when a Zyphr webhook signature fails verification.
+ *
+ * Use the verification helper shown in `examples/14-webhook-handler.ts`
+ * (or write your own) to detect tampered or replayed webhook deliveries.
+ */
+export class ZyphrWebhookVerificationError extends ZyphrError {
+  constructor(message: string) {
+    super({ message, status: 401, code: 'webhook_verification_failed' });
+    this.name = 'ZyphrWebhookVerificationError';
+  }
+}
+
+/**
+ * Alias for {@link ZyphrWebhookVerificationError}. Provided for symmetry with
+ * `Zyphr*Error` naming and shorter import statements in webhook handlers.
+ */
+export const WebhookVerificationError = ZyphrWebhookVerificationError;
+export type WebhookVerificationError = ZyphrWebhookVerificationError;
+
 /**
  * Parse an API error response and throw the appropriate ZyphrError subclass.
  */

package/src/src/apis/EmailsApi.ts

@@ -148,7 +148,7 @@ export interface EmailsApiInterface {
     listEmails(status?: ListEmailsStatusEnum, tag?: string, limit?: number, offset?: number, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<EmailListResponse>;
 
     /**
-     * Send up to 100 emails in a single request. Each recipient gets their own message record.
+     * Send a single email to up to 100 recipients in one request. Each recipient gets their own message record. Provide either raw content (`subject` plus `html` and/or `text`) or a `template_id` with `template_data`. Per-recipient `variables` are merged on top of the batch-level `template_data`. 
      * @summary Send batch emails
      * @param {SendBatchEmailRequest} sendBatchEmailRequest 
      * @param {*} [options] Override http request option.
@@ -158,7 +158,7 @@ export interface EmailsApiInterface {
     sendBatchEmailRaw(requestParameters: EmailsApiSendBatchEmailOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SendBatchEmailResponse>>;
 
     /**
-     * Send up to 100 emails in a single request. Each recipient gets their own message record.
+     * Send a single email to up to 100 recipients in one request. Each recipient gets their own message record. Provide either raw content (`subject` plus `html` and/or `text`) or a `template_id` with `template_data`. Per-recipient `variables` are merged on top of the batch-level `template_data`. 
      * Send batch emails
      */
     sendBatchEmail(sendBatchEmailRequest: SendBatchEmailRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SendBatchEmailResponse>;
@@ -352,7 +352,7 @@ export class EmailsApi extends runtime.BaseAPI implements EmailsApiInterface {
     }
 
     /**
-     * Send up to 100 emails in a single request. Each recipient gets their own message record.
+     * Send a single email to up to 100 recipients in one request. Each recipient gets their own message record. Provide either raw content (`subject` plus `html` and/or `text`) or a `template_id` with `template_data`. Per-recipient `variables` are merged on top of the batch-level `template_data`. 
      * Send batch emails
      */
     async sendBatchEmailRaw(requestParameters: EmailsApiSendBatchEmailOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<SendBatchEmailResponse>> {
@@ -385,7 +385,7 @@ export class EmailsApi extends runtime.BaseAPI implements EmailsApiInterface {
     }
 
     /**
-     * Send up to 100 emails in a single request. Each recipient gets their own message record.
+     * Send a single email to up to 100 recipients in one request. Each recipient gets their own message record. Provide either raw content (`subject` plus `html` and/or `text`) or a `template_id` with `template_data`. Per-recipient `variables` are merged on top of the batch-level `template_data`. 
      * Send batch emails
      */
     async sendBatchEmail(sendBatchEmailRequest: SendBatchEmailRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<SendBatchEmailResponse> {

package/src/src/models/BatchRecipient.ts

@@ -0,0 +1,83 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Zyphr API
+ * Zyphr is a multi-channel notification platform that enables developers to send emails, push notifications, SMS, and in-app messages through a unified API.  ## Authentication  All API requests require authentication using an API key. Include your API key in the `X-API-Key` header:  ``` X-API-Key: zy_live_xxxxxxxxxxxx ```  API keys can be created in the Zyphr Dashboard. Use `zy_test_*` keys for testing and `zy_live_*` keys for production.  ## Rate Limiting  The API implements rate limiting to ensure fair usage. Rate limit information is included in response headers:  - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp when the window resets  ## Errors  All errors follow a consistent format:  ```json {   \"error\": {     \"code\": \"error_code\",     \"message\": \"Human readable message\",     \"details\": {}   },   \"meta\": {     \"request_id\": \"req_xxxx\"   } } ```
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * Contact: support@zyphr.dev
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+/**
+ * 
+ * @export
+ * @interface BatchRecipient
+ */
+export interface BatchRecipient {
+    /**
+     * 
+     * @type {string}
+     * @memberof BatchRecipient
+     */
+    email: string;
+    /**
+     * 
+     * @type {string}
+     * @memberof BatchRecipient
+     */
+    name?: string;
+    /**
+     * Per-recipient template variables. Merged on top of the batch-level `template_data`, so per-recipient values win on key collisions.
+     * 
+     * @type {{ [key: string]: any; }}
+     * @memberof BatchRecipient
+     */
+    variables?: { [key: string]: any; };
+}
+
+/**
+ * Check if a given object implements the BatchRecipient interface.
+ */
+export function instanceOfBatchRecipient(value: object): value is BatchRecipient {
+    if (!('email' in value) || value['email'] === undefined) return false;
+    return true;
+}
+
+export function BatchRecipientFromJSON(json: any): BatchRecipient {
+    return BatchRecipientFromJSONTyped(json, false);
+}
+
+export function BatchRecipientFromJSONTyped(json: any, ignoreDiscriminator: boolean): BatchRecipient {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'email': json['email'],
+        'name': json['name'] == null ? undefined : json['name'],
+        'variables': json['variables'] == null ? undefined : json['variables'],
+    };
+}
+
+export function BatchRecipientToJSON(json: any): BatchRecipient {
+    return BatchRecipientToJSONTyped(json, false);
+}
+
+export function BatchRecipientToJSONTyped(value?: BatchRecipient | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'email': value['email'],
+        'name': value['name'],
+        'variables': value['variables'],
+    };
+}
+

package/src/src/models/CreateTemplateRequest.ts

@@ -32,29 +32,38 @@ export interface CreateTemplateRequest {
      */
     description?: string;
     /**
-     * Email subject line (supports Handlebars)
+     * Email subject line. Supports Handlebars `{{var}}` interpolation;
+     * values are HTML-escaped on render (see `html` field for the full
+     * escape policy).
+     * 
      * @type {string}
      * @memberof CreateTemplateRequest
      */
     subject?: string;
     /**
-     * HTML body (supports Handlebars)
+     * HTML body. Supports Handlebars `{{var}}` interpolation; values are
+     * always HTML-escaped on render.
+     * 
+     * **Triple-brace `{{{var}}}` (raw HTML output) is not supported** for
+     * XSS-prevention reasons — input containing `{{{var}}}` is rewritten
+     * to `{{var}}` on save and the response includes a top-level
+     * `warnings` array describing what changed. To inject pre-rendered
+     * HTML, render the entire `html` field outside Zyphr and POST it to
+     * `/v1/email/send` directly without `template_id`.
+     * 
      * @type {string}
      * @memberof CreateTemplateRequest
      */
     html?: string;
     /**
-     * Plain text body (supports Handlebars)
+     * Plain text body. Supports Handlebars `{{var}}` interpolation;
+     * triple-brace syntax is rewritten to double-brace on save (same
+     * policy as the `html` field).
+     * 
      * @type {string}
      * @memberof CreateTemplateRequest
      */
     text?: string;
-    /**
-     * Default variable values
-     * @type {{ [key: string]: any; }}
-     * @memberof CreateTemplateRequest
-     */
-    variables?: { [key: string]: any; };
 }
 
 /**
@@ -80,7 +89,6 @@ export function CreateTemplateRequestFromJSONTyped(json: any, ignoreDiscriminato
         'subject': json['subject'] == null ? undefined : json['subject'],
         'html': json['html'] == null ? undefined : json['html'],
         'text': json['text'] == null ? undefined : json['text'],
-        'variables': json['variables'] == null ? undefined : json['variables'],
     };
 }
 
@@ -100,7 +108,6 @@ export function CreateTemplateRequestToJSONTyped(value?: CreateTemplateRequest |
         'subject': value['subject'],
         'html': value['html'],
         'text': value['text'],
-        'variables': value['variables'],
     };
 }
 

package/src/src/models/SendBatchEmailRequest.ts

@@ -13,33 +13,99 @@
  */
 
 import { mapValues } from '../runtime';
-import type { SendEmailRequest } from './SendEmailRequest';
+import type { BatchRecipient } from './BatchRecipient';
 import {
-    SendEmailRequestFromJSON,
-    SendEmailRequestFromJSONTyped,
-    SendEmailRequestToJSON,
-    SendEmailRequestToJSONTyped,
-} from './SendEmailRequest';
+    BatchRecipientFromJSON,
+    BatchRecipientFromJSONTyped,
+    BatchRecipientToJSON,
+    BatchRecipientToJSONTyped,
+} from './BatchRecipient';
+import type { EmailAddress } from './EmailAddress';
+import {
+    EmailAddressFromJSON,
+    EmailAddressFromJSONTyped,
+    EmailAddressToJSON,
+    EmailAddressToJSONTyped,
+} from './EmailAddress';
 
 /**
+ * Send a single email to up to 100 recipients in one request. Each recipient gets their own message record. Provide either raw content (`subject` plus `html` and/or `text`) or a `template_id` with `template_data`.
  * 
  * @export
  * @interface SendBatchEmailRequest
  */
 export interface SendBatchEmailRequest {
+    /**
+     * Sender address. The API also accepts a plain email string for convenience.
+     * 
+     * @type {EmailAddress}
+     * @memberof SendBatchEmailRequest
+     */
+    from: EmailAddress;
+    /**
+     * 
+     * @type {Array<BatchRecipient>}
+     * @memberof SendBatchEmailRequest
+     */
+    to: Array<BatchRecipient>;
+    /**
+     * Reply-to address. The API also accepts a plain email string for convenience.
+     * 
+     * @type {EmailAddress}
+     * @memberof SendBatchEmailRequest
+     */
+    replyTo?: EmailAddress;
+    /**
+     * Required when sending raw content (no `template_id`).
+     * @type {string}
+     * @memberof SendBatchEmailRequest
+     */
+    subject?: string;
+    /**
+     * Provide either `html` or `text` (or both) when sending raw content.
+     * @type {string}
+     * @memberof SendBatchEmailRequest
+     */
+    html?: string;
+    /**
+     * Provide either `html` or `text` (or both) when sending raw content.
+     * @type {string}
+     * @memberof SendBatchEmailRequest
+     */
+    text?: string;
+    /**
+     * Template ID to use instead of raw `subject`/`html`/`text`.
+     * @type {string}
+     * @memberof SendBatchEmailRequest
+     */
+    templateId?: string;
+    /**
+     * Default variables to pass to the template. Merged with each recipient's per-recipient `variables` (per-recipient values win on key collisions).
+     * 
+     * @type {{ [key: string]: any; }}
+     * @memberof SendBatchEmailRequest
+     */
+    templateData?: { [key: string]: any; };
+    /**
+     * 
+     * @type {Array<string>}
+     * @memberof SendBatchEmailRequest
+     */
+    tags?: Array<string>;
     /**
      * 
-     * @type {Array<SendEmailRequest>}
+     * @type {{ [key: string]: any; }}
      * @memberof SendBatchEmailRequest
      */
-    messages: Array<SendEmailRequest>;
+    metadata?: { [key: string]: any; };
 }
 
 /**
  * Check if a given object implements the SendBatchEmailRequest interface.
  */
 export function instanceOfSendBatchEmailRequest(value: object): value is SendBatchEmailRequest {
-    if (!('messages' in value) || value['messages'] === undefined) return false;
+    if (!('from' in value) || value['from'] === undefined) return false;
+    if (!('to' in value) || value['to'] === undefined) return false;
     return true;
 }
 
@@ -53,7 +119,16 @@ export function SendBatchEmailRequestFromJSONTyped(json: any, ignoreDiscriminato
     }
     return {
         
-        'messages': ((json['messages'] as Array<any>).map(SendEmailRequestFromJSON)),
+        'from': EmailAddressFromJSON(json['from']),
+        'to': ((json['to'] as Array<any>).map(BatchRecipientFromJSON)),
+        'replyTo': json['reply_to'] == null ? undefined : EmailAddressFromJSON(json['reply_to']),
+        'subject': json['subject'] == null ? undefined : json['subject'],
+        'html': json['html'] == null ? undefined : json['html'],
+        'text': json['text'] == null ? undefined : json['text'],
+        'templateId': json['template_id'] == null ? undefined : json['template_id'],
+        'templateData': json['template_data'] == null ? undefined : json['template_data'],
+        'tags': json['tags'] == null ? undefined : json['tags'],
+        'metadata': json['metadata'] == null ? undefined : json['metadata'],
     };
 }
 
@@ -68,7 +143,16 @@ export function SendBatchEmailRequestToJSONTyped(value?: SendBatchEmailRequest |
 
     return {
         
-        'messages': ((value['messages'] as Array<any>).map(SendEmailRequestToJSON)),
+        'from': EmailAddressToJSON(value['from']),
+        'to': ((value['to'] as Array<any>).map(BatchRecipientToJSON)),
+        'reply_to': EmailAddressToJSON(value['replyTo']),
+        'subject': value['subject'],
+        'html': value['html'],
+        'text': value['text'],
+        'template_id': value['templateId'],
+        'template_data': value['templateData'],
+        'tags': value['tags'],
+        'metadata': value['metadata'],
     };
 }
 

package/src/src/models/Template.ts

@@ -56,11 +56,13 @@ export interface Template {
      */
     text?: string | null;
     /**
+     * Variable names auto-detected from `{{var}}` placeholders in subject,
+     * html, and text. Server-derived; ignored if supplied on create/update.
      * 
-     * @type {object}
+     * @type {Array<string>}
      * @memberof Template
      */
-    variables?: object | null;
+    readonly variables?: Array<string> | null;
     /**
      * 
      * @type {number}
@@ -115,7 +117,7 @@ export function TemplateToJSON(json: any): Template {
     return TemplateToJSONTyped(json, false);
 }
 
-export function TemplateToJSONTyped(value?: Template | null, ignoreDiscriminator: boolean = false): any {
+export function TemplateToJSONTyped(value?: Omit<Template, 'variables'> | null, ignoreDiscriminator: boolean = false): any {
     if (value == null) {
         return value;
     }
@@ -128,7 +130,6 @@ export function TemplateToJSONTyped(value?: Template | null, ignoreDiscriminator
         'subject': value['subject'],
         'html': value['html'],
         'text': value['text'],
-        'variables': value['variables'],
         'version': value['version'],
         'created_at': value['createdAt'] == null ? undefined : ((value['createdAt']).toISOString()),
         'updated_at': value['updatedAt'] == null ? undefined : ((value['updatedAt']).toISOString()),

package/src/src/models/TemplateResponse.ts

@@ -46,6 +46,17 @@ export interface TemplateResponse {
      * @memberof TemplateResponse
      */
     meta?: RequestMeta;
+    /**
+     * Non-fatal advisories about the request. Currently emitted only when
+     * the server rewrites template content for security (see the `html`
+     * field on `CreateTemplateRequest` for the triple-brace policy).
+     * Omitted entirely when no warnings apply — clients should treat its
+     * absence as equivalent to an empty array.
+     * 
+     * @type {Array<string>}
+     * @memberof TemplateResponse
+     */
+    warnings?: Array<string>;
 }
 
 /**
@@ -67,6 +78,7 @@ export function TemplateResponseFromJSONTyped(json: any, ignoreDiscriminator: bo
         
         'data': json['data'] == null ? undefined : TemplateFromJSON(json['data']),
         'meta': json['meta'] == null ? undefined : RequestMetaFromJSON(json['meta']),
+        'warnings': json['warnings'] == null ? undefined : json['warnings'],
     };
 }
 
@@ -83,6 +95,7 @@ export function TemplateResponseToJSONTyped(value?: TemplateResponse | null, ign
         
         'data': TemplateToJSON(value['data']),
         'meta': RequestMetaToJSON(value['meta']),
+        'warnings': value['warnings'],
     };
 }
 

package/src/src/models/UpdateTemplateRequest.ts

@@ -32,29 +32,32 @@ export interface UpdateTemplateRequest {
      */
     description?: string;
     /**
+     * Email subject line. Supports Handlebars `{{var}}` interpolation
+     * (HTML-escaped on render).
      * 
      * @type {string}
      * @memberof UpdateTemplateRequest
      */
     subject?: string;
     /**
+     * HTML body. Supports Handlebars `{{var}}` interpolation; values are
+     * always HTML-escaped on render. Triple-brace `{{{var}}}` is not
+     * supported — input is rewritten to `{{var}}` on save and the
+     * response includes a top-level `warnings` array describing the
+     * rewrite. See `CreateTemplateRequest.html` for full rationale.
      * 
      * @type {string}
      * @memberof UpdateTemplateRequest
      */
     html?: string;
     /**
+     * Plain text body. Supports Handlebars `{{var}}` interpolation; same
+     * triple-brace rewrite policy as `html`.
      * 
      * @type {string}
      * @memberof UpdateTemplateRequest
      */
     text?: string;
-    /**
-     * 
-     * @type {{ [key: string]: any; }}
-     * @memberof UpdateTemplateRequest
-     */
-    variables?: { [key: string]: any; };
 }
 
 /**
@@ -79,7 +82,6 @@ export function UpdateTemplateRequestFromJSONTyped(json: any, ignoreDiscriminato
         'subject': json['subject'] == null ? undefined : json['subject'],
         'html': json['html'] == null ? undefined : json['html'],
         'text': json['text'] == null ? undefined : json['text'],
-        'variables': json['variables'] == null ? undefined : json['variables'],
     };
 }
 
@@ -99,7 +101,6 @@ export function UpdateTemplateRequestToJSONTyped(value?: UpdateTemplateRequest |
         'subject': value['subject'],
         'html': value['html'],
         'text': value['text'],
-        'variables': value['variables'],
     };
 }
 

package/src/src/models/index.ts

@@ -32,6 +32,7 @@ export * from './AuthUser';
 export * from './AuthUserResponse';
 export * from './AuthUserResponseData';
 export * from './BatchPublishWaaSEvents201Response';
+export * from './BatchRecipient';
 export * from './BulkRetryWebhookDeliveriesRequest';
 export * from './BulkUpsertAuthEmailTemplatesRequest';
 export * from './BulkUpsertAuthEmailTemplatesResponse';