@postbrix/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,279 @@
+# PostBrix SDK Commercial License Agreement
+
+**Version:** 1.0  
+**Effective Date:** January 1, 2026  
+**Last Updated:** 2026  
+
+**Copyright © 2026 PostBrix. All rights reserved.**
+
+## 1. Definitions
+
+For purposes of this Agreement:
+
+- **“Licensor,” “PostBrix,” “we,” “us,” or “our”** means **PostBrix**.
+- **“Licensee,” “you,” or “your”** means the individual or legal entity that lawfully obtains or uses the SDK.
+- **“SDK”** means the proprietary PostBrix software development kit, including the software package distributed by PostBrix (including the applicable NPM package), its source or compiled code where provided, APIs, SDK libraries, examples, configuration files, and related technical materials supplied by PostBrix.
+- **“Documentation”** means official documentation, reference materials, examples, and technical instructions supplied by PostBrix for use of the SDK.
+- **“PostBrix Services”** means the PostBrix hosted services, APIs, platforms, websites, and related services made available by PostBrix and intended to be used with the SDK.
+- **“Application”** means software, websites, products, or services developed or operated by Licensee that use or depend on the SDK.
+- **“Authorized Use”** means the use of the SDK expressly permitted under Section 2.
+
+## 2. License Grant
+
+Subject to Licensee's compliance with this Agreement and any applicable PostBrix Services terms, PostBrix grants Licensee a limited, non-exclusive, non-transferable, non-sublicensable license during the applicable license term to:
+
+1. download, install, and execute the SDK;
+2. use the SDK to integrate Licensee's Applications with the PostBrix Services;
+3. copy the SDK as reasonably necessary for development, testing, deployment, backup, and operation of Licensee's Applications; and
+4. include the SDK in, or distribute the SDK with, Licensee's Applications solely as part of those Applications or services.
+
+Licensee does **not** receive ownership of the SDK. Except for the rights expressly granted in this Agreement, all rights are reserved by PostBrix.
+
+Nothing in this Agreement grants Licensee a right to use the SDK as a standalone product or to offer the SDK itself as a separately licensed or commercialized service.
+
+## 3. Permitted Distribution
+
+Licensee may distribute its own Applications that contain or depend upon the SDK, including Applications distributed to Licensee's customers or end users, provided that:
+
+- the SDK is used only as part of the Application;
+- the SDK is not separately sold, licensed, rented, leased, or distributed as a standalone product;
+- Licensee does not grant recipients rights to extract, reuse, or commercialize the SDK independently of the Application; and
+- Licensee remains responsible for complying with this Agreement.
+
+For clarity, ordinary application packaging, bundling, minification, transpilation, containerization, deployment, and similar technical processes required to build or operate an Application do not by themselves constitute prohibited modification or redistribution of the SDK.
+
+## 4. Restrictions
+
+Except where expressly permitted by this Agreement or applicable law, Licensee shall not:
+
+1. sell, resell, sublicense, rent, lease, lend, distribute, or otherwise make the SDK available as a standalone product or service;
+2. use the SDK to provide a standalone SDK, template-rendering engine, API client, or substantially similar competing developer product;
+3. modify the SDK itself or create derivative works of the SDK, except for changes expressly permitted by applicable law or by PostBrix in writing;
+4. reverse engineer, decompile, disassemble, or attempt to derive the source code, algorithms, or underlying structure of the SDK, except to the extent such restriction is prohibited or limited by applicable law;
+5. remove, obscure, or alter copyright, trademark, proprietary, or other legal notices contained in the SDK;
+6. use the SDK to circumvent PostBrix authentication, authorization, subscription, usage limits, rate limits, billing controls, security controls, or other technical restrictions;
+7. use the SDK to interfere with, disrupt, damage, overload, or gain unauthorized access to the PostBrix Services or related systems;
+8. use the SDK in violation of applicable law or applicable PostBrix acceptable-use or security requirements; or
+9. use the SDK for the purpose of creating a product that directly competes with the PostBrix SDK or its underlying developer platform, except that Licensee may develop ordinary software Applications that use the SDK.
+
+Nothing in this Section prohibits any use that cannot lawfully be prohibited under applicable law.
+
+## 5. Intellectual Property
+
+The SDK and Documentation, including all copyrights, trademarks, trade secrets, patents, know-how, designs, interfaces, and other intellectual property rights in them, are and remain the property of PostBrix or its licensors.
+
+This Agreement is a license and not a sale or transfer of ownership.
+
+Licensee retains all rights in its own Applications, code, content, data, and materials, subject to any third-party rights and the rights granted to PostBrix under applicable PostBrix Services terms.
+
+PostBrix trademarks and branding may be used only as expressly permitted by PostBrix's applicable trademark guidelines or written authorization.
+
+## 6. Third-Party and Open-Source Software
+
+The SDK may include or interact with third-party software or open-source components.
+
+Such components may be governed by separate license terms. Where applicable, those terms will control the use of the relevant component to the extent required by its license.
+
+Nothing in this Agreement is intended to restrict rights granted to Licensee under an applicable open-source license.
+
+Applicable third-party and open-source notices should be provided with the SDK distribution or Documentation where required.
+
+## 7. PostBrix Services and Account Requirements
+
+The SDK may require an active PostBrix account, API credentials, subscription, or other authorization to access the PostBrix Services.
+
+Use of the PostBrix Services is separately governed by the applicable PostBrix Terms of Service, subscription terms, acceptable-use policies, privacy policies, and other applicable agreements.
+
+If the SDK is available to users on a particular PostBrix plan, the applicable plan terms and usage limits will control eligibility for the PostBrix Services.
+
+The SDK license does not itself grant unlimited access to the PostBrix Services.
+
+## 8. Credentials and Security
+
+Licensee is responsible for safeguarding API keys, access tokens, credentials, and other authentication information used with the SDK.
+
+Licensee shall not:
+
+- publish secret PostBrix API credentials in public repositories;
+- intentionally expose server-side secret credentials in client-side applications;
+- share credentials with unauthorized persons; or
+- use credentials belonging to another person or organization without authorization.
+
+Licensee should promptly revoke or rotate credentials that are suspected to have been compromised.
+
+## 9. Privacy and Data Protection
+
+Licensee's use of the PostBrix Services may involve the processing of data, including data supplied through SDK requests.
+
+The parties' privacy and data-protection obligations are governed by the applicable PostBrix Privacy Policy, Data Processing Agreement (“DPA”), and other applicable data-protection terms.
+
+Licensee is responsible for ensuring that it has the necessary rights, notices, consents, and lawful bases required for data it submits to the PostBrix Services.
+
+Where a DPA applies, the DPA will govern the parties' applicable data-processing relationship to the extent of any conflict with this Agreement.
+
+## 10. Confidentiality
+
+If PostBrix provides non-public information identified as confidential or that reasonably should be understood to be confidential, Licensee shall use reasonable care to protect that information and shall not disclose it except to personnel or contractors who need to know it and are bound by confidentiality obligations.
+
+Confidential information does not include information that:
+
+- is or becomes publicly available through no breach of this Agreement;
+- was lawfully known by Licensee without confidentiality obligations before disclosure;
+- is independently developed without use of the confidential information; or
+- is lawfully received from a third party without a confidentiality obligation.
+
+If disclosure is required by law, Licensee may disclose the required information, provided that, where legally permitted, it gives PostBrix reasonable advance notice.
+
+The SDK's public documentation and publicly distributed SDK package are not confidential solely because they are subject to this license.
+
+## 11. Updates and Changes
+
+PostBrix may release updates, patches, fixes, improvements, or new versions of the SDK.
+
+Unless otherwise stated, updates are subject to this Agreement.
+
+PostBrix may discontinue or modify versions of the SDK or its compatibility with the PostBrix Services. PostBrix will use commercially reasonable efforts to communicate material breaking changes through its normal product or developer communication channels.
+
+Nothing in this Agreement requires PostBrix to provide maintenance, support, or updates unless separately agreed.
+
+## 12. Support
+
+Unless expressly included in a separate support or subscription agreement, the SDK is provided without a commitment to provide technical support.
+
+Any support, service-level commitments, or professional services are governed by the applicable PostBrix agreement or order.
+
+## 13. Fees and Subscription Status
+
+The SDK license itself does not create fees unless expressly stated in the applicable PostBrix pricing, subscription, order, or commercial terms.
+
+Where continued SDK use or access to PostBrix Services requires an active subscription or account, Licensee must maintain the applicable subscription or account in good standing.
+
+## 14. Term and Termination
+
+This Agreement begins when Licensee accepts it or first lawfully downloads, installs, accesses, or uses the SDK, whichever occurs first, and continues until terminated.
+
+PostBrix may terminate this Agreement if Licensee materially breaches it and, where the breach is capable of cure, fails to cure the breach within thirty (30) days after receiving written notice.
+
+PostBrix may terminate immediately where permitted by applicable law if the breach is incapable of cure or involves unauthorized access, credential abuse, infringement, security abuse, or material harm to the PostBrix Services.
+
+Licensee may terminate this Agreement by ceasing all use of the SDK and deleting copies of the SDK in its possession or control, except for copies that must be retained under applicable law or are contained in Applications already distributed to end users where removal is not reasonably practicable.
+
+Termination does not affect rights or obligations that by their nature should survive termination.
+
+## 15. Effect of Termination
+
+Upon termination, Licensee must stop using the SDK for new development and deployments and must cease standalone distribution of the SDK.
+
+Applications already lawfully distributed to third parties before termination may continue to operate solely to the extent reasonably necessary for existing users, provided that such continued operation does not involve continued access to PostBrix Services after the applicable account, subscription, or service authorization has ended.
+
+Sections concerning intellectual property, confidentiality, restrictions, disclaimers, limitation of liability, dispute resolution, and other provisions intended by their nature to survive termination will survive.
+
+## 16. Disclaimer of Warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SDK AND DOCUMENTATION ARE PROVIDED “AS IS” AND “AS AVAILABLE,” WITHOUT WARRANTIES OF ANY KIND, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE.
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, POSTBRIX DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+POSTBRIX DOES NOT WARRANT THAT THE SDK WILL BE UNINTERRUPTED, ERROR-FREE, SECURE, COMPATIBLE WITH EVERY ENVIRONMENT, OR THAT ALL DEFECTS WILL BE CORRECTED.
+
+THIS DISCLAIMER DOES NOT EXCLUDE WARRANTIES OR RIGHTS THAT CANNOT LAWFULLY BE EXCLUDED.
+
+## 17. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, POSTBRIX WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR FOR LOSS OF PROFITS, REVENUE, BUSINESS, GOODWILL, OR DATA, ARISING OUT OF OR RELATED TO THIS AGREEMENT OR THE SDK, EVEN IF POSTBRIX HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, POSTBRIX'S TOTAL AGGREGATE LIABILITY ARISING OUT OF OR RELATED TO THIS AGREEMENT WILL NOT EXCEED THE GREATER OF:
+
+1. the fees actually paid by Licensee to PostBrix for the applicable PostBrix Services during the twelve (12) months immediately preceding the event giving rise to the claim; or
+2. INR 10,000.
+
+The foregoing limitations do not apply to liability that cannot lawfully be limited or excluded under applicable law.
+
+Any additional exclusions, caps, or exceptions contained in a separate PostBrix Terms of Service, order form, or enterprise agreement will apply according to their terms.
+
+## 18. Indemnification
+
+Unless otherwise provided in a separate agreement, Licensee is responsible for claims arising from:
+
+- Licensee's unlawful use of the SDK;
+- Licensee's violation of this Agreement;
+- Licensee's Applications, content, or data; or
+- Licensee's infringement or misuse of third-party rights through its Applications or use of the SDK.
+
+Any indemnification obligations owed by PostBrix, if any, will be governed exclusively by a separate written agreement that expressly provides for such obligations.
+
+## 19. Compliance With Laws
+
+Each party shall comply with laws applicable to its activities under this Agreement.
+
+Licensee shall not use the SDK or PostBrix Services for unlawful activity or in a manner that violates applicable export controls, sanctions, privacy, cybersecurity, intellectual-property, or other applicable laws.
+
+## 20. Governing Law and Dispute Resolution
+
+This Agreement is governed by the laws of India, without regard to conflict-of-law principles.
+
+The competent courts having jurisdiction over PostBrix will have exclusive jurisdiction over disputes arising from or relating to this Agreement, unless a separate written agreement provides for arbitration or another dispute-resolution mechanism.
+
+## 21. Relationship With Other PostBrix Terms
+
+This Agreement governs the licensing of the SDK.
+
+Your use of the PostBrix Services is also subject to the applicable PostBrix Terms of Service, Privacy Policy, Acceptable Use Policy, subscription/order terms, DPA, and other applicable agreements.
+
+If there is a conflict:
+
+1. a signed enterprise/order agreement controls to the extent of the conflict;
+2. a DPA controls for data-processing matters;
+3. applicable service terms control for use of the PostBrix Services; and
+4. this Agreement controls for licensing of the SDK,
+
+unless the applicable agreement expressly states otherwise.
+
+## 22. Assignment
+
+Licensee may not assign or transfer this Agreement or the license granted under it without PostBrix's prior written consent, except where such restriction is prohibited by applicable law.
+
+PostBrix may assign this Agreement in connection with a merger, acquisition, corporate reorganization, or sale of substantially all relevant assets, provided the assignee assumes the applicable obligations.
+
+## 23. Severability
+
+If any provision of this Agreement is held unenforceable or invalid, that provision will be enforced to the maximum extent permitted by law, and the remaining provisions will remain in full force and effect.
+
+## 24. Waiver
+
+A failure or delay by either party to enforce a provision of this Agreement does not constitute a waiver of that provision or the right to enforce it later.
+
+## 25. Amendments
+
+PostBrix may update this Agreement for future SDK versions or future users by publishing an updated version with a new effective date.
+
+For existing customers, material changes to the license terms will apply only as permitted by the applicable PostBrix commercial or subscription terms and applicable law.
+
+## 26. Entire Agreement
+
+This Agreement, together with any documents expressly incorporated by reference, constitutes the agreement between the parties regarding the SDK and supersedes prior agreements concerning the same subject matter, except for separate written agreements that expressly govern the SDK or PostBrix Services.
+
+## 27. Notices
+
+Legal notices to PostBrix concerning this Agreement should be sent to:
+
+**PostBrix**  
+**Email:** licensing@postbrix.com
+
+Notices to Licensee may be sent to the email address or account associated with the Licensee's PostBrix account, subject to applicable law and the relevant PostBrix service terms.
+
+## 28. Contact
+
+For licensing questions:
+
+**Email:** licensing@postbrix.com
+
+---
+
+# Acceptance
+
+By downloading, accessing, installing, or using the SDK, Licensee acknowledges that it has read and agrees to this Agreement, to the extent permitted by applicable law.
+
+**Licensor:** PostBrix  
+**Effective Date:** January 1, 2026  
+**License Contact:** licensing@postbrix.com

package/README.md

@@ -0,0 +1,325 @@
+# PostBrix SDK
+
+**The Official TypeScript SDK for PostBrix** — the API-first drag-and-drop email template builder platform for modern SaaS applications.
+
+> **Render email templates programmatically with zero runtime dependencies. Designed for speed, security, and developer experience.**
+
+---
+
+> [!CAUTION]
+> **SECURITY NOTICE**: Never expose `pb_live_` secret API keys in browser or client-side code. The PostBrix SDK is designed primarily for trusted server-side environments (Node.js backend servers, serverless functions, background workers). Exposing your API key on the client enables unauthorized usage.
+
+---
+
+## 🌟 Core Features
+
+- **Zero Runtime Dependencies**: Uses native Fetch and Web standard APIs for minimal footprint and maximum security.
+- **Universal Runtime Support**: Node.js 18+, Bun, Deno, Cloudflare Workers, and Vercel Edge Runtime.
+- **Strictly Typed**: Discriminated union response types (`format: "html" | "mjml" | "both"`) with compile-time TypeScript narrowing.
+- **Transient Failure Retries**: Built-in exponential backoff with jitter and automated `Retry-After` compliance.
+- **Timeout Management**: Guaranteed cleanup of native `AbortController` timers without resource leaks.
+- **Detailed Error Classes**: Specific, actionable error classes with `statusCode`, `code`, `requestId`, and `retryable` metadata.
+
+---
+
+## 📦 Installation
+
+### npm
+```bash
+npm install @postbrix/sdk
+```
+
+### yarn
+```bash
+yarn add @postbrix/sdk
+```
+
+### pnpm
+```bash
+pnpm add @postbrix/sdk
+```
+
+### Bun
+```bash
+bun add @postbrix/sdk
+```
+
+---
+
+## 📦 Module Systems
+
+The SDK provides first-class support for both **ES Modules (ESM)** and **CommonJS (CJS)**:
+
+```typescript
+// ESM import (Node.js 18+, modern bundlers, Edge runtimes)
+import { PostBrix } from "@postbrix/sdk";
+
+// CommonJS require
+const { PostBrix } = require("@postbrix/sdk");
+```
+
+---
+
+## 🚀 Quick Start
+
+### Basic HTML Render
+
+```typescript
+import { PostBrix } from "@postbrix/sdk";
+
+const postbrix = new PostBrix({
+  apiKey: process.env.POSTBRIX_API_KEY!,
+});
+
+const result = await postbrix.render("welcome-template", {
+  firstName: "Alex",
+  company: "Acme Inc.",
+});
+
+// Default format is "html"
+console.log(result.html);
+```
+
+---
+
+## 📧 Rendering Templates
+
+### 1. HTML Only (Default)
+
+```typescript
+// Type is automatically inferred as HtmlRenderResponse
+const result = await postbrix.render("welcome-template", {
+  firstName: "Alex",
+});
+
+// Direct access — result.html is guaranteed to be string
+console.log(result.html);
+```
+
+### 2. MJML Only
+
+```typescript
+// Type is automatically inferred as MjmlRenderResponse
+const result = await postbrix.render(
+  "welcome-template",
+  { firstName: "Alex" },
+  { format: "mjml" }
+);
+
+// Direct access — result.mjml is guaranteed to be string
+console.log(result.mjml);
+```
+
+### 3. Both Formats
+
+```typescript
+// Type is automatically inferred as BothFormatsRenderResponse
+const result = await postbrix.render(
+  "welcome-template",
+  { firstName: "Alex" },
+  { format: "both" }
+);
+
+// Direct access to both outputs
+console.log(result.html); // string
+console.log(result.mjml); // string
+```
+
+### 4. Strongly Typed Variables (Generics)
+
+You can optionally pass a TypeScript interface to assist with variable typing at compile-time:
+
+```typescript
+interface WelcomeVariables {
+  firstName: string;
+  orderTotal: number;
+}
+
+const result = await postbrix.render<WelcomeVariables>(
+  "order-confirmation",
+  {
+    firstName: "Alex",
+    orderTotal: 149.99,
+  }
+);
+```
+
+> [!NOTE]
+> Template variables must be JSON-serializable (`Record<string, unknown>`). Unsupported types like `BigInt`, `Function`, `Symbol`, `Map`, `Set`, or circular structures will cause a `PostBrixValidationError` before any network request is sent.
+
+---
+
+## ⚠️ Error Handling
+
+All SDK errors inherit from `PostBrixError` and expose useful diagnostic metadata:
+
+- `statusCode?: number` - HTTP response status code
+- `code: string` - Error code (e.g. `INVALID_API_KEY`, `TEMPLATE_NOT_FOUND`, `RATE_LIMIT_EXCEEDED`)
+- `requestId?: string` - Server request identifier (from `X-Request-ID` header or response body)
+- `retryable: boolean` - Whether the error was retryable
+- `details?: unknown` - Detailed error information provided by the server
+
+```typescript
+import {
+  PostBrix,
+  PostBrixError,
+  PostBrixAuthError,
+  PostBrixValidationError,
+  PostBrixTemplateError,
+  PostBrixLimitError,
+  PostBrixTimeoutError,
+  PostBrixNetworkError,
+  PostBrixResponseError,
+} from "@postbrix/sdk";
+
+const postbrix = new PostBrix({ apiKey: process.env.POSTBRIX_API_KEY! });
+
+try {
+  const result = await postbrix.render("welcome-template", { name: "Alex" });
+  console.log(result.html);
+} catch (error) {
+  if (error instanceof PostBrixAuthError) {
+    // HTTP 401 (Invalid/expired API key) or HTTP 403 (Forbidden)
+    console.error(`Auth failure [${error.code}]:`, error.message);
+  } else if (error instanceof PostBrixValidationError) {
+    // HTTP 400 or invalid template variables
+    console.error(`Validation error [${error.code}]:`, error.message, error.details);
+  } else if (error instanceof PostBrixTemplateError) {
+    // HTTP 404: Template not found
+    console.error(`Template not found:`, error.message);
+  } else if (error instanceof PostBrixLimitError) {
+    // HTTP 429: Rate limit exceeded
+    console.error(`Rate limited. Retry after: ${error.retryAfter}ms`);
+  } else if (error instanceof PostBrixTimeoutError) {
+    // Request exceeded timeout
+    console.error(`Request timed out:`, error.message);
+  } else if (error instanceof PostBrixNetworkError) {
+    // Network connectivity, DNS, or socket failure
+    console.error(`Network error:`, error.message);
+  } else if (error instanceof PostBrixResponseError) {
+    // Malformed response payload from API
+    console.error(`Response error:`, error.message);
+  } else if (error instanceof PostBrixError) {
+    // Base catch-all for any other PostBrix error
+    console.error(`PostBrix error [${error.code}]:`, error.message);
+  } else {
+    console.error("Unknown error:", error);
+  }
+}
+```
+
+---
+
+## ⚙️ Configuration
+
+```typescript
+interface PostBrixConfig {
+  /** API key for authentication (required, e.g. pb_live_xxxxxxxxx) */
+  apiKey: string;
+
+  /** Base URL for API endpoint (default: https://api.postbrix.com/v1) */
+  baseURL?: string;
+
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+
+  /**
+   * Maximum number of retry attempts for transient failures (default: 2)
+   * 1 initial request + 2 retries = maximum 3 attempts
+   */
+  maxRetries?: number;
+}
+```
+
+Example:
+
+```typescript
+const postbrix = new PostBrix({
+  apiKey: process.env.POSTBRIX_API_KEY!,
+  baseURL: "https://api.postbrix.com/v1", // Trailing slashes are normalized automatically
+  timeout: 15000,                         // 15 seconds
+  maxRetries: 2,                          // 1 initial + 2 retries = 3 attempts max
+});
+
+// Inspect active configuration (API key is securely masked)
+const config = postbrix.getConfig();
+console.log(config);
+// { baseURL: 'https://api.postbrix.com/v1', timeout: 15000, maxRetries: 2, apiKey: 'pb_live...[REDACTED]' }
+```
+
+---
+
+## 🔄 Retries & Rate Limiting
+
+The SDK automatically retries transient errors:
+- **Retryable HTTP statuses**: `429` (Rate Limit), `502` (Bad Gateway), `503` (Service Unavailable), `504` (Gateway Timeout)
+- **Retryable exceptions**: Network failures (DNS, connection reset, socket error) and request timeouts
+- **Non-retryable statuses**: `400` (Validation), `401` (Unauthorized), `403` (Forbidden), `404` (Not Found), `422` (Unprocessable Entity)
+
+### Backoff Strategy & Jitter
+- Uses exponential backoff: base delay of `500ms`, doubling on each retry (`500ms`, `1000ms`, `2000ms`...), capped at `10,000ms`.
+- Random jitter (`0-100ms`) is added to each interval to prevent synchronized retry spikes.
+- If the server responds with a `429 Too Many Requests` and a `Retry-After` header, the SDK respects the server's requested delay instead of exponential backoff.
+
+---
+
+## 🌐 Runtime Compatibility
+
+The SDK requires zero runtime dependencies and relies solely on Web Standard APIs (`fetch`, `AbortController`, `Headers`, `Response`).
+
+**Supported and tested runtimes:**
+- **Node.js**: >= 18.0.0 (CJS and ESM)
+- **Bun**: >= 1.0.0 (CJS and ESM)
+- **Deno**: >= 1.30.0 (ESM)
+- **Cloudflare Workers**: Full compatibility
+- **Vercel Edge Runtime**: Full compatibility
+
+---
+
+## 📚 Public TypeScript Exports
+
+```typescript
+// Client
+export { PostBrix } from "@postbrix/sdk";
+
+// Types
+export type {
+  PostBrixConfig,
+  RenderOptions,
+  RenderFormat,
+  RenderResponse,
+  RenderRequest,
+  HtmlRenderResponse,
+  MjmlRenderResponse,
+  BothFormatsRenderResponse,
+  ApiErrorResponse,
+} from "@postbrix/sdk";
+
+// Error Classes
+export {
+  PostBrixError,
+  PostBrixAuthError,
+  PostBrixValidationError,
+  PostBrixTemplateError,
+  PostBrixLimitError,
+  PostBrixTimeoutError,
+  PostBrixNetworkError,
+  PostBrixResponseError,
+} from "@postbrix/sdk";
+
+// Constants
+export { SDK_VERSION } from "@postbrix/sdk";
+```
+
+---
+
+## 📄 License
+
+**Proprietary Commercial License** - All rights reserved.
+
+This SDK is proprietary software. Usage is restricted to authorized customers with an active PostBrix subscription. See the [LICENSE](LICENSE) file for complete terms.
+
+---
+
+*Copyright © 2026 PostBrix. All rights reserved.*
+

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var c=class extends Error{statusCode;requestId;code;retryable;details;cause;constructor(e,t){super(e),this.name="PostBrixError",this.statusCode=t?.statusCode,this.requestId=t?.requestId,this.code=t?.code??"POSTBRIX_ERROR",this.retryable=t?.retryable??false,this.details=t?.details,this.cause=t?.cause,Error.captureStackTrace&&Error.captureStackTrace(this,this.constructor),Object.setPrototypeOf(this,new.target.prototype);}},y=class r extends c{constructor(e,t){super(`Request timed out after ${e}ms`,{code:"POSTBRIX_TIMEOUT",requestId:t?.requestId,retryable:true,cause:t?.cause}),this.name="PostBrixTimeoutError",Object.setPrototypeOf(this,r.prototype);}},b=class r extends c{constructor(e,t){super(e,{code:"POSTBRIX_NETWORK_ERROR",requestId:t?.requestId,retryable:t?.retryable??true,cause:t?.cause}),this.name="PostBrixNetworkError",Object.setPrototypeOf(this,r.prototype);}},d=class r extends c{constructor(e,t){super(e,{statusCode:t?.statusCode??400,requestId:t?.requestId,code:t?.code??"POSTBRIX_VALIDATION_ERROR",retryable:false,details:t?.details,cause:t?.cause}),this.name="PostBrixValidationError",Object.setPrototypeOf(this,r.prototype);}},E=class r extends c{constructor(e,t){let n=t?.statusCode??401,o=n===403?"FORBIDDEN":"POSTBRIX_AUTH_ERROR";super(e,{statusCode:n,requestId:t?.requestId,code:t?.code??o,retryable:false,details:t?.details,cause:t?.cause}),this.name="PostBrixAuthError",Object.setPrototypeOf(this,r.prototype);}},R=class r extends c{retryAfter;constructor(e,t){super(e,{statusCode:t?.statusCode??429,requestId:t?.requestId,code:t?.code??"POSTBRIX_LIMIT_ERROR",retryable:true,details:t?.details,cause:t?.cause}),this.name="PostBrixLimitError",this.retryAfter=t?.retryAfter,Object.setPrototypeOf(this,r.prototype);}},h=class r extends c{constructor(e,t){super(e,{statusCode:t?.statusCode??404,requestId:t?.requestId,code:t?.code??"POSTBRIX_TEMPLATE_ERROR",retryable:false,details:t?.details,cause:t?.cause}),this.name="PostBrixTemplateError",Object.setPrototypeOf(this,r.prototype);}},l=class r extends c{constructor(e,t){super(e,{statusCode:t?.statusCode??502,requestId:t?.requestId,code:t?.code??"INVALID_RESPONSE",retryable:false,details:t?.details,cause:t?.cause}),this.name="PostBrixResponseError",Object.setPrototypeOf(this,r.prototype);}},g=class r extends E{constructor(e,t){super(e,{statusCode:t?.statusCode??403,requestId:t?.requestId,code:t?.code??"FORBIDDEN",details:t?.details,cause:t?.cause}),this.name="PostBrixForbiddenError",Object.setPrototypeOf(this,r.prototype);}},f=class r extends c{constructor(e,t){super(e,{statusCode:t?.statusCode??500,requestId:t?.requestId,code:t?.code??"SERVER_ERROR",retryable:t?.retryable??true,details:t?.details,cause:t?.cause}),this.name="PostBrixServerError",Object.setPrototypeOf(this,r.prototype);}},k=E,_=R,j=h;function O(r,e,t){let n=typeof t=="string"?{requestId:t}:t,{requestId:o,code:a,details:s,retryAfter:i}=n??{};switch(r){case 400:return new d(e,{statusCode:r,requestId:o,code:a??"VALIDATION_ERROR",details:s});case 401:return new E(e,{statusCode:r,requestId:o,code:a??"INVALID_API_KEY",details:s});case 403:return new g(e,{statusCode:r,requestId:o,code:a??"FORBIDDEN",details:s});case 404:return new h(e,{statusCode:r,requestId:o,code:a??"TEMPLATE_NOT_FOUND",details:s});case 429:return new R(e,{statusCode:r,requestId:o,code:a??"RATE_LIMIT_EXCEEDED",retryAfter:i,details:s});case 500:return new f(e,{statusCode:500,requestId:o,code:a??"INTERNAL_SERVER_ERROR",retryable:true,details:s});case 502:return new f(e,{statusCode:502,requestId:o,code:a??"BAD_GATEWAY",retryable:true,details:s});case 503:return new f(e,{statusCode:503,requestId:o,code:a??"SERVICE_UNAVAILABLE",retryable:true,details:s});case 504:return new f(e,{statusCode:504,requestId:o,code:a??"GATEWAY_TIMEOUT",retryable:true,details:s});default:return r>=500?new f(e,{statusCode:r,requestId:o,code:a??"SERVER_ERROR",retryable:true,details:s}):new c(e,{statusCode:r,requestId:o,code:a??"POSTBRIX_ERROR",retryable:false,details:s})}}function x(r,e){if(typeof r!="string"||r.trim().length===0)throw new d(`${e} must be a non-empty string`)}function P(r,e){if(typeof r!="number"||Number.isNaN(r)||r<=0)throw new d(`${e} must be greater than 0`)}function C(r,e){if(typeof r!="number"||Number.isNaN(r)||r<0||!Number.isInteger(r))throw new d(`${e} must be a non-negative integer`)}function S(r){let n=500*Math.pow(2,r),o=Math.random()*100;return Math.min(n+o,1e4)}function q(r){if(!r)return null;let e=r.trim();if(!e)return null;let t=Number(e);if(!Number.isNaN(t)&&t>=0)return t*1e3;let n=Date.parse(e);if(!Number.isNaN(n)){let o=n-Date.now();return Math.max(0,o)}return null}function B(r){return [429,502,503,504].includes(r)}function D(r){return new Promise(e=>setTimeout(e,r))}function I(r,e){let t=r.replace(/bearer\s+[a-zA-Z0-9_.-]+/gi,"Bearer [REDACTED]").replace(/pb_(?:live|test)_[a-zA-Z0-9_-]+/gi,"pb_[REDACTED]").replace(/sk_(?:live|test)_[a-zA-Z0-9_-]+/gi,"sk_[REDACTED]").replace(/api[_-]?key[=:]\s*[a-zA-Z0-9_.-]+/gi,"apiKey=[REDACTED]").replace(/authorization[=:]\s*[^\s,]+/gi,"authorization=[REDACTED]");return e&&e.trim().length>0&&(t=t.split(e.trim()).join("[REDACTED]")),t}function N(r){if(!r)return {};if(typeof r!="object"||Array.isArray(r))throw new d("Template variables must be an object with string keys");let e=new WeakSet;function t(n,o){if(n==null)return n;if(typeof n=="bigint")throw new d(`Unsupported variable type 'bigint' at '${o}'. Template variables must be JSON-serializable.`);if(typeof n=="function")throw new d(`Unsupported variable type 'function' at '${o}'. Template variables must be JSON-serializable.`);if(typeof n=="symbol")throw new d(`Unsupported variable type 'symbol' at '${o}'. Template variables must be JSON-serializable.`);if(typeof n!="object")return n;if(n instanceof Map||n instanceof Set)throw new d(`Unsupported variable collection '${n.constructor.name}' at '${o}'. Template variables must be JSON-serializable.`);if(e.has(n))throw new d(`Circular reference detected at '${o}'. Template variables must be JSON-serializable.`);if(e.add(n),Array.isArray(n)){let i=n.map((u,m)=>t(u,`${o}[${m}]`));return e.delete(n),i}if(n instanceof Date)return e.delete(n),new Date(n.getTime());if(n instanceof RegExp)return e.delete(n),new RegExp(n.source,n.flags);let a=n,s={};for(let i of Object.keys(a)){let u=o?`${o}.${i}`:i;s[i]=t(a[i],u);}return e.delete(n),s}return t(r,"")}var T="1.0.0",L=T;var A=class r{apiKey;baseURL;timeout;maxRetries;static DEFAULT_BASE_URL="https://api.postbrix.com/v1";static DEFAULT_TIMEOUT=3e4;static DEFAULT_MAX_RETRIES=2;constructor(e){this.validateConfig(e),this.apiKey=e.apiKey.trim(),this.baseURL=(e.baseURL??r.DEFAULT_BASE_URL).trim().replace(/\/+$/,""),this.timeout=e.timeout??r.DEFAULT_TIMEOUT,this.maxRetries=e.maxRetries??r.DEFAULT_MAX_RETRIES;}validateConfig(e){if(!e||typeof e!="object")throw new d("Configuration object is required. Usage: new PostBrix({ apiKey: 'pb_live_...' })");x(e.apiKey,"apiKey"),e.baseURL!==void 0&&e.baseURL!==null&&x(e.baseURL,"baseURL"),e.timeout!==void 0&&e.timeout!==null&&P(e.timeout,"timeout"),e.maxRetries!==void 0&&e.maxRetries!==null&&C(e.maxRetries,"maxRetries");}getConfig(){let e=this.apiKey.length>8?`${this.apiKey.slice(0,7)}...[REDACTED]`:"[REDACTED]";return Object.freeze({baseURL:this.baseURL,timeout:this.timeout,maxRetries:this.maxRetries,apiKey:e})}async render(e,t,n){x(e,"templateId");let o=e.trim();if(o.length===0)throw new d("templateId must be a non-empty string");let a=n?.format??"html";if(a!=="html"&&a!=="mjml"&&a!=="both")throw new d(`Invalid format '${String(a)}'. Must be 'html', 'mjml', or 'both'.`);let s=N(t),i=`${this.baseURL}/templates/${encodeURIComponent(o)}/render`,u={variables:s,format:a};return await this.request(i,{method:"POST",body:JSON.stringify(u)},a)}async request(e,t={},n="html"){let o;for(let a=0;a<=this.maxRetries;a++)try{return await this.executeRequest(e,t,n)}catch(s){if(o=s instanceof Error?s:new Error(String(s)),!this.isRetryableError(s)||a===this.maxRetries)throw s;let i;s instanceof R&&typeof s.retryAfter=="number"&&s.retryAfter>=0?i=s.retryAfter:i=S(a),await D(i);}throw o??new c("Request failed after max retries")}async executeRequest(e,t={},n="html"){let o=new AbortController,a=setTimeout(()=>o.abort(),this.timeout);try{let s=this.buildHeaders(),i=t.method??"GET",u=await fetch(e,{method:i,headers:s,body:t.body,signal:o.signal});return u.ok?await this.handleSuccessResponse(u,n):await this.handleErrorResponse(u)}catch(s){if(s instanceof Error&&s.name==="AbortError"||typeof DOMException<"u"&&s instanceof DOMException&&s.name==="AbortError")throw new y(this.timeout,{cause:s instanceof Error?s:void 0});if(s instanceof c)throw s;let i=s instanceof Error?s.message:String(s),u=I(i,this.apiKey);throw new b(`Network request failed: ${u}`,{cause:s instanceof Error?s:void 0,retryable:true})}finally{clearTimeout(a);}}buildHeaders(){return {Authorization:`Bearer ${this.apiKey}`,"Content-Type":"application/json",Accept:"application/json","User-Agent":`postbrix-sdk/${T}`}}async handleSuccessResponse(e,t){let n=e.headers.get("x-request-id")??void 0,o;try{o=await e.json();}catch(p){throw new l("Failed to parse response body as JSON",{statusCode:e.status,requestId:n,cause:p instanceof Error?p:void 0})}if(!o||typeof o!="object")throw new l("Server returned an invalid response structure",{statusCode:e.status,requestId:n});let a=o,s=a.data&&typeof a.data=="object"?a.data:a,i=typeof s.html=="string"?s.html:void 0,u=typeof s.mjml=="string"?s.mjml:void 0,m=typeof s.format=="string"?s.format:t;if(m==="html"){if(typeof i!="string")throw new l("Server response missing required 'html' string field for format 'html'",{statusCode:e.status,requestId:n,details:o});return {format:"html",html:i}}if(m==="mjml"){if(typeof u!="string")throw new l("Server response missing required 'mjml' string field for format 'mjml'",{statusCode:e.status,requestId:n,details:o});return {format:"mjml",mjml:u}}if(m==="both"){if(typeof i!="string"||typeof u!="string")throw new l("Server response missing required 'html' or 'mjml' string fields for format 'both'",{statusCode:e.status,requestId:n,details:o});return {format:"both",html:i,mjml:u}}throw new l(`Unexpected response format '${String(m)}'`,{statusCode:e.status,requestId:n,details:o})}async handleErrorResponse(e){let t=e.headers.get("x-request-id")??void 0,n=e.headers.get("retry-after"),o=q(n)??void 0,a=null,s=null;try{a=await e.json();}catch{try{s=await e.text();}catch{}}let i=t??a?.requestId??void 0,u=a?.message??(typeof a?.error=="string"?a.error:void 0);u||(s&&s.trim().length>0&&!s.trim().startsWith("<")?u=s.trim():u=`HTTP ${e.status}: ${e.statusText||"Error"}`);let m=I(u,this.apiKey),p=a?.code;throw !p&&typeof a?.error=="string"&&/^[A-Z0-9_-]+$/.test(a.error)&&(p=a.error),O(e.status,m,{requestId:i,code:p,details:a?.details,retryAfter:o})}isRetryableError(e){if(e instanceof c){if(e.retryable)return  true;let t=e.statusCode;return t!==void 0&&B(t)}return e instanceof y||e instanceof b}};
+exports.PostBrix=A;exports.PostBrixAuthError=E;exports.PostBrixAuthenticationError=k;exports.PostBrixError=c;exports.PostBrixForbiddenError=g;exports.PostBrixLimitError=R;exports.PostBrixNetworkError=b;exports.PostBrixNotFoundError=j;exports.PostBrixRateLimitError=_;exports.PostBrixResponseError=l;exports.PostBrixServerError=f;exports.PostBrixTemplateError=h;exports.PostBrixTimeoutError=y;exports.PostBrixValidationError=d;exports.SDK_VERSION=T;exports.VERSION=L;