@chronicle.app/linkedin 0.4.0 → 0.5.0

package/README.md

@@ -1,10 +1,11 @@
 # LinkedIn plugin
 
 Reads the **member data export** — the ZIP that Settings & Privacy → Data
-Privacy → "Get a copy of your data" produces, unpacked to a directory.
+Privacy → "Get a copy of your data" produces, read in place or unpacked to a
+directory.
 
 ```bash
-chronicle extract linkedin --input ~/Downloads/Basic_LinkedInDataExport_08-08-2026 --limit 0
+chronicle extract linkedin --input ~/Downloads/Basic_LinkedInDataExport_08-08-2026.zip --limit 0
 chronicle extract linkedin --input <dir> --type messages --limit 5   # one record kind
 ```
 
@@ -114,8 +115,8 @@ made in 2010 would claim they worked there then. `Positions.csv` and
 `Education.csv` are snapshots for the same reason. Messages, endorsements,
 follows and learning are events.
 
-**Re-importing the same directory is a no-op.** The sighting time is the
-export's own file time, not the moment of import, so a second run restates
+**Re-importing the same export is a no-op.** The sighting time is the
+export's own file time, in a zip from its index, not the moment of import, so a second run restates
 identical assertions instead of minting fresh ones.
 
 ## Not read, and why

package/dist/connectors/LinkedInTransformer.js

@@ -289,14 +289,15 @@ export default class LinkedInTransformer extends ChronicleTransformer {
                 '@type',
                 'source',
                 'timestamp',
-                'object.isPartOf[*].sourceId',
+                'result.isPartOf[*].sourceId',
                 'agent.handle',
                 'agent.name',
             ],
             source: SOURCE,
             timestamp: data.sentAt,
             ...(sender && { agent: sender }),
-            object: message,
+            // Sending makes the message, so it's the action's result.
+            result: message,
         };
         return [sent];
     }

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

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
 import { LinkedInArchiveExtractor } from './LinkedInArchiveExtractor.js';
 /**
@@ -43,6 +43,10 @@ export declare class LinkedInArchiveConnectionsExtractor extends LinkedInArchive
     /** The connection's profile URL — LinkedIn's own id for them, and stable per export. */
     keyOf(record: Record): string | null;
     extract(): AsyncGenerator<Record>;
+    /** The connections a run reads, and the day each was made. */
+    survey(options?: SurveyOptions): Promise<Survey>;
+    /** Every connection in the export that names someone, newest first. */
+    private connections;
     determineCount(): Promise<number>;
 }
 //# sourceMappingURL=LinkedInArchiveConnectionsExtractor.d.ts.map

package/dist/connectors/archive/LinkedInArchiveConnectionsExtractor.js

@@ -26,6 +26,26 @@ export class LinkedInArchiveConnectionsExtractor extends LinkedInArchiveExtracto
         return record.data.url ?? null;
     }
     async *extract() {
+        let count = 0;
+        for (const connection of await this.connections()) {
+            if (this.shouldStopExtracting(count))
+                break;
+            if (!this.withinWindow(connection.connectedOn))
+                continue;
+            yield this.createRecordWithArchiveContext({
+                ...connection,
+                occurredAt: connection.connectedOn,
+            });
+            count++;
+        }
+    }
+    /** The connections a run reads, and the day each was made. */
+    async survey(options = {}) {
+        const dates = (await this.connections()).map(connection => connection.connectedOn);
+        return { connections: this.surveyDates(dates, options) };
+    }
+    /** Every connection in the export that names someone, newest first. */
+    async connections() {
         const rows = await this.readCsv('Connections.csv');
         const connections = rows
             .map(row => {
@@ -47,18 +67,7 @@ export class LinkedInArchiveConnectionsExtractor extends LinkedInArchiveExtracto
             // A row with neither a profile URL nor a name names nobody.
             .filter(connection => connection.handle || connection.name)
             .sort((a, b) => ((a.connectedOn ?? '') < (b.connectedOn ?? '') ? 1 : -1));
-        let count = 0;
-        for (const connection of connections) {
-            if (this.shouldStopExtracting(count))
-                break;
-            if (!this.withinWindow(connection.connectedOn))
-                continue;
-            yield this.createRecordWithArchiveContext({
-                ...connection,
-                occurredAt: connection.connectedOn,
-            });
-            count++;
-        }
+        return connections;
     }
     async determineCount() {
         return (await this.readCsv('Connections.csv')).length;

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

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
 import { LinkedInArchiveExtractor } from './LinkedInArchiveExtractor.js';
 /**
@@ -31,6 +31,10 @@ export declare class LinkedInArchiveEducationExtractor extends LinkedInArchiveEx
         limit?: number | undefined;
     }>;
     extract(): AsyncGenerator<Record>;
+    /** The schools a run reads, and when each began. */
+    survey(options?: SurveyOptions): Promise<Survey>;
+    /** Every school in the export with a name and a start, newest first. */
+    private enrollments;
     determineCount(): Promise<number>;
 }
 //# sourceMappingURL=LinkedInArchiveEducationExtractor.d.ts.map

package/dist/connectors/archive/LinkedInArchiveEducationExtractor.js

@@ -12,20 +12,8 @@ export class LinkedInArchiveEducationExtractor extends LinkedInArchiveExtractor
     static defaultTransformer = LinkedInTransformer;
     static schema = LinkedInArchiveExtractor.schema;
     async *extract() {
-        const rows = await this.readCsv('Education.csv');
-        const enrollments = rows
-            .map(row => ({
-            school: row['School Name']?.trim(),
-            degree: row['Degree Name']?.trim(),
-            notes: row.Notes?.trim(),
-            activities: row.Activities?.trim(),
-            startedOn: parseCoarseDate(row['Start Date']),
-            finishedOn: parseCoarseDate(row['End Date']),
-        }))
-            .filter(enrollment => enrollment.school && enrollment.startedOn)
-            .sort((a, b) => (a.startedOn < b.startedOn ? 1 : -1));
         let count = 0;
-        for (const enrollment of enrollments) {
+        for (const enrollment of await this.enrollments()) {
             if (this.shouldStopExtracting(count))
                 break;
             if (!this.withinWindow(enrollment.startedOn))
@@ -37,6 +25,26 @@ export class LinkedInArchiveEducationExtractor extends LinkedInArchiveExtractor
             count++;
         }
     }
+    /** The schools a run reads, and when each began. */
+    async survey(options = {}) {
+        const dates = (await this.enrollments()).map(enrollment => enrollment.startedOn);
+        return { education: this.surveyDates(dates, options) };
+    }
+    /** Every school in the export with a name and a start, newest first. */
+    async enrollments() {
+        const rows = await this.readCsv('Education.csv');
+        return rows
+            .map(row => ({
+            school: row['School Name']?.trim(),
+            degree: row['Degree Name']?.trim(),
+            notes: row.Notes?.trim(),
+            activities: row.Activities?.trim(),
+            startedOn: parseCoarseDate(row['Start Date']),
+            finishedOn: parseCoarseDate(row['End Date']),
+        }))
+            .filter(enrollment => enrollment.school && enrollment.startedOn)
+            .sort((a, b) => (a.startedOn < b.startedOn ? 1 : -1));
+    }
     async determineCount() {
         return (await this.readCsv('Education.csv')).length;
     }

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

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
 import { LinkedInArchiveExtractor } from './LinkedInArchiveExtractor.js';
 /**
@@ -39,6 +39,10 @@ export declare class LinkedInArchiveEndorsementsExtractor extends LinkedInArchiv
         limit?: number | undefined;
     }>;
     extract(): AsyncGenerator<Record>;
+    /** The endorsements a run reads, both ways, and when each was made. */
+    survey(options?: SurveyOptions): Promise<Survey>;
+    /** Both endorsement files as one list, newest first. */
+    private endorsements;
     /** One endorsement file, with the other party's columns read by prefix. */
     private readEndorsements;
     determineCount(): Promise<number>;

package/dist/connectors/archive/LinkedInArchiveEndorsementsExtractor.js

@@ -20,11 +20,8 @@ export class LinkedInArchiveEndorsementsExtractor extends LinkedInArchiveExtract
     static defaultTransformer = LinkedInTransformer;
     static schema = LinkedInArchiveExtractor.schema;
     async *extract() {
-        const given = await this.readEndorsements('Endorsement_Given_Info.csv', 'given');
-        const received = await this.readEndorsements('Endorsement_Received_Info.csv', 'received');
-        const endorsements = [...given, ...received].sort((a, b) => (a.endorsedAt ?? '') < (b.endorsedAt ?? '') ? 1 : -1);
         let count = 0;
-        for (const endorsement of endorsements) {
+        for (const endorsement of await this.endorsements()) {
             if (this.shouldStopExtracting(count))
                 break;
             if (!this.withinWindow(endorsement.endorsedAt))
@@ -36,6 +33,17 @@ export class LinkedInArchiveEndorsementsExtractor extends LinkedInArchiveExtract
             count++;
         }
     }
+    /** The endorsements a run reads, both ways, and when each was made. */
+    async survey(options = {}) {
+        const dates = (await this.endorsements()).map(endorsement => endorsement.endorsedAt);
+        return { endorsements: this.surveyDates(dates, options) };
+    }
+    /** Both endorsement files as one list, newest first. */
+    async endorsements() {
+        const given = await this.readEndorsements('Endorsement_Given_Info.csv', 'given');
+        const received = await this.readEndorsements('Endorsement_Received_Info.csv', 'received');
+        return [...given, ...received].sort((a, b) => (a.endorsedAt ?? '') < (b.endorsedAt ?? '') ? 1 : -1);
+    }
     /** One endorsement file, with the other party's columns read by prefix. */
     async readEndorsements(fileName, direction) {
         const prefix = direction === 'given' ? 'Endorsee' : 'Endorser';

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

@@ -1,4 +1,4 @@
-import { ArchiveExtractor } from '@chronicle.app/etl';
+import { ArchiveExtractor, type KindSurvey, type SurveyOptions } from '@chronicle.app/etl';
 import { z } from 'zod';
 /** What one export knows about the member who requested it. */
 export interface LinkedInAccount {
@@ -13,8 +13,8 @@ export interface LinkedInAccount {
 }
 /**
  * Base for the LinkedIn member data export — the ZIP that Settings & Privacy →
- * Data Privacy → "Get a copy of your data" produces, unpacked to a directory of
- * CSVs.
+ * Data Privacy → "Get a copy of your data" produces: a folder of CSVs, read
+ * as the zip or unpacked.
  *
  * Shared here: reading a named CSV out of the export, the account info every
  * record carries, and the date window. One subclass per file, because the files
@@ -50,10 +50,11 @@ export declare abstract class LinkedInArchiveExtractor<T extends typeof LinkedIn
         limit?: number | undefined;
     }>;
     protected accountInfo: LinkedInAccount;
+    protected readonly exportName = "LinkedIn export";
     /** Lower-cased file name → real file name, so a renamed case still resolves. */
     private fileIndex?;
     /** When LinkedIn wrote this export — see {@link asOfTime}. */
-    private compiledAt?;
+    protected compiledAt?: Date;
     /**
      * Read the export's own facts before extraction: who it belongs to, and when
      * LinkedIn built it. The base class defines `loadAccountInfo` but never calls
@@ -71,7 +72,7 @@ export declare abstract class LinkedInArchiveExtractor<T extends typeof LinkedIn
      * of a fresh sighting of unchanged facts.
      */
     protected asOfTime(): Date;
-    /** The newest mtime among the export's files, or none if it has none. */
+    /** The newest mtime among the export's files, or none if it has none; in a zip, from its index. */
     private newestFileTime;
     /**
      * The export's own account facts, read once per run: the profile, the primary
@@ -105,7 +106,7 @@ export declare abstract class LinkedInArchiveExtractor<T extends typeof LinkedIn
     protected readCsv(fileName: string): Promise<Array<{
         [column: string]: string | undefined;
     }>>;
-    /** The real path for a file name, matched case-insensitively, or none. */
+    /** The real name of a file in the export, matched case-insensitively, or none. */
     private resolveFile;
     /** Every file in the export, listed once and indexed for case-insensitive lookup. */
     private fileNames;
@@ -116,5 +117,12 @@ export declare abstract class LinkedInArchiveExtractor<T extends typeof LinkedIn
      * record on the strength of a date the source never wrote.
      */
     protected withinWindow(date: string | undefined): boolean;
+    /**
+     * One record type's survey, from the date of each record a run would read,
+     * undated ones too: kept or dropped by the same since/until window, and
+     * placed by {@link occurrenceTime}. An undated record counts, but has no
+     * time or month to add.
+     */
+    protected surveyDates(dates: Array<string | undefined>, options: SurveyOptions): KindSurvey;
 }
 //# sourceMappingURL=LinkedInArchiveExtractor.d.ts.map

package/dist/connectors/archive/LinkedInArchiveExtractor.js

@@ -1,13 +1,11 @@
-import { ArchiveExtractor, Extractor, InputNotFound, fileError } from '@chronicle.app/etl';
+import { ArchiveExtractor, countMonth, Extractor, } from '@chronicle.app/etl';
 import { parse } from 'csv-parse/sync';
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { join } from 'node:path';
 import { z } from 'zod';
-import { profileHandle } from '../fields.js';
+import { occurrenceTime, profileHandle } from '../fields.js';
 /**
  * Base for the LinkedIn member data export — the ZIP that Settings & Privacy →
- * Data Privacy → "Get a copy of your data" produces, unpacked to a directory of
- * CSVs.
+ * Data Privacy → "Get a copy of your data" produces: a folder of CSVs, read
+ * as the zip or unpacked.
  *
  * Shared here: reading a named CSV out of the export, the account info every
  * record carries, and the date window. One subclass per file, because the files
@@ -23,13 +21,14 @@ export class LinkedInArchiveExtractor extends ArchiveExtractor {
     static source = 'linkedin';
     static strategy = 'archive';
     static schema = Extractor.schema.extend({
-        input: z.string().describe('Path to the unpacked LinkedIn export directory'),
+        input: z.string().describe('The LinkedIn export, as a zip or its unpacked folder'),
         'profile-url': z
             .string()
             .optional()
             .describe('Your LinkedIn profile URL (https://www.linkedin.com/in/…). Only needed when the export carries no invitation to infer it from.'),
     });
     accountInfo = {};
+    exportName = 'LinkedIn export';
     /** Lower-cased file name → real file name, so a renamed case still resolves. */
     fileIndex;
     /** When LinkedIn wrote this export — see {@link asOfTime}. */
@@ -57,19 +56,14 @@ export class LinkedInArchiveExtractor extends ArchiveExtractor {
     asOfTime() {
         return this.compiledAt ?? super.asOfTime();
     }
-    /** The newest mtime among the export's files, or none if it has none. */
+    /** The newest mtime among the export's files, or none if it has none; in a zip, from its index. */
     async newestFileTime() {
-        const { input } = this.config;
         let newest;
         for (const name of await this.fileNames()) {
-            try {
-                const { mtimeMs } = await stat(join(input, name));
-                if (newest === undefined || mtimeMs > newest)
-                    newest = mtimeMs;
-            }
-            catch {
-                // A file that vanished between listing and stat tells us nothing.
-            }
+            // A file that vanished between listing and stat tells us nothing.
+            const mtimeMs = (await this.files.modified(name))?.getTime();
+            if (mtimeMs !== undefined && (newest === undefined || mtimeMs > newest))
+                newest = mtimeMs;
         }
         return newest === undefined ? undefined : new Date(newest);
     }
@@ -147,7 +141,7 @@ export class LinkedInArchiveExtractor extends ArchiveExtractor {
         const path = await this.resolveFile(fileName);
         if (!path)
             return [];
-        const text = stripPreamble(await readFile(path, 'utf8'));
+        const text = stripPreamble(await this.files.readText(path));
         if (!text.trim())
             return [];
         return parse(text, {
@@ -158,27 +152,15 @@ export class LinkedInArchiveExtractor extends ArchiveExtractor {
             bom: true,
         });
     }
-    /** The real path for a file name, matched case-insensitively, or none. */
+    /** The real name of a file in the export, matched case-insensitively, or none. */
     async resolveFile(fileName) {
         await this.fileNames();
-        const resolved = this.fileIndex.get(fileName.toLowerCase());
-        const { input } = this.config;
-        return resolved ? join(input, resolved) : undefined;
+        return this.fileIndex.get(fileName.toLowerCase());
     }
     /** Every file in the export, listed once and indexed for case-insensitive lookup. */
     async fileNames() {
         if (!this.fileIndex) {
-            const { input } = this.config;
-            let entries = [];
-            try {
-                entries = await readdir(input);
-            }
-            catch (error) {
-                const typed = fileError(error, input, 'LinkedIn export');
-                throw typed === error
-                    ? new InputNotFound("Couldn't read the LinkedIn export", { path: input, cause: error })
-                    : typed;
-            }
+            const entries = (await this.files.children('')).filter(name => !name.endsWith('/'));
             this.fileIndex = new Map(entries.map(name => [name.toLowerCase(), name]));
         }
         return [...this.fileIndex.values()];
@@ -195,6 +177,30 @@ export class LinkedInArchiveExtractor extends ArchiveExtractor {
         const parsed = new Date(date);
         return Number.isNaN(parsed.getTime()) ? true : this.isWithinDateRange(parsed);
     }
+    /**
+     * One record type's survey, from the date of each record a run would read,
+     * undated ones too: kept or dropped by the same since/until window, and
+     * placed by {@link occurrenceTime}. An undated record counts, but has no
+     * time or month to add.
+     */
+    surveyDates(dates, options) {
+        const kind = { count: 0, ...(options.byMonth && { byMonth: {} }) };
+        for (const date of dates) {
+            if (!this.withinWindow(date))
+                continue;
+            kind.count++;
+            const time = occurrenceTime(date);
+            if (!time)
+                continue;
+            if (!kind.earliest || time < kind.earliest)
+                kind.earliest = time;
+            if (!kind.latest || time > kind.latest)
+                kind.latest = time;
+            if (kind.byMonth)
+                countMonth(kind.byMonth, time);
+        }
+        return kind;
+    }
 }
 /**
  * Drop the prose LinkedIn writes above the header of `Connections.csv` — a

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

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
 import { LinkedInArchiveExtractor } from './LinkedInArchiveExtractor.js';
 /**
@@ -34,6 +34,10 @@ export declare class LinkedInArchiveFollowsExtractor extends LinkedInArchiveExtr
         limit?: number | undefined;
     }>;
     extract(): AsyncGenerator<Record>;
+    /** The follows a run reads, and when each was made. */
+    survey(options?: SurveyOptions): Promise<Survey>;
+    /** Every follow in the export that names what it follows, newest first. */
+    private follows;
     determineCount(): Promise<number>;
 }
 //# sourceMappingURL=LinkedInArchiveFollowsExtractor.d.ts.map

package/dist/connectors/archive/LinkedInArchiveFollowsExtractor.js

@@ -15,16 +15,8 @@ export class LinkedInArchiveFollowsExtractor extends LinkedInArchiveExtractor {
     static defaultTransformer = LinkedInTransformer;
     static schema = LinkedInArchiveExtractor.schema;
     async *extract() {
-        const rows = await this.readCsv('Company Follows.csv');
-        const follows = rows
-            .map(row => ({
-            organization: row.Organization?.trim(),
-            followedAt: parseLongStamp(row['Followed On']),
-        }))
-            .filter(follow => follow.organization)
-            .sort((a, b) => ((a.followedAt ?? '') < (b.followedAt ?? '') ? 1 : -1));
         let count = 0;
-        for (const follow of follows) {
+        for (const follow of await this.follows()) {
             if (this.shouldStopExtracting(count))
                 break;
             if (!this.withinWindow(follow.followedAt))
@@ -36,6 +28,22 @@ export class LinkedInArchiveFollowsExtractor extends LinkedInArchiveExtractor {
             count++;
         }
     }
+    /** The follows a run reads, and when each was made. */
+    async survey(options = {}) {
+        const dates = (await this.follows()).map(follow => follow.followedAt);
+        return { follows: this.surveyDates(dates, options) };
+    }
+    /** Every follow in the export that names what it follows, newest first. */
+    async follows() {
+        const rows = await this.readCsv('Company Follows.csv');
+        return rows
+            .map(row => ({
+            organization: row.Organization?.trim(),
+            followedAt: parseLongStamp(row['Followed On']),
+        }))
+            .filter(follow => follow.organization)
+            .sort((a, b) => ((a.followedAt ?? '') < (b.followedAt ?? '') ? 1 : -1));
+    }
     async determineCount() {
         return (await this.readCsv('Company Follows.csv')).length;
     }

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

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
 import { LinkedInArchiveExtractor } from './LinkedInArchiveExtractor.js';
 /**
@@ -36,6 +36,10 @@ export declare class LinkedInArchiveLearningExtractor extends LinkedInArchiveExt
         limit?: number | undefined;
     }>;
     extract(): AsyncGenerator<Record>;
+    /** The courses a run reads, and when each was last watched, else completed. */
+    survey(options?: SurveyOptions): Promise<Survey>;
+    /** Every course in the export with a title, newest-watched first. */
+    private courses;
     determineCount(): Promise<number>;
 }
 //# sourceMappingURL=LinkedInArchiveLearningExtractor.d.ts.map

package/dist/connectors/archive/LinkedInArchiveLearningExtractor.js

@@ -17,8 +17,26 @@ export class LinkedInArchiveLearningExtractor extends LinkedInArchiveExtractor {
     static defaultTransformer = LinkedInTransformer;
     static schema = LinkedInArchiveExtractor.schema;
     async *extract() {
+        let count = 0;
+        for (const course of await this.courses()) {
+            if (this.shouldStopExtracting(count))
+                break;
+            const occurredAt = lastSeen(course);
+            if (!this.withinWindow(occurredAt))
+                continue;
+            yield this.createRecordWithArchiveContext({ ...course, occurredAt });
+            count++;
+        }
+    }
+    /** The courses a run reads, and when each was last watched, else completed. */
+    async survey(options = {}) {
+        const dates = (await this.courses()).map(course => lastSeen(course));
+        return { learning: this.surveyDates(dates, options) };
+    }
+    /** Every course in the export with a title, newest-watched first. */
+    async courses() {
         const rows = await this.readCsv('Learning.csv');
-        const courses = rows
+        return rows
             .map(row => ({
             title: row['Content Title']?.trim(),
             description: row['Content Description']?.trim() || undefined,
@@ -29,18 +47,12 @@ export class LinkedInArchiveLearningExtractor extends LinkedInArchiveExtractor {
         }))
             .filter(course => course.title)
             .sort((a, b) => ((a.watchedAt ?? '') < (b.watchedAt ?? '') ? 1 : -1));
-        let count = 0;
-        for (const course of courses) {
-            if (this.shouldStopExtracting(count))
-                break;
-            const occurredAt = course.watchedAt ?? course.completedAt;
-            if (!this.withinWindow(occurredAt))
-                continue;
-            yield this.createRecordWithArchiveContext({ ...course, occurredAt });
-            count++;
-        }
     }
     async determineCount() {
         return (await this.readCsv('Learning.csv')).length;
     }
 }
+/** When a course dates to: the last time it was watched, else when it was completed. */
+function lastSeen(course) {
+    return course.watchedAt ?? course.completedAt;
+}

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

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
 import { LinkedInArchiveExtractor } from './LinkedInArchiveExtractor.js';
 /** A party to a message: the handle when LinkedIn gave one, the name when it did not. */
@@ -58,6 +58,10 @@ export declare class LinkedInArchiveMessagesExtractor extends LinkedInArchiveExt
         limit?: number | undefined;
     }>;
     extract(): AsyncGenerator<Record>;
+    /** The messages a run reads and when they were sent, with how many conversations they're in. */
+    survey(options?: SurveyOptions): Promise<Survey>;
+    /** Every message in the export that can be placed, newest first. */
+    private messages;
     determineCount(): Promise<number>;
 }
 //# sourceMappingURL=LinkedInArchiveMessagesExtractor.d.ts.map

package/dist/connectors/archive/LinkedInArchiveMessagesExtractor.js

@@ -34,6 +34,33 @@ export class LinkedInArchiveMessagesExtractor extends LinkedInArchiveExtractor {
     static defaultTransformer = LinkedInTransformer;
     static schema = LinkedInArchiveExtractor.schema;
     async *extract() {
+        let count = 0;
+        for (const message of await this.messages()) {
+            if (this.shouldStopExtracting(count))
+                break;
+            if (!this.withinWindow(message.sentAt))
+                continue;
+            yield this.createRecordWithArchiveContext({
+                ...message,
+                occurredAt: message.sentAt,
+            });
+            count++;
+        }
+    }
+    /** The messages a run reads and when they were sent, with how many conversations they're in. */
+    async survey(options = {}) {
+        const messages = (await this.messages()).filter(message => this.withinWindow(message.sentAt));
+        const dates = messages.map(message => message.sentAt);
+        const conversations = new Set(messages.map(message => message.conversationId)).size;
+        return {
+            messages: {
+                ...this.surveyDates(dates, options),
+                measures: [{ key: 'conversations', label: 'conversations', value: conversations }],
+            },
+        };
+    }
+    /** Every message in the export that can be placed, newest first. */
+    async messages() {
         const rows = await this.readCsv('messages.csv');
         const messages = rows
             .map(row => {
@@ -55,18 +82,7 @@ export class LinkedInArchiveMessagesExtractor extends LinkedInArchiveExtractor {
             // a row missing either is not a message we can place.
             .filter(message => message.conversationId && message.sentAt)
             .sort((a, b) => ((a.sentAt ?? '') < (b.sentAt ?? '') ? 1 : -1));
-        let count = 0;
-        for (const message of messages) {
-            if (this.shouldStopExtracting(count))
-                break;
-            if (!this.withinWindow(message.sentAt))
-                continue;
-            yield this.createRecordWithArchiveContext({
-                ...message,
-                occurredAt: message.sentAt,
-            });
-            count++;
-        }
+        return messages;
     }
     async determineCount() {
         return (await this.readCsv('messages.csv')).length;

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

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey, type SurveyOptions } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
 import { LinkedInArchiveExtractor } from './LinkedInArchiveExtractor.js';
 /**
@@ -35,6 +35,10 @@ export declare class LinkedInArchivePositionsExtractor extends LinkedInArchiveEx
         limit?: number | undefined;
     }>;
     extract(): AsyncGenerator<Record>;
+    /** The positions a run reads, and when each began. */
+    survey(options?: SurveyOptions): Promise<Survey>;
+    /** Every position in the export with a company and a start, newest first. */
+    private positions;
     determineCount(): Promise<number>;
 }
 //# sourceMappingURL=LinkedInArchivePositionsExtractor.d.ts.map

package/dist/connectors/archive/LinkedInArchivePositionsExtractor.js

@@ -16,20 +16,8 @@ export class LinkedInArchivePositionsExtractor extends LinkedInArchiveExtractor
     static defaultTransformer = LinkedInTransformer;
     static schema = LinkedInArchiveExtractor.schema;
     async *extract() {
-        const rows = await this.readCsv('Positions.csv');
-        const positions = rows
-            .map(row => ({
-            company: row['Company Name']?.trim(),
-            title: row.Title?.trim(),
-            description: row.Description?.trim(),
-            location: row.Location?.trim(),
-            startedOn: parseCoarseDate(row['Started On']),
-            finishedOn: parseCoarseDate(row['Finished On']),
-        }))
-            .filter(position => position.company && position.startedOn)
-            .sort((a, b) => (a.startedOn < b.startedOn ? 1 : -1));
         let count = 0;
-        for (const position of positions) {
+        for (const position of await this.positions()) {
             if (this.shouldStopExtracting(count))
                 break;
             if (!this.withinWindow(position.startedOn))
@@ -41,6 +29,26 @@ export class LinkedInArchivePositionsExtractor extends LinkedInArchiveExtractor
             count++;
         }
     }
+    /** The positions a run reads, and when each began. */
+    async survey(options = {}) {
+        const dates = (await this.positions()).map(position => position.startedOn);
+        return { positions: this.surveyDates(dates, options) };
+    }
+    /** Every position in the export with a company and a start, newest first. */
+    async positions() {
+        const rows = await this.readCsv('Positions.csv');
+        return rows
+            .map(row => ({
+            company: row['Company Name']?.trim(),
+            title: row.Title?.trim(),
+            description: row.Description?.trim(),
+            location: row.Location?.trim(),
+            startedOn: parseCoarseDate(row['Started On']),
+            finishedOn: parseCoarseDate(row['Finished On']),
+        }))
+            .filter(position => position.company && position.startedOn)
+            .sort((a, b) => (a.startedOn < b.startedOn ? 1 : -1));
+    }
     async determineCount() {
         return (await this.readCsv('Positions.csv')).length;
     }

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

@@ -1,4 +1,4 @@
-import { Record } from '@chronicle.app/etl';
+import { Record, type Survey } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
 import { LinkedInArchiveExtractor } from './LinkedInArchiveExtractor.js';
 /**
@@ -36,6 +36,13 @@ export declare class LinkedInArchiveProfileExtractor extends LinkedInArchiveExtr
         limit?: number | undefined;
     }>;
     extract(): AsyncGenerator<Record>;
+    /**
+     * The profile a run reads, as of when LinkedIn compiled the export: it has
+     * no time of its own, and dates its sighting to that.
+     */
+    survey(): Promise<Survey>;
+    /** The account, when the export names its member at all. */
+    private profile;
     determineCount(): Promise<number>;
 }
 //# sourceMappingURL=LinkedInArchiveProfileExtractor.d.ts.map

package/dist/connectors/archive/LinkedInArchiveProfileExtractor.js

@@ -16,11 +16,25 @@ export class LinkedInArchiveProfileExtractor extends LinkedInArchiveExtractor {
     static defaultTransformer = LinkedInTransformer;
     static schema = LinkedInArchiveExtractor.schema;
     async *extract() {
-        const account = this.accountInfo;
-        if (!account.name && !account.handle && !account.email)
+        const account = this.profile();
+        if (!account)
             return;
         yield this.createRecordWithArchiveContext({ ...account });
     }
+    /**
+     * The profile a run reads, as of when LinkedIn compiled the export: it has
+     * no time of its own, and dates its sighting to that.
+     */
+    async survey() {
+        if (!this.profile())
+            return { profile: { count: 0 } };
+        return { profile: { count: 1, ...(this.compiledAt && { asOf: this.compiledAt }) } };
+    }
+    /** The account, when the export names its member at all. */
+    profile() {
+        const account = this.accountInfo;
+        return account.name || account.handle || account.email ? account : undefined;
+    }
     async determineCount() {
         return 1;
     }

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

@@ -1,6 +1,13 @@
 import { MergingExtractor, Record } from '@chronicle.app/etl';
 import LinkedInTransformer from '../LinkedInTransformer.js';
+import { LinkedInArchiveConnectionsExtractor } from './LinkedInArchiveConnectionsExtractor.js';
+import { LinkedInArchiveEducationExtractor } from './LinkedInArchiveEducationExtractor.js';
+import { LinkedInArchiveEndorsementsExtractor } from './LinkedInArchiveEndorsementsExtractor.js';
+import { LinkedInArchiveFollowsExtractor } from './LinkedInArchiveFollowsExtractor.js';
+import { LinkedInArchiveLearningExtractor } from './LinkedInArchiveLearningExtractor.js';
 import { LinkedInArchiveMessagesExtractor } from './LinkedInArchiveMessagesExtractor.js';
+import { LinkedInArchivePositionsExtractor } from './LinkedInArchivePositionsExtractor.js';
+import { LinkedInArchiveProfileExtractor } from './LinkedInArchiveProfileExtractor.js';
 /**
  * The whole export in one reverse-chronological pass — what a bare
  * `extract linkedin -i <dir>` means.
@@ -18,7 +25,7 @@ export declare class LinkedInDefaultExtractor extends MergingExtractor<typeof Li
     static recordTypes: string[];
     static default: boolean;
     static defaultTransformer: typeof LinkedInTransformer;
-    static children: (typeof LinkedInArchiveMessagesExtractor)[];
+    static children: (typeof LinkedInArchiveMessagesExtractor | typeof LinkedInArchiveConnectionsExtractor | typeof LinkedInArchiveEducationExtractor | typeof LinkedInArchiveEndorsementsExtractor | typeof LinkedInArchiveFollowsExtractor | typeof LinkedInArchiveLearningExtractor | typeof LinkedInArchivePositionsExtractor | typeof LinkedInArchiveProfileExtractor)[];
     static schema: any;
     /**
      * Every child dates its records the same way, on `occurredAt`. A record with

package/dist/connectors/archive/LinkedInDefaultExtractor.js

@@ -48,7 +48,7 @@ export class LinkedInDefaultExtractor extends MergingExtractor {
     // The union of the children's flags, so the runner forwards them to the merge
     // and the merge forwards the raw config to each child.
     static schema = MergingExtractor.schema.extend({
-        input: z.string().describe('Path to the unpacked LinkedIn export directory'),
+        input: z.string().describe('The LinkedIn export, as a zip or its unpacked folder'),
         'profile-url': z
             .string()
             .optional()

package/dist/connectors/fields.d.ts

@@ -53,4 +53,12 @@ export declare function parseDayDate(raw: string | undefined): string | undefine
  * its own precision, which is why widening them to a day would be a lie.
  */
 export declare function parseCoarseDate(raw: string | undefined): string | undefined;
+/**
+ * A date one of these readers returned, as the moment a survey counts it at:
+ * an instant as itself, and a civil date (`2009`, `2022-08`, `2026-06-06`) at
+ * the start of its year, month, or day in local time. `new Date` would put a
+ * civil date at midnight UTC, which west of Greenwich is the day, month, or
+ * year before.
+ */
+export declare function occurrenceTime(value: string | undefined): Date | undefined;
 //# sourceMappingURL=fields.d.ts.map

package/dist/connectors/fields.js

@@ -107,6 +107,23 @@ export function parseCoarseDate(raw) {
     const month = MONTHS[match[1].slice(0, 3).toLowerCase()];
     return month ? `${match[2]}-${month}` : undefined;
 }
+/**
+ * A date one of these readers returned, as the moment a survey counts it at:
+ * an instant as itself, and a civil date (`2009`, `2022-08`, `2026-06-06`) at
+ * the start of its year, month, or day in local time. `new Date` would put a
+ * civil date at midnight UTC, which west of Greenwich is the day, month, or
+ * year before.
+ */
+export function occurrenceTime(value) {
+    if (!value)
+        return undefined;
+    const civil = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/.exec(value);
+    if (civil) {
+        return new Date(Number(civil[1]), Number(civil[2] ?? 1) - 1, Number(civil[3] ?? 1));
+    }
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}
 const MONTHS = {
     jan: '01',
     feb: '02',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/linkedin",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -22,9 +22,9 @@
   "type": "module",
   "description": "Chronicle plugin for the LinkedIn member data export archive",
   "devDependencies": {
-    "@chronicle.app/etl": "0.4.0",
-    "@chronicle.app/schema": "0.4.0",
-    "@chronicle.app/tsconfig": "0.4.0",
+    "@chronicle.app/etl": "0.5.0",
+    "@chronicle.app/schema": "0.5.0",
+    "@chronicle.app/tsconfig": "0.5.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   },
@@ -62,6 +62,14 @@
         "strategies": {
           "archive": {
             "delivery": "export",
+            "layouts": [
+              {
+                "files": [
+                  "Connections.csv",
+                  "Profile.csv"
+                ]
+              }
+            ],
             "recordTypes": [
               "connections",
               "education",