@chronicle.app/facebook 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @chronicle.app/facebook
+
+Chronicle plugin for facebook
+
+## Installation
+
+```bash
+npm install @chronicle.app/facebook
+```
+
+## Usage
+
+### Basic extraction
+
+```bash
+chronicle extract facebook --input /path/to/facebook/file
+```
+
+This reads Messenger conversations, the default. Pass `--type reactions`, `--type comments` or `--type searches` for the rest of the export.
+
+### With date filtering
+
+```bash
+chronicle extract facebook \
+  --type messages \
+  --input /path/to/facebook/file \
+  --since 2024-01-01 \
+  --until 2024-12-31 \
+  --limit 1000
+```
+
+## Configuration
+
+The extractor supports the following options:
+
+- `--input` (required): Path to the facebook file
+- `--type` (required): What to read: `messages`, `reactions`, `comments`, or `searches`
+- `--since`: Extract records from this date onwards
+- `--until`: Extract records up to this date
+- `--limit`: Maximum number of records to extract
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin
+npm run build
+```
+
+## File Format
+
+TODO: Document the expected file format and any parsing specifics.
+
+## Schema
+
+TODO: Document what Chronicle schema types are generated from this data source.
+
+## Tests
+
+Tests write a small synthetic Facebook export to a temporary directory and run
+it through each extractor and the transformer. They never read the host's data
+or accounts.

package/dist/connectors/FacebookTransformer.d.ts

@@ -0,0 +1,35 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class FacebookTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildMessageActions;
+    private buildMessageSender;
+    private buildMessage;
+    private buildSearchActions;
+    /**
+     * The like button routes to LikeAction — payload-free, driving the boolean
+     * `liked` run — while the emotive reactions (LOVE/HAHA/WOW/SAD/ANGRY/CARE)
+     * are payloads: RespondAction → result Response carrying the export's own
+     * reaction word verbatim in `body` (never mapped to an emoji or a sentiment;
+     * that is a derivation, not data). A record whose reaction type didn't parse
+     * keeps today's LikeAction routing rather than minting a fabricated payload.
+     */
+    private buildReactionActions;
+    /**
+     * The reacted-to post. The label_values export format carries its URL and
+     * owner; the data-array format carries the owner alone, leaving the post as
+     * weak as the export makes it.
+     */
+    private buildReactionTarget;
+    /**
+     * A comment is a prose response — RespondAction → result Comment (the
+     * Response leaf), joining the same family as reactions. The action carries
+     * no `object`: the export's only pointer to the commented-on post is a
+     * localized prose title ("X commented on Y's post."), and scraping a name
+     * out of that sentence would break silently on non-English archives — so
+     * the edge is left unasserted rather than fabricated.
+     */
+    private buildCommentActions;
+    private buildFacebookAgent;
+}
+//# sourceMappingURL=FacebookTransformer.d.ts.map

package/dist/connectors/FacebookTransformer.js

@@ -0,0 +1,238 @@
+import { ChronicleTransformer, selfAgent } from '@chronicle.app/etl';
+export default class FacebookTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        switch (record.extraction.recordType) {
+            case 'messages': {
+                actions.push(...this.buildMessageActions(record));
+                break;
+            }
+            case 'searches': {
+                actions.push(...this.buildSearchActions(record));
+                break;
+            }
+            case 'reactions': {
+                actions.push(...this.buildReactionActions(record));
+                break;
+            }
+            case 'comments': {
+                actions.push(...this.buildCommentActions(record));
+                break;
+            }
+            // No default
+        }
+        return actions;
+    }
+    buildMessageActions(record) {
+        const actions = [];
+        if (!record.data.timestamp) {
+            return actions;
+        }
+        try {
+            const sender = this.buildMessageSender(record);
+            const message = this.buildMessage(record);
+            const messageAction = {
+                '@type': 'MessageAction',
+                timestamp: record.data.timestamp,
+                '@key': ['@type', 'source', 'timestamp', 'agent.name', 'object.body'],
+                source: 'facebook',
+                agent: sender,
+                object: message,
+            };
+            actions.push(messageAction);
+        }
+        catch {
+            // Skip messages where we can't identify the sender
+            // Skipping message due to unidentifiable sender
+        }
+        return actions;
+    }
+    buildMessageSender(record) {
+        // Improve name resolution - try to find a better name than "Unknown"
+        let { senderName } = record.data;
+        if (!senderName && record.data.participants?.length === 1) {
+            // If only one participant, that must be the sender
+            senderName = record.data.participants[0];
+        }
+        else if (!senderName && record.data.participants?.length === 2) {
+            // In a 2-person conversation, try to identify which participant is the sender
+            // This would require more context about the user's own name, which we don't have
+            // For now, we'll skip this message rather than use "Unknown"
+            senderName = null;
+        }
+        if (!senderName) {
+            // Skip messages without identifiable senders rather than using "Unknown"
+            throw new Error('Cannot identify sender for message');
+        }
+        return {
+            '@type': 'Agent',
+            '@key': ['@type', 'source', 'name'],
+            source: 'facebook',
+            name: senderName,
+        };
+    }
+    buildMessage(record) {
+        const recipients = record.data.participants
+            ?.filter((name) => name !== record.data.senderName)
+            ?.map((name) => ({
+            '@type': 'Agent',
+            '@key': ['@type', 'source', 'name'],
+            source: 'facebook',
+            name,
+        })) || [];
+        return {
+            '@type': 'Message',
+            '@key': ['@type', 'source', 'body', 'recipient'],
+            source: 'facebook',
+            body: record.data.content || '',
+            recipient: recipients,
+        };
+    }
+    buildSearchActions(record) {
+        const actions = [];
+        if (!record.data.timestamp || !record.data.searchText) {
+            return actions;
+        }
+        const agent = this.buildFacebookAgent();
+        const findAction = {
+            '@type': 'FindAction',
+            timestamp: record.data.timestamp,
+            '@key': ['@type', 'source', 'timestamp', 'agent.name', 'object.body'],
+            source: 'facebook',
+            agent,
+            object: {
+                '@type': 'Query',
+                '@key': ['@type', 'source', 'body'],
+                source: 'facebook',
+                name: record.data.searchText,
+                body: record.data.searchText,
+            },
+        };
+        actions.push(findAction);
+        return actions;
+    }
+    /**
+     * The like button routes to LikeAction — payload-free, driving the boolean
+     * `liked` run — while the emotive reactions (LOVE/HAHA/WOW/SAD/ANGRY/CARE)
+     * are payloads: RespondAction → result Response carrying the export's own
+     * reaction word verbatim in `body` (never mapped to an emoji or a sentiment;
+     * that is a derivation, not data). A record whose reaction type didn't parse
+     * keeps today's LikeAction routing rather than minting a fabricated payload.
+     */
+    buildReactionActions(record) {
+        const actions = [];
+        if (!record.data.timestamp) {
+            return actions;
+        }
+        const agent = this.buildFacebookAgent();
+        const target = this.buildReactionTarget(record);
+        const { reactionType } = record.data;
+        if (!reactionType || reactionType === 'like' || reactionType === 'unknown') {
+            const likeAction = {
+                '@type': 'LikeAction',
+                timestamp: record.data.timestamp,
+                '@key': ['@type', 'source', 'timestamp', 'agent.name', 'object.url'],
+                source: 'facebook',
+                agent,
+                object: target,
+            };
+            actions.push(likeAction);
+            return actions;
+        }
+        // The Response keys on real export data via `action.`-prefixed dot-paths
+        // into the enclosing action's roles — no synthesized id. `action.timestamp`
+        // stays in the key because the data-array export format carries no post
+        // URL: without it, every same-word reaction by the same agent would
+        // collapse into one artifact.
+        const response = {
+            '@type': 'Response',
+            '@key': [
+                '@type',
+                'source',
+                'body',
+                'action.timestamp',
+                'action.agent.name',
+                'action.object.url',
+            ],
+            source: 'facebook',
+            body: reactionType,
+        };
+        const respondAction = {
+            '@type': 'RespondAction',
+            timestamp: record.data.timestamp,
+            '@key': ['@type', 'source', 'timestamp', 'agent.name', 'object.url', 'result.body'],
+            source: 'facebook',
+            agent,
+            object: target,
+            result: response,
+        };
+        actions.push(respondAction);
+        return actions;
+    }
+    /**
+     * The reacted-to post. The label_values export format carries its URL and
+     * owner; the data-array format carries the owner alone, leaving the post as
+     * weak as the export makes it.
+     */
+    buildReactionTarget(record) {
+        return {
+            '@type': 'Post',
+            '@key': ['@type', 'source', 'url'],
+            source: 'facebook',
+            url: record.data.contentUrl,
+            author: record.data.targetPerson
+                ? [
+                    {
+                        '@type': 'Person',
+                        '@key': ['@type', 'source', 'name'],
+                        source: 'facebook',
+                        name: record.data.targetPerson,
+                    },
+                ]
+                : undefined,
+        };
+    }
+    /**
+     * A comment is a prose response — RespondAction → result Comment (the
+     * Response leaf), joining the same family as reactions. The action carries
+     * no `object`: the export's only pointer to the commented-on post is a
+     * localized prose title ("X commented on Y's post."), and scraping a name
+     * out of that sentence would break silently on non-English archives — so
+     * the edge is left unasserted rather than fabricated.
+     */
+    buildCommentActions(record) {
+        const actions = [];
+        if (!record.data.timestamp || !record.data.commentText) {
+            return actions;
+        }
+        const agent = this.buildFacebookAgent(record.data.author);
+        const respondAction = {
+            '@type': 'RespondAction',
+            timestamp: record.data.timestamp,
+            '@key': ['@type', 'source', 'timestamp', 'agent.name', 'result.body'],
+            source: 'facebook',
+            agent,
+            result: {
+                '@type': 'Comment',
+                '@key': ['@type', 'source', 'body'],
+                source: 'facebook',
+                body: record.data.commentText,
+                author: [agent],
+            },
+        };
+        actions.push(respondAction);
+        return actions;
+    }
+    buildFacebookAgent(name) {
+        // This builder is only ever the account owner — their own searches,
+        // reactions, and comments. Message senders go through buildMessageSender
+        // (which can be the other party) and are left untagged. When the archive
+        // carries no account name there is nothing to key on, so the node falls
+        // back to the per-source singleton — identity is never invented.
+        return selfAgent({
+            type: 'Agent',
+            source: 'facebook',
+            ...(name ? { name, key: ['@type', 'source', 'name'] } : {}),
+        });
+    }
+}

package/dist/connectors/archive/FacebookArchiveExtractor.d.ts

@@ -0,0 +1,36 @@
+import { ArchiveExtractor } from '@chronicle.app/etl';
+import { z } from 'zod';
+export declare abstract class FacebookArchiveExtractor extends ArchiveExtractor<typeof FacebookArchiveExtractor> {
+    static source: string;
+    static strategy: string;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        input: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        input: string;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }, {
+        input: string;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }>;
+    protected exportSegments: string[];
+    initialize(): Promise<void>;
+    protected discoverExportSegments(): Promise<void>;
+    protected loadAccountInfo(): Promise<any>;
+    protected iterateExportSegments(): AsyncGenerator<{
+        segmentPath: string;
+        facebookDir: string;
+        fullPath: string;
+    }>;
+    protected readFacebookJson(filePath: string): Promise<any>;
+    protected convertFacebookTimestamp(timestamp: number): string;
+    protected fixFacebookTextEncoding(text: string): string;
+}
+//# sourceMappingURL=FacebookArchiveExtractor.d.ts.map

package/dist/connectors/archive/FacebookArchiveExtractor.js

@@ -0,0 +1,163 @@
+import { ArchiveExtractor, Extractor } from '@chronicle.app/etl';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+export class FacebookArchiveExtractor extends ArchiveExtractor {
+    static source = 'facebook';
+    static strategy = 'archive';
+    static schema = Extractor.schema.extend({
+        input: z.string().describe('Path to the Facebook export directory'),
+    });
+    exportSegments = [];
+    async initialize() {
+        await this.discoverExportSegments();
+        this.accountInfo = await this.loadAccountInfo();
+    }
+    async discoverExportSegments() {
+        const config = this.config;
+        try {
+            const entries = await readdir(config.input, { withFileTypes: true });
+            // Check if this is a new format export (direct structure)
+            const hasDirectStructure = entries.some(entry => entry.isDirectory() &&
+                (entry.name === 'personal_information' || entry.name === 'your_facebook_activity'));
+            if (hasDirectStructure) {
+                // New format: direct structure
+                this.exportSegments = [config.input];
+                // Detected new Facebook export format (direct structure)
+            }
+            else {
+                // Old format: Find all export segment directories (meta-* or facebook-*)
+                this.exportSegments = entries
+                    .filter(entry => entry.isDirectory())
+                    .map(entry => entry.name)
+                    .filter(name => name.startsWith('meta-') || name.startsWith('facebook-'))
+                    .map(name => join(config.input, name));
+                // Discovered export segments (legacy format)
+            }
+        }
+        catch {
+            // Could not discover export segments
+            this.exportSegments = [config.input]; // Fallback to input path
+        }
+    }
+    async loadAccountInfo() {
+        // Try to find account info in any of the segments
+        for (const segmentPath of this.exportSegments) {
+            try {
+                // Check for new format (direct structure)
+                const directProfilePath = join(segmentPath, 'personal_information', 'profile_information', 'profile_information.json');
+                try {
+                    const content = await readFile(directProfilePath, 'utf-8');
+                    const data = JSON.parse(content);
+                    return {
+                        name: data.profile_v2?.name?.full_name || data.profile_v2?.name?.value || 'unknown',
+                        email: data.profile_v2?.emails?.emails?.[0] ||
+                            data.profile_v2?.emails?.primary_email ||
+                            null,
+                        username: data.profile_v2?.username || null,
+                        phone: data.profile_v2?.phone_numbers?.[0]?.phone_number ||
+                            data.profile_v2?.phone_numbers?.primary_phone ||
+                            null,
+                    };
+                }
+                catch {
+                    // Not new format, try legacy format
+                }
+                // Legacy format: look for facebook-* subdirectories
+                const entries = await readdir(segmentPath, { withFileTypes: true });
+                const facebookDirs = entries
+                    .filter(entry => entry.isDirectory() && entry.name.startsWith('facebook-'))
+                    .map(entry => entry.name);
+                for (const fbDir of facebookDirs) {
+                    try {
+                        const personalInfoPath = join(segmentPath, fbDir, 'personal_information', 'profile_information', 'profile_information.json');
+                        const content = await readFile(personalInfoPath, 'utf-8');
+                        const data = JSON.parse(content);
+                        return {
+                            name: data.profile_v2?.name?.full_name || data.profile_v2?.name?.value || 'unknown',
+                            email: data.profile_v2?.emails?.emails?.[0] ||
+                                data.profile_v2?.emails?.primary_email ||
+                                null,
+                            username: data.profile_v2?.username || null,
+                            phone: data.profile_v2?.phone_numbers?.[0]?.phone_number ||
+                                data.profile_v2?.phone_numbers?.primary_phone ||
+                                null,
+                        };
+                    }
+                    catch {
+                        // Continue to next directory
+                    }
+                }
+            }
+            catch {
+                // Continue to next segment
+            }
+        }
+        // Could not load Facebook account info
+        return { name: 'unknown' };
+    }
+    async *iterateExportSegments() {
+        for (const segmentPath of this.exportSegments) {
+            try {
+                // Check if this is new format (direct structure)
+                const entries = await readdir(segmentPath, { withFileTypes: true });
+                const hasDirectStructure = entries.some(entry => entry.isDirectory() &&
+                    (entry.name === 'personal_information' || entry.name === 'your_facebook_activity'));
+                if (hasDirectStructure) {
+                    // New format: yield the segment path directly
+                    yield { segmentPath, facebookDir: '', fullPath: segmentPath };
+                }
+                else {
+                    // Legacy format: look for facebook-* subdirectories
+                    const facebookDirs = entries
+                        .filter(entry => entry.isDirectory() && entry.name.startsWith('facebook-'))
+                        .map(entry => entry.name);
+                    for (const facebookDir of facebookDirs) {
+                        const fullPath = join(segmentPath, facebookDir);
+                        yield { segmentPath, facebookDir, fullPath };
+                    }
+                }
+            }
+            catch {
+                // Could not read segment
+            }
+        }
+    }
+    async readFacebookJson(filePath) {
+        return this.readArchiveJson(filePath);
+    }
+    convertFacebookTimestamp(timestamp) {
+        // Facebook timestamps are in milliseconds
+        return new Date(timestamp).toISOString();
+    }
+    fixFacebookTextEncoding(text) {
+        if (!text)
+            return text;
+        // Fix common social media export encoding issues
+        const fixed = text
+            // Handle escaped Unicode sequences (in JSON strings)
+            .replaceAll('\\u00e2\\u0080\\u0099', "'") // Fix apostrophe
+            .replaceAll('\\u00e2\\u0080\\u009c', '"') // Fix opening quote
+            .replaceAll('\\u00e2\\u0080\\u009d', '"') // Fix closing quote
+            .replaceAll('\\u00e2\\u0080\\u0094', '—') // Fix em dash
+            .replaceAll('\\u00e2\\u0080\\u0093', '–') // Fix en dash
+            .replaceAll('\\u00e2\\u0080\\u00a6', '...') // Fix ellipsis
+            // Handle direct UTF-8 bytes interpreted as Latin-1
+            .replaceAll('\u00E2\u0080\u0099', "'") // Fix apostrophe
+            .replaceAll('\u00E2\u0080\u009C', '"') // Fix opening quote
+            .replaceAll('\u00E2\u0080\u009D', '"') // Fix closing quote
+            .replaceAll('\u00E2\u0080\u0094', '—') // Fix em dash
+            .replaceAll('\u00E2\u0080\u0093', '–') // Fix en dash
+            .replaceAll('\u00E2\u0080\u00A6', '...') // Fix ellipsis
+            // Handle additional accented characters and emojis
+            .replaceAll('\u00E2\u009D\u00A4', '❤') // Fix heart emoji
+            .replaceAll('\u00C3\u00A9', 'é') // Fix é
+            .replaceAll('\u00C3\u00A1', 'á') // Fix á
+            .replaceAll('\u00C3\u00AD', 'í') // Fix í
+            .replaceAll('\u00C3\u00B3', 'ó') // Fix ó
+            .replaceAll('\u00C3\u00BA', 'ú') // Fix ú
+            .replaceAll('\u00C3\u00B1', 'ñ') // Fix ñ
+            .trim();
+        return fixed;
+    }
+}

package/dist/connectors/archive/FacebookArchiveMessagesExtractor.d.ts

@@ -0,0 +1,16 @@
+import { Record } from '@chronicle.app/etl';
+import { FacebookArchiveExtractor } from './FacebookArchiveExtractor.js';
+import FacebookTransformer from '../FacebookTransformer.js';
+export declare class FacebookArchiveMessagesExtractor extends FacebookArchiveExtractor {
+    static recordTypes: string[];
+    static description: string;
+    static default: boolean;
+    static defaultTransformer: typeof FacebookTransformer;
+    extract(): AsyncGenerator<Record>;
+    private extractMessagesFromSegment;
+    private extractFromMessageFolder;
+    private extractMessagesFromConversation;
+    private processConversationData;
+    private determineMessageType;
+}
+//# sourceMappingURL=FacebookArchiveMessagesExtractor.d.ts.map

package/dist/connectors/archive/FacebookArchiveMessagesExtractor.js

@@ -0,0 +1,181 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FacebookArchiveExtractor } from './FacebookArchiveExtractor.js';
+import FacebookTransformer from '../FacebookTransformer.js';
+export class FacebookArchiveMessagesExtractor extends FacebookArchiveExtractor {
+    static recordTypes = ['messages'];
+    static description = 'Messenger conversations';
+    static default = true;
+    static defaultTransformer = FacebookTransformer;
+    async *extract() {
+        await this.initialize();
+        const processedConversations = new Set();
+        let recordCount = 0;
+        for await (const { fullPath } of this.iterateExportSegments()) {
+            for await (const record of this.extractMessagesFromSegment(fullPath, processedConversations)) {
+                yield record;
+                recordCount++;
+                if (this.shouldStopExtracting(recordCount)) {
+                    return;
+                }
+            }
+        }
+    }
+    async *extractMessagesFromSegment(segmentPath, processedConversations) {
+        const messagesPath = join(segmentPath, 'your_facebook_activity', 'messages');
+        try {
+            await stat(messagesPath);
+        }
+        catch {
+            // No messages directory found
+            return;
+        }
+        // Process different message types
+        yield* this.extractFromMessageFolder(messagesPath, 'inbox', processedConversations);
+        yield* this.extractFromMessageFolder(messagesPath, 'archived_threads', processedConversations);
+        yield* this.extractFromMessageFolder(messagesPath, 'message_requests', processedConversations);
+        yield* this.extractFromMessageFolder(messagesPath, 'filtered_threads', processedConversations);
+    }
+    async *extractFromMessageFolder(messagesPath, folderName, processedConversations) {
+        const folderPath = join(messagesPath, folderName);
+        try {
+            await stat(folderPath);
+        }
+        catch {
+            return; // Folder doesn't exist in this segment
+        }
+        try {
+            const conversations = await readdir(folderPath, { withFileTypes: true });
+            for (const conversation of conversations) {
+                if (!conversation.isDirectory())
+                    continue;
+                const conversationId = conversation.name;
+                // Skip if already processed (avoid duplicates across segments)
+                if (processedConversations.has(conversationId)) {
+                    continue;
+                }
+                const conversationPath = join(folderPath, conversationId);
+                try {
+                    yield* this.extractMessagesFromConversation(conversationPath, conversationId, folderName);
+                    processedConversations.add(conversationId);
+                }
+                catch {
+                    // Error processing conversation
+                }
+            }
+        }
+        catch {
+            // Error reading message folder
+        }
+    }
+    async *extractMessagesFromConversation(conversationPath, conversationId, threadType) {
+        try {
+            const files = await readdir(conversationPath);
+            const messageFiles = files.filter(file => file.startsWith('message_') && file.endsWith('.json'));
+            if (messageFiles.length === 0) {
+                // No message files found in conversation
+                return;
+            }
+            // Sort message files to process in order
+            messageFiles.sort((a, b) => {
+                const aNum = Number.parseInt(a.match(/message_(\d+)\.json/)?.[1] || '0');
+                const bNum = Number.parseInt(b.match(/message_(\d+)\.json/)?.[1] || '0');
+                return aNum - bNum;
+            });
+            for (const messageFile of messageFiles) {
+                const filePath = join(conversationPath, messageFile);
+                try {
+                    const data = await this.readFacebookJson(filePath);
+                    yield* this.processConversationData(data, conversationId, threadType);
+                }
+                catch {
+                    // Error reading message file
+                }
+            }
+        }
+        catch {
+            // Error processing conversation
+        }
+    }
+    async *processConversationData(data, conversationId, threadType) {
+        if (!data.messages || !Array.isArray(data.messages)) {
+            // No messages array found in conversation
+            return;
+        }
+        const participants = data.participants || [];
+        const conversationTitle = data.title || conversationId;
+        for (const message of data.messages) {
+            // Skip messages outside date range if configured
+            if (message.timestamp_ms && !this.isWithinDateRange(new Date(message.timestamp_ms))) {
+                continue;
+            }
+            const processedMessage = {
+                conversationId,
+                conversationTitle,
+                threadType,
+                participants: participants.map((p) => p.name),
+                senderName: message.sender_name,
+                content: this.fixFacebookTextEncoding(message.content || ''),
+                timestamp: message.timestamp_ms
+                    ? this.convertFacebookTimestamp(message.timestamp_ms)
+                    : null,
+                messageType: this.determineMessageType(message),
+                hasMedia: Boolean(message.photos || message.videos || message.audio_files || message.files || message.gifs),
+                photos: message.photos?.map((p) => ({
+                    uri: p.uri,
+                    creation_timestamp: p.creation_timestamp,
+                })) || [],
+                videos: message.videos?.map((v) => ({
+                    uri: v.uri,
+                    creation_timestamp: v.creation_timestamp,
+                })) || [],
+                audioFiles: message.audio_files?.map((a) => ({
+                    uri: a.uri,
+                    creation_timestamp: a.creation_timestamp,
+                })) || [],
+                files: message.files?.map((f) => ({
+                    uri: f.uri,
+                    creation_timestamp: f.creation_timestamp,
+                })) || [],
+                gifs: message.gifs?.map((g) => ({
+                    uri: g.uri,
+                })) || [],
+                sticker: message.sticker
+                    ? {
+                        uri: message.sticker.uri,
+                    }
+                    : null,
+                reactions: message.reactions?.map((r) => ({
+                    reaction: r.reaction,
+                    actor: r.actor,
+                })) || [],
+                isUnsent: message.is_unsent || false,
+                rawData: message,
+            };
+            yield this.createRecordWithArchiveContext(processedMessage, {
+                conversationId,
+                threadType,
+                messageFile: true,
+            });
+        }
+    }
+    determineMessageType(message) {
+        if (message.photos?.length > 0)
+            return 'photo';
+        if (message.videos?.length > 0)
+            return 'video';
+        if (message.audio_files?.length > 0)
+            return 'audio';
+        if (message.files?.length > 0)
+            return 'file';
+        if (message.gifs?.length > 0)
+            return 'gif';
+        if (message.sticker)
+            return 'sticker';
+        if (message.content)
+            return 'text';
+        if (message.is_unsent)
+            return 'unsent';
+        return 'unknown';
+    }
+}

package/dist/connectors/archive/FacebookArchiveReactionsExtractor.d.ts

@@ -0,0 +1,26 @@
+import { Record } from '@chronicle.app/etl';
+import { FacebookArchiveExtractor } from './FacebookArchiveExtractor.js';
+import FacebookTransformer from '../FacebookTransformer.js';
+export declare class FacebookArchiveReactionsExtractor extends FacebookArchiveExtractor {
+    static recordTypes: string[];
+    static description: string;
+    static default: boolean;
+    static defaultTransformer: typeof FacebookTransformer;
+    /**
+     * The reaction's `fbid` — Facebook's own numeric id, carried verbatim by the
+     * `label_values` export dialect. The data-array dialect and the comments file
+     * carry no id at all, so those records are keyless.
+     */
+    keyOf(record: Record): string | null;
+    extract(): AsyncGenerator<Record>;
+    private extractReactionsFromSegment;
+    private extractFromReactionsFile;
+    private extractFromCommentsFile;
+    private processReactionsArrayData;
+    private processCommentsData;
+    private parseReactionData;
+    private parseCommentData;
+    private extractPostIdFromUrl;
+    private hashReactionContent;
+}
+//# sourceMappingURL=FacebookArchiveReactionsExtractor.d.ts.map

package/dist/connectors/archive/FacebookArchiveReactionsExtractor.js

@@ -0,0 +1,238 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FacebookArchiveExtractor } from './FacebookArchiveExtractor.js';
+import FacebookTransformer from '../FacebookTransformer.js';
+export class FacebookArchiveReactionsExtractor extends FacebookArchiveExtractor {
+    static recordTypes = ['reactions', 'comments'];
+    static description = 'Reactions, likes, and comments';
+    static default = false;
+    static defaultTransformer = FacebookTransformer;
+    /**
+     * The reaction's `fbid` — Facebook's own numeric id, carried verbatim by the
+     * `label_values` export dialect. The data-array dialect and the comments file
+     * carry no id at all, so those records are keyless.
+     */
+    keyOf(record) {
+        return record.data.fbid ?? null;
+    }
+    async *extract() {
+        await this.initialize();
+        const processedReactions = new Set();
+        let recordCount = 0;
+        for await (const { fullPath } of this.iterateExportSegments()) {
+            for await (const record of this.extractReactionsFromSegment(fullPath, processedReactions)) {
+                yield record;
+                recordCount++;
+                if (this.shouldStopExtracting(recordCount)) {
+                    return;
+                }
+            }
+        }
+    }
+    async *extractReactionsFromSegment(segmentPath, processedReactions) {
+        const reactionsPath = join(segmentPath, 'your_facebook_activity', 'comments_and_reactions');
+        try {
+            await stat(reactionsPath);
+        }
+        catch {
+            // No reactions directory found
+            return;
+        }
+        // Process different reaction/comment files
+        yield* this.extractFromReactionsFile(reactionsPath, 'likes_and_reactions.json', processedReactions);
+        yield* this.extractFromReactionsFile(reactionsPath, 'likes_and_reactions_1.json', processedReactions);
+        yield* this.extractFromCommentsFile(reactionsPath, 'comments.json', processedReactions);
+    }
+    async *extractFromReactionsFile(reactionsPath, fileName, processedReactions) {
+        const filePath = join(reactionsPath, fileName);
+        try {
+            await stat(filePath);
+        }
+        catch {
+            return; // File doesn't exist
+        }
+        try {
+            const data = await this.readFacebookJson(filePath);
+            if (Array.isArray(data)) {
+                // Handle array format (likes_and_reactions.json)
+                yield* this.processReactionsArrayData(data, fileName, processedReactions);
+            }
+            else if (data.reactions_v2 || data.likes_and_reactions_v2) {
+                // Handle object format with versioned arrays
+                const reactions = data.reactions_v2 || data.likes_and_reactions_v2 || [];
+                yield* this.processReactionsArrayData(reactions, fileName, processedReactions);
+            }
+        }
+        catch {
+            // Error reading reactions file
+        }
+    }
+    async *extractFromCommentsFile(reactionsPath, fileName, processedReactions) {
+        const filePath = join(reactionsPath, fileName);
+        try {
+            await stat(filePath);
+        }
+        catch {
+            return; // File doesn't exist
+        }
+        try {
+            const data = await this.readFacebookJson(filePath);
+            if (data.comments_v2 && Array.isArray(data.comments_v2)) {
+                yield* this.processCommentsData(data.comments_v2, fileName, processedReactions);
+            }
+        }
+        catch {
+            // Error reading comments file
+        }
+    }
+    async *processReactionsArrayData(reactions, fileName, processedReactions) {
+        for (const reaction of reactions) {
+            if (!reaction.timestamp)
+                continue;
+            // Skip reactions outside date range if configured
+            if (!this.isWithinDateRange(new Date(reaction.timestamp * 1000))) {
+                continue;
+            }
+            const reactionId = `reaction-${reaction.timestamp}-${fileName}-${this.hashReactionContent(reaction)}`;
+            // Skip if already processed (avoid duplicates)
+            if (processedReactions.has(reactionId)) {
+                continue;
+            }
+            const processedReaction = this.parseReactionData(reaction, reactionId, fileName);
+            if (processedReaction) {
+                yield this.createRecordWithArchiveContext(processedReaction, {
+                    recordType: 'reactions',
+                    reactionType: processedReaction.reactionType,
+                    fileName,
+                    dataSource: 'reactions',
+                });
+                processedReactions.add(reactionId);
+            }
+        }
+    }
+    async *processCommentsData(comments, fileName, processedReactions) {
+        for (const commentEntry of comments) {
+            if (!commentEntry.timestamp || !commentEntry.data)
+                continue;
+            // Skip comments outside date range if configured
+            if (!this.isWithinDateRange(new Date(commentEntry.timestamp * 1000))) {
+                continue;
+            }
+            const commentId = `comment-${commentEntry.timestamp}-${fileName}-${this.hashReactionContent(commentEntry)}`;
+            // Skip if already processed (avoid duplicates)
+            if (processedReactions.has(commentId)) {
+                continue;
+            }
+            const processedComment = this.parseCommentData(commentEntry, commentId, fileName);
+            if (processedComment) {
+                yield this.createRecordWithArchiveContext(processedComment, {
+                    recordType: 'comments',
+                    reactionType: 'comment',
+                    fileName,
+                    dataSource: 'comments',
+                });
+                processedReactions.add(commentId);
+            }
+        }
+    }
+    parseReactionData(reaction, reactionId, fileName) {
+        let reactionType = 'unknown';
+        let contentUrl = null;
+        let targetPerson = null;
+        let targetPostId = null;
+        let title = null;
+        // Handle different reaction data formats
+        if (reaction.label_values) {
+            // Format: likes_and_reactions.json (label_values format)
+            for (const labelValue of reaction.label_values) {
+                switch (labelValue.label) {
+                    case 'Reaction':
+                        reactionType = labelValue.value.toLowerCase();
+                        break;
+                    case 'URL':
+                        contentUrl = labelValue.value;
+                        targetPostId = this.extractPostIdFromUrl(labelValue.value);
+                        break;
+                    case 'Name':
+                        targetPerson = labelValue.value;
+                        break;
+                }
+            }
+        }
+        else if (reaction.data && Array.isArray(reaction.data)) {
+            // Format: likes_and_reactions_1.json (data array format)
+            const reactionData = reaction.data[0]?.reaction;
+            if (reactionData) {
+                reactionType = reactionData.reaction ? reactionData.reaction.toLowerCase() : 'like';
+                targetPerson = reactionData.actor;
+            }
+            title = reaction.title;
+        }
+        // Extract additional metadata
+        const hasMedia = Boolean(reaction.media && reaction.media.length > 0);
+        const { fbid } = reaction;
+        return {
+            id: reactionId,
+            timestamp: this.convertFacebookTimestamp(reaction.timestamp * 1000),
+            type: 'reaction',
+            reactionType,
+            contentUrl,
+            targetPerson: targetPerson ? this.fixFacebookTextEncoding(targetPerson) : null,
+            targetPostId,
+            title: title ? this.fixFacebookTextEncoding(title) : null,
+            hasMedia,
+            fbid,
+            fileName,
+            rawData: reaction,
+        };
+    }
+    parseCommentData(commentEntry, commentId, fileName) {
+        if (!commentEntry.data || !Array.isArray(commentEntry.data) || !commentEntry.data[0]?.comment) {
+            return null;
+        }
+        const { comment } = commentEntry.data[0];
+        return {
+            id: commentId,
+            timestamp: this.convertFacebookTimestamp(commentEntry.timestamp * 1000),
+            type: 'comment',
+            reactionType: 'comment',
+            commentText: comment.comment ? this.fixFacebookTextEncoding(comment.comment) : null,
+            author: comment.author ? this.fixFacebookTextEncoding(comment.author) : null,
+            title: commentEntry.title ? this.fixFacebookTextEncoding(commentEntry.title) : null,
+            commentTimestamp: comment.timestamp
+                ? this.convertFacebookTimestamp(comment.timestamp * 1000)
+                : null,
+            fileName,
+            rawData: commentEntry,
+        };
+    }
+    extractPostIdFromUrl(url) {
+        if (!url)
+            return null;
+        // Extract post ID from Facebook URLs
+        const patterns = [/\/posts\/([^/?]+)/, /story_fbid=([^&]+)/, /pfbid([^/?&]+)/];
+        for (const pattern of patterns) {
+            const match = url.match(pattern);
+            if (match) {
+                return match[1];
+            }
+        }
+        return null;
+    }
+    hashReactionContent(reaction) {
+        // Create a simple hash of the reaction content for deduplication
+        const content = JSON.stringify({
+            label_values: reaction.label_values,
+            data: reaction.data,
+            title: reaction.title,
+            fbid: reaction.fbid,
+        });
+        // Simple hash function
+        let hash = 0;
+        for (let i = 0; i < content.length; i++) {
+            const char = content.codePointAt(i) ?? 0;
+            hash = (hash * 33 + char) % 2_147_483_647; // Simple hash without bitwise operators
+        }
+        return Math.abs(hash).toString(36);
+    }
+}

package/dist/connectors/archive/FacebookArchiveSearchHistoryExtractor.d.ts

@@ -0,0 +1,17 @@
+import { Record } from '@chronicle.app/etl';
+import { FacebookArchiveExtractor } from './FacebookArchiveExtractor.js';
+import FacebookTransformer from '../FacebookTransformer.js';
+export declare class FacebookArchiveSearchHistoryExtractor extends FacebookArchiveExtractor {
+    static recordTypes: string[];
+    static description: string;
+    static default: boolean;
+    static defaultTransformer: typeof FacebookTransformer;
+    extract(): AsyncGenerator<Record>;
+    private extractSearchHistoryFromSegment;
+    private processSearchHistoryData;
+    private parseSearchData;
+    private determineSearchType;
+    private isProfileSearch;
+    private hashSearchText;
+}
+//# sourceMappingURL=FacebookArchiveSearchHistoryExtractor.d.ts.map

package/dist/connectors/archive/FacebookArchiveSearchHistoryExtractor.js

@@ -0,0 +1,144 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FacebookArchiveExtractor } from './FacebookArchiveExtractor.js';
+import FacebookTransformer from '../FacebookTransformer.js';
+export class FacebookArchiveSearchHistoryExtractor extends FacebookArchiveExtractor {
+    static recordTypes = ['searches'];
+    static description = 'Search history';
+    static default = false;
+    static defaultTransformer = FacebookTransformer;
+    async *extract() {
+        await this.initialize();
+        const processedSearches = new Set();
+        let recordCount = 0;
+        for await (const { fullPath } of this.iterateExportSegments()) {
+            for await (const record of this.extractSearchHistoryFromSegment(fullPath, processedSearches)) {
+                yield record;
+                recordCount++;
+                if (this.shouldStopExtracting(recordCount)) {
+                    return;
+                }
+            }
+        }
+    }
+    async *extractSearchHistoryFromSegment(segmentPath, processedSearches) {
+        const searchHistoryPath = join(segmentPath, 'logged_information', 'search', 'your_search_history.json');
+        try {
+            await stat(searchHistoryPath);
+        }
+        catch {
+            // No search history file found
+            return;
+        }
+        try {
+            const data = await this.readFacebookJson(searchHistoryPath);
+            yield* this.processSearchHistoryData(data, processedSearches);
+        }
+        catch {
+            // Error reading search history file
+        }
+    }
+    async *processSearchHistoryData(data, processedSearches) {
+        if (!data.searches_v2 || !Array.isArray(data.searches_v2)) {
+            // No searches_v2 array found in search history data
+            return;
+        }
+        for (const search of data.searches_v2) {
+            if (!search.timestamp)
+                continue;
+            // Skip searches outside date range if configured
+            if (!this.isWithinDateRange(new Date(search.timestamp * 1000))) {
+                continue;
+            }
+            const searchId = `search-${search.timestamp}-${this.hashSearchText(search)}`;
+            // Skip if already processed (avoid duplicates)
+            if (processedSearches.has(searchId)) {
+                continue;
+            }
+            const processedSearch = this.parseSearchData(search, searchId);
+            if (processedSearch) {
+                yield this.createRecordWithArchiveContext(processedSearch, {
+                    searchType: 'facebook_search',
+                    dataSource: 'search_history',
+                });
+                processedSearches.add(searchId);
+            }
+        }
+    }
+    parseSearchData(search, searchId) {
+        // Extract search text from multiple possible locations
+        let searchText = '';
+        let searchQuery = '';
+        // Try to get search text from data array
+        if (search.data && Array.isArray(search.data) && search.data[0]?.text) {
+            searchText = search.data[0].text;
+        }
+        // Try to get search text from attachments
+        if (search.attachments && Array.isArray(search.attachments)) {
+            for (const attachment of search.attachments) {
+                if (attachment.data && Array.isArray(attachment.data) && attachment.data[0]?.text) {
+                    searchQuery = attachment.data[0].text;
+                    // Remove quotes if present
+                    searchQuery = searchQuery.replace(/^"(.*)"$/, '$1');
+                    break;
+                }
+            }
+        }
+        // Use searchQuery if available, otherwise fallback to searchText
+        const finalSearchText = searchQuery || searchText;
+        if (!finalSearchText) {
+            return null;
+        }
+        const searchType = this.determineSearchType(search.title || '');
+        const isProfileSearch = this.isProfileSearch(finalSearchText, search.title || '');
+        return {
+            id: searchId,
+            timestamp: this.convertFacebookTimestamp(search.timestamp * 1000),
+            searchText: this.fixFacebookTextEncoding(finalSearchText),
+            searchQuery: searchQuery ? this.fixFacebookTextEncoding(searchQuery) : null,
+            title: search.title ? this.fixFacebookTextEncoding(search.title) : null,
+            searchType,
+            isProfileSearch,
+            isVisited: (search.title || '').includes('visited'),
+            isSearched: (search.title || '').includes('searched'),
+            rawSearchText: searchText,
+            hasAttachments: Boolean(search.attachments && search.attachments.length > 0),
+            rawData: search,
+        };
+    }
+    determineSearchType(title) {
+        const lowerTitle = title.toLowerCase();
+        if (lowerTitle.includes('visited'))
+            return 'visit';
+        if (lowerTitle.includes('searched'))
+            return 'search';
+        if (lowerTitle.includes('looked for'))
+            return 'lookup';
+        return 'unknown';
+    }
+    isProfileSearch(searchText, title) {
+        // Check if this appears to be searching for a person
+        const hasPersonIndicators = [
+            /^[A-Z][a-z]+ [A-Z]/, // First Last name pattern
+            title.includes('visited'),
+            title.includes('profile'),
+            !searchText.includes(' ') && searchText.length > 2, // Single word that might be a name
+        ];
+        return hasPersonIndicators.some(indicator => typeof indicator === 'boolean' ? indicator : indicator.test(searchText));
+    }
+    hashSearchText(search) {
+        // Create a simple hash of the search content for deduplication
+        const content = JSON.stringify({
+            data: search.data,
+            attachments: search.attachments,
+            title: search.title,
+        });
+        // Simple hash function
+        let hash = 0;
+        for (let i = 0; i < content.length; i++) {
+            const char = content.codePointAt(i) ?? 0;
+            hash = (hash * 33 + char) % 2_147_483_647; // Simple hash without bitwise operators
+        }
+        return Math.abs(hash).toString(36);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { default as FacebookTransformer } from './connectors/FacebookTransformer.js';
+export { FacebookArchiveExtractor } from './connectors/archive/FacebookArchiveExtractor.js';
+export { FacebookArchiveMessagesExtractor } from './connectors/archive/FacebookArchiveMessagesExtractor.js';
+export { FacebookArchiveReactionsExtractor } from './connectors/archive/FacebookArchiveReactionsExtractor.js';
+export { FacebookArchiveSearchHistoryExtractor } from './connectors/archive/FacebookArchiveSearchHistoryExtractor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,5 @@
+export { default as FacebookTransformer } from './connectors/FacebookTransformer.js';
+export { FacebookArchiveExtractor } from './connectors/archive/FacebookArchiveExtractor.js';
+export { FacebookArchiveMessagesExtractor } from './connectors/archive/FacebookArchiveMessagesExtractor.js';
+export { FacebookArchiveReactionsExtractor } from './connectors/archive/FacebookArchiveReactionsExtractor.js';
+export { FacebookArchiveSearchHistoryExtractor } from './connectors/archive/FacebookArchiveSearchHistoryExtractor.js';

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@chronicle.app/facebook",
+  "version": "0.3.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [
+    "chronicle",
+    "facebook"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for Chronicle plugin for facebook",
+  "devDependencies": {
+    "@chronicle.app/etl": "0.3.0",
+    "@chronicle.app/schema": "0.3.0",
+    "@chronicle.app/tsconfig": "0.3.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "plugins/facebook"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "peerDependencies": {
+    "@chronicle.app/etl": ">=0.1.0 <1.0.0",
+    "@chronicle.app/schema": ">=0.1.0 <1.0.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "chronicle": {
+    "plugin": true,
+    "sources": {
+      "facebook": {
+        "strategies": {
+          "archive": {
+            "delivery": "export",
+            "recordTypes": [
+              "messages",
+              "reactions",
+              "comments",
+              "searches"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}