import { CardTypeEnum } from './value-objects/CardType'; import { UrlType } from './value-objects/UrlType'; import { DID } from '../../atproto/domain/DID'; import { CollectionId } from './value-objects/CollectionId'; import { ConnectionTypeEnum } from './value-objects/ConnectionType'; export interface CardQueryOptions { page: number; limit: number; sortBy: CardSortField; sortOrder: SortOrder; urlType?: UrlType; uncollected?: boolean; searchText?: string; } export interface SearchUrlsOptions { searchQuery: string; page: number; limit: number; sortBy: CardSortField; sortOrder: SortOrder; urlType?: UrlType; authorDid?: DID; collectionId?: CollectionId; } // Raw result from URL search - will be enriched with library info in use case export interface UrlSearchResultDTO { url: string; contentData: any; // JSONB contentData with metadata updatedAt: Date; } export interface PaginatedQueryResult { items: T[]; totalCount: number; hasMore: boolean; } export enum CardSortField { CREATED_AT = 'createdAt', UPDATED_AT = 'updatedAt', LIBRARY_COUNT = 'libraryCount', } export enum SortOrder { ASC = 'asc', DESC = 'desc', } // Simplified DTO for cards in a collection (no collections array to avoid circular data) export interface UrlCardView { id: string; type: CardTypeEnum.URL; url: string; uri?: string; cardContent: { url: string; title?: string; description?: string; author?: string; publishedDate?: Date; siteName?: string; imageUrl?: string; type?: string; retrievedAt?: Date; doi?: string; isbn?: string; }; libraryCount: number; urlLibraryCount: number; urlInLibrary?: boolean; urlConnectionCount?: number; urlIsConnected?: boolean; createdAt: Date; updatedAt: Date; authorId: string; // NEW - needed to enrich with author profile note?: { id: string; text: string; }; } export type CollectionCardQueryResultDTO = UrlCardView; // Raw data from repository - minimal, just what's stored export interface WithCollections { collections: { id: string; name: string; authorId: string; accessType: string; }[]; } export interface WithLibraries { libraries: { userId: string }[]; } export type UrlCardQueryResultDTO = UrlCardView & WithCollections; // DTO for single URL card view with library and collection info export type UrlCardViewDTO = UrlCardView & WithCollections & WithLibraries; // Repository returns card data - will be enriched with user profile in use case export interface LibraryForUrlDTO { userId: string; card: { id: string; url: string; uri?: string; cardContent: { url: string; title?: string; description?: string; author?: string; publishedDate?: Date; siteName?: string; imageUrl?: string; type?: string; retrievedAt?: Date; doi?: string; isbn?: string; }; libraryCount: number; urlLibraryCount: number; urlInLibrary?: boolean; createdAt: Date; updatedAt: Date; note?: { id: string; text: string; }; }; // Note: userId is the card author in this context (it's their card in their library) } // Raw repository DTO - what the repository returns (not enriched) export interface NoteCardForUrlRawDTO { id: string; note: string; authorId: string; createdAt: Date; updatedAt: Date; } // Public DTO - what the use case returns (enriched with author profile) export interface NoteCardForUrlDTO { id: string; note: string; author: { id: string; name: string; handle: string; avatarUrl?: string; }; createdAt: Date; updatedAt: Date; } // Batch URL library info for efficient multi-URL queries export interface UrlLibraryInfo { urlLibraryCount: number; // distinct users with this URL urlInLibrary?: boolean; // whether calling user has it urlConnectionCount?: number; // total connections involving this URL urlIsConnected?: boolean; // whether calling user has any connection with this URL metadata: { url: string; title?: string; description?: string; author?: string; publishedDate?: Date; siteName?: string; imageUrl?: string; type?: string; retrievedAt?: Date; doi?: string; isbn?: string; }; } // Batch user activity stats used for user recommendation scoring export interface UserActivityStats { cardCount: number; // cards authored by the user collectionCount: number; // collections created by the user connectionCount: number; // connections curated by the user lastActivityAt: Date | null; // most recent card, collection add, or connection } /** * URL↔URL connection counts for a URL. Connections to non-URL targets/sources * are excluded. A self-loop counts once in each direction. Connections with no * type count toward the totals but not the by-type maps. */ export interface UrlConnectionCounts { forwardTotal: number; // connections where the URL is the source backwardTotal: number; // connections where the URL is the target forwardByType: Map; backwardByType: Map; } /** * Canonical aggregate stats for a URL (exact string match on the URL). * All other URL count surfaces should agree with these definitions. */ export interface UrlStats { libraryCount: number; // distinct users with a URL card for this URL in their library noteCount: number; // NOTE cards whose url is this URL collectionCount: number; // distinct collections containing a URL card for this URL connections: UrlConnectionCounts; urlInLibrary?: boolean; // only set when a calling user is given urlIsConnected?: boolean; // only set when a calling user is given } export interface ICardQueryRepository { getUrlCardsOfUser( userId: string, options: CardQueryOptions, callingUserId?: string, ): Promise>; getCardsInCollection( collectionId: string, options: CardQueryOptions, callingUserId?: string, ): Promise>; getUrlCardView( cardId: string, callingUserId?: string, ): Promise; getUrlCardBasic( cardId: string, callingUserId?: string, ): Promise; getLibrariesForCard(cardId: string): Promise; getLibrariesForUrl( url: string, options: CardQueryOptions, ): Promise>; getNoteCardsForUrl( url: string, options: CardQueryOptions, ): Promise>; getBatchUrlCardViews( cardIds: string[], callingUserId?: string, ): Promise>; getBatchUrlLibraryInfo( urls: string[], callingUserId?: string, ): Promise>; /** * Canonical aggregate stats for each URL. Every input URL is present in the * result (zeroed if unknown). urlInLibrary/urlIsConnected are set only when * callingUserId is given. */ getBatchUrlStats( urls: string[], callingUserId?: string, ): Promise>; /** * Get distinct DIDs of users who saved any of the URLs as URL cards * or made connections with any of the URLs (as source or target) */ getUsersForUrls(urls: string[]): Promise; /** * Of the given URLs, return the subset the user has saved as URL cards */ getUrlsSavedByUser(userId: string, urls: string[]): Promise>; getBatchUserActivityStats( userIds: string[], ): Promise>; /** * Most recent card creation time per user. Users with no cards are omitted. */ getBatchLatestCardCreatedAt(userIds: string[]): Promise>; searchUrls( options: SearchUrlsOptions, ): Promise>; /** * Get aggregate card statistics for a user profile * Used for efficient counting of URL cards authored by user */ getProfileCardStats(authorId: string): Promise<{ urlCardCount: number; }>; }