@postbrix/sdk 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,361 @@
+/**
+ * Configuration options for PostBrix client
+ */
+interface PostBrixConfig {
+    /** API key for authentication (required) */
+    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 errors (default: 2) */
+    maxRetries?: number;
+}
+/**
+ * Output format for rendered templates
+ */
+type RenderFormat = "html" | "mjml" | "both";
+/**
+ * Options for render request
+ *
+ * @typeParam TFormat - Desired output format (default: RenderFormat)
+ */
+interface RenderOptions<TFormat extends RenderFormat = RenderFormat> {
+    /** Output format (default: "html") */
+    format?: TFormat;
+}
+/**
+ * Render request body
+ */
+interface RenderRequest {
+    variables?: Record<string, unknown>;
+    format: RenderFormat;
+}
+/**
+ * HTML render response
+ */
+interface HtmlRenderResponse {
+    format: "html";
+    html: string;
+    mjml?: never;
+}
+/**
+ * MJML render response
+ */
+interface MjmlRenderResponse {
+    format: "mjml";
+    mjml: string;
+    html?: never;
+}
+/**
+ * Both formats render response
+ */
+interface BothFormatsRenderResponse {
+    format: "both";
+    html: string;
+    mjml: string;
+}
+/**
+ * Render response discriminated union
+ */
+type RenderResponse = HtmlRenderResponse | MjmlRenderResponse | BothFormatsRenderResponse;
+/**
+ * Resolves concrete return type based on requested format:
+ * - "html" -> HtmlRenderResponse (guaranteed .html: string)
+ * - "mjml" -> MjmlRenderResponse (guaranteed .mjml: string)
+ * - "both" -> BothFormatsRenderResponse (guaranteed .html: string, .mjml: string)
+ * - RenderFormat / union -> RenderResponse (discriminated union)
+ */
+type RenderResult<TFormat extends RenderFormat = "html"> = [
+    TFormat
+] extends ["mjml"] ? MjmlRenderResponse : [TFormat] extends ["both"] ? BothFormatsRenderResponse : [TFormat] extends ["html"] ? HtmlRenderResponse : RenderResponse;
+/**
+ * API error response from server
+ */
+interface ApiErrorResponse {
+    message?: string;
+    error?: string;
+    code?: string;
+    statusCode?: number;
+    requestId?: string;
+    details?: unknown;
+}
+/**
+ * HTTP response wrapper
+ */
+interface HttpResponse<T> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+}
+
+/**
+ * PostBrix SDK Client
+ *
+ * Main entry point for interacting with the PostBrix Template Render API.
+ * Provides zero-dependency, strongly typed template rendering with built-in
+ * exponential jitter retries, timeout management, and comprehensive error handling.
+ */
+declare class PostBrix {
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly timeout;
+    private readonly maxRetries;
+    private static readonly DEFAULT_BASE_URL;
+    private static readonly DEFAULT_TIMEOUT;
+    private static readonly DEFAULT_MAX_RETRIES;
+    /**
+     * Initialize a new PostBrix SDK client instance.
+     *
+     * @param config - Configuration options for the client
+     * @param config.apiKey - PostBrix API key for authentication (starts with `pb_live_` or `pb_test_`)
+     * @param config.baseURL - Base URL for the PostBrix API (default: `https://api.postbrix.com/v1`)
+     * @param config.timeout - Request timeout in milliseconds (default: `30000`)
+     * @param config.maxRetries - Maximum retry attempts for transient errors (default: `2`)
+     *
+     * @example
+     * ```ts
+     * import { PostBrix } from "@postbrix/sdk";
+     *
+     * // Standard initialization
+     * const postbrix = new PostBrix({
+     *   apiKey: process.env.POSTBRIX_API_KEY!,
+     * });
+     *
+     * // Custom timeout and retries
+     * const postbrix = new PostBrix({
+     *   apiKey: "pb_live_xxxxxxxxxxxxxxxxxxxxxxxx",
+     *   baseURL: "https://api.postbrix.com/v1",
+     *   timeout: 10000,
+     *   maxRetries: 3,
+     * });
+     * ```
+     *
+     * @throws {PostBrixValidationError} If any configuration parameter is invalid
+     */
+    constructor(config: PostBrixConfig);
+    /**
+     * Validate configuration options in detail
+     *
+     * @param config - Configuration object to validate
+     * @throws {PostBrixValidationError} If configuration is missing or invalid
+     */
+    private validateConfig;
+    /**
+     * Returns active client configuration with sensitive secrets securely masked.
+     * Useful for debugging, logging, and environment verification.
+     *
+     * @returns Read-only sanitized configuration object
+     *
+     * @example
+     * ```ts
+     * const config = postbrix.getConfig();
+     * console.log(config);
+     * // { baseURL: 'https://api.postbrix.com/v1', timeout: 30000, maxRetries: 2, apiKey: 'pb_live...[REDACTED]' }
+     * ```
+     */
+    getConfig(): Readonly<{
+        baseURL: string;
+        timeout: number;
+        maxRetries: number;
+        apiKey: string;
+    }>;
+    /**
+     * Render an email template with dynamic variables.
+     *
+     * @typeParam TVariables - Shape of dynamic variables passed to the template
+     * @typeParam TFormat - Desired output format: "html" (default), "mjml", or "both"
+     *
+     * @param templateId - Template identifier or slug (e.g. "welcome-email")
+     * @param variables - Key-value variables to substitute into template tags (must be JSON-serializable)
+     * @param options - Configuration options for rendering (e.g. `{ format: "html" }`)
+     * @returns Promise resolving to the rendered template output matching the requested format
+     *
+     * @example
+     * ```ts
+     * // 1. Render HTML (default - returns { format: "html", html: string })
+     * const result = await postbrix.render("welcome-email", { name: "Alex" });
+     * console.log(result.html);
+     *
+     * // 2. Render MJML (returns { format: "mjml", mjml: string })
+     * const mjmlResult = await postbrix.render("welcome-email", { name: "Alex" }, { format: "mjml" });
+     * console.log(mjmlResult.mjml);
+     *
+     * // 3. Render Both (returns { format: "both", html: string, mjml: string })
+     * const bothResult = await postbrix.render("welcome-email", { name: "Alex" }, { format: "both" });
+     * console.log(bothResult.html, bothResult.mjml);
+     * ```
+     *
+     * @throws {PostBrixValidationError} If templateId, variables, format, or circular data are invalid
+     * @throws {PostBrixAuthenticationError} If the API key is missing or invalid (401)
+     * @throws {PostBrixForbiddenError} If API key lacks permissions (403)
+     * @throws {PostBrixNotFoundError} If templateId does not exist (404)
+     * @throws {PostBrixRateLimitError} If rate limit is exceeded (429)
+     * @throws {PostBrixServerError} If server encounters an internal error (500, 502, 503, 504)
+     * @throws {PostBrixTimeoutError} If request times out
+     * @throws {PostBrixNetworkError} If network connection fails
+     */
+    render<TVariables extends Record<string, unknown> = Record<string, unknown>, TFormat extends RenderFormat = "html">(templateId: string, variables?: TVariables, options?: RenderOptions<TFormat>): Promise<RenderResult<TFormat>>;
+    /**
+     * Internal request method with retry logic
+     */
+    private request;
+    /**
+     * Execute a single request
+     */
+    private executeRequest;
+    /**
+     * Build request headers
+     */
+    private buildHeaders;
+    /**
+     * Handle successful response with schema validation and backend unwrap
+     */
+    private handleSuccessResponse;
+    /**
+     * Handle error response
+     */
+    private handleErrorResponse;
+    /**
+     * Determine if error is retryable
+     */
+    private isRetryableError;
+}
+
+/**
+ * Base error class for all PostBrix SDK errors
+ */
+declare class PostBrixError extends Error {
+    readonly statusCode?: number;
+    readonly requestId?: string;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly details?: unknown;
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        code?: string;
+        retryable?: boolean;
+        details?: unknown;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when request times out
+ */
+declare class PostBrixTimeoutError extends PostBrixError {
+    constructor(timeoutMs: number, options?: {
+        requestId?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown for network issues
+ */
+declare class PostBrixNetworkError extends PostBrixError {
+    constructor(message: string, options?: {
+        requestId?: string;
+        retryable?: boolean;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown for validation issues
+ */
+declare class PostBrixValidationError extends PostBrixError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        code?: string;
+        details?: unknown;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown for authentication/authorization issues
+ */
+declare class PostBrixAuthError extends PostBrixError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        code?: string;
+        details?: unknown;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+declare class PostBrixLimitError extends PostBrixError {
+    readonly retryAfter?: number;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        code?: string;
+        retryAfter?: number;
+        details?: unknown;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when template is not found
+ */
+declare class PostBrixTemplateError extends PostBrixError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        code?: string;
+        details?: unknown;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when API returns a malformed response
+ */
+declare class PostBrixResponseError extends PostBrixError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        code?: string;
+        details?: unknown;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown when access is forbidden (403)
+ */
+declare class PostBrixForbiddenError extends PostBrixAuthError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        code?: string;
+        details?: unknown;
+        cause?: Error;
+    });
+}
+/**
+ * Error thrown for server-side failures (5xx)
+ */
+declare class PostBrixServerError extends PostBrixError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        requestId?: string;
+        code?: string;
+        retryable?: boolean;
+        details?: unknown;
+        cause?: Error;
+    });
+}
+/** Canonical Aliases for Error Classes */
+declare const PostBrixAuthenticationError: typeof PostBrixAuthError;
+type PostBrixAuthenticationError = PostBrixAuthError;
+declare const PostBrixRateLimitError: typeof PostBrixLimitError;
+type PostBrixRateLimitError = PostBrixLimitError;
+declare const PostBrixNotFoundError: typeof PostBrixTemplateError;
+type PostBrixNotFoundError = PostBrixTemplateError;
+
+declare const SDK_VERSION = "1.0.0";
+declare const VERSION = "1.0.0";
+
+export { type ApiErrorResponse, type BothFormatsRenderResponse, type HtmlRenderResponse, type HttpResponse, type MjmlRenderResponse, PostBrix, PostBrixAuthError, PostBrixAuthenticationError, type PostBrixConfig, PostBrixError, PostBrixForbiddenError, PostBrixLimitError, PostBrixNetworkError, PostBrixNotFoundError, PostBrixRateLimitError, PostBrixResponseError, PostBrixServerError, PostBrixTemplateError, PostBrixTimeoutError, PostBrixValidationError, type RenderFormat, type RenderOptions, type RenderRequest, type RenderResponse, type RenderResult, SDK_VERSION, VERSION };