linkedin-member-data 0.1.0

data/doc/LinkedIn/MemberData/Event.md

@@ -0,0 +1,90 @@
+# Class LinkedIn::MemberData::Event <a id="class-LinkedIn-MemberData-Event"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/linkedin/member_data/event.rb |
+
+One Member Changelog event. Immutable. Times are UTC. `activity` and friends
+stay raw. Fields missing in the API response are `nil`.
+
+`method` is the API field (`CREATE`, `UPDATE`, ...). It shadows Ruby's
+`Object#method` on purpose, so `event.method(:name)` does not work on an
+Event.
+
+## Attributes
+### `activity` [R] <a id="attribute-i-activity"></a> <a id="activity-instance_method"></a>
+- **@return** [Hash, nil] raw activity payload.
+
+### `activity_id` [R] <a id="attribute-i-activity_id"></a> <a id="activity_id-instance_method"></a>
+- **@return** [String, nil] value as sent by the API.
+
+### `activity_status` [R] <a id="attribute-i-activity_status"></a> <a id="activity_status-instance_method"></a>
+- **@return** [String, nil] value as sent by the API.
+
+### `actor` [R] <a id="attribute-i-actor"></a> <a id="actor-instance_method"></a>
+- **@return** [String, nil] who did the action, as sent by the API.
+
+### `captured_at` [R] <a id="attribute-i-captured_at"></a> <a id="captured_at-instance_method"></a>
+- **@return** [Time, nil] when LinkedIn captured the event. UTC.
+
+### `config_version` [R] <a id="attribute-i-config_version"></a> <a id="config_version-instance_method"></a>
+- **@return** [Object, nil] value as sent by the API.
+
+### `id` [R] <a id="attribute-i-id"></a> <a id="id-instance_method"></a>
+- **@return** [String, nil] event id. Used to skip events seen on the previous page.
+
+### `method` [R] <a id="attribute-i-method"></a> <a id="method-instance_method"></a>
+- **@return** [String, nil] API method, for example `CREATE` or `UPDATE`.
+
+### `method_name` [R] <a id="attribute-i-method_name"></a> <a id="method_name-instance_method"></a>
+- **@return** [String, nil] value as sent by the API.
+
+### `owner` [R] <a id="attribute-i-owner"></a> <a id="owner-instance_method"></a>
+- **@return** [String, nil] owner of the event, as sent by the API.
+
+### `parent_sibling_activities` [R] <a id="attribute-i-parent_sibling_activities"></a> <a id="parent_sibling_activities-instance_method"></a>
+- **@return** [Array<Hash>, nil] raw parent sibling activities.
+
+### `processed_activity` [R] <a id="attribute-i-processed_activity"></a> <a id="processed_activity-instance_method"></a>
+- **@return** [Hash, nil] raw processed activity payload.
+
+### `processed_at` [R] <a id="attribute-i-processed_at"></a> <a id="processed_at-instance_method"></a>
+- **@return** [Time, nil] when LinkedIn processed the event. UTC. Used as the cursor.
+
+### `raw` [R] <a id="attribute-i-raw"></a> <a id="raw-instance_method"></a>
+- **@return** [Hash] the original event Hash from the API.
+
+### `resource_id` [R] <a id="attribute-i-resource_id"></a> <a id="resource_id-instance_method"></a>
+- **@return** [String, nil] value as sent by the API.
+
+### `resource_name` [R] <a id="attribute-i-resource_name"></a> <a id="resource_name-instance_method"></a>
+- **@return** [String, nil] kind of resource that changed.
+
+### `resource_uri` [R] <a id="attribute-i-resource_uri"></a> <a id="resource_uri-instance_method"></a>
+- **@return** [String, nil] value as sent by the API.
+
+### `sibling_activities` [R] <a id="attribute-i-sibling_activities"></a> <a id="sibling_activities-instance_method"></a>
+- **@return** [Array<Hash>, nil] raw sibling activities.
+
+## Public Class Methods
+### `from_api(hash)` <a id="method-c-from_api"></a> <a id="from_api-class_method"></a>
+Builds an event from one element of the API response.
+- **@param** `hash` [Hash] one element of `elements` from the changelog response.
+- **@return** [Event]
+
+**@example**
+```ruby
+event = LinkedIn::MemberData::Event.from_api(
+  "id" => "1", "method" => "CREATE", "processedAt" => 1_788_000_000_000
+)
+event.method        # => "CREATE"
+event.processed_at  # => 2026-08-29 10:40:00 UTC
+event.processed_at_ms # => 1788000000000
+```
+
+## Public Instance Methods
+### `processed_at_ms()` <a id="method-i-processed_at_ms"></a> <a id="processed_at_ms-instance_method"></a>
+Raw epoch milliseconds, used as the next `startTime` cursor. Pass it as
+<code>since:</code> to `Client#changelog` to resume.
+- **@return** [Integer, nil] `nil` when the event has no `processedAt`.

data/doc/LinkedIn/MemberData/Forbidden.md

@@ -0,0 +1,8 @@
+# Class LinkedIn::MemberData::Forbidden <a id="class-LinkedIn-MemberData-Forbidden"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [LinkedIn::MemberData::ApiError](ApiError.md) |
+| **Defined in** | lib/linkedin/member_data/errors.rb |
+
+HTTP 403. The token is not allowed to read this data.

data/doc/LinkedIn/MemberData/NotFound.md

@@ -0,0 +1,8 @@
+# Class LinkedIn::MemberData::NotFound <a id="class-LinkedIn-MemberData-NotFound"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [LinkedIn::MemberData::ApiError](ApiError.md) |
+| **Defined in** | lib/linkedin/member_data/errors.rb |
+
+HTTP 404. For snapshots it can mean "No data found for this memberId".

data/doc/LinkedIn/MemberData/RateLimited.md

@@ -0,0 +1,25 @@
+# Class LinkedIn::MemberData::RateLimited <a id="class-LinkedIn-MemberData-RateLimited"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [LinkedIn::MemberData::ApiError](ApiError.md) |
+| **Defined in** | lib/linkedin/member_data/errors.rb |
+
+HTTP 429. Retryable.
+
+## Attributes
+### `retry_after` [R] <a id="attribute-i-retry_after"></a> <a id="retry_after-instance_method"></a>
+Seconds to wait, from the <code>Retry-After</code> header.
+- **@return** [Integer, nil] `nil` when the header is absent, is not a positive number, or is an HTTP date.
+
+## Public Instance Methods
+### `initialize(message, status:, code: = nil, body: = nil, retry_after: = nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@param** `message` [String] error message.
+- **@param** `status` [Integer] HTTP status code.
+- **@param** `code` [Integer, String, nil] error code from the body.
+- **@param** `body` [Hash, nil] parsed response body.
+- **@param** `retry_after` [Integer, nil] seconds from the `Retry-After` header.
+- **@return** [RateLimited] a new instance of RateLimited
+
+### `retryable?()` <a id="method-i-retryable-3F"></a> <a id="retryable?-instance_method"></a>
+- **@return** [true] a rate limit is worth a retry.

data/doc/LinkedIn/MemberData/ServerError.md

@@ -0,0 +1,12 @@
+# Class LinkedIn::MemberData::ServerError <a id="class-LinkedIn-MemberData-ServerError"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [LinkedIn::MemberData::ApiError](ApiError.md) |
+| **Defined in** | lib/linkedin/member_data/errors.rb |
+
+HTTP 5xx. Retryable.
+
+## Public Instance Methods
+### `retryable?()` <a id="method-i-retryable-3F"></a> <a id="retryable?-instance_method"></a>
+- **@return** [true] server errors are worth a retry.

data/doc/LinkedIn/MemberData/Snapshot/Page.md

@@ -0,0 +1,43 @@
+# Class LinkedIn::MemberData::Snapshot::Page <a id="class-LinkedIn-MemberData-Snapshot-Page"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/linkedin/member_data/snapshot/page.rb |
+
+One response page of snapshot data. Immutable.
+
+## Attributes
+### `count` [R] <a id="attribute-i-count"></a> <a id="count-instance_method"></a>
+- **@return** [Integer, nil] page size from the `paging` object.
+
+### `domain` [R] <a id="attribute-i-domain"></a> <a id="domain-instance_method"></a>
+- **@return** [String, nil] `snapshotDomain` of the first element. An all-domains call may return several.
+
+### `has_next` [R] <a id="attribute-i-has_next"></a> <a id="has_next-instance_method"></a>
+- **@return** [Boolean] true when `paging.links` has a link with rel `next`.
+
+### `raw` [R] <a id="attribute-i-raw"></a> <a id="raw-instance_method"></a>
+- **@return** [Hash] the parsed response body.
+
+### `rows` [R] <a id="attribute-i-rows"></a> <a id="rows-instance_method"></a>
+- **@return** [Array<Hash{String => Object}>] rows of every element on this page. Keys differ per domain.
+
+### `start` [R] <a id="attribute-i-start"></a> <a id="start-instance_method"></a>
+- **@return** [Integer, nil] page index from the `paging` object.
+
+### `total` [R] <a id="attribute-i-total"></a> <a id="total-instance_method"></a>
+- **@return** [Integer, nil] total number of items from the `paging` object.
+
+## Public Class Methods
+### `from_api(raw)` <a id="method-c-from_api"></a> <a id="from_api-class_method"></a>
+Builds a page from a parsed response body. Missing keys give empty or nil
+values.
+- **@param** `raw` [Hash] parsed JSON body of the API response.
+- **@return** [Snapshot::Page]
+
+## Public Instance Methods
+### `next?()` <a id="method-i-next-3F"></a> <a id="next?-instance_method"></a>
+Tells if another page may follow. Same value as <code>#has_next</code>. The
+last page can still carry a `next` link, so an empty next page is possible.
+- **@return** [Boolean]

data/doc/LinkedIn/MemberData/Snapshot.md

@@ -0,0 +1,90 @@
+# Class LinkedIn::MemberData::Snapshot <a id="class-LinkedIn-MemberData-Snapshot"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Includes** | Enumerable |
+| **Defined in** | lib/linkedin/member_data/snapshot.rb, lib/linkedin/member_data/snapshot/page.rb |
+
+Lazy view over `GET /rest/memberSnapshotData` for one domain (or all). Nothing
+is fetched until you iterate. Each iteration starts a new walk from the first
+page.
+
+Pages are indexed by `start` (0, 1, 2, ...). The API says to keep going until
+it answers "No data found for this memberId", so that error ends iteration
+instead of raising. A page with no rows also ends iteration.
+
+It includes `Enumerable`, so `first`, `to_a`, `lazy`, `select` and the rest
+work on rows. `first` fetches one page only.
+
+**@example Walk all rows of one domain**
+```ruby
+snapshot = client.snapshot(:connections)
+snapshot.each { |row| puts row["First Name"] }
+snapshot.first                                       # fetches one page
+snapshot.lazy.select { |row| row["Company"] }.first(5)
+```
+
+## Constants
+### `NO_DATA_MESSAGE` <a id="constant-NO_DATA_MESSAGE"></a> <a id="NO_DATA_MESSAGE-constant"></a>
+Text of the API error that means "no more data". It ends iteration.
+- **@return** [String]
+
+### `PATH` <a id="constant-PATH"></a> <a id="PATH-constant"></a>
+API path of the snapshot resource.
+- **@return** [String]
+
+## Attributes
+### `domain` [R] <a id="attribute-i-domain"></a> <a id="domain-instance_method"></a>
+The domain name sent to the API. `nil` means all domains.
+- **@return** [String, nil]
+
+## Public Instance Methods
+### `each(&block)` <a id="method-i-each"></a> <a id="each-instance_method"></a>
+Yields every row of every page. Pages are fetched one by one while you
+iterate. Rows are plain Hashes with the keys LinkedIn returns. Keys differ per
+domain.
+- **@raise** [ApiError] on a non-2xx response, except the "No data found" answer.
+- **@raise** [ConnectionError] on a network failure after all retries.
+- **@return** [Snapshot] self, when a block is given.
+- **@return** [Enumerator<Hash>] when no block is given.
+- **@yieldparam** `row` [Hash{String => Object}] one row of snapshot data.
+
+**@example Block form**
+```ruby
+client.snapshot(:connections).each { |row| puts row["First Name"] }
+```
+
+**@example Without a block, you get an Enumerator**
+```ruby
+client.snapshot(:connections).each.first(3)
+```
+
+### `page(start)` <a id="method-i-page"></a> <a id="page-instance_method"></a>
+Fetches one page by index. Does not walk. Does not hide the "No data found"
+error.
+- **@param** `start` [Integer] zero-based page index.
+- **@raise** [NotFound] past the end of the data.
+- **@raise** [ApiError] on any other non-2xx response.
+- **@raise** [ConnectionError] on a network failure after all retries.
+- **@return** [Snapshot::Page]
+
+**@example**
+```ruby
+client.snapshot(:profile).page(0).rows
+```
+
+### `pages()` <a id="method-i-pages"></a> <a id="pages-instance_method"></a>
+Lazy Enumerator of pages. The walk stops at the first page without a `next`
+link. It also stops at an empty page or at the "No data found" answer. Any
+other API error raises.
+- **@raise** [ApiError] while iterating, on a non-2xx response except "No data found".
+- **@raise** [ConnectionError] while iterating, on a network failure after all retries.
+- **@return** [Enumerator<Snapshot::Page>]
+
+**@example Inspect paging data**
+```ruby
+client.snapshot(:profile).pages.each do |page|
+  puts "#{page.domain}: #{page.rows.size} rows, total #{page.total}"
+end
+```

data/doc/LinkedIn/MemberData/Unauthorized.md

@@ -0,0 +1,8 @@
+# Class LinkedIn::MemberData::Unauthorized <a id="class-LinkedIn-MemberData-Unauthorized"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [LinkedIn::MemberData::ApiError](ApiError.md) |
+| **Defined in** | lib/linkedin/member_data/errors.rb |
+
+HTTP 401. The token is invalid or expired.

data/doc/LinkedIn/MemberData/VersionError.md

@@ -0,0 +1,8 @@
+# Class LinkedIn::MemberData::VersionError <a id="class-LinkedIn-MemberData-VersionError"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [LinkedIn::MemberData::ApiError](ApiError.md) |
+| **Defined in** | lib/linkedin/member_data/errors.rb |
+
+HTTP 426. The API version sent by the gem is not supported.

data/doc/LinkedIn/MemberData.md

@@ -0,0 +1,44 @@
+# Module LinkedIn::MemberData <a id="module-LinkedIn-MemberData"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/linkedin/member_data/version.rb, lib/linkedin/member_data/cli.rb, lib/linkedin/member_data/util.rb, lib/linkedin/member_data/event.rb, lib/linkedin/member_data/client.rb, lib/linkedin/member_data/errors.rb, lib/linkedin/member_data/domains.rb, lib/linkedin/member_data/snapshot.rb, lib/linkedin/member_data/changelog.rb, lib/linkedin/member_data/connection.rb, lib/linkedin/member_data/cli/command.rb, lib/linkedin/member_data/cli/support.rb, lib/linkedin/member_data/authorization.rb, lib/linkedin/member_data/snapshot/page.rb, lib/linkedin/member_data/changelog/page.rb, lib/linkedin/member_data/cli/since_parser.rb, lib/linkedin/member_data/cli/global_options.rb, lib/linkedin/member_data/cli/simple_commands.rb, lib/linkedin/member_data/cli/snapshot_command.rb, lib/linkedin/member_data/cli/changelog_command.rb |
+
+Ruby client and CLI for the LinkedIn Member Data Portability (Member) API.
+Start with `Client`.
+
+**@example**
+```ruby
+client = LinkedIn::MemberData::Client.new(access_token: ENV["LINKEDIN_ACCESS_TOKEN"])
+client.snapshot(:connections).each { |row| puts row["First Name"] }
+```
+
+## Constants
+### `EVENT_KEYS` <a id="constant-EVENT_KEYS"></a> <a id="EVENT_KEYS-constant"></a>
+Data member name => JSON key. Time fields are handled separately.
+- **@api** private
+
+### `VERSION` <a id="constant-VERSION"></a> <a id="VERSION-constant"></a>
+Gem version.
+- **@return** [String]
+
+# Documentation
+
+- [MemberData/ApiError.md](MemberData/ApiError.md)
+- [MemberData/Authorization.md](MemberData/Authorization.md)
+- [MemberData/Changelog/Page.md](MemberData/Changelog/Page.md)
+- [MemberData/Changelog.md](MemberData/Changelog.md)
+- [MemberData/Client.md](MemberData/Client.md)
+- [MemberData/ConfigurationError.md](MemberData/ConfigurationError.md)
+- [MemberData/ConnectionError.md](MemberData/ConnectionError.md)
+- [MemberData/Domains.md](MemberData/Domains.md)
+- [MemberData/Error.md](MemberData/Error.md)
+- [MemberData/Event.md](MemberData/Event.md)
+- [MemberData/Forbidden.md](MemberData/Forbidden.md)
+- [MemberData/NotFound.md](MemberData/NotFound.md)
+- [MemberData/RateLimited.md](MemberData/RateLimited.md)
+- [MemberData/ServerError.md](MemberData/ServerError.md)
+- [MemberData/Snapshot/Page.md](MemberData/Snapshot/Page.md)
+- [MemberData/Snapshot.md](MemberData/Snapshot.md)
+- [MemberData/Unauthorized.md](MemberData/Unauthorized.md)
+- [MemberData/VersionError.md](MemberData/VersionError.md)

data/doc/LinkedIn.md

@@ -0,0 +1,7 @@
+# Module LinkedIn <a id="module-LinkedIn"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/linkedin/member_data/version.rb, lib/linkedin/member_data/cli.rb, lib/linkedin/member_data/util.rb, lib/linkedin/member_data/event.rb, lib/linkedin/member_data/client.rb, lib/linkedin/member_data/errors.rb, lib/linkedin/member_data/domains.rb, lib/linkedin/member_data/snapshot.rb, lib/linkedin/member_data/changelog.rb, lib/linkedin/member_data/connection.rb, lib/linkedin/member_data/cli/command.rb, lib/linkedin/member_data/cli/support.rb, lib/linkedin/member_data/authorization.rb, lib/linkedin/member_data/snapshot/page.rb, lib/linkedin/member_data/changelog/page.rb, lib/linkedin/member_data/cli/since_parser.rb, lib/linkedin/member_data/cli/global_options.rb, lib/linkedin/member_data/cli/simple_commands.rb, lib/linkedin/member_data/cli/snapshot_command.rb, lib/linkedin/member_data/cli/changelog_command.rb |
+
+Namespace of the LinkedIn gems.

data/doc/README.md

@@ -0,0 +1,186 @@
+# linkedin-member-data
+
+Ruby client and CLI for the LinkedIn [Member Data Portability (Member) API](https://learn.microsoft.com/en-us/linkedin/dma/member-data-portability/member-data-portability-member/). Download your own LinkedIn data: 66 snapshot domains (profile, connections, messages, posts, ...) and the changelog of your activity from the last 28 days.
+
+Zero runtime dependencies. Ruby 3.2+.
+
+## Installation
+
+```bash
+bundle add linkedin-member-data
+```
+
+Or install the CLI only:
+
+```bash
+gem install linkedin-member-data
+```
+
+## Getting a token
+
+1. Create an app in the [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps/) using the [Member Data Portability (Member) Default Company](https://www.linkedin.com/company/member-data-portability-member-default-company) page.
+2. Under Products, request access to **Member Data Portability API (Member)**.
+3. Open **Docs and tools > OAuth Token Tools**, create a token with scope `r_dma_portability_self_serve`, and consent.
+
+Tokens last 60 days. Only EEA and Swiss members can consent today.
+
+## Quick start
+
+```ruby
+require "linkedin/member_data"
+
+client = LinkedIn::MemberData::Client.new(access_token: ENV["LINKEDIN_ACCESS_TOKEN"])
+
+client.snapshot(:connections).each do |row|
+  puts row["First Name"], row["Company"]
+end
+
+client.changelog(since: Time.now - 7 * 86_400).each do |event|
+  puts "#{event.method} #{event.resource_name} at #{event.processed_at}"
+end
+```
+
+Row keys differ per domain. These are CONNECTIONS keys.
+
+## Snapshot
+
+```ruby
+snap = client.snapshot(:profile)       # symbol is upcased: "PROFILE"
+snap = client.snapshot("ALL_COMMENTS") # strings are sent as given
+snap = client.snapshot                 # all domains
+
+snap.first                             # first row, fetches one page
+snap.to_a                              # every row, walks all pages
+snap.lazy.select { |row| row["Company"] }.first(5)  # Enumerable, so anything goes
+
+snap.pages.each do |page|
+  page.domain; page.rows; page.start; page.count; page.total; page.next?; page.raw
+end
+
+snap.page(0)                           # one page by index, no walking. Raises past the end.
+
+LinkedIn::MemberData::Domains::ALL     # list of domain names
+```
+
+Rows are plain Hashes with the keys LinkedIn returns, for example `"First Name"`. Keys differ per domain.
+
+Pages are walked until LinkedIn answers "No data found for this memberId". That answer ends iteration and is not raised. A page with no rows also ends iteration.
+
+## Changelog
+
+```ruby
+log = client.changelog(since: Date.new(2026, 9, 1), count: 10)   # since: Time, Date or epoch ms; count: 1..50
+
+log.each do |event|
+  event.id; event.method; event.resource_name; event.resource_id
+  event.captured_at; event.processed_at        # Time (UTC)
+  event.activity; event.processed_activity     # Hash
+  event.raw                                    # the original Hash
+end
+
+log.pages.each { |page| page.events; page.next_start_time }
+```
+
+The API returns the cursor event again on the next page. The gem skips events it has already seen. Iteration stops when a page has no new events, or when the last event has no `processedAt`.
+
+`event.method` is the API field (`CREATE`, `UPDATE`, ...). It shadows Ruby's `Object#method` on purpose, so `event.method(:name)` does not work on an Event.
+
+`count` defaults to 10. A value outside 1..50 raises `ArgumentError` before any request.
+
+Event fields: `id, activity_id, activity_status, config_version, owner, actor, resource_name, resource_id, resource_uri, method, method_name, captured_at, processed_at, activity, processed_activity, sibling_activities, parent_sibling_activities, raw`.
+
+Known limit: when more than `count` events share one `processedAt`, the cursor cannot reach the rest. Raise `count` (max 50) to reduce the chance.
+
+To resume later, store the last `event.processed_at_ms` and pass it as `since:`.
+
+```ruby
+last_seen = client.changelog.to_a.last&.processed_at_ms
+client.changelog(since: last_seen).each { |event| puts event.id }
+```
+
+## Authorization
+
+```ruby
+client.authorization        # => Authorization or nil
+client.authorization.regulated_at
+client.enable_changelog!    # start changelog archiving (usually automatic)
+```
+
+`Authorization` also has `member`, `developer_application`, `scopes` and `raw`.
+
+## Options
+
+```ruby
+require "logger"
+
+LinkedIn::MemberData::Client.new(
+  access_token: "...",
+  retries: 3,       # retries on 429, 5xx and network errors, with backoff; 0 disables
+  timeout: 30,      # seconds
+  logger: Logger.new($stderr)  # logs "GET url -> status" at debug level
+)
+```
+
+Retries wait for `Retry-After` when it is present, capped at 60 seconds. Otherwise the wait grows with each try (exponential backoff).
+
+## Errors
+
+```
+LinkedIn::MemberData::Error
+  ConfigurationError           # missing token
+  ConnectionError              # network failure after retries
+  ApiError                     # status, code, body
+    Unauthorized Forbidden NotFound VersionError RateLimited ServerError
+```
+
+`ConnectionError` covers timeouts, reset connections, DNS and TLS failures. `retryable?` is true for `RateLimited`, `ServerError` and `ConnectionError`. `ApiError#code` comes from `serviceErrorCode` or `code` in the response body. `RateLimited#retry_after` is nil when the header is absent.
+
+```ruby
+begin
+  client.snapshot(:profile).to_a
+rescue LinkedIn::MemberData::Unauthorized
+  warn "Token is invalid or expired"
+rescue LinkedIn::MemberData::ApiError => error
+  warn "#{error.status}: #{error.message}"
+end
+```
+
+## CLI
+
+```bash
+export LINKEDIN_ACCESS_TOKEN=...
+
+linkedin-member-data snapshot CONNECTIONS --out connections.json
+linkedin-member-data snapshot --all --out-dir ./export
+linkedin-member-data changelog --since 2026-09-01 --count 50 --out changelog.json
+linkedin-member-data domains
+linkedin-member-data auth
+linkedin-member-data version
+```
+
+Use `-h` or `--help` to print usage. The DOMAIN argument is upcased, so `snapshot connections` works. The token comes from `--token TOKEN` (before or after the command) or `LINKEDIN_ACCESS_TOKEN`. Data goes to stdout or `--out FILE`. Progress and errors go to stderr. `--since` takes an ISO date (midnight UTC) or an ISO datetime.
+
+`snapshot --all` writes one `<DOMAIN>.json` per domain. Without `--out-dir DIR` it is a usage error (exit 2). A failing domain is reported and the run continues. The exit code is 1 at the end. Unauthorized and Forbidden stop the run, because a bad token fails every domain.
+
+`auth` exits 1 with "No authorization found for this token" when none exists.
+
+Exit codes: 0 success, 1 API error, network error or file write error, 2 usage error.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake               # tests + rubocop
+bundle exec rake branchproof   # MC/DC coverage (Ruby 4.0+)
+bundle exec rake quality       # quality_gate fast, verify, audit
+bundle exec rake docs          # YARD Markdown docs in doc/ and llms.txt
+ruby bin/prepare_release       # full gate, then builds pkg/<gem>.gem
+```
+
+## For AI agents
+
+The gem ships its API reference as Markdown. Start at `llms.txt` in the gem root, which links every page under `doc/`. The same files are inside the installed gem (`gem contents linkedin-member-data | grep doc/`).
+
+## License
+
+MIT

data/exe/linkedin-member-data

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "linkedin/member_data/cli"
+
+exit LinkedIn::MemberData::CLI.new(ARGV).run

data/lib/linkedin/member_data/authorization.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LinkedIn
+  module MemberData
+    # The member's authorization record from `memberAuthorizations`. Immutable.
+    #
+    # @!attribute [r] member
+    #   @return [String, nil] member, as sent by the API.
+    # @!attribute [r] developer_application
+    #   @return [String, nil] developer application, as sent by the API.
+    # @!attribute [r] regulated_at
+    #   @return [Time, nil] when the member gave consent. UTC.
+    # @!attribute [r] scopes
+    #   @return [Array<String>] granted scopes. Empty when the API sends none.
+    # @!attribute [r] raw
+    #   @return [Hash] the original element from the API.
+    Authorization = Data.define(:member, :developer_application, :regulated_at, :scopes, :raw) do
+      # Builds an authorization from one element of the API response.
+      #
+      # @param hash [Hash] one element of `elements` from the `memberAuthorizations` response.
+      # @return [Authorization]
+      def self.from_api(hash)
+        key = hash.fetch("memberComplianceAuthorizationKey", {})
+        new(member: key["member"], developer_application: key["developerApplication"],
+            regulated_at: Util.time_from_ms(hash["regulatedAt"]),
+            scopes: hash.fetch("memberComplianceScopes", []), raw: hash)
+      end
+    end
+  end
+end

data/lib/linkedin/member_data/changelog/page.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LinkedIn
+  module MemberData
+    class Changelog
+      # One response page of changelog events. Immutable.
+      #
+      # @!attribute [r] events
+      #   @return [Array<Event>] events of this page, in API order (oldest first).
+      # @!attribute [r] raw
+      #   @return [Hash] the parsed response body.
+      Page = Data.define(:events, :raw) do
+        # Builds a page from a parsed response body. A missing `elements` key gives no events.
+        #
+        # @param raw [Hash] parsed JSON body of the API response.
+        # @return [Changelog::Page]
+        def self.from_api(raw)
+          new(events: raw.fetch("elements", []).map { |element| Event.from_api(element) }, raw: raw)
+        end
+
+        # Cursor for the next request: `processedAt` of the last event, in epoch milliseconds.
+        #
+        # @return [Integer, nil] `nil` when the page has no events or the last event has no `processedAt`.
+        def next_start_time = events.last&.processed_at_ms
+      end
+    end
+  end
+end