linkedin-member-data 0.1.0

data/lib/linkedin/member_data/snapshot.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "snapshot/page"
+
+module LinkedIn
+  module MemberData
+    # 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
+    #   snapshot = client.snapshot(:connections)
+    #   snapshot.each { |row| puts row["First Name"] }
+    #   snapshot.first                                       # fetches one page
+    #   snapshot.lazy.select { |row| row["Company"] }.first(5)
+    class Snapshot
+      include Enumerable
+
+      # API path of the snapshot resource.
+      # @return [String]
+      PATH = "/rest/memberSnapshotData"
+
+      # Text of the API error that means "no more data". It ends iteration.
+      # @return [String]
+      NO_DATA_MESSAGE = "No data found for this memberId"
+
+      # The domain name sent to the API. `nil` means all domains.
+      # @return [String, nil]
+      attr_reader :domain
+
+      # @api private
+      # @param connection [Connection] used for every request.
+      # @param domain [String, nil] domain name as sent to the API. `nil` means all domains.
+      def initialize(connection, domain)
+        @connection = connection
+        @domain = domain
+      end
+
+      # 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.
+      #
+      # @example Block form
+      #   client.snapshot(:connections).each { |row| puts row["First Name"] }
+      # @example Without a block, you get an Enumerator
+      #   client.snapshot(:connections).each.first(3)
+      # @yieldparam row [Hash{String => Object}] one row of snapshot data.
+      # @return [Snapshot] self, when a block is given.
+      # @return [Enumerator<Hash>] when no block is given.
+      # @raise [ApiError] on a non-2xx response, except the "No data found" answer.
+      # @raise [ConnectionError] on a network failure after all retries.
+      def each(&block)
+        return enum_for(:each) unless block
+
+        pages.each { |page| page.rows.each(&block) }
+        self
+      end
+
+      # 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.
+      #
+      # @example Inspect paging data
+      #   client.snapshot(:profile).pages.each do |page|
+      #     puts "#{page.domain}: #{page.rows.size} rows, total #{page.total}"
+      #   end
+      # @return [Enumerator<Snapshot::Page>]
+      # @raise [ApiError] while iterating, on a non-2xx response except "No data found".
+      # @raise [ConnectionError] while iterating, on a network failure after all retries.
+      def pages = Enumerator.new { |yielder| each_page(yielder) }
+
+      # Fetches one page by index. Does not walk. Does not hide the "No data found" error.
+      #
+      # @example
+      #   client.snapshot(:profile).page(0).rows
+      # @param start [Integer] zero-based page index.
+      # @return [Snapshot::Page]
+      # @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.
+      def page(start)
+        Page.from_api(@connection.get(PATH, q: "criteria", start: start, domain: domain))
+      end
+
+      private
+
+      def each_page(yielder)
+        (0..).each do |start|
+          page = usable_page(start)
+          yielder << page unless page.nil?
+          break unless page&.next?
+        end
+      end
+
+      # nil ends the walk. An empty page counts as the end even with a next
+      # link, because `next` links can appear on the last page.
+      def usable_page(start)
+        page_or_nil(start)&.then { |page| page unless page.rows.empty? }
+      end
+
+      def page_or_nil(start)
+        page(start)
+      rescue ApiError => error
+        raise unless error.message.include?(NO_DATA_MESSAGE)
+
+        nil
+      end
+    end
+  end
+end

data/lib/linkedin/member_data/util.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "date"
+
+module LinkedIn
+  module MemberData
+    # Conversions between epoch milliseconds (LinkedIn wire format) and Time.
+    # @api private
+    module Util
+      module_function
+
+      # Converts epoch milliseconds to a UTC Time. Keeps sub-second precision.
+      #
+      # @param milliseconds [Integer, nil] epoch milliseconds.
+      # @return [Time, nil] UTC Time, or `nil` when `milliseconds` is `nil`.
+      def time_from_ms(milliseconds)
+        return nil if milliseconds.nil?
+
+        Time.at(Rational(milliseconds, 1000)).utc
+      end
+
+      # Converts a Time, Date or Integer to epoch milliseconds. Rounds down.
+      #
+      # @example
+      #   LinkedIn::MemberData::Util.epoch_ms(Time.utc(2026, 9, 1))  # => 1788220800000
+      #   LinkedIn::MemberData::Util.epoch_ms(Date.new(2026, 9, 1))  # => 1788220800000 (midnight UTC)
+      #   LinkedIn::MemberData::Util.epoch_ms(1_788_220_800_000)     # => 1788220800000
+      #   LinkedIn::MemberData::Util.epoch_ms(nil)                   # => nil
+      # @param value [Time, Date, Integer, nil] an Integer is taken as epoch milliseconds.
+      #   A Date counts as midnight UTC.
+      # @return [Integer, nil] epoch milliseconds, or `nil` when `value` is `nil`.
+      # @raise [ArgumentError] when `value` is any other type.
+      def epoch_ms(value)
+        case value
+        when nil, Integer then value
+        when Time, Date then (to_time(value).to_r * 1000).floor
+        else raise ArgumentError, "expected Time, Date or Integer epoch milliseconds, got #{value.class}"
+        end
+      end
+
+      # A Date counts as midnight UTC.
+      def to_time(value)
+        case value
+        when DateTime then value.to_time
+        when Date then Time.utc(value.year, value.month, value.day)
+        else value
+        end
+      end
+      private_class_method :to_time
+    end
+  end
+end

data/lib/linkedin/member_data/version.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Namespace of the LinkedIn gems.
+module LinkedIn
+  # Ruby client and CLI for the LinkedIn Member Data Portability (Member) API.
+  # Start with `Client`.
+  #
+  # @example
+  #   client = LinkedIn::MemberData::Client.new(access_token: ENV["LINKEDIN_ACCESS_TOKEN"])
+  #   client.snapshot(:connections).each { |row| puts row["First Name"] }
+  module MemberData
+    # Gem version.
+    # @return [String]
+    VERSION = "0.1.0"
+  end
+end

data/lib/linkedin/member_data.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "member_data/version"
+require_relative "member_data/errors"
+require_relative "member_data/util"
+require_relative "member_data/domains"
+require_relative "member_data/connection"
+require_relative "member_data/authorization"
+require_relative "member_data/event"
+require_relative "member_data/snapshot"
+require_relative "member_data/changelog"
+require_relative "member_data/client"

data/llms.txt

@@ -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](doc/LinkedIn/MemberData/ApiError.md)
+- [MemberData/Authorization.md](doc/LinkedIn/MemberData/Authorization.md)
+- [MemberData/Changelog/Page.md](doc/LinkedIn/MemberData/Changelog/Page.md)
+- [MemberData/Changelog.md](doc/LinkedIn/MemberData/Changelog.md)
+- [MemberData/Client.md](doc/LinkedIn/MemberData/Client.md)
+- [MemberData/ConfigurationError.md](doc/LinkedIn/MemberData/ConfigurationError.md)
+- [MemberData/ConnectionError.md](doc/LinkedIn/MemberData/ConnectionError.md)
+- [MemberData/Domains.md](doc/LinkedIn/MemberData/Domains.md)
+- [MemberData/Error.md](doc/LinkedIn/MemberData/Error.md)
+- [MemberData/Event.md](doc/LinkedIn/MemberData/Event.md)
+- [MemberData/Forbidden.md](doc/LinkedIn/MemberData/Forbidden.md)
+- [MemberData/NotFound.md](doc/LinkedIn/MemberData/NotFound.md)
+- [MemberData/RateLimited.md](doc/LinkedIn/MemberData/RateLimited.md)
+- [MemberData/ServerError.md](doc/LinkedIn/MemberData/ServerError.md)
+- [MemberData/Snapshot/Page.md](doc/LinkedIn/MemberData/Snapshot/Page.md)
+- [MemberData/Snapshot.md](doc/LinkedIn/MemberData/Snapshot.md)
+- [MemberData/Unauthorized.md](doc/LinkedIn/MemberData/Unauthorized.md)
+- [MemberData/VersionError.md](doc/LinkedIn/MemberData/VersionError.md)

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: linkedin-member-data
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lucian Ghinda
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Download your own LinkedIn data (snapshot domains and changelog events)
+  through the Member Data Portability API. Zero runtime dependencies.
+email:
+- lucianghinda@users.noreply.github.com
+executables:
+- linkedin-member-data
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- doc/CHANGELOG.md
+- doc/LinkedIn.md
+- doc/LinkedIn/MemberData.md
+- doc/LinkedIn/MemberData/ApiError.md
+- doc/LinkedIn/MemberData/Authorization.md
+- doc/LinkedIn/MemberData/Changelog.md
+- doc/LinkedIn/MemberData/Changelog/Page.md
+- doc/LinkedIn/MemberData/Client.md
+- doc/LinkedIn/MemberData/ConfigurationError.md
+- doc/LinkedIn/MemberData/ConnectionError.md
+- doc/LinkedIn/MemberData/Domains.md
+- doc/LinkedIn/MemberData/Error.md
+- doc/LinkedIn/MemberData/Event.md
+- doc/LinkedIn/MemberData/Forbidden.md
+- doc/LinkedIn/MemberData/NotFound.md
+- doc/LinkedIn/MemberData/RateLimited.md
+- doc/LinkedIn/MemberData/ServerError.md
+- doc/LinkedIn/MemberData/Snapshot.md
+- doc/LinkedIn/MemberData/Snapshot/Page.md
+- doc/LinkedIn/MemberData/Unauthorized.md
+- doc/LinkedIn/MemberData/VersionError.md
+- doc/README.md
+- exe/linkedin-member-data
+- lib/linkedin/member_data.rb
+- lib/linkedin/member_data/authorization.rb
+- lib/linkedin/member_data/changelog.rb
+- lib/linkedin/member_data/changelog/page.rb
+- lib/linkedin/member_data/cli.rb
+- lib/linkedin/member_data/cli/changelog_command.rb
+- lib/linkedin/member_data/cli/command.rb
+- lib/linkedin/member_data/cli/global_options.rb
+- lib/linkedin/member_data/cli/simple_commands.rb
+- lib/linkedin/member_data/cli/since_parser.rb
+- lib/linkedin/member_data/cli/snapshot_command.rb
+- lib/linkedin/member_data/cli/support.rb
+- lib/linkedin/member_data/client.rb
+- lib/linkedin/member_data/connection.rb
+- lib/linkedin/member_data/domains.rb
+- lib/linkedin/member_data/errors.rb
+- lib/linkedin/member_data/event.rb
+- lib/linkedin/member_data/snapshot.rb
+- lib/linkedin/member_data/snapshot/page.rb
+- lib/linkedin/member_data/util.rb
+- lib/linkedin/member_data/version.rb
+- llms.txt
+homepage: https://github.com/lucianghinda/linkedin-member-data
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lucianghinda/linkedin-member-data
+  source_code_uri: https://github.com/lucianghinda/linkedin-member-data/tree/main
+  changelog_uri: https://github.com/lucianghinda/linkedin-member-data/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Ruby client and CLI for the LinkedIn Member Data Portability (Member) API.
+test_files: []