@kitbase/messaging 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Configuration for the Messaging SDK
+ *
+ * @example CDN / Script tag
+ * ```html
+ * <script>
+ *   window.KITBASE_MESSAGING = { sdkKey: 'your-api-key' };
+ * </script>
+ * <script src="https://unpkg.com/@kitbase/messaging/dist/cdn.js"></script>
+ * ```
+ *
+ * @example NPM
+ * ```typescript
+ * import { Messaging } from '@kitbase/messaging';
+ *
+ * const messaging = new Messaging({
+ *   sdkKey: 'your-api-key',
+ *   metadata: { plan: 'pro' },
+ * });
+ * ```
+ */
+interface MessagingConfig {
+    /** Your Kitbase SDK key */
+    sdkKey: string;
+    /**
+     * Override the API base URL (for self-hosted instances).
+     * @default 'https://api.kitbase.dev'
+     */
+    baseUrl?: string;
+    /**
+     * Current user ID. When provided, show-once messages that the user
+     * has already viewed are excluded from results.
+     *
+     * @example
+     * ```typescript
+     * new Messaging({
+     *   sdkKey: '...',
+     *   userId: currentUser.id,
+     * });
+     * ```
+     */
+    userId?: string;
+    /**
+     * Metadata key-value pairs for targeting evaluation.
+     * Only messages whose targeting conditions match this metadata
+     * will be returned.
+     *
+     * @example
+     * ```typescript
+     * new Messaging({
+     *   sdkKey: '...',
+     *   metadata: { plan: 'free', country: 'US' },
+     * });
+     * ```
+     */
+    metadata?: Record<string, string>;
+    /**
+     * How often to poll for new messages (milliseconds).
+     * Set to `0` to disable polling (fetch once on init only).
+     * @default 60000
+     */
+    pollInterval?: number;
+    /**
+     * Automatically render messages in the page.
+     * Set to `false` to use data-only mode (fetch without rendering).
+     * @default true
+     */
+    autoShow?: boolean;
+    /** Called when a message is displayed to the user. */
+    onShow?: (message: InAppMessage) => void;
+    /** Called when a message is dismissed (close button or after action). */
+    onDismiss?: (message: InAppMessage) => void;
+    /**
+     * Called when an action button is clicked.
+     * By default, the URL is opened in a new tab.
+     * Return `false` to prevent the default navigation.
+     */
+    onAction?: (message: InAppMessage, button: MessageButton) => void | false;
+}
+/** Message display format */
+type MessageType = 'modal' | 'banner' | 'card' | 'image';
+/**
+ * A message action button with optional styling
+ */
+interface MessageButton {
+    /** Button label */
+    text: string;
+    /** URL to navigate to when clicked */
+    url: string;
+    /** Button background color (hex, e.g. '#4F46E5') */
+    color?: string;
+    /** Button text color (hex, e.g. '#FFFFFF') */
+    textColor?: string;
+}
+/**
+ * An in-app message
+ */
+interface InAppMessage {
+    /** Unique message ID */
+    id: string;
+    /** Message heading */
+    title: string;
+    /** Message body */
+    body: string;
+    /** If true, the message is hidden after the user views it once */
+    showOnce: boolean;
+    /** Display format */
+    type: MessageType;
+    /** Channel this message belongs to, or null */
+    channel: string | null;
+    /** Optional image URL */
+    imageUrl?: string;
+    /** Primary action button */
+    actionButton?: MessageButton;
+    /** Secondary action button (e.g. dismiss) */
+    secondaryButton?: MessageButton;
+    /** Background color (hex) */
+    backgroundColor?: string;
+    /** Scheduled start date (ISO-8601) */
+    startDate?: string;
+    /** Scheduled end date (ISO-8601) */
+    endDate?: string;
+}
+/**
+ * Options for fetching in-app messages
+ */
+interface GetMessagesOptions {
+    /** User ID for filtering already-viewed show-once messages */
+    userId?: string;
+    /** Metadata for targeting evaluation */
+    metadata?: Record<string, string>;
+}
+/**
+ * Options for subscribing to messages with polling
+ */
+interface SubscribeOptions extends GetMessagesOptions {
+    /**
+     * How often to poll for new messages (milliseconds).
+     * @default 60000
+     */
+    pollInterval?: number;
+}
+
+/**
+ * Initialize the Kitbase In-App Messaging SDK.
+ *
+ * Creates a singleton instance that is used for all messaging.
+ * Call this once at the top of your application entry point.
+ *
+ * @param config - SDK configuration
+ * @returns The Messaging instance
+ *
+ * @example
+ * ```typescript
+ * import { init } from '@kitbase/messaging';
+ *
+ * const messaging = init({
+ *   sdkKey: 'your-api-key',
+ *   userId: currentUser.id,
+ *   metadata: { plan: 'pro' },
+ * });
+ * ```
+ */
+declare function init(config: MessagingConfig): Messaging;
+/**
+ * Get the current Messaging singleton instance.
+ *
+ * @returns The instance, or null if `init()` has not been called
+ */
+declare function getInstance(): Messaging | null;
+/**
+ * Kitbase In-App Messaging SDK
+ *
+ * Fetches targeted in-app messages and renders them directly in the page.
+ * Supports modals, banners, cards, and full-screen images with automatic
+ * stacking.
+ *
+ * @example Using init (recommended)
+ * ```typescript
+ * import { init } from '@kitbase/messaging';
+ *
+ * const messaging = init({
+ *   sdkKey: 'your-api-key',
+ *   metadata: { plan: 'pro' },
+ *   onAction: (msg, btn) => {
+ *     console.log('User clicked:', btn.text);
+ *   },
+ * });
+ *
+ * // Later: clean up
+ * messaging.close();
+ * ```
+ *
+ * @example CDN (zero-config)
+ * ```html
+ * <script>
+ *   window.KITBASE_MESSAGING = { sdkKey: 'your-api-key' };
+ * </script>
+ * <script src="https://unpkg.com/@kitbase/messaging/dist/cdn.js"></script>
+ * <!-- Messages appear automatically! -->
+ * ```
+ *
+ * @example Data-only (no rendering)
+ * ```typescript
+ * const messaging = init({
+ *   sdkKey: 'your-api-key',
+ *   autoShow: false,
+ * });
+ *
+ * const messages = await messaging.getMessages();
+ * // render messages yourself
+ * ```
+ */
+declare class Messaging {
+    private api;
+    private renderer;
+    private config;
+    private pollTimer;
+    private dismissed;
+    private subscriptionTimers;
+    private pendingPoll;
+    private visibilityHandler;
+    private userId;
+    constructor(config: MessagingConfig);
+    /**
+     * Start fetching and rendering messages.
+     * Called automatically unless `autoShow: false`.
+     */
+    start(): void;
+    /**
+     * Stop polling and remove all rendered messages.
+     */
+    stop(): void;
+    /**
+     * Stop everything and remove all rendered UI.
+     */
+    close(): void;
+    /**
+     * Set the current user ID.
+     * Triggers an immediate re-fetch so show-once messages that the user
+     * has already viewed are filtered out.
+     */
+    identify(userId: string): void;
+    /**
+     * Clear the current user ID and reset dismissed messages.
+     * Call this on logout.
+     */
+    reset(): void;
+    /**
+     * Record that the current user has viewed a message.
+     * The message is optimistically removed from the UI.
+     *
+     * @throws {ValidationError} When no user ID has been set
+     * @throws {ApiError} When the API returns an error
+     */
+    markViewed(messageId: string): Promise<void>;
+    /**
+     * Fetch active messages without rendering.
+     * Use this when `autoShow: false` or for custom rendering.
+     *
+     * @param options - Metadata for targeting evaluation
+     * @throws {AuthenticationError} When the API key is invalid
+     * @throws {ApiError} When the API returns an error
+     * @throws {TimeoutError} When the request times out
+     */
+    getMessages(options?: GetMessagesOptions): Promise<InAppMessage[]>;
+    /**
+     * Subscribe to messages with polling (data-only, no rendering).
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * ```typescript
+     * const unsub = messaging.subscribe(
+     *   (messages) => renderMyUI(messages),
+     *   { pollInterval: 30_000 },
+     * );
+     *
+     * // Later
+     * unsub();
+     * ```
+     */
+    subscribe(callback: (messages: InAppMessage[]) => void, options?: SubscribeOptions): () => void;
+    private poll;
+}
+
+/**
+ * Base error class for Messaging SDK errors
+ */
+declare class MessagingError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when API authentication fails
+ */
+declare class AuthenticationError extends MessagingError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the API request fails
+ */
+declare class ApiError extends MessagingError {
+    readonly statusCode: number;
+    readonly response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+/**
+ * Error thrown when request validation fails
+ */
+declare class ValidationError extends MessagingError {
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/**
+ * Error thrown when a request times out
+ */
+declare class TimeoutError extends MessagingError {
+    constructor(message?: string);
+}
+
+export { ApiError, AuthenticationError, type GetMessagesOptions, type InAppMessage, type MessageButton, type MessageType, Messaging, type MessagingConfig, MessagingError, type SubscribeOptions, TimeoutError, ValidationError, getInstance, init };