Something went wrong. Try again.
A social knowledge tool for research trails, built on ATProto semble.so
research-tool social-network tools-for-thought atproto
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301import { 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 caseexport interface UrlSearchResultDTO { url: string; contentData: any; // JSONB contentData with metadata updatedAt: Date;}
export interface PaginatedQueryResult<T> { 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 storedexport 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 infoexport type UrlCardViewDTO = UrlCardView & WithCollections & WithLibraries;
// Repository returns card data - will be enriched with user profile in use caseexport 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 queriesexport 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 scoringexport 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<ConnectionTypeEnum, number>; backwardByType: Map<ConnectionTypeEnum, number>;}
/** * 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<PaginatedQueryResult<UrlCardQueryResultDTO>>;
getCardsInCollection( collectionId: string, options: CardQueryOptions, callingUserId?: string, ): Promise<PaginatedQueryResult<CollectionCardQueryResultDTO>>;
getUrlCardView( cardId: string, callingUserId?: string, ): Promise<UrlCardViewDTO | null>;
getUrlCardBasic( cardId: string, callingUserId?: string, ): Promise<UrlCardView | null>;
getLibrariesForCard(cardId: string): Promise<string[]>;
getLibrariesForUrl( url: string, options: CardQueryOptions, ): Promise<PaginatedQueryResult<LibraryForUrlDTO>>;
getNoteCardsForUrl( url: string, options: CardQueryOptions, ): Promise<PaginatedQueryResult<NoteCardForUrlRawDTO>>;
getBatchUrlCardViews( cardIds: string[], callingUserId?: string, ): Promise<Map<string, UrlCardView>>;
getBatchUrlLibraryInfo( urls: string[], callingUserId?: string, ): Promise<Map<string, UrlLibraryInfo>>;
/** * 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<Map<string, UrlStats>>;
/** * 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<string[]>;
/** * Of the given URLs, return the subset the user has saved as URL cards */ getUrlsSavedByUser(userId: string, urls: string[]): Promise<Set<string>>;
getBatchUserActivityStats( userIds: string[], ): Promise<Map<string, UserActivityStats>>;
/** * Most recent card creation time per user. Users with no cards are omitted. */ getBatchLatestCardCreatedAt(userIds: string[]): Promise<Map<string, Date>>;
searchUrls( options: SearchUrlsOptions, ): Promise<PaginatedQueryResult<UrlSearchResultDTO>>;
/** * Get aggregate card statistics for a user profile * Used for efficient counting of URL cards authored by user */ getProfileCardStats(authorId: string): Promise<{ urlCardCount: number; }>;}