@clianta/sdk 1.5.0 → 1.6.0

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import { ReactNode, ErrorInfo } from 'react';
 
 /**
  * Clianta SDK - CRM API Client
@@ -87,6 +87,63 @@ interface ConsentState {
     personalization?: boolean;
 }
 type EventType = 'page_view' | 'button_click' | 'form_view' | 'form_submit' | 'form_interaction' | 'scroll_depth' | 'engagement' | 'download' | 'exit_intent' | 'error' | 'performance' | 'time_on_page' | 'custom';
+interface TrackingEvent {
+    /** Workspace/project ID */
+    workspaceId: string;
+    /** Anonymous visitor identifier */
+    visitorId: string;
+    /** Session identifier */
+    sessionId: string;
+    /** Event type category */
+    eventType: EventType;
+    /** Human-readable event name */
+    eventName: string;
+    /** Current page URL */
+    url: string;
+    /** Referrer URL */
+    referrer?: string;
+    /** Event properties/metadata */
+    properties: Record<string, unknown>;
+    /** Device information */
+    device: DeviceInfo;
+    /** UTM parameters */
+    utm?: UTMParams;
+    /** ISO timestamp */
+    timestamp: string;
+    /** SDK version */
+    sdkVersion: string;
+}
+interface DeviceInfo {
+    userAgent: string;
+    screen: string;
+    language: string;
+    timezone?: string;
+}
+interface UTMParams {
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmTerm?: string;
+    utmContent?: string;
+}
+interface GroupTraits {
+    /** Company/account name */
+    name?: string;
+    /** Industry */
+    industry?: string;
+    /** Company size */
+    employees?: number;
+    /** Annual revenue */
+    revenue?: number;
+    /** Company website */
+    website?: string;
+    /** Company plan/tier */
+    plan?: string;
+    /** Additional custom properties */
+    [key: string]: unknown;
+}
+/** Event middleware function — intercept or transform events before they are sent */
+type MiddlewareFn = (event: TrackingEvent, next: () => void) => void;
 interface UserTraits {
     firstName?: string;
     lastName?: string;
@@ -122,6 +179,18 @@ interface TrackerCore {
     deleteData(): void;
     /** Get current consent state */
     getConsentState(): ConsentState;
+    /** Associate the current visitor with a group (company/account) */
+    group(groupId: string, traits?: GroupTraits): void;
+    /** Merge two visitor identities (e.g., anonymous → logged-in) */
+    alias(newId: string, previousId?: string): Promise<boolean>;
+    /** Track a screen view (for mobile-first PWAs and SPAs) */
+    screen(name: string, properties?: Record<string, unknown>): void;
+    /** Register event middleware to intercept/transform events before sending */
+    use(middleware: MiddlewareFn): void;
+    /** Register a callback to be invoked when the SDK is fully initialized */
+    onReady(callback: () => void): void;
+    /** Check if the SDK is fully initialized and ready */
+    isReady(): boolean;
     /** Get the current visitor's profile from the CRM */
     getVisitorProfile(): Promise<VisitorProfile | null>;
     /** Get the current visitor's recent activity */
@@ -140,6 +209,16 @@ interface TrackerCore {
     getVisitorEngagement(): Promise<EngagementMetrics | null>;
     /** Send a server-side inbound event (requires apiKey in config) */
     sendEvent(payload: InboundEventPayload): Promise<InboundEventResult>;
+    /** Create or update a contact by email (upsert) */
+    createContact(data: PublicContactData): Promise<PublicCrmResult>;
+    /** Update an existing contact by ID (limited fields) */
+    updateContact(contactId: string, data: PublicContactUpdate): Promise<PublicCrmResult>;
+    /** Submit a form — creates/updates contact from form data */
+    submitForm(formId: string, data: PublicFormSubmission): Promise<PublicCrmResult>;
+    /** Log an activity linked to a contact (append-only) */
+    logActivity(data: PublicActivityData): Promise<PublicCrmResult>;
+    /** Create an opportunity (e.g., from "Request Demo" forms) */
+    createOpportunity(data: PublicOpportunityData): Promise<PublicCrmResult>;
 }
 interface VisitorProfile {
     visitorId: string;
@@ -211,23 +290,83 @@ interface VisitorActivityOptions {
     startDate?: string;
     endDate?: string;
 }
+interface PublicContactData {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    jobTitle?: string;
+    phone?: string;
+    source?: string;
+    tags?: string[];
+    customFields?: Record<string, unknown>;
+}
+interface PublicContactUpdate {
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    jobTitle?: string;
+    phone?: string;
+    tags?: string[];
+    customFields?: Record<string, unknown>;
+}
+interface PublicActivityData {
+    contactId: string;
+    type: 'call' | 'email' | 'meeting' | 'note' | 'other';
+    title: string;
+    description?: string;
+    direction?: 'inbound' | 'outbound';
+    duration?: number;
+    emailSubject?: string;
+    metadata?: Record<string, unknown>;
+}
+interface PublicOpportunityData {
+    title: string;
+    contactId: string;
+    pipelineId: string;
+    stageId: string;
+    value?: number;
+    currency?: string;
+    description?: string;
+    expectedCloseDate?: string;
+    customFields?: Record<string, unknown>;
+}
+interface PublicFormSubmission {
+    fields: Record<string, unknown>;
+    metadata?: {
+        visitorId?: string;
+        sessionId?: string;
+        pageUrl?: string;
+        referrer?: string;
+    };
+}
+interface PublicCrmResult {
+    success: boolean;
+    data?: Record<string, unknown>;
+    error?: string;
+    status?: number;
+}
 
 interface CliantaProviderProps {
     /** Configuration object (from clianta.config.ts) */
     config: CliantaConfig;
     /** React children */
     children: ReactNode;
+    /** Optional error handler when the SDK encounters errors */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
 }
 /**
  * CliantaProvider - Wrap your app to enable tracking
  *
+ * Includes an ErrorBoundary so SDK failures never crash the host app.
+ *
  * @example
  * // In clianta.config.ts:
  * import { CliantaConfig } from '@clianta/sdk';
  *
  * const config: CliantaConfig = {
  *   projectId: 'your-project-id',
- *   apiEndpoint: 'https://api.clianta.online',
+ *   apiEndpoint: process.env.NEXT_PUBLIC_CLIANTA_API_ENDPOINT || 'http://localhost:5000',
  *   debug: process.env.NODE_ENV === 'development',
  * };
  *
@@ -241,7 +380,7 @@ interface CliantaProviderProps {
  *   {children}
  * </CliantaProvider>
  */
-declare function CliantaProvider({ config, children }: CliantaProviderProps): react_jsx_runtime.JSX.Element;
+declare function CliantaProvider({ config, children, onError }: CliantaProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * useClianta - Hook to access tracker in any component
  *
@@ -250,6 +389,19 @@ declare function CliantaProvider({ config, children }: CliantaProviderProps): re
  * tracker?.track('button_click', 'CTA Button');
  */
 declare function useClianta(): TrackerCore | null;
+/**
+ * useCliantaReady - Hook to check if SDK is initialized
+ *
+ * @example
+ * const { isReady, tracker } = useCliantaReady();
+ * if (isReady) {
+ *   tracker.track('purchase', 'Order', { value: 99 });
+ * }
+ */
+declare function useCliantaReady(): {
+    isReady: boolean;
+    tracker: TrackerCore | null;
+};
 /**
  * useCliantaTrack - Convenience hook for tracking events
  *
@@ -259,5 +411,5 @@ declare function useClianta(): TrackerCore | null;
  */
 declare function useCliantaTrack(): (eventType: string, eventName: string, properties?: Record<string, unknown>) => void;
 
-export { CliantaProvider, useClianta, useCliantaTrack };
+export { CliantaProvider, useClianta, useCliantaReady, useCliantaTrack };
 export type { CliantaConfig, CliantaProviderProps, TrackerCore };