parakey-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7a9e0253c3a8e5a39e372c39c77be783d54ae0875290af41a2215588ed96b1c
+  data.tar.gz: 1cf12063617bcc57125e2560e9cc44b6e4906c06e93101be114ca1ea3fae3e24
+SHA512:
+  metadata.gz: 1539da5296f053cfaa0cf0bbf0ecb22ab12f4d95811a5a44f94b1e46af1b029ddc3d0807296f0d7b16d5078568b2380681bab3b6ecf7720a547ab8c98fd9e85a
+  data.tar.gz: e63ec011675cf935074272dee5f01f5e3ad5ffbb1be966ad5234f6d35d10827e4329fdf41fbe0f6fcc93f7a60c3a2ad3ae597243deffca50a815ef948874caaa

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-10
+
+First release as `parakey-client`, extracted from the Parakey integration Guestit runs in production. The specs are
+that integration's provider specs, ported with their recorded VCR cassettes (scrubbed of emails, names and unit
+identifiers — this repo is public).
+
+### Added
+
+- `Parakey.configure` for the access token, the domain id, the base URL and the request timeout. No Rails
+  dependency.
+- Wire API on the `Parakey` module: `connection` and `request` with the retry policy (reads retry 429/502/503/504
+  and connection-level failures; a write never retries), the `Access-Token` auth header and the `ApiError` wrap with
+  `#unapplied?` delivery classification.
+- `sig/parakey.rbs` declaring the public API.
+- Operations, each returning a dry-monads `Result`:
+  - Access grants: `Create` (regular and time-controlled windows), `Delete` and `Index`, sharing the
+    `Parakey::AccessGrants` kind and status vocabulary.
+  - `Keys::Index` for the API-enabled accesses, `Locks::Index` for the devices joined with their accesses and
+    battery charge.
+  - Members: `Index` with wire filters and `Destroy` by email.
+  - `AccessEvents::Normalize` for event-log items and webhook deliveries.
+
+[Unreleased]: https://github.com/guestitab/parakey-client/compare/v0.1.0...staging
+[0.1.0]: https://github.com/guestitab/parakey-client/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guestit
+
+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.

data/README.md

@@ -0,0 +1,149 @@
+# parakey-client
+
+A Ruby client for the [Parakey API](https://api.parakey.co/). Each endpoint is one operation class that returns a
+[dry-monads](https://dry-rb.org/gems/dry-monads/) `Result`. The gem handles authentication, retries and response
+normalization. It does not depend on Rails, only on ActiveSupport and Faraday. Your app supplies the access token
+and the domain id.
+
+[Guestit](https://guestit.se) built it and runs it in production.
+
+Requires Ruby 4.0 or later.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'parakey-client'
+```
+
+Bundler loads it for you. Outside Bundler, `require 'parakey'`.
+
+## Configuration
+
+```ruby
+Parakey.configure do |config|
+  config.access_token = ENV.fetch('PARAKEY_ACCESS_TOKEN')
+  config.domain_id    = ENV.fetch('PARAKEY_DOMAIN_ID')
+end
+```
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `access_token` | `nil` | The account's static API token, sent as the `Access-Token` header. Parakey issues one per account; there is no OAuth minting and no token store. |
+| `domain_id` | `nil` | The domain every list and member call scopes to (the `domainId` parameter). |
+| `base_url` | `https://api.parakey.co/` | API root. |
+| `timeout` | `nil` | Faraday request timeout in seconds. |
+
+## Usage
+
+Operations live under `Parakey::<Resource>::<Action>`. Build a fresh instance for every call:
+
+```ruby
+result = Parakey::AccessGrants::Index.new.call(skip: 0, take: 100)
+
+if result.success?
+  result.value!   # => [{ external_id: 'f163gXNFWc', recipient_email: '...', kind: 'regular', ... }]
+else
+  result.failure  # => a Parakey::Error or a Faraday::Error
+end
+```
+
+`call` never raises. It returns `Success(value)` or `Failure(error)`. `call!` returns the `Success` and raises the
+error where `call` would return a `Failure`. Response bodies come back as hashes with symbol keys.
+
+The gem covers access grants (create, delete, index), accesses (`Keys::Index`), devices (`Locks::Index`, joining
+the accesses that reach each device), members (index, destroy) and access events (`AccessEvents::Normalize`, which
+maps one event-log item or webhook delivery to plain attributes). [CHANGELOG.md](CHANGELOG.md) lists every
+operation.
+
+### Grants, keys and locks
+
+An access key (a grant) points at an access (a reusable key) and a user. A key with both `startDate` and
+`expirationDate` is time-controlled (`kind: 'tca'`); any other is permanent (`kind: 'regular'`). Creating a
+time-controlled grant without the window, or a permanent one with one, is refused before any request:
+
+```ruby
+Parakey::AccessGrants::Create.new.call(
+  attributes: {
+    access_id: 'hJ7Jt5aPIL',
+    recipient_email: 'guest@example.com',
+    kind: 'tca',
+    start_date: Time.utc(2026, 11, 10),
+    end_date: Time.utc(2026, 11, 12)
+  }
+)
+```
+
+Parakey upserts an access key by access, user and window: re-creating an identical grant resolves to the existing
+key. Deletes answer 404 for an already-missing key or member, which the gem reads as success.
+
+Lists page 1-based with `page` and `limit` on the wire; the operations take `skip` and `take` and derive the page.
+`Keys::Index` is always filtered to API-enabled accesses; `Locks::Index` reports `batteryStatus` as a percentage
+(`high`/`medium`/`low`/`veryLow` → 100/75/50/25).
+
+### Errors
+
+| Class | Raised when |
+| --- | --- |
+| `Parakey::ArgumentError` | The arguments are unusable. Raised before any request. |
+| `Parakey::ApiError` | Parakey answered with an error status. `#status` holds the HTTP status. |
+| `Parakey::Error` | The parent of the two above, also raised when no access token is configured. |
+
+### Retries and delivery
+
+Reads retry 429/502/503/504 and connection-level failures with backoff. A write never retries on a status, and a
+connection-level failure retries on reads only — `POST /access-keys` has no provider idempotency key. After a
+failed write:
+
+```ruby
+error.is_a?(Parakey::ApiError) && error.unapplied? # the write certainly did not take, so a retry is safe
+```
+
+Anything else (a server error, a timeout after the request left) leaves delivery unknown: read back before
+retrying.
+
+### Webhooks
+
+Parakey POSTs event-log items to your webhook URL with the account's webhook key in the `?token=` query parameter.
+Verify it in your app (a `secure_compare` against your stored key), then normalize the payload:
+
+```ruby
+Parakey::AccessEvents::Normalize.new.call(item: params)
+# => Success({ external_id:, event_type:, occurred_at:, grant_external_id:, provider_lock_id:, access_id:, metadata: })
+```
+
+A delivery gets six attempts over about five hours and is then dropped, and Parakey disables a webhook after 10
+failures in five days or 100 in a day. Dropped events can be recovered from `GET /event-logs`
+(`Accept-Version: 2.0`), polling by `createdAt`.
+
+## Type signatures
+
+The gem ships RBS for its public API in `sig/parakey.rbs`. `rbs collection install` picks it up from your
+`Gemfile.lock`, so Steep sees it with no extra setup.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake        # specs and RuboCop
+bundle exec rspec       # specs only
+bundle exec rubocop -A  # autocorrect; review every change
+```
+
+The specs run offline against recorded VCR cassettes in `spec/fixtures/cassettes`. Recording a new cassette needs
+live credentials for a Parakey account. Scrub the token, the domain id (the spec_helper filters handle both) and
+any real emails, names or unit identifiers from the cassette before you commit it — this repo is public.
+
+## Releasing
+
+1. Bump `Parakey::VERSION` in `lib/parakey/version.rb` and move the `Unreleased` notes in `CHANGELOG.md` under the
+   new version.
+2. Commit on `staging` and run `bundle exec rake`.
+3. Run `gem signin` once per machine. The gem requires MFA, so every push asks for a one-time code.
+4. Run `bundle exec rake release`. It builds `pkg/parakey-client-<version>.gem`, tags `v<version>`, pushes the
+   branch and the tag, and pushes the gem to RubyGems.
+5. Fast-forward `production` to the release tag.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/parakey/access_events/normalize.rb

@@ -0,0 +1,42 @@
+module Parakey
+  module AccessEvents
+    # Normalizes one event-log item or webhook delivery into the access event
+    # attributes the host persists. The wire item is left untouched under
+    # metadata[:payload].
+    class Normalize
+      include Parakey::Operation
+
+      # Device maintenance activities report as a sync, not an unlock.
+      SYNC_ACTIVITIES = %w[calibrate dfu setTime].freeze #: ::Array[::String]
+
+      # @rbs (item: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(item:)
+        argument! item: :required if item.blank?
+
+        Success(attributes(item))
+      end
+
+      private
+
+      # @rbs (::Hash[::Symbol, untyped] item) -> ::Hash[::Symbol, untyped]
+      def attributes(item)
+        {
+          external_id: item[:id],
+          event_type: event_type(item),
+          occurred_at: item[:timestamp].presence&.in_time_zone,
+          grant_external_id: item.dig(:info, :accessKey, :id).presence,
+          provider_lock_id: item.dig(:info, :device, :id).presence,
+          access_id: item.dig(:info, :access, :id).presence,
+          metadata: { payload: item }
+        }
+      end
+
+      # @rbs (::Hash[::Symbol, untyped] item) -> ::String?
+      def event_type(item)
+        return 'synced' if SYNC_ACTIVITIES.include?(item[:activity])
+
+        item[:activity].presence
+      end
+    end
+  end
+end

data/lib/parakey/access_grants/create.rb

@@ -0,0 +1,47 @@
+module Parakey
+  module AccessGrants
+    # Creates an access key: permanent for a regular grant, time-windowed for a
+    # time-controlled one. Parakey upserts by access, user and window, so a repeat
+    # of an identical grant resolves to the existing key instead of duplicating it.
+    class Create
+      include Parakey::Operation
+
+      # @rbs (attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      def call(attributes:)
+        argument! access_id: :required if attributes[:access_id].blank?
+        argument! kind: :invalid unless KINDS.include?(attributes[:kind])
+        argument! recipient_email: :required if attributes[:recipient_email].blank?
+
+        validate_validity_window!(attributes)
+
+        body = Parakey.request(:post, 'access-keys', params: payload(attributes))
+
+        Success(external_id: body.fetch(:id), metadata: { raw: body })
+      end
+
+      private
+
+      # A regular grant never carries a window; a time-controlled one always
+      # does, ending after it starts.
+      # @rbs (::Hash[::Symbol, untyped] attributes) -> void
+      def validate_validity_window!(attributes)
+        if attributes[:kind] == KIND_TIME_CONTROLLED
+          argument! validity_window: :required if attributes[:start_date].blank? || attributes[:end_date].blank?
+          argument! end_date: :invalid if attributes[:start_date].in_time_zone >= attributes[:end_date].in_time_zone
+        elsif attributes[:start_date].present? || attributes[:end_date].present?
+          argument! validity_window: :invalid
+        end
+      end
+
+      # @rbs (::Hash[::Symbol, untyped] attributes) -> ::Hash[::Symbol, untyped]
+      def payload(attributes)
+        {
+          access: { id: attributes[:access_id] },
+          user: { email: attributes[:recipient_email] },
+          startDate: attributes[:start_date]&.iso8601,
+          expirationDate: attributes[:end_date]&.iso8601
+        }.compact
+      end
+    end
+  end
+end

data/lib/parakey/access_grants/delete.rb

@@ -0,0 +1,19 @@
+module Parakey
+  module AccessGrants
+    # Deletes an access key. A key that is already gone answers 404, which reads
+    # as success: the desired end state is reached either way.
+    class Delete
+      include Parakey::Operation
+
+      # @rbs (attributes: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[bool]
+      def call(attributes:)
+        argument! external_id: :required if attributes[:external_id].blank?
+
+        path = "access-keys/#{ERB::Util.url_encode(attributes[:external_id])}"
+        Parakey.request(:delete, path, accepted_statuses: [404])
+
+        Success(true)
+      end
+    end
+  end
+end

data/lib/parakey/access_grants/index.rb

@@ -0,0 +1,42 @@
+module Parakey
+  module AccessGrants
+    # Lists the domain's access keys, one page per call.
+    class Index
+      include Parakey::Operation
+
+      # @rbs (?skip: ::Integer, ?take: ::Integer) -> Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      def call(skip: 0, take: 100)
+        body = Parakey.request(:get, 'access-keys', params: page_params(skip, take))
+
+        Success(body.fetch(:items, []).map { |item| attributes(item) })
+      end
+
+      private
+
+      # @rbs (::Hash[::Symbol, untyped] item) -> ::Hash[::Symbol, untyped]
+      def attributes(item)
+        user = item[:user] || {}
+
+        {
+          external_id: item[:id],
+          label: item[:aliasTag],
+          recipient_email: user[:email],
+          recipient_name: user[:name],
+          status: item[:enabled] ? STATUS_ACTIVE : STATUS_INACTIVE,
+          kind: grant_kind(item),
+          access_id: item.dig(:access, :id),
+          start_date: item[:startDate],
+          end_date: item[:expirationDate]
+        }
+      end
+
+      # A key with both dates is time-controlled; anything else is permanent.
+      # @rbs (::Hash[::Symbol, untyped] item) -> ::String
+      def grant_kind(item)
+        return KIND_TIME_CONTROLLED if item[:startDate].present? && item[:expirationDate].present?
+
+        KIND_REGULAR
+      end
+    end
+  end
+end

data/lib/parakey/access_grants.rb

@@ -0,0 +1,13 @@
+module Parakey
+  # The normalized vocabulary the access-key operations return. Parakey access
+  # keys come in two kinds: a permanent key (regular) and a time-windowed key
+  # (time-controlled access, tca); a key is active while enabled.
+  module AccessGrants
+    KIND_REGULAR = 'regular'.freeze
+    KIND_TIME_CONTROLLED = 'tca'.freeze
+    KINDS = [KIND_REGULAR, KIND_TIME_CONTROLLED].freeze #: ::Array[::String]
+
+    STATUS_ACTIVE = 'active'.freeze
+    STATUS_INACTIVE = 'inactive'.freeze
+  end
+end

data/lib/parakey/api_error.rb

@@ -0,0 +1,20 @@
+module Parakey
+  # A rejected Parakey response, carrying the HTTP status. #unapplied? marks a
+  # refusal where the write certainly did not land, so a retry is safe; anything
+  # else (a server error, a timeout after a write) leaves delivery unknown.
+  class ApiError < Error
+    attr_reader :status #: ::Integer
+
+    # @rbs (::String message, status: ::Integer) -> void
+    def initialize(message, status:)
+      super(message)
+
+      @status = status
+    end
+
+    # @rbs () -> bool
+    def unapplied?
+      status.between?(400, 499) && [408, 409].exclude?(status)
+    end
+  end
+end

data/lib/parakey/client.rb

@@ -0,0 +1,49 @@
+module Parakey
+  BASE_URL = 'https://api.parakey.co/'.freeze #: ::String
+
+  # Access-key POSTs create grants without a provider idempotency key, so a write
+  # never retries; reads retry on a status or a connection-level failure.
+  RETRY_OPTIONS = {
+    max: 3,
+    interval: 0.5,
+    interval_randomness: 0.5,
+    backoff_factor: 2,
+    retry_statuses: [429, 502, 503, 504],
+    methods: %i[get delete],
+    exceptions: [*Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS, Faraday::ConnectionFailed, Faraday::SSLError]
+  }.freeze #: ::Hash[::Symbol, untyped]
+
+  # @rbs () -> Faraday::Connection
+  def self.connection
+    @connection ||= Faraday.new(url: config.base_url) do |builder|
+      builder.request :json
+      builder.request :retry, RETRY_OPTIONS
+      builder.response :json, parser_options: { symbolize_names: true, mode: :rails, decoder: [Oj, :load] }
+      builder.options[:timeout] = config.timeout
+    end
+  end
+
+  # @rbs (::Symbol method, ::String path, ?params: ::Hash[::Symbol, untyped]?, ?accepted_statuses: ::Array[::Integer]) -> untyped
+  def self.request(method, path, params: nil, accepted_statuses: [])
+    response = connection.public_send(method, path, params, auth_headers)
+
+    return response.body if response.success? || accepted_statuses.include?(response.status)
+
+    raise ApiError.new(error_message(response), status: response.status)
+  end
+
+  # @rbs () -> ::Hash[::String, ::String]
+  private_class_method def self.auth_headers
+    access_token = config.access_token.presence || raise(Error, 'Parakey access token is required.')
+
+    { 'Access-Token' => access_token }
+  end
+
+  # @rbs (Faraday::Response response) -> ::String
+  private_class_method def self.error_message(response)
+    body = response.body
+    message = body.is_a?(Hash) ? body[:message] : nil
+
+    message.presence || body.to_s.presence || "Provider request failed with status #{response.status}"
+  end
+end

data/lib/parakey/config.rb

@@ -0,0 +1,16 @@
+module Parakey
+  # Injected by the host app (see the Parakey.configure initializer): the static
+  # API access token and the domain every call scopes to. Keeping these out of
+  # the gem is what makes it host-agnostic.
+  #
+  # Parakey issues one long-lived access token per account (no OAuth minting), so
+  # there is no token store to inject; the host reads the token from its own
+  # credentials and hands it over here.
+  class Config
+    attr_accessor :access_token, :domain_id, :base_url, :timeout
+
+    def initialize
+      @base_url = BASE_URL
+    end
+  end
+end

data/lib/parakey/error.rb

@@ -0,0 +1,6 @@
+module Parakey
+  class Error < StandardError; end
+
+  # Raised by operations before any network call when the arguments are unusable.
+  class ArgumentError < Error; end
+end

data/lib/parakey/keys/index.rb

@@ -0,0 +1,34 @@
+module Parakey
+  module Keys
+    # Lists the domain's accesses (the reusable "keys" a grant points at),
+    # restricted to API-enabled ones. Extra wire filters merge in verbatim, e.g.
+    # { deviceIds: { in: [...] } }.
+    class Index
+      include Parakey::Operation
+
+      ACCESS_FILTERS = {
+        allowedOrigins: 'api',
+        enabled: true
+      }.freeze
+
+      # @rbs (?skip: ::Integer, ?take: ::Integer, ?filters: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      def call(skip: 0, take: 100, filters: {})
+        params = ACCESS_FILTERS.merge(filters, page_params(skip, take))
+        body = Parakey.request(:get, 'accesses', params:)
+
+        Success(body.fetch(:items, []).map { |item| attributes(item) })
+      end
+
+      private
+
+      # @rbs (::Hash[::Symbol, untyped] item) -> ::Hash[::Symbol, untyped]
+      def attributes(item)
+        {
+          external_id: item[:id],
+          name: item[:name].presence,
+          device_ids: item.fetch(:devices, []).pluck(:id)
+        }.compact
+      end
+    end
+  end
+end

data/lib/parakey/locks/index.rb

@@ -0,0 +1,60 @@
+module Parakey
+  module Locks
+    # Lists the domain's devices, each with the accesses that reach it. One page
+    # of devices per call; the accesses join pages through Keys::Index on its own.
+    class Index
+      include Parakey::Operation
+
+      BATTERY_CHARGES = {
+        'high' => 100,
+        'medium' => 75,
+        'low' => 50,
+        'veryLow' => 25
+      }.freeze #: ::Hash[::String, ::Integer]
+
+      ACCESS_BATCH_SIZE = 500
+
+      # The wire reports no device status; a device the API lists reads as online.
+      STATUS_ONLINE = 'online'.freeze
+
+      # @rbs (?skip: ::Integer, ?take: ::Integer) -> Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      def call(skip: 0, take: 100)
+        devices = Parakey.request(:get, 'devices', params: page_params(skip, take)).fetch(:items, [])
+        accesses = accesses(devices.pluck(:id))
+
+        Success(devices.map { |device| attributes(device, accesses) })
+      end
+
+      private
+
+      # @rbs (::Array[::String] device_ids) -> ::Array[::Hash[::Symbol, untyped]]
+      def accesses(device_ids)
+        return [] if device_ids.empty?
+
+        filters = { deviceIds: { in: device_ids } }
+        result = []
+
+        loop do
+          page = Parakey::Keys::Index.new.call!(skip: result.size, take: ACCESS_BATCH_SIZE, filters:).value!
+          result.concat(page)
+          break if page.size < ACCESS_BATCH_SIZE
+        end
+
+        result
+      end
+
+      # @rbs (::Hash[::Symbol, untyped] device, ::Array[::Hash[::Symbol, untyped]] accesses) -> ::Hash[::Symbol, untyped]
+      def attributes(device, accesses)
+        reaching = accesses.select { |access| access[:device_ids].include?(device[:id]) }
+
+        {
+          external_id: device[:id],
+          name: device[:name],
+          status: STATUS_ONLINE,
+          charge: BATTERY_CHARGES[device[:batteryStatus]],
+          keys: reaching.map { |access| access.slice(:external_id, :name) }
+        }
+      end
+    end
+  end
+end

data/lib/parakey/members/destroy.rb

@@ -0,0 +1,23 @@
+module Parakey
+  module Members
+    # Removes a domain member by email. An unknown member answers 404, which
+    # reads as success: the member is gone either way.
+    class Destroy
+      include Parakey::Operation
+
+      # @rbs (email: ::String?) -> Dry::Monads::Result[bool]
+      def call(email:)
+        argument! email: :required if email.blank?
+        argument! domain_id: :required if Parakey.config.domain_id.blank?
+
+        filter = {
+          domainId: Parakey.config.domain_id,
+          email:
+        }
+        Parakey.request(:post, 'members/delete', params: { filter: }, accepted_statuses: [404])
+
+        Success(true)
+      end
+    end
+  end
+end

data/lib/parakey/members/index.rb

@@ -0,0 +1,17 @@
+module Parakey
+  module Members
+    # Lists the domain's members, one page per call, items in the wire's own
+    # shape (symbolized camelCase keys). Wire filters merge in verbatim, e.g.
+    # { status: 'emailProblem' } for members whose invitation email bounced.
+    class Index
+      include Parakey::Operation
+
+      # @rbs (?skip: ::Integer, ?take: ::Integer, ?filters: ::Hash[::Symbol, untyped]) -> Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      def call(skip: 0, take: 100, filters: {})
+        body = Parakey.request(:get, 'members', params: filters.merge(page_params(skip, take)))
+
+        Success(body.fetch(:items, []))
+      end
+    end
+  end
+end

data/lib/parakey/operation.rb

@@ -0,0 +1,45 @@
+module Parakey
+  # Shared monadic contract for the client operations: #call returns a Result,
+  # #call! unwraps it and raises the underlying failure. An error raised inside
+  # #call becomes Failure(error), mirroring the host's operation base.
+  module Operation
+    def self.included(base)
+      base.include Dry::Monads[:result]
+      base.prepend(Call)
+    end
+
+    module Call
+      def call(*, **, &)
+        super
+      rescue StandardError => e
+        Failure(e)
+      end
+    end
+
+    def call!(...)
+      result = call(...)
+      raise result.failure if result.failure?
+
+      result
+    end
+
+    private
+
+    def argument!(**attrs)
+      key, reason = attrs.first
+      raise Parakey::ArgumentError, "#{key}: #{reason}"
+    end
+
+    # Lists page 1-based by page and limit on the wire; the operations take an item offset.
+    # @rbs (::Integer skip, ::Integer take) -> ::Hash[::Symbol, untyped]
+    def page_params(skip, take)
+      argument! take: :invalid unless take.to_i.positive?
+
+      {
+        domainId: Parakey.config.domain_id,
+        limit: take,
+        page: skip.div(take) + 1
+      }
+    end
+  end
+end

data/lib/parakey/version.rb

@@ -0,0 +1,3 @@
+module Parakey
+  VERSION = '0.1.0'.freeze
+end

data/lib/parakey-client.rb

@@ -0,0 +1 @@
+require_relative 'parakey'

data/lib/parakey.rb

@@ -0,0 +1,37 @@
+require 'active_support'
+require 'active_support/core_ext'
+require 'dry/monads'
+require 'erb'
+require 'faraday'
+require 'faraday/retry'
+require 'oj'
+
+require_relative 'parakey/version'
+require_relative 'parakey/error'
+require_relative 'parakey/api_error'
+require_relative 'parakey/config'
+require_relative 'parakey/operation'
+require_relative 'parakey/client'
+require_relative 'parakey/access_grants'
+require_relative 'parakey/access_events/normalize'
+require_relative 'parakey/access_grants/create'
+require_relative 'parakey/access_grants/delete'
+require_relative 'parakey/access_grants/index'
+require_relative 'parakey/keys/index'
+require_relative 'parakey/locks/index'
+require_relative 'parakey/members/destroy'
+require_relative 'parakey/members/index'
+
+module Parakey
+  class << self
+    # @rbs () { (Config) -> void } -> void
+    def configure
+      yield(config)
+    end
+
+    # @rbs () -> Config
+    def config
+      @config ||= Config.new
+    end
+  end
+end

data/sig/parakey.rbs

@@ -0,0 +1,107 @@
+# Public API of the gem, mirroring the inline `# @rbs` annotations in lib/.
+# Shipped with the gem so host apps pick it up through `rbs collection`.
+module Parakey
+  VERSION: ::String
+
+  BASE_URL: ::String
+  RETRY_OPTIONS: ::Hash[::Symbol, untyped]
+
+  def self.configure: () { (Config) -> void } -> void
+  def self.config: () -> Config
+
+  def self.connection: () -> untyped
+  def self.request: (::Symbol method, ::String path, ?params: ::Hash[::Symbol, untyped]?, ?accepted_statuses: ::Array[::Integer]) -> untyped
+
+  class Error < ::StandardError
+  end
+
+  # Raised by operations before any network call when the arguments are unusable.
+  class ArgumentError < Error
+  end
+
+  # A rejected Parakey response; #unapplied? marks a write that never landed.
+  class ApiError < Error
+    attr_reader status: ::Integer
+
+    def initialize: (::String message, status: ::Integer) -> void
+
+    def unapplied?: () -> bool
+  end
+
+  class Config
+    attr_accessor access_token: ::String?
+    attr_accessor domain_id: ::String?
+    attr_accessor base_url: ::String
+    attr_accessor timeout: (::Integer | ::Float)?
+  end
+
+  # #call! returns the same Result as #call, raising the failure instead of
+  # wrapping it — hence the `alias call! call` on every operation below.
+  module Operation
+    def call!: (*untyped, **untyped) -> untyped
+  end
+
+  module AccessGrants
+    KIND_REGULAR: ::String
+    KIND_TIME_CONTROLLED: ::String
+    KINDS: ::Array[::String]
+    STATUS_ACTIVE: ::String
+    STATUS_INACTIVE: ::String
+
+    class Create
+      def call: (attributes: ::Hash[::Symbol, untyped]) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+
+    class Delete
+      def call: (attributes: ::Hash[::Symbol, untyped]) -> ::Dry::Monads::Result[bool]
+      alias call! call
+    end
+
+    class Index
+      def call: (?skip: ::Integer, ?take: ::Integer) -> ::Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      alias call! call
+    end
+  end
+
+  module AccessEvents
+    class Normalize
+      SYNC_ACTIVITIES: ::Array[::String]
+
+      def call: (item: ::Hash[::Symbol, untyped]) -> ::Dry::Monads::Result[::Hash[::Symbol, untyped]]
+      alias call! call
+    end
+  end
+
+  module Keys
+    class Index
+      ACCESS_FILTERS: ::Hash[::Symbol, untyped]
+
+      def call: (?skip: ::Integer, ?take: ::Integer, ?filters: ::Hash[::Symbol, untyped]) -> ::Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      alias call! call
+    end
+  end
+
+  module Locks
+    class Index
+      BATTERY_CHARGES: ::Hash[::String, ::Integer]
+      ACCESS_BATCH_SIZE: ::Integer
+      STATUS_ONLINE: ::String
+
+      def call: (?skip: ::Integer, ?take: ::Integer) -> ::Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      alias call! call
+    end
+  end
+
+  module Members
+    class Index
+      def call: (?skip: ::Integer, ?take: ::Integer, ?filters: ::Hash[::Symbol, untyped]) -> ::Dry::Monads::Result[::Array[::Hash[::Symbol, untyped]]]
+      alias call! call
+    end
+
+    class Destroy
+      def call: (email: ::String?) -> ::Dry::Monads::Result[bool]
+      alias call! call
+    end
+  end
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: parakey-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Guestit
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: dry-monads
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: oj
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.17'
+description: 'One operation per Parakey API endpoint, returning dry-monads Results,
+  with retries and response normalization. Framework-free: the host injects the access
+  token and the domain id.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/parakey-client.rb
+- lib/parakey.rb
+- lib/parakey/access_events/normalize.rb
+- lib/parakey/access_grants.rb
+- lib/parakey/access_grants/create.rb
+- lib/parakey/access_grants/delete.rb
+- lib/parakey/access_grants/index.rb
+- lib/parakey/api_error.rb
+- lib/parakey/client.rb
+- lib/parakey/config.rb
+- lib/parakey/error.rb
+- lib/parakey/keys/index.rb
+- lib/parakey/locks/index.rb
+- lib/parakey/members/destroy.rb
+- lib/parakey/members/index.rb
+- lib/parakey/operation.rb
+- lib/parakey/version.rb
+- sig/parakey.rbs
+homepage: https://github.com/guestitab/parakey-client
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/guestitab/parakey-client
+  changelog_uri: https://github.com/guestitab/parakey-client/blob/staging/CHANGELOG.md
+  bug_tracker_uri: https://github.com/guestitab/parakey-client/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: Ruby client for the Parakey API
+test_files: []