longurl-js

/** * Type definitions for the longurl package */ /** * Options for URL generation with backward compatibility */ export interface UrlGenerationOptions { /** Length of generated ID (default: 6) */ idLength?: number; /** Domain for generated URLs */ domain?: string; /** Enable URL shortening with random IDs (default: true) */ enableShortening?: boolean; /** Include entity type in URL path (default: false) */ includeEntityInPath?: boolean; /** URL pattern with placeholders (e.g., 'furniture-vintage-table-lamp-{publicId}') */ urlPattern?: string; /** NEW: Clear naming for public-facing identifier */ publicId?: string; /** DEPRECATED: Use publicId instead for clarity */ endpointId?: string; /** Whether to include publicId in the URL slug (default: true) */ includeInSlug?: boolean; /** Whether to generate QR code for the URL (default: true) */ generate_qr_code?: boolean; } /** * Entity configuration for custom entity types */ export interface EntityConfig { /** Database table name for this entity */ tableName: string; /** Primary key column name */ primaryKey: string; /** Optional URL path prefix (defaults to entity name) */ urlPrefix?: string; } /** * Storage strategy for URLs */ export declare enum StorageStrategy { /** Store URLs in a separate lookup table */ LOOKUP_TABLE = "LOOKUP_TABLE", /** Store URLs directly in the entity tables */ INLINE = "INLINE" } /** * Database configuration for storage and retrieval */ export interface DatabaseConfig { /** Storage strategy for URLs */ strategy: StorageStrategy; /** Database connection details */ connection: { url: string; key: string; }; /** Lookup table name (for LOOKUP_TABLE strategy) */ lookupTable?: string; /** URL ID column name (for INLINE strategy) */ urlIdColumn?: string; } /** * Main configuration for LongURL */ export interface LongURLConfig { /** Custom entity configurations */ entities?: Record<string, EntityConfig>; /** Base domain for shortened URLs */ baseUrl?: string; /** * Include entity type in URL path (default: false for shortest URLs) * * Design Philosophy: URL shorteners should prioritize brevity by default. * - false (default): https://yourdomain.co/X7gT5p (shortest) * - true (opt-in): https://yourdomain.co/product/X7gT5p (organized) * * Use shortest URLs for: social media, SMS, QR codes, character limits * Use entity URLs for: SEO, organized link management, branded experiences */ includeEntityInPath?: boolean; /** * Enable URL shortening with random IDs (default: true) * * Design Philosophy: Transform from URL shortener to URL management framework. * - true (default): Generate short random IDs -> https://yourdomain.co/product/X7gT5p * - false (framework mode): Use entity IDs directly -> https://yourdomain.co/product/laptop-123 * * Framework mode benefits: * - Readable URLs with entity context * - SEO-friendly URL structure * - Still gets analytics, collision detection, and entity management * - Perfect for content management, e-commerce catalogs, user profiles */ enableShortening?: boolean; /** Supabase configuration (default database) */ supabase?: { url?: string; key?: string; options?: { schema?: string; headers?: Record<string, string>; realTime?: { enabled: boolean; params?: Record<string, any>; }; cache?: { enabled?: boolean; ttlMs?: number; maxSize?: number; }; storage?: { /** Store QR code base64 in endpoints table (default: false = use bucket) */ storeQRInTable?: boolean; /** Bucket name for QR code storage (default: 'qr-codes') */ qrCodeBucket?: string; }; }; }; /** Advanced: Custom adapter injection */ adapter?: any; /** Legacy: Database config (for backward compatibility) */ database?: DatabaseConfig; } /** * Result of URL generation */ export interface GenerationResult { /** The public path segment (readable slug or short ID) */ urlSlug?: string; /** The destination URL or internal route */ urlBase?: string; /** The complete generated URL */ urlOutput?: string; /** @deprecated Use urlSlug instead. The public path segment */ urlId?: string; /** @deprecated Use urlOutput instead. Full shortened URL */ shortUrl?: string; /** @deprecated Use urlBase instead. Original long URL or internal route */ originalUrl?: string; /** Entity type */ entityType?: string; /** Original entity ID */ entityId?: string; /** The generated or provided public ID */ publicId?: string; /** QR code as base64 data URL (if generated and storeQRInTable: true) */ qrCode?: string; /** QR code URL from storage bucket (default storage method) */ qrCodeUrl?: string; /** Short URL slug for sharing (always generated, even in Framework Mode) */ url_slug_short?: string; /** Whether generation was successful */ success: boolean; /** Error message if generation failed */ error?: string; } /** * Result of URL resolution */ export interface ResolutionResult<T = any> { /** Resolved entity data */ entity?: T; /** Original entity ID */ entityId?: string; /** Entity type */ entityType?: string; /** The destination URL or internal route */ urlBase?: string; /** The public path segment */ urlSlug?: string; /** @deprecated Use urlBase instead. Original long URL or internal route */ originalUrl?: string; /** @deprecated Use urlSlug instead. URL ID */ urlId?: string; /** Click count */ clickCount?: number; /** Metadata (optional) */ metadata?: Record<string, any>; /** Whether resolution was successful */ success: boolean; /** Error message if resolution failed */ error?: string; } /** * Analytics data structure */ export interface AnalyticsData { /** The public path segment */ urlSlug: string; /** @deprecated Use urlSlug instead. URL ID */ urlId: string; /** Total clicks across all URLs */ totalClicks: number; /** When the URL was created */ createdAt: string; /** When the URL was last updated */ updatedAt: string; /** Last click timestamp */ lastClickAt?: string; /** Click history */ clickHistory?: Array<{ /** Timestamp of the click */ timestamp: string; /** User agent of the click */ userAgent?: string; /** Referer of the click */ referer?: string; /** IP address of the click */ ip?: string; /** Country of the click */ country?: string; }>; } /** * Default database configuration */ export declare const DEFAULT_DB_CONFIG: DatabaseConfig; /** * Cache statistics */ export interface CacheStats { /** Number of cache hits */ hits: number; /** Number of cache misses */ misses: number; /** Hit ratio (hits / total) */ ratio: number; /** Total lookups */ total: number; } /** * Structure for parsed entity URLs */ export interface ParsedEntityUrl { /** The entity type from the URL */ entityType: string; /** The URL ID */ urlId: string; } /** * Database record structure for URL endpoints */ export interface EndpointRecord { /** Primary key */ id: string; /** URL slug/path segment */ url_slug: string; /** Short URL slug for sharing (optional) */ url_slug_short?: string; /** Base URL/route target */ url_base: string; /** ID of the entity this URL points to (optional) */ entity_id?: string; /** Type of entity (optional) */ entity_type?: string; /** QR code as base64 data URL (optional, only if storeQRInTable: true) */ qr_code?: string; /** QR code URL from storage bucket (default storage method) */ qr_code_url?: string; /** Click count */ click_count: number; /** Metadata (optional) */ metadata?: Record<string, any>; /** When the URL was created */ created_at: string; /** When the URL was last updated */ updated_at: string; } /** * @deprecated Use EndpointRecord instead. Legacy database record structure for backwards compatibility */ export interface ShortUrlRecord { /** Primary key */ id: string; /** @deprecated Use url_slug instead. Short URL ID */ url_id: string; /** @deprecated Use url_base instead. Original long URL */ original_url: string; /** ID of the entity this URL points to (optional) */ entity_id?: string; /** Type of entity (optional) */ entity_type?: string; /** Click count */ click_count: number; /** Metadata (optional) */ metadata?: Record<string, any>; /** When the URL was created */ created_at: string; /** When the URL was last updated */ updated_at: string; }