@codematic/opencdp 5.0.13

package/dist/cjs/index.d.ts

@@ -0,0 +1,2 @@
+export { CDPClient } from './client';
+export { CDPConfig, SendEmailRequestOptions, SendEmailRequestWithTemplate, SendEmailRequestWithoutTemplate, SendEmailRequest, SendPushRequest, SendSmsRequest, Identifiers } from './types';

package/dist/cjs/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SendEmailRequest = exports.CDPClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "CDPClient", { enumerable: true, get: function () { return client_1.CDPClient; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "SendEmailRequest", { enumerable: true, get: function () { return types_1.SendEmailRequest; } });

package/dist/cjs/types.d.ts

@@ -0,0 +1,122 @@
+export interface CDPConfig {
+    /**
+     * API key for the CDP.
+     * This is required for authentication.
+     */
+    cdpApiKey: string;
+    /**
+     * Base URL for the OpenCDP API.
+     * If not provided, defaults to cdp server.
+     */
+    cdpEndpoint?: string;
+    /**
+     * Logger for OpenCDP operations.
+     * If not provided, defaults to console logging.
+     */
+    cdpLogger?: Logger;
+    /**
+     * Maximum number of concurrent OpenCDP requests.
+     * Default: 10. Hard-capped internally at 30.
+     */
+    maxConcurrentRequests?: number;
+    /**
+     * Request timeout in milliseconds.
+     * Default: 10000 (10 seconds).
+     */
+    timeout?: number;
+    /**
+     * Customer.io config for dual-write
+     */
+    customerIo?: {
+        siteId: string;
+        apiKey: string;
+        region?: 'us' | 'eu';
+    };
+    /**
+     * Optional: If true, sends events to both OpenCDP and Customer.io.
+     * This is useful for dual-write scenarios.
+     */
+    sendToCustomerIo?: boolean;
+    debug?: boolean;
+    /**
+     * Optional: Opt-in to throwing errors from the SDK.
+     * Default: false. When false, the SDK logs errors and resolves without throwing.
+     * When true, validation and request failures will throw so callers can catch them.
+     */
+    failOnException?: boolean;
+}
+export interface Logger {
+    debug(message: string): void;
+    error(message: string, context?: Record<string, any>): void;
+    warn(message: string): void;
+}
+export type Identifiers = {
+    id: string | number;
+} | {
+    email: string;
+};
+export type SendEmailRequestRequiredOptions = {
+    to: string;
+    identifiers: Identifiers;
+};
+export type SendEmailRequestOptionalOptions = Partial<{
+    message_data: Record<string, any>;
+    headers: Record<string, any>;
+    preheader: string;
+    reply_to: string;
+    bcc: string[];
+    cc: string[];
+    plaintext_body: string;
+    amp_body: string;
+    fake_bcc: boolean;
+    disable_message_retention: boolean;
+    send_to_unsubscribed: boolean;
+    tracked: boolean;
+    queue_draft: boolean;
+    send_at: number;
+    disable_css_preprocessing: boolean;
+    language: string;
+    attachments: Record<string, string>;
+}>;
+export type SendEmailRequestWithTemplate = SendEmailRequestRequiredOptions & SendEmailRequestOptionalOptions & {
+    transactional_message_id: string | number;
+};
+export type SendEmailRequestWithoutTemplate = SendEmailRequestRequiredOptions & SendEmailRequestOptionalOptions & {
+    body: string;
+    subject: string;
+    from: string;
+};
+export type SendEmailRequestOptions = SendEmailRequestWithTemplate | SendEmailRequestWithoutTemplate;
+export type Message = Partial<SendEmailRequestWithTemplate & SendEmailRequestWithoutTemplate> & {
+    attachments?: Record<string, string>;
+};
+export declare class SendEmailRequest {
+    message: Message;
+    constructor(opts: SendEmailRequestOptions);
+    attach(name: string, data: any, options?: {
+        encode?: boolean | undefined;
+    }): void;
+}
+export interface SendPushRequest {
+    identifiers: {
+        id?: string;
+        email?: string;
+        cdp_id?: string;
+    };
+    transactional_message_id: string | number;
+    title?: string;
+    body?: string;
+    message_data?: Record<string, any>;
+}
+export interface SendSmsRequest {
+    identifiers: {
+        id?: string;
+        email?: string;
+        cdp_id?: string;
+    };
+    transactional_message_id?: string | number;
+    to?: string;
+    from?: string;
+    body?: string;
+    message_data?: Record<string, any>;
+}

package/dist/cjs/types.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SendEmailRequest = void 0;
+class SendEmailRequest {
+    constructor(opts) {
+        this.message = {
+            to: opts.to,
+            identifiers: opts.identifiers,
+            message_data: opts.message_data,
+            send_at: opts.send_at,
+            disable_message_retention: opts.disable_message_retention,
+            send_to_unsubscribed: opts.send_to_unsubscribed,
+            queue_draft: opts.queue_draft,
+            bcc: opts.bcc,
+            cc: opts.cc,
+            fake_bcc: opts.fake_bcc,
+            reply_to: opts.reply_to,
+            preheader: opts.preheader,
+            headers: opts.headers,
+            disable_css_preprocessing: opts.disable_css_preprocessing,
+            tracked: opts.tracked,
+            language: opts.language,
+            attachments: opts.attachments,
+            // Template-based fields
+            transactional_message_id: 'transactional_message_id' in opts ? opts.transactional_message_id : undefined,
+            body: 'body' in opts ? opts.body : undefined,
+            amp_body: opts.amp_body,
+            plaintext_body: opts.plaintext_body,
+            subject: 'subject' in opts ? opts.subject : undefined,
+            from: 'from' in opts ? opts.from : undefined
+        };
+    }
+    attach(name, data, options) {
+        if (!this.message.attachments) {
+            this.message.attachments = {};
+        }
+        this.message.attachments[name] = data;
+    }
+}
+exports.SendEmailRequest = SendEmailRequest;

package/dist/esm/client.d.ts

@@ -0,0 +1,87 @@
+import { CDPConfig, SendEmailRequest, SendPushRequest, SendSmsRequest } from "./types";
+interface DeviceRegistrationParameters {
+    deviceId: string;
+    name?: string;
+    platform: "android" | "ios" | "web";
+    osVersion?: string;
+    model?: string;
+    fcmToken: string;
+    apnToken?: string;
+    appVersion?: string;
+    last_active_at?: string;
+    attributes?: Record<string, any>;
+}
+export declare class CDPClient {
+    private config;
+    private readonly customerIoClient;
+    private readonly apiRoot;
+    private readonly sendToCustomerIo;
+    private readonly logger;
+    private limit;
+    private timeout;
+    private readonly axiosInstance;
+    constructor(config: CDPConfig);
+    /**
+     * Tests the connection to the OpenCDP API server.
+     * Sends a ping request to verify that the configured endpoint is reachable and valid.
+     *
+     * This method ensures that credentials, and network access are configured correctly.
+     * It does NOT establish a persistent connection.
+     *
+     * Do not ping before sending each request
+     * @throws Error only when config.failOnException === true and the connection fails due to invalid credentials, network issues, or timeouts.
+     */
+    ping(): Promise<void>;
+    validateConnection(): Promise<void>;
+    private limited;
+    /**
+     * Identify a person in the CDP
+     * This method is concurrency-limited using p-limit to avoid overwhelming traffic external traffic.
+     * @param identifier The person identifier
+     * @param properties Additional properties for the person
+     * @throws Error only when config.failOnException === true (e.g., when the identifier is empty or the request fails)
+     */
+    identify(identifier: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Track an event for a person.
+     * @param identifier The person identifier
+     * @param eventName The event name
+     * @param properties Additional properties for the event
+     * @throws Error only when config.failOnException === true (e.g., when validation or request fails)
+     */
+    track(identifier: string, eventName: string, properties?: Record<string, any>): Promise<void>;
+    /**
+     * Register a device for a person. A device must be registered to send push notifications
+     * @param identifier
+     * @param deviceRegistrationParameters
+     * @throws Error only when config.failOnException === true (e.g., when validation or request fails)
+     */
+    registerDevice(identifier: string, deviceRegistrationParameters: DeviceRegistrationParameters): Promise<void>;
+    /**
+     * Send an email using the CDP transactional email service
+     * @param request The send email request parameters
+     * @returns Promise that resolves when the email is sent
+    * @throws Error only when config.failOnException === true and validation or the request fails
+     */
+    sendEmail(request: SendEmailRequest): Promise<Record<string, any>>;
+    /**
+     * Warns about unsupported fields that are accepted but not processed by the backend
+     * @param request The send email request parameters
+     */
+    private warnUnsupportedFields;
+    /**
+     * Send a push notification using the OpenCDP transactional push service
+     * @param request The send push request parameters
+     * @returns Promise that resolves when the push notification is sent
+     * @throws Error only when config.failOnException === true and validation or the request fails
+     */
+    sendPush(request: SendPushRequest): Promise<any>;
+    /**
+     * Send an SMS using the OpenCDP transactional SMS service
+     * @param request The send SMS request parameters
+     * @returns Promise that resolves when the SMS is sent
+     * @throws Error only when config.failOnException === true and validation or the request fails
+     */
+    sendSms(request: SendSmsRequest): Promise<any>;
+}
+export {};