facebook-comments-client 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,293 @@
+/** Normalized comment author. Every field is null-safe — Facebook data is frequently incomplete. */
+interface FacebookCommentAuthor {
+    id: string | null;
+    name: string | null;
+    profileUrl: string | null;
+    /** Author profile-picture URL (validated https Facebook CDN), when rendered. */
+    avatarUrl: string | null;
+}
+interface FacebookCommentAttachment {
+    type: "image" | "sticker";
+    url: string;
+    alt: string | null;
+    width: number | null;
+    height: number | null;
+}
+/** Normalized comment, independent of Facebook's internal response structure. */
+interface FacebookComment {
+    id: string | null;
+    author: FacebookCommentAuthor;
+    message: string;
+    /** ISO 8601 string, or null when no parseable timestamp is available. */
+    createdAt: string | null;
+    reactions: {
+        total: number | null;
+    };
+    /** Parent comment id for replies, null for top-level comments. */
+    parentId: string | null;
+    attachments?: FacebookCommentAttachment[];
+    replies?: FacebookComment[];
+}
+/**
+ * Shape produced by extractors before normalization.
+ * All fields optional — never trust Facebook markup to populate them.
+ */
+interface RawFacebookComment {
+    id?: string | null;
+    /** Post id embedded in the comment's profile link (comment_id param) — used to
+     *  drop comments that belong to a different post rendered on the same page. */
+    postRefId?: string | null;
+    authorId?: string | null;
+    authorName?: string | null;
+    authorProfileUrl?: string | null;
+    authorAvatarUrl?: string | null;
+    message?: string | null;
+    /** Timestamp exactly as rendered ("2h", "January 5 at 3:04 PM", ISO, ...). */
+    createdAtRaw?: string | null;
+    reactionsTotal?: number | null;
+    parentId?: string | null;
+    /** True when the article's aria-label marks it as a reply ("Reply by ...").
+     *  Facebook renders some replies as flat sibling articles — the flag plus
+     *  parentAuthorName re-attach them to their parent comment. */
+    isReply?: boolean;
+    /** Parent comment author name captured from "Reply by X to Y's comment". */
+    parentAuthorName?: string | null;
+    attachments?: FacebookCommentAttachment[];
+    replies?: RawFacebookComment[];
+}
+interface ExtractionOptions {
+    maxComments: number;
+    includeReplies: boolean;
+    maxReplies: number;
+}
+
+interface FacebookPost {
+    id: string | null;
+    url: string;
+}
+
+/**
+ * Loose, library-owned session types. Deliberately tolerant (optional fields):
+ * sessions exported by older Playwright versions or trimmed by users may omit
+ * defaults. ContextFactory normalizes these into Playwright's strict shape.
+ */
+interface Cookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    /** Unix time in seconds; -1 means session cookie. */
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+interface StorageStateOrigin {
+    origin: string;
+    localStorage: Array<{
+        name: string;
+        value: string;
+    }>;
+}
+interface StorageState {
+    cookies: Cookie[];
+    origins?: StorageStateOrigin[];
+}
+/** Session stored as a storage-state JSON file on disk. */
+interface FileSessionConfig {
+    /** "storage" is accepted as an alias of "file". */
+    type: "file" | "storage";
+    path: string;
+}
+/** Session loaded from a base64-encoded storage state in an environment variable. */
+interface EnvSessionConfig {
+    type: "env";
+    envKey: string;
+}
+/** Session provided as a plain array of cookies. */
+interface CookiesSessionConfig {
+    type: "cookies";
+    cookies: Cookie[];
+}
+/** Session provided inline as a storage-state object. */
+interface InlineSessionConfig {
+    type: "state";
+    state: StorageState;
+}
+type SessionConfig = FileSessionConfig | EnvSessionConfig | CookiesSessionConfig | InlineSessionConfig;
+interface SessionValidationResult {
+    /** True when the session data is structurally valid (parses, has expected shape). */
+    valid: boolean;
+    /** True when the session appears authenticated (auth cookies present and accepted). */
+    authenticated: boolean;
+    /** Best-effort account name; null when not safely available. */
+    user?: {
+        name: string | null;
+    };
+}
+
+interface GetCommentsOptions {
+    /** Facebook post URL (group posts, permalinks, photo/video posts, ...). */
+    url: string;
+    /** Maximum top-level comments to return per call. Default 50. */
+    maxComments?: number;
+    /** Expand and include reply threads. Default false. */
+    includeReplies?: boolean;
+    /** Maximum replies per comment when includeReplies is true. Default 20. */
+    maxReplies?: number;
+    /** Cursor from a previous call's pagination.nextCursor. */
+    cursor?: string | null;
+    /** Navigation timeout in milliseconds. Default 30000. */
+    timeout?: number;
+    /** Override the client-level headless setting for this call. */
+    headless?: boolean;
+}
+interface PaginationInfo {
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+interface GetCommentsResult {
+    post: FacebookPost;
+    comments: FacebookComment[];
+    pagination: PaginationInfo;
+}
+interface BrowserOptions {
+    /** Default headless mode. Default true. */
+    headless?: boolean;
+    /** Default Playwright action timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Optional Chromium binary, useful with serverless Chromium distributions. */
+    executablePath?: string;
+    /** Extra Chromium launch arguments, useful on serverless platforms. */
+    args?: string[];
+}
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+interface FacebookCommentsClientOptions {
+    session: SessionConfig;
+    browser?: BrowserOptions;
+    /** Custom logger. A quiet console logger is used by default; sensitive values are always redacted. */
+    logger?: Logger;
+}
+interface LoginOptions {
+    /** Where to write the exported storage state. */
+    outputPath: string;
+    /** How long to wait for the user to finish logging in. Default 300000 (5 minutes). */
+    timeoutMs?: number;
+}
+
+declare class FacebookCommentsClient {
+    private readonly options;
+    private readonly browserManager;
+    private readonly logger;
+    constructor(options: FacebookCommentsClientOptions);
+    /**
+     * Interactive login helper: opens a visible browser, waits for you to log in
+     * manually, then exports the storage state. Never enters credentials for you.
+     */
+    static login(loginOptions: LoginOptions): Promise<void>;
+    /** Fetch and normalize comments for one post URL. */
+    getComments(options: GetCommentsOptions): Promise<GetCommentsResult>;
+    /**
+     * Cheap session check: resolves the session, verifies auth cookies, and
+     * confirms Facebook still accepts them. Never throws for session problems —
+     * inspect the returned flags instead.
+     */
+    validateSession(): Promise<SessionValidationResult>;
+    close(): Promise<void>;
+}
+
+type FacebookErrorCode = "FB_CLIENT" | "FB_AUTH" | "FB_SESSION_EXPIRED" | "FB_POST_NOT_FOUND" | "FB_ACCESS_DENIED" | "FB_EXTRACTION";
+interface FacebookErrorOptions {
+    retryable?: boolean;
+    cause?: unknown;
+}
+/**
+ * Base error for all library failures.
+ * Messages must never contain session cookies, tokens, or storage-state content.
+ */
+declare class FacebookClientError extends Error {
+    readonly code: FacebookErrorCode;
+    readonly retryable: boolean;
+    constructor(message: string, options?: FacebookErrorOptions & {
+        code?: FacebookErrorCode;
+    });
+}
+
+/** Session data is missing, unreadable, malformed, or contains no Facebook auth cookies. */
+declare class FacebookAuthenticationError extends FacebookClientError {
+    constructor(message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+
+/** Session was structurally valid but Facebook no longer accepts it (login redirect observed). */
+declare class FacebookSessionExpiredError extends FacebookClientError {
+    constructor(message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+
+/** Post URL does not exist, was deleted, or is not visible ("this content isn't available"). */
+declare class FacebookPostNotFoundError extends FacebookClientError {
+    constructor(message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+
+/** Post exists but the account lacks access (e.g. private group the account has not joined). */
+declare class FacebookAccessDeniedError extends FacebookClientError {
+    constructor(message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+
+/** Page loaded but no extractor could produce usable comment data. Usually a markup change. */
+declare class FacebookExtractionError extends FacebookClientError {
+    constructor(message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+
+interface ParsedPostUrl {
+    /** Normalized absolute URL. */
+    url: string;
+    /** Best-effort post identifier; null when it cannot be determined from the URL. */
+    postId: string | null;
+    /** Group identifier when the post lives in a group. */
+    groupId: string | null;
+}
+/**
+ * Validate and parse a Facebook post URL. Throws FacebookClientError for
+ * non-Facebook or non-http(s) URLs. Id extraction is best-effort — a null postId
+ * never blocks fetching; extraction falls back to page data.
+ */
+declare function parseFacebookPostUrl(input: string): ParsedPostUrl;
+
+/**
+ * Recursively replace values of sensitive keys so session data never reaches logs
+ * or error messages. Known Facebook auth cookie names are always redacted.
+ */
+declare function redact(value: unknown, depth?: number): unknown;
+/** Console logger that redacts every interpolated argument. Quiet (warn+) by default. */
+declare function createConsoleLogger(level?: LogLevel): Logger;
+
+/**
+ * Best-effort timestamp parsing. Understands ISO strings, unix seconds,
+ * Facebook relative times ("2h", "5m", "just now", "Yesterday at 3:04 PM")
+ * and month-name formats ("January 5 at 3:04 PM", "5 January 2026 at 15:04").
+ * Returns null when nothing parses — never throws.
+ */
+declare function parseTimestamp(input: string | null | undefined, now?: Date): string | null;
+
+export { type BrowserOptions, type Cookie, type CookiesSessionConfig, type EnvSessionConfig, type ExtractionOptions, FacebookAccessDeniedError, FacebookAuthenticationError, FacebookClientError, type FacebookComment, type FacebookCommentAttachment, type FacebookCommentAuthor, FacebookCommentsClient, type FacebookCommentsClientOptions, type FacebookErrorCode, FacebookExtractionError, type FacebookPost, FacebookPostNotFoundError, FacebookSessionExpiredError, type FileSessionConfig, type GetCommentsOptions, type GetCommentsResult, type InlineSessionConfig, type LogLevel, type Logger, type LoginOptions, type PaginationInfo, type ParsedPostUrl, type RawFacebookComment, type SessionConfig, type SessionValidationResult, type StorageState, createConsoleLogger, parseFacebookPostUrl, parseTimestamp, redact };