@attrove/sdk 0.1.3 → 0.1.4

package/types/src/types/index.d.ts

@@ -0,0 +1,807 @@
+/**
+ * Attrove SDK Types
+ *
+ * Standalone type definitions for the SDK. These are bundled with the package
+ * and do not depend on internal monorepo packages.
+ */
+/**
+ * Branded type for UUID strings.
+ * Prevents accidental mixing of different ID types at compile time.
+ */
+export type UUID = string & {
+    readonly __brand: 'UUID';
+};
+/**
+ * Branded type for user IDs.
+ */
+export type UserId = string & {
+    readonly __brand: 'UserId';
+};
+/**
+ * Branded type for integration IDs.
+ */
+export type IntegrationId = string & {
+    readonly __brand: 'IntegrationId';
+};
+/**
+ * Branded type for message IDs.
+ */
+export type MessageId = string & {
+    readonly __brand: 'MessageId';
+};
+/**
+ * Branded type for conversation IDs.
+ */
+export type ConversationId = string & {
+    readonly __brand: 'ConversationId';
+};
+/**
+ * Template literal type for API key format validation.
+ * Provides compile-time validation that API keys start with 'sk_'.
+ */
+export type ApiKeyFormat = `sk_${string}`;
+/**
+ * Branded type for API key tokens (sk_ prefix).
+ * Use ApiKeyFormat for compile-time validation of the prefix format.
+ */
+export type ApiKeyToken = ApiKeyFormat & {
+    readonly __brand: 'ApiKeyToken';
+};
+/**
+ * Branded type for ISO 8601 date strings.
+ */
+export type ISODateString = string & {
+    readonly __brand: 'ISODateString';
+};
+/**
+ * Helper to cast a string to a branded type.
+ *
+ * Use with caution - this bypasses type safety. Prefer using the
+ * validation factory functions (createUserId, createApiKey, etc.)
+ * which validate the input before branding.
+ *
+ * @example
+ * ```ts
+ * // Only use after validating the format
+ * const userId = asBrandedString<UserId>(validatedUuid);
+ * ```
+ */
+export declare function asBrandedString<T extends string>(value: string): T;
+/**
+ * Check if a string is a valid UUID format.
+ * Validates the 8-4-4-4-12 hexadecimal format but does not enforce a specific UUID version.
+ *
+ * @param value - String to validate
+ * @returns True if the string is a valid UUID format
+ *
+ * @example
+ * ```ts
+ * if (isValidUUID(userId)) {
+ *   // proceed with the valid UUID
+ * }
+ * ```
+ */
+export declare function isValidUUID(value: string): boolean;
+/**
+ * Result of a validation attempt.
+ */
+export type ValidationResult<T> = {
+    success: true;
+    value: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Validate and create a UserId from a string.
+ *
+ * @param value - String to validate
+ * @returns Validation result with branded UserId or error message
+ *
+ * @example
+ * ```ts
+ * const result = createUserId('550e8400-e29b-41d4-a716-446655440000');
+ * if (result.success) {
+ *   const userId: UserId = result.value;
+ * } else {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+export declare function createUserId(value: string): ValidationResult<UserId>;
+/**
+ * Validate and create an IntegrationId from a string.
+ */
+export declare function createIntegrationId(value: string): ValidationResult<IntegrationId>;
+/**
+ * Validate and create a MessageId from a string.
+ */
+export declare function createMessageId(value: string): ValidationResult<MessageId>;
+/**
+ * Validate and create a ConversationId from a string.
+ */
+export declare function createConversationId(value: string): ValidationResult<ConversationId>;
+/**
+ * Validate and create an ApiKeyToken from a string.
+ *
+ * @example
+ * ```ts
+ * const result = createApiKey('sk_live_abc123');
+ * if (result.success) {
+ *   const apiKey: ApiKeyToken = result.value;
+ * }
+ * ```
+ */
+export declare function createApiKey(value: string): ValidationResult<ApiKeyToken>;
+/**
+ * Validate and create an ISODateString from a string.
+ *
+ * @example
+ * ```ts
+ * const result = createISODate('2024-01-15T10:30:00Z');
+ * if (result.success) {
+ *   const date: ISODateString = result.value;
+ * }
+ * ```
+ */
+export declare function createISODate(value: string): ValidationResult<ISODateString>;
+/**
+ * Validate and create a UUID from a string.
+ */
+export declare function createUUID(value: string): ValidationResult<UUID>;
+/**
+ * Check if a string is a valid API key format.
+ */
+export declare function isValidApiKey(value: string): boolean;
+/**
+ * Check if a string is a valid ISO 8601 date format.
+ */
+export declare function isValidISODate(value: string): boolean;
+/**
+ * Configuration options for the Attrove client.
+ */
+export interface AttroveConfig {
+    /**
+     * API key for authentication. Must start with `sk_` prefix.
+     * Template literal type provides compile-time validation of the prefix.
+     */
+    apiKey: ApiKeyFormat;
+    /**
+     * User ID (UUID) to scope API calls to a specific user.
+     */
+    userId: string;
+    /**
+     * Optional base URL for the API. Defaults to https://api.attrove.com.
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds. Defaults to 30000 (30 seconds).
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts for failed requests. Defaults to 3.
+     */
+    maxRetries?: number;
+    /**
+     * Optional callback invoked before each retry attempt.
+     * Useful for logging or monitoring retry behavior.
+     */
+    onRetry?: (info: RetryInfo) => void;
+}
+/**
+ * Information about a retry attempt.
+ */
+export interface RetryInfo {
+    /** Current retry attempt (1-indexed) */
+    attempt: number;
+    /** Maximum number of retries configured */
+    maxRetries: number;
+    /** The error that triggered the retry */
+    error: Error;
+    /** Delay in milliseconds before the retry */
+    delayMs: number;
+    /** The URL being requested */
+    url: string;
+    /** The HTTP method */
+    method: string;
+}
+/**
+ * Configuration options for the Attrove admin client (server-to-server).
+ */
+export interface AttroveAdminConfig {
+    /**
+     * Partner client ID.
+     */
+    clientId: string;
+    /**
+     * Partner client secret.
+     */
+    clientSecret: string;
+    /**
+     * Optional base URL for the API. Defaults to https://api.attrove.com.
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds. Defaults to 30000 (30 seconds).
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts for failed requests. Defaults to 3.
+     */
+    maxRetries?: number;
+    /**
+     * Optional callback invoked before each retry attempt.
+     */
+    onRetry?: (info: RetryInfo) => void;
+}
+/**
+ * Standardized error codes from the Attrove API.
+ */
+export declare const ErrorCodes: {
+    readonly AUTH_MISSING_TOKEN: "AUTH_MISSING_TOKEN";
+    readonly AUTH_INVALID_TOKEN: "AUTH_INVALID_TOKEN";
+    readonly AUTH_EXPIRED_TOKEN: "AUTH_EXPIRED_TOKEN";
+    readonly AUTH_USER_MISMATCH: "AUTH_USER_MISMATCH";
+    readonly AUTH_INSUFFICIENT_PERMISSIONS: "AUTH_INSUFFICIENT_PERMISSIONS";
+    readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+    readonly RESOURCE_ACCESS_DENIED: "RESOURCE_ACCESS_DENIED";
+    readonly RESOURCE_ALREADY_EXISTS: "RESOURCE_ALREADY_EXISTS";
+    readonly RESOURCE_DELETED: "RESOURCE_DELETED";
+    readonly VALIDATION_INVALID_ID: "VALIDATION_INVALID_ID";
+    readonly VALIDATION_REQUIRED_FIELD: "VALIDATION_REQUIRED_FIELD";
+    readonly VALIDATION_INVALID_FORMAT: "VALIDATION_INVALID_FORMAT";
+    readonly VALIDATION_OUT_OF_RANGE: "VALIDATION_OUT_OF_RANGE";
+    readonly INTEGRATION_OAUTH_FAILED: "INTEGRATION_OAUTH_FAILED";
+    readonly INTEGRATION_EMAIL_EXISTS: "INTEGRATION_EMAIL_EXISTS";
+    readonly INTEGRATION_TOKEN_EXPIRED: "INTEGRATION_TOKEN_EXPIRED";
+    readonly INTEGRATION_SYNC_FAILED: "INTEGRATION_SYNC_FAILED";
+    readonly INTEGRATION_NOT_CONNECTED: "INTEGRATION_NOT_CONNECTED";
+    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+};
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Authentication-related error codes.
+ */
+export type AuthErrorCode = typeof ErrorCodes.AUTH_MISSING_TOKEN | typeof ErrorCodes.AUTH_INVALID_TOKEN | typeof ErrorCodes.AUTH_EXPIRED_TOKEN | typeof ErrorCodes.AUTH_USER_MISMATCH | typeof ErrorCodes.AUTH_INSUFFICIENT_PERMISSIONS;
+/**
+ * Validation-related error codes.
+ */
+export type ValidationErrorCode = typeof ErrorCodes.VALIDATION_INVALID_ID | typeof ErrorCodes.VALIDATION_REQUIRED_FIELD | typeof ErrorCodes.VALIDATION_INVALID_FORMAT | typeof ErrorCodes.VALIDATION_OUT_OF_RANGE;
+/**
+ * Base error details shared by all error types.
+ */
+interface BaseErrorDetails {
+    /** Additional context-specific properties */
+    [key: string]: unknown;
+}
+/**
+ * Error details for validation errors.
+ */
+export interface ValidationErrorDetails extends BaseErrorDetails {
+    category: 'validation';
+    /** Field name that failed validation */
+    field?: string;
+    /** Fields that were provided (for partial credential errors) */
+    providedFields?: string[];
+    /** Expected value or format */
+    expected?: string;
+    /** Received value or format */
+    received?: string;
+    /** Actual value that caused the error */
+    value?: unknown;
+}
+/**
+ * Error details for rate limiting errors.
+ */
+export interface RateLimitErrorDetails extends BaseErrorDetails {
+    category: 'rateLimit';
+    /** Time in seconds until rate limit resets */
+    retryAfter?: number;
+    /** Rate limit ceiling */
+    limit?: number;
+}
+/**
+ * Error details for resource errors (not found, access denied, etc.).
+ */
+export interface ResourceErrorDetails extends BaseErrorDetails {
+    category: 'resource';
+    /** Type of resource involved */
+    resourceType?: string;
+    /** ID of resource involved */
+    resourceId?: string;
+}
+/**
+ * Error details for network/wrapped errors.
+ */
+export interface NetworkErrorDetails extends BaseErrorDetails {
+    category: 'network';
+    /** Original error name for wrapped errors */
+    originalErrorName?: string;
+    /** Original error message for wrapped errors */
+    originalErrorMessage?: string;
+    /** Truncated stack trace for debugging */
+    originalStack?: string;
+}
+/**
+ * Error details for parse/serialization errors.
+ */
+export interface ParseErrorDetails extends BaseErrorDetails {
+    category: 'parse';
+    /** Truncated response preview for debugging */
+    responsePreview?: string;
+    /** Truncated raw data preview for debugging */
+    rawDataPreview?: string;
+}
+/**
+ * Generic error details for errors that don't fit other categories.
+ * Note: category is optional for backward compatibility with existing code
+ * that passes arbitrary details without specifying a category.
+ */
+export interface GenericErrorDetails extends BaseErrorDetails {
+    category?: 'generic';
+}
+/**
+ * Discriminated union of error details for type-safe error handling.
+ * The `category` field discriminates which type of error details are present.
+ *
+ * @example
+ * ```ts
+ * if (error.details?.category === 'validation') {
+ *   console.log('Invalid field:', error.details.field);
+ * } else if (error.details?.category === 'rateLimit') {
+ *   console.log('Retry after:', error.details.retryAfter);
+ * }
+ * ```
+ */
+export type ErrorDetails = ValidationErrorDetails | RateLimitErrorDetails | ResourceErrorDetails | NetworkErrorDetails | ParseErrorDetails | GenericErrorDetails;
+/**
+ * API error response structure.
+ */
+export interface ApiError {
+    code: ErrorCode;
+    message: string;
+    details?: ErrorDetails;
+}
+/**
+ * Pagination metadata for list responses.
+ */
+export interface Pagination {
+    limit: number;
+    offset: number;
+    has_more: boolean;
+    total_count?: number;
+}
+/**
+ * Success response wrapper.
+ */
+export interface SuccessResponse<T> {
+    success: true;
+    data: T;
+}
+/**
+ * Paginated success response wrapper.
+ */
+export interface PaginatedResponse<T> {
+    success: true;
+    data: T[];
+    pagination: Pagination;
+}
+/**
+ * Error response wrapper.
+ * Note: The error is always normalized to ApiError format in the SDK.
+ */
+export interface ErrorResponse {
+    success: false;
+    error: ApiError;
+}
+/**
+ * Generic API response type.
+ */
+export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse;
+/**
+ * Supported integration providers.
+ * Note: 'unknown' is included for forward compatibility with new providers.
+ */
+export type IntegrationProvider = 'slack' | 'gmail' | 'outlook' | 'google_calendar' | 'unknown';
+/**
+ * Authentication status for an integration.
+ * Note: 'unknown' is included for forward compatibility with new statuses.
+ */
+export type AuthStatus = 'connected' | 'disconnected' | 'expired' | 'error' | 'pending' | 'unknown';
+/**
+ * Sync status for an integration.
+ * Note: 'unknown' is included for forward compatibility with new statuses.
+ */
+export type SyncStatus = 'syncing' | 'complete' | 'partial' | 'error' | 'pending' | 'paused' | 'unknown';
+/**
+ * User profile information.
+ */
+export interface User {
+    id: string;
+    email: string;
+    first_name: string | null;
+    last_name: string | null;
+    full_name: string | null;
+    role: string | null;
+    timezone: string | null;
+    onboarded: boolean;
+}
+/**
+ * Integration (connected service) information.
+ */
+export interface Integration {
+    id: string;
+    provider: IntegrationProvider;
+    name: string;
+    is_active: boolean;
+    auth_status: AuthStatus;
+}
+/**
+ * Message from a connected service.
+ */
+export interface Message {
+    id: string;
+    integration_id: string;
+    body_text?: string;
+    subject: string | null;
+    received_at: string;
+    parent_message_id: string | null;
+    thread_position: number | null;
+    is_bot: boolean;
+    conversation_id: string | null;
+}
+/**
+ * Conversation type.
+ * Note: 'unknown' is included for forward compatibility with new types.
+ */
+export type ConversationType = 'channel' | 'direct_message' | 'group' | 'email_thread' | 'other' | 'unknown';
+/**
+ * Conversation (channel, thread, etc.) from a connected service.
+ */
+export interface Conversation {
+    id: string;
+    integration_id: string;
+    title: string;
+    type: ConversationType;
+    provider: IntegrationProvider;
+    import_messages: boolean;
+}
+/**
+ * Calendar event.
+ */
+export interface CalendarEvent {
+    id: string;
+    calendar_id: string;
+    title: string;
+    start_time: string;
+    end_time: string;
+    all_day: boolean;
+    description?: string;
+    location?: string;
+    attendees?: Array<{
+        email: string;
+        name?: string;
+        status?: string;
+    }>;
+    html_link?: string;
+}
+/**
+ * Meeting with AI-generated summary.
+ */
+export interface Meeting {
+    id: string;
+    event_id: string;
+    title: string;
+    start_time: string;
+    end_time: string;
+    summary?: string;
+    short_summary?: string;
+    action_items?: string[];
+    attendees?: Array<{
+        email: string;
+        name?: string;
+    }>;
+    meeting_link?: string;
+}
+/**
+ * Entity type.
+ */
+export type EntityType = 'person' | 'company' | 'other';
+/**
+ * Entity (person, company, etc.) identified from messages.
+ */
+export interface Entity {
+    id: string;
+    name: string;
+    type: EntityType;
+    email?: string;
+    domain?: string;
+    message_count: number;
+    last_interaction?: string;
+}
+/**
+ * Overall sync status.
+ */
+export type OverallSyncStatus = 'syncing' | 'complete' | 'partial' | 'error' | 'pending';
+/**
+ * Integration sync statistics.
+ */
+export interface IntegrationSyncStats {
+    id: string;
+    provider: IntegrationProvider;
+    name: string;
+    status: SyncStatus;
+    message_count: number;
+    meeting_count: number;
+    event_count: number;
+    last_synced_at: string | null;
+}
+/**
+ * Sync statistics for a user's integrations.
+ */
+export interface SyncStats {
+    user_id: string;
+    overall_status: OverallSyncStatus;
+    last_sync_at: string | null;
+    totals: {
+        messages: {
+            count: number;
+            earliest?: string;
+            latest?: string;
+        };
+        meetings: {
+            count: number;
+            earliest?: string;
+            latest?: string;
+        };
+        events: {
+            count: number;
+            earliest?: string;
+            latest?: string;
+        };
+    };
+    integrations: IntegrationSyncStats[];
+}
+/**
+ * Conversation history message for RAG queries.
+ */
+export interface ConversationMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+/**
+ * Options for the query() method.
+ */
+export interface QueryOptions {
+    /**
+     * Conversation history for multi-turn conversations.
+     */
+    history?: ConversationMessage[];
+    /**
+     * User's timezone (IANA format). Helps with date-aware queries.
+     */
+    timezone?: string;
+    /**
+     * Filter to specific integration IDs.
+     */
+    integrationIds?: string[];
+    /**
+     * Filter to specific conversation IDs.
+     */
+    conversationIds?: string[];
+    /**
+     * Include bot messages in search results. Defaults to false.
+     */
+    allowBotMessages?: boolean;
+    /**
+     * Include source snippets in response. Defaults to false.
+     */
+    includeSources?: boolean;
+}
+/**
+ * Source reference from a RAG query response.
+ */
+export interface QuerySource {
+    title: string;
+    snippet: string;
+}
+/**
+ * Response from the query() method.
+ */
+export interface QueryResponse {
+    answer: string;
+    history: ConversationMessage[];
+    used_message_ids: string[];
+    sources?: QuerySource[];
+}
+/**
+ * Options for the search() method.
+ */
+export interface SearchOptions {
+    /**
+     * Filter to specific integration IDs.
+     */
+    integrationIds?: string[];
+    /**
+     * Filter to specific conversation IDs.
+     */
+    conversationIds?: string[];
+    /**
+     * Filter messages after this date (ISO 8601).
+     */
+    afterDate?: string;
+    /**
+     * Filter messages before this date (ISO 8601).
+     */
+    beforeDate?: string;
+    /**
+     * Include bot messages in search results. Defaults to false.
+     */
+    allowBotMessages?: boolean;
+    /**
+     * Filter by sender email domains (e.g., ['acme.com']).
+     */
+    senderDomains?: string[];
+    /**
+     * Filter by entity IDs.
+     */
+    entityIds?: string[];
+    /**
+     * Include message body text. Defaults to false.
+     */
+    includeBodyText?: boolean;
+}
+/**
+ * Key message reference from search results.
+ * Note: IDs are strings for consistency (converted from API numbers).
+ */
+export interface SearchKeyMessage {
+    message_id: string;
+    thread_id: string | null;
+    conversation_id: string | null;
+}
+/**
+ * Thread message in search results.
+ * Note: IDs are strings for consistency (converted from API numbers).
+ */
+export interface SearchThreadMessage {
+    message_id: string;
+    received_at: string;
+    integration_type: IntegrationProvider;
+    integration_type_generic: string;
+    sender_name: string;
+    recipient_names: string[];
+    body_text?: string;
+    thread_id: string | null;
+    thread_message_count: number | null;
+    thread_position: number | null;
+    parent_message_id: string | null;
+    conversation_type: ConversationType | null;
+    conversation_id: string | null;
+    conversation_participants: Array<{
+        name: string;
+    }>;
+}
+/**
+ * Conversation data in search results.
+ */
+export interface SearchConversation {
+    conversation_name: string | null;
+    threads: Record<string, SearchThreadMessage[]>;
+}
+/**
+ * Response from the search() method.
+ */
+export interface SearchResponse {
+    key_messages: SearchKeyMessage[];
+    conversations: Record<string, SearchConversation>;
+}
+/**
+ * Options for creating a user.
+ */
+export interface CreateUserOptions {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    role?: string;
+}
+/**
+ * Response from creating a user.
+ * Note: `apiKey` is an sk_ prefixed API key for authenticating as this user.
+ */
+export interface CreateUserResponse {
+    /** The user's ID (UUID format) */
+    id: string;
+    /** API key (sk_ prefix) for authenticating requests as this user */
+    apiKey: string;
+}
+/**
+ * Response from creating an integration token.
+ */
+export interface CreateTokenResponse {
+    token: string;
+    expires_at: string;
+}
+/**
+ * Stream state during query processing.
+ */
+export type StreamState = 'selecting_messages' | 'streaming' | 'completed' | 'cancelled' | 'error';
+/**
+ * Stream end reasons.
+ */
+export type StreamEndReason = 'completed' | 'cancelled' | 'error';
+/**
+ * Frame types for WebSocket streaming.
+ * Note: used_message_ids are strings for consistency.
+ */
+export type StreamFrame = {
+    type: 'chunk';
+    message_id: string;
+    content: string;
+} | {
+    type: 'end';
+    message_id: string;
+    reason: StreamEndReason;
+    used_message_ids?: string[];
+} | {
+    type: 'error';
+    message_id: string;
+    error: string;
+} | {
+    type: 'state';
+    message_id: string;
+    state: StreamState;
+} | {
+    type: 'message_ids';
+    message_id: string;
+    used_message_ids: string[];
+} | {
+    type: 'stream_start';
+    message_id: string;
+};
+/**
+ * Runtime validator for StreamFrame objects.
+ * Validates that parsed JSON has the required structure for a StreamFrame.
+ *
+ * @param data - Unknown data to validate (typically from JSON.parse)
+ * @returns True if the data is a valid StreamFrame, false otherwise
+ *
+ * @example
+ * ```ts
+ * const parsed = JSON.parse(event.data);
+ * if (isValidStreamFrame(parsed)) {
+ *   // TypeScript knows parsed is StreamFrame
+ *   handleFrame(parsed);
+ * }
+ * ```
+ */
+export declare function isValidStreamFrame(data: unknown): data is StreamFrame;
+/**
+ * Pagination options for list methods.
+ */
+export interface PaginationOptions {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Options for listing messages.
+ */
+export interface ListMessagesOptions extends PaginationOptions {
+    ids?: string[];
+    integrationId?: string;
+    conversationId?: string;
+    startDate?: string;
+    endDate?: string;
+    expand?: string[];
+}
+/**
+ * Options for listing conversations.
+ */
+export interface ListConversationsOptions extends PaginationOptions {
+    integrationIds?: string[];
+    syncedOnly?: boolean;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map