API Reference

interface RaindropItem {
    id: number;
    title: string;
    url: string;
    created: string;
    updated: string;
    type: RaindropType;
    cover?: string;
    excerpt?: string;
    note?: string;
    tags: string[];
    highlights: Highlight[];
    collection: Collection;
    media: Media[];
    important: boolean;
    broken: boolean;
    canEdit: boolean;
    lastUpdate: string;
    domain: string;
    creatorRef: CreatorRef;
    sort: number;
    collectionId: number;
    user: User;
}

interface Collection {
    id: number;
    title: string;
    parent_id?: number;
    group?: string; // Top-level sidebar Group name
    path: string; // Full path including Group
    count: number;
    created: string;
    updated: string;
    user: User;
    cover?: string[];
    view: string;
    sort: number;
    expanded: boolean;
    public: boolean;
    type: string;
    description?: string;
}

interface TemplateConfig {
    name: string;
    content: string;
    variables: string[];
    type?: RaindropType;
    collectionId?: number;
}

class RaindropService {
    // Authentication
    setToken(token: string): void;
    validateToken(): Promise<boolean>;
    
    // Collections
    getCollections(): Promise<Collection[]>;
    getCollection(id: number): Promise<Collection>;
    getCollectionItems(id: number, options?: FetchOptions): Promise<RaindropItem[]>;
    
    // Items
    getItem(id: number): Promise<RaindropItem>;
    searchItems(query: string, options?: SearchOptions): Promise<RaindropItem[]>;
    
    // Rate Limiting
    getRateLimit(): Promise<RateLimit>;
    handleRateLimit(): Promise<void>;
}

class TemplateService {
    // Template Management
    registerTemplate(config: TemplateConfig): void;
    getTemplate(type: RaindropType, collectionId?: number): string;
    validateTemplate(template: string): ValidationResult;
    
    // Template Processing
    processTemplate(template: string, data: any): string;
    previewTemplate(template: string, data: any): string;
    
    // Helper Functions
    registerHelper(name: string, fn: Function): void;
    registerHelpers(helpers: Record<string, Function>): void;
}

class ImportService {
    // Import Operations
    importItems(items: RaindropItem[], options: ImportOptions): Promise<void>;
    updateItems(items: RaindropItem[], options: UpdateOptions): Promise<void>;
    
    // File Management
    createNote(item: RaindropItem, template: string): Promise<void>;
    updateNote(item: RaindropItem, template: string): Promise<void>;
    deleteNote(item: RaindropItem): Promise<void>;
    
    // Progress Tracking
    onProgress(callback: (progress: ImportProgress) => void): void;
    onComplete(callback: (result: ImportResult) => void): void;
    onError(callback: (error: Error) => void): void;
}

// Format date to ISO string
formatDateISO(date: Date): string;

// Format date to locale string
formatDate(date: Date, format?: string): string;

// Format time to locale string
formatTime(date: Date): string;

// Get relative time
relativeTime(date: Date): string;

// Sanitize text for Obsidian
sanitize(text: string): string;

// Truncate text to length
truncate(text: string, length: number): string;

// Convert to title case
titleCase(text: string): string;

// Join array elements
join(array: any[], separator?: string): string;

// Get array length
length(array: any[]): number;

// Get first element
first(array: any[]): any;

// Get last element
last(array: any[]): any;

// Check if value exists
exists(value: any): boolean;

// Check if array is empty
isEmpty(array: any[]): boolean;

// Check if string is empty
isBlank(text: string): boolean;

// Get Raindrop type
raindropType(type: string): string;

// Check if has highlights
hasHighlights(item: RaindropItem): boolean;

// Check if has tags
hasTags(item: RaindropItem): boolean;

// Format tags
formatTags(tags: string[]): string;

// Format highlights
formatHighlights(highlights: Highlight[]): string;

enum PluginEventType {
    IMPORT_START = 'import:start',
    IMPORT_PROGRESS = 'import:progress',
    IMPORT_COMPLETE = 'import:complete',
    IMPORT_ERROR = 'import:error',
    TEMPLATE_VALIDATE = 'template:validate',
    TEMPLATE_ERROR = 'template:error',
    SETTINGS_CHANGE = 'settings:change',
    API_ERROR = 'api:error'
}

interface EventHandler {
    (event: PluginEvent): void;
}

class EventManager {
    on(type: PluginEventType, handler: EventHandler): void;
    off(type: PluginEventType, handler: EventHandler): void;
    emit(type: PluginEventType, data: any): void;
}

// Create directory if not exists
createDirectory(path: string): Promise<void>;

// Check if file exists
fileExists(path: string): Promise<boolean>;

// Read file content
readFile(path: string): Promise<string>;

// Write file content
writeFile(path: string, content: string): Promise<void>;

// Delete file
deleteFile(path: string): Promise<void>;

// Sanitize filename
sanitizeFilename(name: string): string;

// Generate unique filename
generateUniqueFilename(name: string, path: string): Promise<string>;

// Format path
formatPath(path: string): string;

// Join paths
joinPaths(...paths: string[]): string;

// Parse date string
parseDate(date: string): Date;

// Format date string
formatDateString(date: Date, format: string): string;

// Get relative time string
getRelativeTimeString(date: Date): string;

// Check if date is valid
isValidDate(date: any): boolean;

// Validate template
validateTemplate(template: string): ValidationResult;

// Validate options
validateOptions(options: any): ValidationResult;

// Validate path
validatePath(path: string): ValidationResult;

// Validate token
validateToken(token: string): ValidationResult;

// Create error
createError(message: string, code?: string): Error;

// Handle error
handleError(error: Error): void;

// Log error
logError(error: Error): void;

// Format error
formatError(error: Error): string;

interface PluginSettings {
    apiToken: string;
    defaultPath: string;
    filenameTemplate: string;
    showRibbonIcon: boolean;
    bannerFieldName: string;
    rateLimit: number;
    retryCount: number;
    retryDelay: number;
    debugMode: boolean;
}

// Load settings
loadSettings(): Promise<PluginSettings>;

// Save settings
saveSettings(settings: PluginSettings): Promise<void>;

// Reset settings
resetSettings(): Promise<void>;

// Validate settings
validateSettings(settings: PluginSettings): ValidationResult;

const API_BASE_URL = 'https://api.raindrop.io/rest/v1';
const API_RATE_LIMIT = 120;
const API_RETRY_COUNT = 3;
const API_RETRY_DELAY = 1000;

const DEFAULT_PATH = 'Raindrops';
const DEFAULT_TEMPLATE = '';
const DEFAULT_BANNER_FIELD = 'banner';
const FILE_EXTENSION = '.md';

const ERROR_CODES = {
    INVALID_TOKEN: 'INVALID_TOKEN',
    RATE_LIMIT: 'RATE_LIMIT',
    NETWORK_ERROR: 'NETWORK_ERROR',
    VALIDATION_ERROR: 'VALIDATION_ERROR',
    FILE_ERROR: 'FILE_ERROR'
};