lyzr-cortex-sdk 0.1.2

package/dist/index.d.mts

@@ -0,0 +1,438 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Cortex SDK Type Definitions
+ */
+/**
+ * User context from Cortex platform.
+ * Contains identity, organization, team memberships, and permissions.
+ */
+interface CortexUser {
+    /** User's unique identifier */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** User's display name */
+    name?: string;
+    /** Organization ID */
+    orgId: string;
+    /** Organization name */
+    orgName?: string;
+    /** Team memberships */
+    teams: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Organization role: admin, member */
+    role: string;
+    /** Permission list */
+    permissions: string[];
+}
+/**
+ * Document to push to Cortex Knowledge Graph.
+ */
+interface CortexDocument {
+    /** Unique ID from source tool */
+    externalId: string;
+    /** Document type: meeting_transcript, deal, etc. */
+    type: string;
+    /** Text content for RAG indexing */
+    content: string;
+    /** Display name */
+    name?: string;
+    /** URL to view in source tool */
+    externalUrl?: string;
+    /** Access scope */
+    scope?: 'global' | 'team' | 'personal';
+    /** Team IDs if scope is 'team' */
+    teamIds?: string[];
+    /** Additional metadata for filtering */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Source document returned from a query.
+ */
+interface CortexSource {
+    /** Document ID in Cortex */
+    id: string;
+    /** Document type */
+    type: string;
+    /** Document name */
+    name: string;
+    /** Relevant excerpt */
+    excerpt: string;
+    /** Relevance score */
+    score?: number;
+    /** URL to source */
+    url?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from Cortex knowledge query.
+ */
+interface CortexQueryResult {
+    /** AI-generated answer */
+    answer: string;
+    /** Source documents used */
+    sources: CortexSource[];
+    /** Original query */
+    query: string;
+}
+/**
+ * Options for querying Cortex.
+ */
+interface QueryOptions {
+    /** Filter by document type, etc. */
+    filters?: Record<string, unknown>;
+    /** Limit to recent documents (days) */
+    timeRangeDays?: number;
+    /** Maximum results to return */
+    maxResults?: number;
+}
+/**
+ * SDK configuration options.
+ */
+interface CortexConfig {
+    /** Cortex gateway URL */
+    apiUrl?: string;
+    /** Tool's API key */
+    apiKey?: string;
+    /** Tool identifier */
+    toolId?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Context value provided by CortexProvider.
+ */
+interface CortexContextValue {
+    /** Current user (null if not in embedded mode) */
+    user: CortexUser | null;
+    /** Whether app is embedded in Cortex shell */
+    isEmbedded: boolean;
+    /** Whether SDK is initialized and ready */
+    isReady: boolean;
+    /** Current theme from Cortex */
+    theme: 'light' | 'dark';
+    /** Push a document to Knowledge Graph */
+    push: (doc: Omit<CortexDocument, 'externalId'> & {
+        id: string;
+    }) => Promise<void>;
+    /** Query the Knowledge Graph */
+    query: (question: string, options?: QueryOptions) => Promise<CortexQueryResult>;
+    /** Open Cortex chat with optional prefilled query */
+    openChat: (prefilledQuery?: string) => void;
+    /** Show notification in Cortex shell */
+    showNotification: (message: string, type?: 'success' | 'error' | 'info') => void;
+}
+/**
+ * Message types for postMessage communication.
+ */
+type CortexMessageType = 'TOOL_READY' | 'CORTEX_INIT' | 'CORTEX_THEME' | 'OPEN_CHAT' | 'SHOW_NOTIFICATION' | 'NAVIGATE';
+/**
+ * PostMessage structure.
+ */
+interface CortexMessage<T = unknown> {
+    type: CortexMessageType;
+    payload?: T;
+}
+/**
+ * Payload for CORTEX_INIT message.
+ */
+interface CortexInitPayload {
+    user: CortexUser | null;
+    theme?: 'light' | 'dark';
+}
+/**
+ * Payload for CORTEX_THEME message.
+ */
+interface CortexThemePayload {
+    theme: 'light' | 'dark';
+}
+/**
+ * Payload for OPEN_CHAT message.
+ */
+interface OpenChatPayload {
+    query?: string;
+}
+/**
+ * Payload for SHOW_NOTIFICATION message.
+ */
+interface ShowNotificationPayload {
+    message: string;
+    type?: 'success' | 'error' | 'info';
+}
+/**
+ * Payload for NAVIGATE message.
+ */
+interface NavigatePayload {
+    path: string;
+}
+
+/**
+ * Props for CortexProvider component.
+ */
+interface CortexProviderProps {
+    children: ReactNode;
+    /** Cortex gateway URL (for API calls) */
+    apiUrl?: string;
+    /** Tool's API key */
+    apiKey?: string;
+    /** Tool identifier */
+    toolId?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Provider component for Cortex integration.
+ *
+ * Wrap your app with this provider to enable Cortex features.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <CortexProvider
+ *       apiUrl={process.env.REACT_APP_CORTEX_API_URL}
+ *       apiKey={process.env.REACT_APP_CORTEX_API_KEY}
+ *     >
+ *       <YourApp />
+ *     </CortexProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function CortexProvider({ children, apiUrl, apiKey, toolId, debug, }: CortexProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access Cortex context.
+ *
+ * Returns a no-op implementation if used outside CortexProvider,
+ * making it safe to use in components that may render both
+ * inside and outside the provider.
+ *
+ * @example
+ * ```tsx
+ * function MeetingCard({ meeting }) {
+ *   const { isEmbedded, openChat } = useCortex();
+ *
+ *   return (
+ *     <div>
+ *       <h3>{meeting.title}</h3>
+ *       {isEmbedded && (
+ *         <button onClick={() => openChat(`Tell me about ${meeting.title}`)}>
+ *           Ask Cortex
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useCortex(): CortexContextValue;
+/**
+ * Hook to check if currently embedded in Cortex.
+ * More efficient than useCortex() if you only need the embedded status.
+ */
+declare function useIsEmbedded(): boolean;
+/**
+ * Hook to get current Cortex user.
+ * Returns null if not embedded or not authenticated.
+ */
+declare function useCortexUser(): CortexUser | null;
+/**
+ * Hook to get current theme from Cortex.
+ */
+declare function useCortexTheme(): 'light' | 'dark';
+
+/**
+ * CortexBridge - PostMessage communication for iframe embedding.
+ *
+ * Handles bidirectional communication between tool (iframe) and
+ * Cortex shell (parent window).
+ */
+
+type MessageHandler<T = unknown> = (payload: T) => void;
+/**
+ * Public interface for CortexBridge.
+ */
+interface ICortexBridge {
+    readonly isEmbedded: boolean;
+    readonly isReady: boolean;
+    readonly user: CortexUser | null;
+    readonly theme: 'light' | 'dark';
+    waitForReady(): Promise<CortexUser | null>;
+    on<T = unknown>(messageType: string, handler: MessageHandler<T>): () => void;
+    sendToParent(message: CortexMessage): void;
+    openChat(prefilledQuery?: string): void;
+    showNotification(message: string, type?: 'success' | 'error' | 'info'): void;
+    navigate(path: string): void;
+    destroy(): void;
+}
+/**
+ * Bridge for postMessage communication with Cortex shell.
+ *
+ * @example
+ * ```typescript
+ * const bridge = new CortexBridge();
+ *
+ * // Wait for initialization
+ * const user = await bridge.waitForReady();
+ *
+ * // Send messages to Cortex
+ * bridge.openChat('What were the action items?');
+ * bridge.showNotification('Document saved', 'success');
+ * ```
+ */
+declare class CortexBridge implements ICortexBridge {
+    private handlers;
+    private parentOrigin;
+    private _isEmbedded;
+    private _isReady;
+    private _user;
+    private _theme;
+    private readyPromise;
+    private readyResolve;
+    constructor();
+    /** Whether app is embedded in Cortex shell */
+    get isEmbedded(): boolean;
+    /** Whether bridge is initialized */
+    get isReady(): boolean;
+    /** Current user from Cortex (null if standalone) */
+    get user(): CortexUser | null;
+    /** Current theme from Cortex */
+    get theme(): 'light' | 'dark';
+    /**
+     * Wait for Cortex initialization.
+     * Resolves with user if embedded, null if standalone.
+     */
+    waitForReady(): Promise<CortexUser | null>;
+    private handleMessage;
+    /**
+     * Register a handler for a message type.
+     * Returns unsubscribe function.
+     */
+    on<T = unknown>(messageType: string, handler: MessageHandler<T>): () => void;
+    /**
+     * Send a message to parent window (Cortex shell).
+     */
+    sendToParent(message: CortexMessage): void;
+    /**
+     * Open Cortex chat, optionally with a prefilled query.
+     */
+    openChat(prefilledQuery?: string): void;
+    /**
+     * Show a notification in Cortex shell.
+     */
+    showNotification(message: string, type?: 'success' | 'error' | 'info'): void;
+    /**
+     * Navigate to a path within Cortex.
+     */
+    navigate(path: string): void;
+    /**
+     * Cleanup - remove message listener.
+     */
+    destroy(): void;
+}
+/**
+ * Get the shared CortexBridge instance.
+ * Creates one if it doesn't exist.
+ */
+declare function getBridge(): ICortexBridge;
+/**
+ * Check if currently embedded in Cortex shell.
+ * Safe to call during SSR.
+ */
+declare function isEmbeddedInCortex(): boolean;
+
+/**
+ * CortexClient - HTTP client for Cortex API.
+ *
+ * For direct API calls without React context.
+ */
+
+/**
+ * HTTP client for Cortex Platform APIs.
+ *
+ * @example
+ * ```typescript
+ * const client = new CortexClient({
+ *   apiUrl: 'https://api.cortex.ai',
+ *   apiKey: 'your-api-key',
+ *   toolId: 'your-tool',
+ * });
+ *
+ * await client.push({
+ *   id: 'doc_123',
+ *   type: 'meeting_transcript',
+ *   content: 'Full transcript...',
+ * });
+ * ```
+ */
+declare class CortexClient {
+    private apiUrl;
+    private apiKey;
+    private toolId;
+    private debug;
+    constructor(config?: CortexConfig);
+    /** Whether client is configured */
+    get isConfigured(): boolean;
+    private log;
+    private request;
+    /**
+     * Push a document to Cortex Knowledge Graph.
+     */
+    push(doc: Omit<CortexDocument, 'externalId'> & {
+        id: string;
+    }): Promise<{
+        id: string;
+        status: string;
+    }>;
+    /**
+     * Query Cortex Knowledge Graph.
+     */
+    query(question: string, options?: QueryOptions & {
+        userEmail?: string;
+    }): Promise<CortexQueryResult>;
+    /**
+     * Get user context from Cortex.
+     * Calls GET /api/tools/context/{userEmail}
+     */
+    getUserContext(userEmail: string): Promise<CortexUser | null>;
+    /**
+     * Share a document with another user.
+     * Calls POST /api/tools/share-document-for-user
+     *
+     * Creates a share record so the document appears in
+     * the recipient's "Shared with Me" at /personal/shared.
+     */
+    shareDocument(params: {
+        documentExternalId: string;
+        sharedByEmail: string;
+        sharedWithEmail: string;
+        documentName?: string;
+        content?: string;
+        externalUrl?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+        id?: string;
+    }>;
+    /**
+     * Get list of users in the tool's organization.
+     * Calls GET /api/tools/org-users-for-tool
+     */
+    getOrgUsers(excludeEmail?: string): Promise<Array<{
+        id: string;
+        email: string;
+        full_name: string;
+        avatar_url?: string;
+    }>>;
+}
+/**
+ * Create a configured CortexClient instance.
+ */
+declare function createCortexClient(config: CortexConfig): CortexClient;
+
+export { CortexBridge, CortexClient, type CortexConfig, type CortexContextValue, type CortexDocument, type CortexInitPayload, type CortexMessage, type CortexMessageType, CortexProvider, type CortexProviderProps, type CortexQueryResult, type CortexSource, type CortexThemePayload, type CortexUser, type ICortexBridge, type NavigatePayload, type OpenChatPayload, type QueryOptions, type ShowNotificationPayload, createCortexClient, getBridge, isEmbeddedInCortex, useCortex, useCortexTheme, useCortexUser, useIsEmbedded };