@omnikit-ai/sdk 2.0.9 → 2.2.0

package/dist/index.d.ts

@@ -1,5 +1,70 @@
 export { cleanTokenFromUrl, getAccessToken, isTokenInUrl, removeAccessToken, saveAccessToken, setAccessToken } from './auth-utils.js';
 
+/**
+ * Omnikit SDK - Connectors Module
+ *
+ * Provides access to connected external services (Slack, Google Calendar, Notion, etc.)
+ * Like Base44's connectors module - allows backend functions to get access tokens
+ * for making direct API calls to external services.
+ *
+ * SECURITY: getAccessToken requires service token authentication.
+ * Only available to backend functions, not frontend code.
+ */
+type ConnectorType = 'slack' | 'google_calendar' | 'notion' | 'salesforce';
+interface ConnectorAccessTokenResponse {
+    success: boolean;
+    access_token: string;
+    connector_type: string;
+    external_workspace_id?: string;
+    external_workspace_name?: string;
+}
+interface ConnectorStatusResponse {
+    success: boolean;
+    connector?: {
+        connector_type: string;
+        status: string;
+        external_workspace_id?: string;
+        external_workspace_name?: string;
+        external_user_email?: string;
+    };
+}
+interface ConnectorsModule$1 {
+    /**
+     * Get access token for a connector.
+     *
+     * SECURITY: Requires service token authentication.
+     * Only available in backend functions, not frontend code.
+     *
+     * @example
+     * ```typescript
+     * // In a backend function
+     * const { access_token } = await omnikit.connectors.getAccessToken('slack');
+     *
+     * // Make direct Slack API call
+     * const response = await fetch('https://slack.com/api/chat.postMessage', {
+     *   method: 'POST',
+     *   headers: {
+     *     'Authorization': `Bearer ${access_token}`,
+     *     'Content-Type': 'application/json',
+     *   },
+     *   body: JSON.stringify({
+     *     channel: '#general',
+     *     text: 'Hello from Omnikit!'
+     *   })
+     * });
+     * ```
+     */
+    getAccessToken(connectorType: ConnectorType): Promise<ConnectorAccessTokenResponse>;
+    /**
+     * Check if a connector is connected.
+     */
+    isConnected(connectorType: ConnectorType): Promise<boolean>;
+    /**
+     * Get connector status and info.
+     */
+    getStatus(connectorType: ConnectorType): Promise<ConnectorStatusResponse>;
+}
+
 /**
  * Omnikit SDK Type Definitions v2.0
  */
@@ -795,6 +860,48 @@ interface AuthModule {
      */
     onUserChange(callback: (user: UserInfo | null) => void): () => void;
 }
+/**
+ * Connectors module interface for accessing external service tokens.
+ * SECURITY: Only available via client.service for backend functions.
+ */
+interface ConnectorsModule {
+    /**
+     * Get access token for a connector (e.g., Slack, Google Calendar).
+     * SECURITY: Only available in backend functions, not frontend code.
+     *
+     * @example
+     * ```typescript
+     * const omnikit = createServerClient(req);
+     * const { access_token } = await omnikit.service.connectors.getAccessToken('slack');
+     *
+     * // Make direct Slack API call
+     * await fetch('https://slack.com/api/chat.postMessage', {
+     *   headers: { Authorization: `Bearer ${access_token}` },
+     *   body: JSON.stringify({ channel: '#general', text: 'Hello!' })
+     * });
+     * ```
+     */
+    getAccessToken(connectorType: string): Promise<{
+        success: boolean;
+        access_token: string;
+        connector_type: string;
+        external_workspace_id?: string;
+        external_workspace_name?: string;
+    }>;
+    /** Check if a connector is connected */
+    isConnected(connectorType: string): Promise<boolean>;
+    /** Get connector status */
+    getStatus(connectorType: string): Promise<{
+        success: boolean;
+        connector?: {
+            connector_type: string;
+            status: string;
+            external_workspace_id?: string;
+            external_workspace_name?: string;
+            external_user_email?: string;
+        };
+    }>;
+}
 /**
  * Service role client interface (elevated admin operations)
  * Available when serviceToken is provided in config
@@ -808,6 +915,17 @@ interface ServiceRoleClient {
     services: Record<string, IntegrationMethod>;
     /** @deprecated Use services instead. Integration operations with service role privileges */
     integrations: Record<string, Record<string, IntegrationMethod>>;
+    /**
+     * Connectors module for accessing external service tokens (Slack, Google Calendar, etc.)
+     * SECURITY: Only available via client.service for backend functions.
+     *
+     * @example
+     * ```typescript
+     * const omnikit = createServerClient(req);
+     * const { access_token } = await omnikit.service.connectors.getAccessToken('slack');
+     * ```
+     */
+    connectors: ConnectorsModule;
 }
 /**
  * Main Omnikit Client interface
@@ -867,11 +985,36 @@ interface OmnikitClient {
     /** Authentication methods */
     auth: AuthModule;
     /**
-     * Service role operations (admin/elevated privileges)
-     * Only available when serviceToken is provided in config
-     * Throws error if accessed without serviceToken
+     * Service-level operations (elevated privileges).
+     * Only available when serviceToken is provided (e.g., via createServerClient).
+     * Throws error if accessed without serviceToken.
+     *
+     * @example
+     * ```typescript
+     * // In a backend function
+     * const omnikit = createServerClient(req);
+     * const { access_token } = await omnikit.service.connectors.getAccessToken('slack');
+     * ```
+     */
+    service?: ServiceRoleClient;
+    /**
+     * @deprecated Use service instead. Will be removed in next major version.
      */
     asServiceRole?: ServiceRoleClient;
+    /**
+     * Connectors module for accessing external service tokens.
+     *
+     * SECURITY: getAccessToken requires service token authentication.
+     * Prefer using omnikit.service.connectors in backend functions.
+     *
+     * @example
+     * ```typescript
+     * // In a backend function (using service role)
+     * const omnikit = createServerClient(req);
+     * const { access_token } = await omnikit.service.connectors.getAccessToken('slack');
+     * ```
+     */
+    connectors: ConnectorsModule;
     /** @internal */
     getAppMetadata(): Promise<AppSchema>;
     /** @internal */
@@ -1183,10 +1326,16 @@ declare class APIClient implements OmnikitClient {
     private _integrations;
     private _auth;
     private _asServiceRole?;
+    private _connectors?;
     private _metadata;
     private _metadataListeners;
     private _userListeners;
     constructor(config: OmnikitConfig);
+    /**
+     * Initialize built-in services with their definitions
+     * These services don't require backend schema - they're defined in the SDK
+     */
+    private initializeBuiltInServices;
     /**
      * Load metadata from localStorage cache, falling back to initial config
      * Guards localStorage access for Deno/Node compatibility
@@ -1264,10 +1413,35 @@ declare class APIClient implements OmnikitClient {
      */
     get auth(): AuthModule;
     /**
-     * Lazy getter for service role operations
-     * Only available when serviceToken is provided
+     * Service-level operations (elevated privileges).
+     * Only available when serviceToken is provided (e.g., via createServerClient).
+     */
+    get service(): ServiceRoleClient;
+    /**
+     * @deprecated Use service instead
      */
     get asServiceRole(): ServiceRoleClient;
+    /**
+     * Lazy getter for connectors module
+     * Like Base44's connectors - provides access to external service tokens
+     *
+     * SECURITY: getAccessToken requires service token authentication.
+     * Only use in backend functions, not frontend code.
+     *
+     * @example
+     * ```typescript
+     * // In a backend function
+     * const { access_token } = await omnikit.connectors.getAccessToken('slack');
+     *
+     * // Make direct Slack API call
+     * const response = await fetch('https://slack.com/api/chat.postMessage', {
+     *   method: 'POST',
+     *   headers: { Authorization: `Bearer ${access_token}` },
+     *   body: JSON.stringify({ channel: '#general', text: 'Hello!' })
+     * });
+     * ```
+     */
+    get connectors(): ConnectorsModule$1;
     /**
      * Create auth proxy that auto-initializes
      */
@@ -1475,6 +1649,60 @@ declare class APIClient implements OmnikitClient {
  * ```
  */
 declare function createClient(config: OmnikitConfig): OmnikitClient;
+/**
+ * Request object interface for createServerClient.
+ * Matches Deno/Node HTTP request interface.
+ */
+interface ServerRequest {
+    headers: {
+        get?(name: string): string | null;
+        [key: string]: any;
+    };
+}
+/**
+ * Create an Omnikit client for server-side (backend function) use.
+ *
+ * Extracts authentication tokens from HTTP headers injected by the Omnikit platform:
+ * - Authorization: Bearer <user_jwt> (identifies the user making the request)
+ * - X-Omnikit-Service-Authorization: <service_token> (for privileged operations)
+ * - X-Omnikit-App-Id: <app_id> (identifies the app)
+ * - X-Omnikit-Server-Url: <server_url> (API server URL)
+ *
+ * SECURITY: The service token is injected at runtime by the platform,
+ * ensuring it cannot be leaked through source code.
+ *
+ * @example
+ * ```typescript
+ * // In a backend function (Deno Edge Function)
+ * import { createServerClient } from '@omnikit-ai/sdk';
+ *
+ * Deno.serve(async (req) => {
+ *   const omnikit = createServerClient(req);
+ *
+ *   // Access user data (user JWT auth)
+ *   const currentUser = await omnikit.auth.me();
+ *
+ *   // Access connectors (requires service token)
+ *   const { access_token } = await omnikit.service.connectors.getAccessToken('slack');
+ *
+ *   // Make direct Slack API call
+ *   await fetch('https://slack.com/api/chat.postMessage', {
+ *     headers: { Authorization: `Bearer ${access_token}` },
+ *     body: JSON.stringify({ channel: '#general', text: `Hello from ${currentUser.email}!` })
+ *   });
+ *
+ *   return new Response(JSON.stringify({ success: true }));
+ * });
+ * ```
+ *
+ * @param request - HTTP request object with headers
+ * @returns Omnikit client configured with tokens from headers
+ */
+declare function createServerClient(request: ServerRequest): OmnikitClient;
+/**
+ * @deprecated Use createServerClient instead
+ */
+declare const createClientFromRequest: typeof createServerClient;
 
 /**
  * Live Voice Session Implementation
@@ -1556,4 +1784,103 @@ declare class LiveVoiceSessionImpl implements LiveVoiceSession {
     private cleanup;
 }
 
-export { APIClient, type AppMetadata, type AppSchema, type AsyncJobCreatedResponse, type AsyncJobStatus, type AsyncJobStatusResponse, type AsyncJobType, type AsyncOptions, type AuthModule, type AuthResponse, type BuiltInIntegration, type BulkResult, type CachedMetadata, type CheckJobStatusParams, type CollectionClass, type CollectionDefinition, type CollectionField, type CollectionRecord, type EmailParams, type Entity, type EntityClass, type EntityDefinition, type EntityField, type EntityRecord, type ExtractParams, type ImageParams, type ImportResult, type InitialMetadata, type IntegrationEndpoint, type IntegrationMethod, type IntegrationPackage, type IntegrationSchema, type LLMMessage, type LLMModel, type LLMParams, type LLMStreamEvent, type LLMStreamResult, type ListOptions, type LiveVoiceClientMessage, type LiveVoiceConfig, type LiveVoiceServerMessage, type LiveVoiceSession, LiveVoiceSessionImpl, type LiveVoiceStatus, type LiveVoiceVoice, type OAuthProvider, type OAuthProvidersResponse, type OmnikitClient, type OmnikitConfig, OmnikitError, type QueryOptions, type RequestOptions, type SMSParams, type ServiceDefinition, type ServiceResponse, type ServiceRoleClient, type ServicesSchema, type SpeechParams, type TemplateDefinition, type UserCollectionClass, type UserEntityClass, type UserInfo, type VideoParams, type VideoStatusParams, createClient };
+/**
+ * Omnikit Analytics Module
+ *
+ * Provides automatic event tracking for generated apps.
+ * Supports page views, errors, auth events, and custom events.
+ *
+ * @example
+ * ```typescript
+ * import { Analytics } from '@omnikit/sdk';
+ *
+ * const analytics = new Analytics({
+ *   appId: 'your-app-id',
+ *   apiUrl: 'https://api.omnikit.ai'
+ * });
+ *
+ * // Log events
+ * analytics.logPageView('/dashboard');
+ * analytics.logEvent('button_click', { action: 'submit' });
+ * ```
+ */
+interface EventPayload {
+    page_name?: string;
+    action?: string;
+    inputs?: Record<string, any>;
+    metadata?: Record<string, any>;
+    error_message?: string;
+    error_stack?: string;
+}
+interface AnalyticsConfig {
+    appId: string;
+    apiUrl: string;
+    sessionId?: string;
+    userId?: string;
+    enabled?: boolean;
+}
+declare class Analytics {
+    private config;
+    private sessionId;
+    private userId?;
+    private eventQueue;
+    private flushTimer?;
+    private enabled;
+    constructor(config: AnalyticsConfig);
+    private initSession;
+    private generateId;
+    private saveSession;
+    /**
+     * Get the current session ID
+     */
+    getSessionId(): string;
+    /**
+     * Start a new session (e.g., after logout)
+     */
+    startNewSession(): string;
+    /**
+     * Associate events with a user ID
+     */
+    setUserId(userId: string): void;
+    /**
+     * Clear user association (e.g., on logout)
+     */
+    clearUserId(): void;
+    /**
+     * Log a custom event
+     */
+    logEvent(eventType: string, payload?: EventPayload): Promise<void>;
+    /**
+     * Log a page view event
+     */
+    logPageView(pageName: string, metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Log an error event
+     */
+    logError(error: Error, componentStack?: string): Promise<void>;
+    /**
+     * Log an API error event
+     */
+    logApiError(endpoint: string, statusCode: number, errorMessage: string, metadata?: Record<string, any>): Promise<void>;
+    private startFlushTimer;
+    /**
+     * Flush all queued events to the server
+     */
+    flush(): Promise<void>;
+    private sendEvent;
+    /**
+     * Enable or disable analytics
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if analytics is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+declare function createAnalytics(config: AnalyticsConfig): Analytics;
+
+export { APIClient, Analytics, type AnalyticsConfig, type AppMetadata, type AppSchema, type AsyncJobCreatedResponse, type AsyncJobStatus, type AsyncJobStatusResponse, type AsyncJobType, type AsyncOptions, type AuthModule, type AuthResponse, type BuiltInIntegration, type BulkResult, type CachedMetadata, type CheckJobStatusParams, type CollectionClass, type CollectionDefinition, type CollectionField, type CollectionRecord, type ConnectorAccessTokenResponse, type ConnectorStatusResponse, type ConnectorType, type ConnectorsModule, type EmailParams, type Entity, type EntityClass, type EntityDefinition, type EntityField, type EntityRecord, type EventPayload, type ExtractParams, type ImageParams, type ImportResult, type InitialMetadata, type IntegrationEndpoint, type IntegrationMethod, type IntegrationPackage, type IntegrationSchema, type LLMMessage, type LLMModel, type LLMParams, type LLMStreamEvent, type LLMStreamResult, type ListOptions, type LiveVoiceClientMessage, type LiveVoiceConfig, type LiveVoiceServerMessage, type LiveVoiceSession, LiveVoiceSessionImpl, type LiveVoiceStatus, type LiveVoiceVoice, type OAuthProvider, type OAuthProvidersResponse, type OmnikitClient, type OmnikitConfig, OmnikitError, type QueryOptions, type RequestOptions, type SMSParams, type ServiceDefinition, type ServiceResponse, type ServiceRoleClient, type ServicesSchema, type SpeechParams, type TemplateDefinition, type UserCollectionClass, type UserEntityClass, type UserInfo, type VideoParams, type VideoStatusParams, createAnalytics, createClient, createClientFromRequest, createServerClient };