@chronicle.app/linkedin 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,153 @@
+# 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.
+
+```bash
+chronicle extract linkedin --input ~/Downloads/Basic_LinkedInDataExport_08-08-2026 --limit 0
+chronicle extract linkedin --input <dir> --type messages --limit 5   # one record kind
+```
+
+`--limit 0` means no limit. The export is small enough to read end to end.
+
+## Why the export and not an API
+
+LinkedIn's only programmatic route to your own data is **Member Data
+Portability (Member)**, built for the EU Digital Markets Act: a Snapshot API
+for history and a Changelog API for live interactions. Only members located in
+the EEA or Switzerland can consent and mint a token. The ordinary LinkedIn API
+returns your name, photo and email — no posts, no activity. There is no RSS.
+
+Even where the API is open, its changelog only answers for the last 28 days and
+only from the moment you consent, so the export stays the only route to
+history.
+
+## Two archives
+
+LinkedIn builds two. The **fast** archive arrives in minutes with your profile,
+network, and messages — that is what this plugin was written against. The
+**full** archive takes up to a day and adds your activity: `Shares.csv`,
+`Comments.csv`, `Reactions.csv`. Those three are not read yet.
+
+Every extractor treats a missing file as an empty one, so a fast archive simply
+yields fewer record types than a full one.
+
+## What it reads
+
+| File                                    | `--type`       | Becomes                                            |
+| --------------------------------------- | -------------- | -------------------------------------------------- |
+| `messages.csv`                          | `messages`     | `MessageAction` → `Message`, `isPartOf` a `Thread` |
+| `Connections.csv`                       | `connections`  | `FollowAction` → `Person` (see below)              |
+| `Endorsement_{Given,Received}_Info.csv` | `endorsements` | `RespondAction` → `Response` about a `DefinedTerm` |
+| `Company Follows.csv`                   | `follows`      | `FollowAction` → `Organization`                    |
+| `Positions.csv`                         | `positions`    | `JoinAction`/`LeaveAction` over a `Tenure`         |
+| `Education.csv`                         | `education`    | `JoinAction`/`LeaveAction` over an `Enrollment`    |
+| `Learning.csv`                          | `learning`     | `WatchAction`, `CompleteAction`, `BookmarkAction`  |
+| `Profile.csv`, `Email Addresses.csv`    | `profile`      | `UpdateAction` → the self `Person`                 |
+
+A bare run merges all eight newest-first (`LinkedInDefaultExtractor`).
+
+## Identity
+
+**People key on the vanity slug** out of `/in/<slug>`. LinkedIn never puts a
+member's numeric id in an export, so this is the only identifier there is. It
+is user-changeable, which makes it imperfect — a member who renames their
+profile arrives in the next export as someone new — but the alternative is
+keying strangers on their display name. Each person also carries their profile
+URL, which mints the portable url-namespace identity that merges them with the
+same page seen from any other source.
+
+**You** come from `Profile.csv` for the name and headline and from
+`Email Addresses.csv` for the primary address, which rides as a `sameAs` in the
+`email` namespace — evidence that merges your LinkedIn self with the self your
+mail and messaging plugins already know.
+
+Your own **profile URL is not in `Profile.csv`**; LinkedIn omits it. It appears
+only in `Invitations.csv`, which carries both parties' URLs _and_ a `Direction`
+column — so an `OUTGOING` row states outright that the inviter is you. That is
+the source declaring it, not a name match. Failing that, pass `--profile-url`;
+failing that too, the self falls back to the per-source singleton. All three
+routes still merge onto one person through `@me`.
+
+**Organizations key on their name.** There is no company id anywhere in an
+export, so two different companies sharing a name will merge.
+
+**Messages have no id of their own.** LinkedIn ships the conversation id, the
+moment, the sender and the text. The `Thread` keys on that conversation id; a
+`Message` keys on the natural tuple. Two messages with identical text from one
+person in one thread therefore resolve to a single `Message` — though their
+sends stay distinct `MessageAction`s at their own timestamps.
+
+## Judgment calls worth knowing
+
+**A connection is recorded as a `FollowAction`, and that is not an exact fit.**
+A LinkedIn connection is mutual and consented; a follow is neither. What makes
+it defensible is that connecting does create a follow in both directions. Only
+your side is written — inventing the reciprocal edge would double every
+connection to say something the row never said. The ontology has no
+"connected with" verb; if one is ever added, this is what should move to it.
+
+**A message body is text, never markup.** A quarter of the messages in an
+export arrive as the LinkedIn editor's raw HTML — sponsored InMail and every
+templated notice. `htmlToText` from `@chronicle.app/etl` turns each back into
+what a reader saw: paragraphs
+and `<br>` become line breaks, list items become lines, entities are decoded,
+and `&nbsp;` becomes an ordinary space rather than an invisible U+00A0 that
+would make the words unfindable by search.
+
+A link keeps **both** its label and its URL, rendered `label (url)`. LinkedIn's
+anchors mostly read "here" or "Get started", so the label alone would say
+nothing about where it went. A tag is only recognized when its name is followed
+by whitespace, `/` or `>`, which is what keeps a bare `<https://example.com>` in
+a plain-text message from being deleted as markup — a tag name cannot contain a
+colon. A body with no tags is entity-decoded and otherwise left exactly as
+typed, because its line breaks are the sender's own.
+
+**Dates keep the precision LinkedIn wrote them at.** A position reads
+`2022-08`, an old one `2009`, a connection `2026-06-06`. The store parses each
+at its own precision, so widening them to a moment would be a lie.
+
+**Snapshot vs event is decided per file.** `Connections.csv` is a `snapshot`
+read even though every row carries a real "Connected On": the date is history,
+but their company and title are current, and back-dating those to a connection
+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
+identical assertions instead of minting fresh ones.
+
+## Not read, and why
+
+- **`Ad_Targeting.csv`** — LinkedIn's inferences _about_ you, not anything you
+  did. Interesting, but not history.
+- **`Skills.csv`** — a bare list with no dates. The schema has no predicate
+  attaching a skill to a person, and the endorsements already mint the skills
+  as `DefinedTerm`s with real dates behind them.
+- **`Invitations.csv`** — no verb for it, and an accepted invitation is already
+  recorded as the connection. It is read for the self-detection above.
+- **`Rich_Media.csv`** — profile photo uploads, behind signed `licdn.com` URLs
+  that expire.
+- **Message attachments** — signed `linkedin.com/dms/…` URLs carrying an expiry
+  and a per-export token. The link dies long before the archive is old, and an
+  entity keyed on it would mint a fresh identity every export. The bytes are
+  not in the ZIP.
+- **Free-text locations** (`Geo Location`, a position's `Location`) — a
+  name-keyed `Place` would collide with the geocoded places other plugins mint.
+- **The message folder** (`INBOX` / `ARCHIVE`) — no home for it that is not a
+  stretch.
+
+## Development
+
+```bash
+npm run build -w @chronicle.app/linkedin
+npm test -w @chronicle.app/linkedin
+```
+
+Tests write a small synthetic export to a temporary directory. It reproduces
+the awkward parts of a real one: the `Notes:` preamble above
+`Connections.csv`'s header, a connection LinkedIn withheld entirely, a group
+thread whose name list is longer than its URL list, an HTML message body, and
+`N/A` where a date should be. The tests pass the export directory explicitly,
+so they never read the host's LinkedIn data or any account.

package/dist/connectors/LinkedInTransformer.d.ts

@@ -0,0 +1,147 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { BaseAndChildren } from '@chronicle.app/schema';
+/**
+ * The one transformer for every file in the export.
+ *
+ * Two decisions run through all of it:
+ *
+ * **People key on the vanity slug.** LinkedIn never puts a member's numeric id
+ * in an export, so `/in/<slug>` is the only identifier there is. It is
+ * user-changeable, which makes it an imperfect key — but it is a real one, and
+ * the alternative is keying strangers on their display name. Each person also
+ * carries their profile URL, which mints the portable url-namespace identity
+ * that merges them with the same page seen from anywhere else.
+ *
+ * **Only what LinkedIn wrote gets written.** Where the export has no id, the
+ * key is built from the natural fields LinkedIn did provide (an organization's
+ * name, a conversation's id, a skill's name) — never from a value invented
+ * here.
+ */
+export default class LinkedInTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<BaseAndChildren[]>;
+    /**
+     * Your own profile, carried by the `UpdateAction` that sighted it.
+     *
+     * The store takes actions, not loose entities, so a standing fact needs an
+     * occurrence to arrive on — the same carrier the Obsidian plugin uses for a
+     * note's subject. Its timestamp is when LinkedIn compiled the export, which
+     * is genuinely when the profile read this way, so a second import of the same
+     * directory restates the identical sighting rather than adding a new one.
+     *
+     * Everything here also rides every other record as the acting agent, so this
+     * matters most for the export that has nothing else in it.
+     */
+    private buildProfile;
+    /**
+     * A job as a `JoinAction`/`LeaveAction` pair over the employer, carrying a
+     * `Tenure` as their shared result. The pair is what the fold turns into a
+     * `memberOf` run across the span; the employer is the boundary's object,
+     * never a property on the tenure.
+     *
+     * The boundaries key on the tenure and the employer, never on the date. A
+     * position whose start month you fix in a later export then revises the run
+     * you already have, instead of appearing beside it as a second job.
+     */
+    private buildPosition;
+    /** Schooling, in the same shape as a job: two boundaries around an `Enrollment`. */
+    private buildEducation;
+    /** The opener, plus the closer when the span has actually ended. */
+    private episode;
+    /**
+     * A connection, as a dated `FollowAction` onto the other person.
+     *
+     * **This is the closest verb the ontology has, and it is not an exact fit.**
+     * A LinkedIn connection is mutual and consented; a follow is neither. What
+     * makes it defensible is that connecting on LinkedIn *does* create a follow,
+     * in both directions — so the edge recorded here is real, just not the whole
+     * of what happened. Only your side is written: this is your archive, and
+     * inventing the reciprocal edge would double every connection on the timeline
+     * to say something the row never said.
+     */
+    private buildConnection;
+    /**
+     * Following an organization — the one place `FollowAction` means exactly what
+     * it says. LinkedIn files topic pages ("Scrum", "Web Development") in the
+     * same list as real employers and gives none of them an id, so the name is
+     * both the label and the key.
+     */
+    private buildFollow;
+    /**
+     * An endorsement: one person vouching that another has a skill.
+     *
+     * `RespondAction` is the schema's verb for a reaction that carries a payload
+     * — the endorsement's payload being *which* skill — so the skill rides the
+     * result `Response` as its body and its `about`, and the action itself points
+     * at the person. A plain `LikeAction` would lose the skill, which is the only
+     * interesting part.
+     *
+     * The response keys through `action.*` onto both parties. Without that, one
+     * endorser vouching for the same skill for two different people would collapse
+     * into a single response shared by both endorsements.
+     */
+    private buildEndorsement;
+    /**
+     * One message, in the conversation LinkedIn assigned it to.
+     *
+     * The `Thread` is the only thing in the whole export with a first-class id, so
+     * it keys on that id and the messages hang off it with `isPartOf`.
+     *
+     * **Individual messages have no id.** LinkedIn ships the conversation, the
+     * moment, the sender, and the text — nothing more — so the message keys on
+     * that natural tuple and the action keys on the same. The cost is visible and
+     * accepted: two messages with identical text from one person in one thread
+     * resolve to a single `Message`, though their sends stay two distinct
+     * `MessageAction`s at their own timestamps.
+     */
+    private buildMessage;
+    /**
+     * A course, and whichever of the three things the row records about it: you
+     * watched it, you finished it, you saved it. LinkedIn gives courses no id, so
+     * the title is the key — it is what the export identifies them by.
+     *
+     * The saved flag has no date of its own. The bookmark is emitted undated
+     * rather than borrowed from the watch, which happened at a different moment.
+     */
+    private buildLearning;
+    /**
+     * The account owner.
+     *
+     * The handle comes from the export when it names one — see the extractor's
+     * note on reading it off an outgoing invitation — and otherwise the self falls
+     * back to `selfAgent`'s per-source singleton. Either way `@me` merges it onto
+     * the one person, and the primary email rides as a `sameAs` in the `email`
+     * namespace, where the mail and messaging plugins already key their people. A
+     * shared email is evidence of one person; a shared display name is not.
+     */
+    private self;
+    /**
+     * Another member. Returns nothing when LinkedIn identified them neither by
+     * slug nor by name — a row about nobody in particular is not a person.
+     *
+     * With a slug, the key is that slug and the profile URL comes along, which
+     * also mints the url-namespace identity every other source can meet them at.
+     * Without one, the display name is all that is left; it is a weak key and two
+     * namesakes will merge, but dropping the row entirely would lose a real
+     * relationship over a missing field.
+     */
+    private person;
+    /**
+     * A message party, which is a person LinkedIn may have declined to name.
+     *
+     * You are a party to every message in your own export, so a party whose slug
+     * is your own resolves to the self node rather than to a stranger who happens
+     * to share your key. Both spellings key identically and would merge anyway;
+     * this way the `@me` edge is on the node from the start, so messages alone
+     * are enough to place you even if the profile record never runs.
+     */
+    private party;
+    /**
+     * An organization, keyed on its name. LinkedIn puts no company id anywhere in
+     * an export — not in the positions, not in the follows — so the name is the
+     * only identifier available, and two different companies sharing a name will
+     * merge. Recorded here rather than worked around: the alternative is a
+     * fabricated id, which would be worse and less honest.
+     */
+    private organization;
+}
+//# sourceMappingURL=LinkedInTransformer.d.ts.map