appnigma-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 90c492f518f92dda13c8abef25384facbcb6080212be54c0e6df3ac83e157d9a
+  data.tar.gz: c0b7f1d24429ac72d1f0131563f9b9291427394bc232a72c7a18d45afd23312e
+SHA512:
+  metadata.gz: 83de48c4ea034b56e10c645f5bd7b524d705938c2ae8086cc0a58f58701d33bd7b6a01749d7fd84651f18eb1d1a99da398a6402aeb9e6b6b7ddc1a99ea2b726b
+  data.tar.gz: eb621ed6f68bfefbf5222f6af45415519b7d59e7fffb96cde3f105a371469a9da860b8f5aadc2c7770462d58427429433b73efd8d119af6a4d448bb81bcd4afc

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appnigma AI Inc.
+
+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,359 @@
+# appnigma-sdk
+
+The gem your product installs to reach its Appnigma microserver. It sends
+records to an end customer's HubSpot, reads them back, reads contacts,
+companies and deals in one shape whichever CRM they use, runs your own
+functions, calls any platform's API, and connects end customers. One gem for
+every customer. Nothing about your account is inside it, and it holds no
+secret: the key is yours to supply.
+
+- Ruby 3.3 or newer. Tested on 3.3, 3.4 and 4.0.
+- The same calls, error codes and retry rules as the TypeScript package
+  `@appnigma/sdk`, with names in Ruby style.
+- Not tied to Rails or any framework.
+
+## Install
+
+```sh
+gem install appnigma-sdk
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "appnigma-sdk"
+```
+
+## The key
+
+Every call carries your SDK key. Appnigma gives you your key when your
+microserver is set up; ask Appnigma for a new one if you need to replace or
+cancel it. It starts with `apn_live_` and is shown once. Keep it on your
+server, in the `APPNIGMA_SDK_KEY` environment variable, never in a browser or
+a repo. The client reads it from there:
+
+```ruby
+require "appnigma"
+
+client = Appnigma::Client.new
+```
+
+If you keep the key somewhere else, pass it in; a passed key wins:
+
+```ruby
+client = Appnigma::Client.new(key: secrets.fetch("appnigma-sdk-key"))
+```
+
+A client started with no key at all, or with a key that does not start with
+`apn_live_`, raises `Appnigma::AuthError` at once, before any call.
+
+## The first call: post a record
+
+`post` creates a record or updates the one that already matches. For a
+contact, the match is on `email` unless you name another property with
+`unique_by`. For a company or a deal, `unique_by` is required: name a property
+the platform treats as unique, and include it in `record` with a non-empty
+text value. Because it is an update when the record exists, a repeated call is
+safe.
+
+```ruby
+result = client.post(
+  end_customer_id: "lawfirm-123",
+  platform: "hubspot",
+  object: "contact",
+  record: { "email" => "jane@firm.com", "firstname" => "Jane", "lastname" => "Doe" }
+)
+puts "#{result[:created] ? "created" : "updated"} #{result[:id]}"
+```
+
+`end_customer_id` is your own id for your customer, 1 to 100 characters of
+letters, digits, dot, dash or underscore. `platform` is required, and `post`
+and `pull` work on `hubspot` only for now. `object` is `contact`, `company` or
+`deal`. `record` uses the platform's own property names, as strings.
+
+## Reading back: pull
+
+`pull` returns one page of records and a marker for the next. `next` is `nil`
+on the last page.
+
+```ruby
+after = nil
+loop do
+  page = client.pull(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", limit: 100, after: after)
+  page[:records].each { |contact| puts "#{contact[:id]} #{contact[:properties]["email"]}" }
+  after = page[:next]
+  break if after.nil?
+end
+```
+
+`limit` is 1 to 100 and defaults to 100.
+
+## Connecting an end customer
+
+Before calls can work for an end customer, they connect their account on that
+platform once. Any platform switched on for your company can be connected, and
+the end customer approves your own app there. Your product asks for a link,
+shows it to the end customer, and they approve on the platform.
+
+1. Ask for a link. It works once and expires after 15 minutes. Opening it does
+   not use it up: it is used when the end customer presses Connect, so a mail
+   scanner or a link preview opening it first does no harm.
+2. Send the end customer to the link's `url`. They log in to the platform and
+   approve.
+3. When they are done, they land on your `return_url` with `status=connected`,
+   or with `status=failed` and a `reason`. `return_url` must be HTTPS and at
+   most 2048 bytes when written as a JSON string, about 2046 plain characters.
+4. Confirm with `connections.get`. The connection is written before the end
+   customer lands, so the answer is already there.
+
+```ruby
+link = client.connections.create_link(
+  end_customer_id: "lawfirm-123",
+  platform: "hubspot",
+  return_url: "https://app.example.com/integrations/hubspot/done"
+)
+puts "send the end customer to #{link[:url]} before #{link[:expires_at]}"
+
+connection = client.connections.get(end_customer_id: "lawfirm-123", platform: "hubspot")
+puts "ready to post and pull" if connection[:status] == "connected"
+```
+
+`status` is `connected`, `needs_reconnect` or `disconnected`. An end customer
+who is already connected can open a new link to connect again, for example
+after changing HubSpot accounts. An end customer the API has never seen is an
+`Appnigma::NotFoundError`, not a status.
+
+The id travels in the URL for this call, so an id that is only `.` or `..` is
+refused before the call with `Appnigma::InputError`: a URL drops those, and
+the request would reach the wrong route. Do not use them as end customer ids.
+
+## CRM data in one shape: crm
+
+`crm.contacts`, `crm.companies` and `crm.deals` read an end customer's CRM in
+one shape, whichever CRM they use. Each has `list` and `get`, and each takes
+`end_customer_id:` and `platform:`.
+
+```ruby
+page = client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "attio", limit: 50)
+page[:records].each { |contact| puts "#{contact[:full_name]} #{contact[:emails].first&.dig(:value)}" }
+
+# The next page, while there is one.
+client.crm.contacts.list(end_customer_id: "lawfirm-123", platform: "attio", cursor: page[:next]) if page[:next]
+
+deal = client.crm.deals.get(end_customer_id: "lawfirm-123", platform: "hubspot", id: "1234")[:record]
+puts "#{deal[:name]} #{deal[:amount]} #{deal[:currency]} #{deal[:status]}"
+```
+
+Every field is always there: a value the CRM does not have is `nil`, never
+left out.
+
+| Object | Fields |
+| --- | --- |
+| Every record | `id`, `platform`, `created_at`, `updated_at`, `custom_fields`, and `raw`, the record exactly as the CRM sent it |
+| Contact | `first_name`, `last_name`, `full_name`, `emails`, `phones` (the primary one first), `company_id`, `owner_id` |
+| Company | `name`, `domain`, `owner_id` |
+| Deal | `name`, `amount`, `currency`, `status` (`open`, `won` or `lost`), `stage`, `pipeline`, `probability`, `close_date`, `closed_at`, `company_id`, `owner_id` |
+
+`custom_fields` is keyed by the CRM's own field names, as strings, and `raw`
+is exactly what the CRM sent. A platform with no unified data yet for that
+object is an `Appnigma::NotAvailableError` with `DATA_TYPE_NOT_AVAILABLE`;
+reach it with `request` instead. An id that does not exist is an
+`Appnigma::NotFoundError` with `RECORD_NOT_FOUND`. Reads are retried like
+`pull`.
+
+## Anything else on the platform: request
+
+`request` calls the end customer's platform's own API, for anything the shared
+shapes do not cover. It works on every platform switched on for you, including
+ones with no unified data yet.
+
+```ruby
+answer = client.request(
+  end_customer_id: "lawfirm-123",
+  platform: "hubspot",
+  method: "GET",
+  path: "/crm/v3/objects/notes?limit=10"
+)
+puts answer[:body] if answer[:status] == 200
+```
+
+`path` is a path on the platform's own API, with its query: never a full
+address, and it cannot step out of that API, so `..` and `//host` are refused.
+`body` is sent as JSON; leave it out on a `GET`.
+
+The answer is the platform's own: its `status`, its `headers` (content type,
+paging and rate limits) and its `body`, parsed from JSON when the platform
+answered JSON and as text otherwise. A refusal from the platform comes back
+the same way, with its status, rather than as an error: check
+`answer[:status]`. A `GET` is retried like `pull`; any other method is made
+once, because only you know whether repeating it is harmless.
+
+## Your own functions: catalog
+
+Beyond `post` and `pull`, your microserver can hold functions written for you.
+`catalog` lists them, with the platform each one is for, its version, and the
+JSON Schema of its input and output. Leave `platform:` out for every platform,
+or name one to narrow the list.
+
+```ruby
+client.catalog(platform: "hubspot")[:functions].each do |function|
+  puts "#{function[:platform]} #{function[:name]} v#{function[:version]} #{function[:description]}"
+end
+```
+
+A function's `owner` is `{ type: "customer" }` when every end customer can use
+it, or `{ type: "end_customer", end_customer_id: "..." }` when it was written
+for one of them. `input_schema` and `output_schema` are JSON Schema, as
+written. Until a function has gone live for you, the list is empty, not an
+error.
+
+## Your own functions: run
+
+`run` calls one of them, by platform and name, for one end customer. The input
+is checked against the function's shape before anything runs, so a wrong or
+missing field is an `Appnigma::InputError` listing every problem. Formats and
+patterns, such as an email or a fixed layout for a code, are checked by the
+function itself, so those refusals arrive from it with the same code. The
+answer is `{ output: ... }`, in the shape the function declared, with its keys
+as the function wrote them.
+
+```ruby
+result = client.run(
+  end_customer_id: "lawfirm-123",
+  platform: "hubspot",
+  function_name: "invoice-to-deal",
+  input: { "invoiceId" => "inv_1042", "amount" => 1250 }
+)
+puts "deal #{result[:output]["dealId"]}"
+```
+
+`platform` and `function_name` are both required: the same name can exist on
+two platforms and mean two different things. Leave `version:` out to run the
+oldest version still live, or name one. A name that exists only on another
+platform is an `Appnigma::NotFoundError` whose `details["platforms"]` says
+which. A platform that is not switched on for you is an `Appnigma::AuthError`
+with `PLATFORM_NOT_ENABLED`.
+
+`run` is made once and never retried: it is your own function, and only you
+know whether running it twice is harmless. If it fails with a network or
+server error, decide in your code whether to call again.
+
+## Your own guide
+
+One page, written for your company: install, the key, connecting an end
+customer to each platform switched on for you, `post`, `pull` and `run`, every
+one of your functions with its fields and an example call, and every error
+with what to do about it. `guide` answers it as markdown, built from what is
+live right now.
+
+```ruby
+File.write("appnigma-guide.md", client.guide[:guide])
+```
+
+## Telling failures apart
+
+Every failure is an exception you can rescue by class. All of them inherit
+from `Appnigma::Error`, so one `rescue Appnigma::Error` catches anything from
+Appnigma. Every error carries `code`, `message`, `status` and `request_id`.
+Quote the request id when you write to support@appnigma.ai, and never include
+your key or a token.
+
+| Class | When | Extra field |
+| --- | --- | --- |
+| `Appnigma::InputError` | 400. A field is wrong or missing. Also raised locally for a bad setting or a bad end customer id, before any call. | `problems`, a list of `{ field:, problem: }` |
+| `Appnigma::AuthError` | 401 or 403. The key is missing, unknown or cancelled, the microserver is not enabled, or the platform is not switched on for you. Also raised at start with no key. | |
+| `Appnigma::NotFoundError` | 404. No connection for that end customer on that platform, no such function or version, or no such record (`RECORD_NOT_FOUND`). When the function exists on another platform, `details["platforms"]` names it. | |
+| `Appnigma::ReconnectError` | 409 with `CONNECTION_NEEDS_RECONNECT`. The end customer has to approve again. | |
+| `Appnigma::NotAvailableError` | Any other 409. The platform has no unified data for that yet (`DATA_TYPE_NOT_AVAILABLE`); use `request`. | |
+| `Appnigma::RateLimitError` | 429, after the retries. Too many calls, or the platform asked us to slow down. | `retry_after_seconds`, or `nil` when the server named no wait |
+| `Appnigma::ServerError` | Any 5xx, after the retries. Also any answer that is not JSON. | |
+| `Appnigma::NetworkError` | The API could not be reached, or an attempt ran out of time, after the retries. `status` and `request_id` are `nil`. | `cause`, the underlying exception |
+
+```ruby
+begin
+  client.post(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", record: {})
+rescue Appnigma::InputError => e
+  e.problems.each { |problem| puts "#{problem[:field]} #{problem[:problem]}" }
+rescue Appnigma::AuthError => e
+  puts "check the key: #{e.code}"
+rescue Appnigma::NotFoundError
+  puts "this end customer is not connected yet"
+rescue Appnigma::ReconnectError
+  puts "ask the end customer to connect again"
+rescue Appnigma::RateLimitError => e
+  puts "wait #{e.retry_after_seconds} seconds"
+rescue Appnigma::ServerError => e
+  puts "our side failed, quote this id to support: #{e.request_id}"
+rescue Appnigma::NetworkError => e
+  puts "could not reach the API: #{e.cause&.message}"
+end
+```
+
+Or rescue the base class:
+
+```ruby
+begin
+  client.connections.get(end_customer_id: "nobody-here", platform: "hubspot")
+rescue Appnigma::Error => e
+  puts "#{e.class} #{e.code} #{e.status} #{e.request_id}"
+end
+```
+
+`code` is one of the strings in `Appnigma::ERROR_CODES`, or whatever a newer
+server sent. A code this version of the gem does not know is kept as is,
+never replaced.
+
+## Retries and time limits
+
+A call is tried again only when trying again is safe: the API could not be
+reached, it answered 5xx, or it answered 429. A 400, 401, 403, 404 or 409 is
+never retried, because the same call would be refused the same way. By default
+a call is made up to three times.
+
+`connections.create_link`, `run`, and `request` with a method other than `GET`
+are the exceptions: each is made once, never retried. Every call to
+`create_link` makes a new link, and a repeat after a lost answer would leave a
+working link nobody saw; `run` is your own function, and whether a repeat is
+harmless is yours to know. If either fails, decide in your code whether to
+call again.
+
+The wait between tries is what the `Retry-After` header says when the server
+sent one, otherwise half a second and then a second, with a little random
+spread so many clients do not retry in the same instant. A `Retry-After`
+longer than `max_retry_wait_ms` is not waited for: the call fails at once with
+an `Appnigma::RateLimitError` that carries the wait, so your code decides what
+to do with half a minute rather than sitting through it.
+
+Every attempt has a time limit, 30 seconds by default. An attempt that runs out
+of time counts as a network failure and is retried like one. Each call can set
+its own limit:
+
+```ruby
+page = client.pull(end_customer_id: "lawfirm-123", platform: "hubspot", object: "contact", limit: 1, timeout_ms: 10_000)
+puts "one record: #{page[:records].size}"
+```
+
+## Settings
+
+All passed to `Appnigma::Client.new`, and all optional.
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `key:` | the `APPNIGMA_SDK_KEY` environment variable | Your SDK key. |
+| `timeout_ms:` | `30_000` | How long one attempt may take. A whole number of milliseconds, at most 2147483647. |
+| `max_retries:` | `2` | How many times a call is tried again. `0` means one attempt. |
+| `max_retry_wait_ms:` | `30_000` | The longest `Retry-After` the client will sit through, in milliseconds, at most 2147483647. |
+
+Per call, as a keyword argument: `timeout_ms:`.
+
+## What is exported
+
+`Appnigma::Client`, `Appnigma::Error` and its eight subclasses, the constants
+`Appnigma::ERROR_CODES`, `Appnigma::OBJECTS`, `Appnigma::CONNECTION_STATUSES`
+and `Appnigma::PLATFORM_REQUEST_METHODS`, `Appnigma::VERSION`, and
+`Appnigma::API_DESCRIPTION_VERSION`, the version of the published description
+of the API that this version of the gem was generated from.
+
+## License
+
+MIT. See `LICENSE`.

data/lib/appnigma/checks.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "constants"
+require_relative "errors"
+
+module Appnigma
+  # Refusals made here, before any call, for a setting or an input the server
+  # would refuse anyway. Same shape as the server's, so one rescue handles
+  # both.
+  module Checks
+    module_function
+
+    def refuse(field, problem)
+      raise InputError.new(
+        code: "INVALID_INPUT",
+        message: "#{field} #{problem}",
+        details: { "problems" => [{ "field" => field, "problem" => problem }] }
+      )
+    end
+
+    def key!(key)
+      if key.nil? || key.empty?
+        raise AuthError.new(code: "SDK_KEY_MISSING", message: "No SDK key: pass key:, or set #{KEY_ENV_NAME}")
+      end
+      unless key.start_with?(KEY_PREFIX)
+        raise AuthError.new(code: "SDK_KEY_MISSING",
+                            message: "That is not an Appnigma SDK key, it starts with #{KEY_PREFIX}")
+      end
+
+      key
+    end
+
+    def timeout_ms!(value)
+      return value if value.is_a?(Integer) && value.between?(1, MAX_TIMER_MS)
+
+      refuse("timeout_ms", "must be a whole number of milliseconds from 1 to #{MAX_TIMER_MS}")
+    end
+
+    def max_retries!(value)
+      return value if value.is_a?(Integer) && value >= 0
+
+      refuse("max_retries", "must be a whole number, 0 or more")
+    end
+
+    def max_retry_wait_ms!(value)
+      return value if value.is_a?(Numeric) && value.finite? && value.between?(0, MAX_TIMER_MS)
+
+      refuse("max_retry_wait_ms", "must be a number of milliseconds from 0 to #{MAX_TIMER_MS}")
+    end
+
+    def end_customer_id!(value)
+      unless value.is_a?(String) && value.match?(END_CUSTOMER_ID_PATTERN)
+        refuse("end_customer_id",
+               END_CUSTOMER_ID_RULE)
+      end
+      refuse("end_customer_id", END_CUSTOMER_ID_PATH_RULE) if END_CUSTOMER_ID_PATH_UNSAFE.include?(value)
+      value
+    end
+
+    def platform!(value)
+      return value if value.is_a?(String) && !value.empty?
+
+      refuse("platform", "must be a platform key, such as hubspot")
+    end
+
+    # The setting if there is one, else production. An empty setting counts
+    # as none. Only https, or http to this machine, so a key never crosses a
+    # network unencrypted.
+    def base_url!(setting)
+      address = (setting.to_s.strip.empty? ? DEFAULT_BASE_URL : setting.strip).sub(%r{/+\z}, "")
+      refuse(API_URL_ENV_NAME, "must be an https:// address, or http:// to localhost") unless allowed_address?(address)
+      address
+    end
+
+    def allowed_address?(address)
+      parsed = parse_address(address)
+      return false if parsed.nil?
+      return !parsed.host.to_s.empty? if parsed.scheme == "https"
+
+      parsed.scheme == "http" && LOCAL_HOSTS.include?(parsed.host)
+    end
+
+    def parse_address(address)
+      URI.parse(address)
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/lib/appnigma/client.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "checks"
+require_relative "names"
+require_relative "retry"
+require_relative "transport"
+require_relative "connections"
+require_relative "crm"
+
+module Appnigma
+  # What a customer creates. The key comes from `key:` or from the
+  # APPNIGMA_SDK_KEY environment variable; a client started with no key, or
+  # with one that does not start with apn_live_, raises AuthError at once,
+  # before any call.
+  #
+  # Every call takes keyword arguments in Ruby style and answers a Hash with
+  # symbol keys in Ruby style, except inside content that is not ours (a
+  # record's properties, a function's input and output, a platform's answer),
+  # which comes back exactly as it was sent. Every call also takes
+  # `timeout_ms:`, the time limit of one attempt.
+  class Client
+    attr_reader :base_url, :timeout_ms, :max_retries, :max_retry_wait_ms, :connections, :crm
+
+    # `transport` is for tests; a customer never passes it.
+    def initialize(key: nil, timeout_ms: DEFAULT_TIMEOUT_MS, max_retries: DEFAULT_MAX_RETRIES,
+                   max_retry_wait_ms: DEFAULT_MAX_RETRY_WAIT_MS, transport: nil)
+      @key = Checks.key!(key || ENV.fetch(KEY_ENV_NAME, nil))
+      @base_url = Checks.base_url!(ENV.fetch(API_URL_ENV_NAME, nil))
+      @timeout_ms = Checks.timeout_ms!(timeout_ms)
+      @max_retries = Checks.max_retries!(max_retries)
+      @max_retry_wait_ms = Checks.max_retry_wait_ms!(max_retry_wait_ms)
+      @policy = Retry::Policy.new(max_retries: @max_retries, max_retry_wait_ms: @max_retry_wait_ms)
+      # A write whose repeat is not harmless gets one attempt. create_link
+      # makes a new link every time; run is your own function, and only you
+      # know whether running it twice is harmless; request with a method
+      # other than GET may change the platform. post is retried because the
+      # server updates the record that matches.
+      @one_attempt = Retry::Policy.new(max_retries: 0, max_retry_wait_ms: @max_retry_wait_ms)
+      @transport = transport || Transport.new(base_url: @base_url, key: @key)
+      @connections = Connections.new(self)
+      @crm = Crm.new(self)
+    end
+
+    # Creates a record in the end customer's HubSpot, or updates the one that
+    # already matches on `unique_by` (email for a contact unless you name
+    # another property; required for a company and a deal).
+    def post(end_customer_id:, platform:, object:, record:, unique_by: nil, timeout_ms: nil)
+      body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, object: object, record: record,
+                              unique_by: unique_by)
+      call(:post_record, body, timeout_ms: timeout_ms)
+    end
+
+    # One page of records and a marker for the next; `next` is nil on the
+    # last page. `limit` is 1 to 100.
+    def pull(end_customer_id:, platform:, object:, limit: nil, after: nil, timeout_ms: nil)
+      body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, object: object, limit: limit,
+                              after: after)
+      call(:pull_records, body, timeout_ms: timeout_ms)
+    end
+
+    # One of your own functions, by platform and name. Made once, never
+    # retried.
+    def run(end_customer_id:, platform:, function_name:, input:, version: nil, timeout_ms: nil)
+      body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, function_name: function_name,
+                              input: input, version: version)
+      call(:run_function, body, policy: @one_attempt, timeout_ms: timeout_ms)
+    end
+
+    # Your own functions, with their shapes. `platform` narrows the list.
+    def catalog(platform: nil, timeout_ms: nil)
+      call(:list_functions, opts: platform.nil? ? {} : { platform: platform }, timeout_ms: timeout_ms)
+    end
+
+    # The guide for your developers, as markdown, written for your company
+    # from what is live right now.
+    def guide(timeout_ms: nil)
+      call(:get_guide, timeout_ms: timeout_ms)
+    end
+
+    # Anything else on the end customer's platform, answered as the platform
+    # answered, refusals included. A GET is retried like a read; any other
+    # method is made once.
+    def request(end_customer_id:, platform:, method:, path:, body: nil, timeout_ms: nil)
+      payload = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, method: method, path: path,
+                                 body: body)
+      call(:platform_request, payload, policy: method == "GET" ? @policy : @one_attempt, timeout_ms: timeout_ms)
+    end
+
+    # One call: through the transport, under the given retry policy, and
+    # into the answer or the error for its status. Used by Connections and
+    # Crm as well.
+    def call(operation, *args, policy: @policy, timeout_ms: nil, opts: {})
+      attempt_ms = timeout_ms.nil? ? @timeout_ms : Checks.timeout_ms!(timeout_ms)
+      answer = Retry.with_retries(policy) { @transport.attempt(operation, *args, timeout_ms: attempt_ms, opts: opts) }
+      read_answer(answer)
+    end
+
+    # Used by Connections for the one call that is never retried.
+    attr_reader :one_attempt
+
+    private
+
+    # A success whose body is not JSON is a server error: a proxy page or an
+    # empty body is never handed back as data.
+    def read_answer(answer)
+      unless answer[:ok]
+        raise Errors.from_answer(status: answer[:status], body: answer[:json], request_id: answer[:request_id],
+                                 retry_after_seconds: answer[:retry_after_seconds])
+      end
+      if answer[:json].nil?
+        raise ServerError.new(code: "INTERNAL_ERROR", status: answer[:status], request_id: answer[:request_id],
+                              message: "The Appnigma API answered #{answer[:status]} with a body that is not JSON")
+      end
+      Names.answer(answer[:json])
+    end
+  end
+end

data/lib/appnigma/connections.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "checks"
+require_relative "names"
+
+module Appnigma
+  # Connecting an end customer to their account on a platform:
+  # `client.connections.create_link` and `client.connections.get`.
+  class Connections
+    def initialize(client)
+      @client = client
+    end
+
+    # A link to the connect page for one end customer on one platform. It
+    # works once and expires after 15 minutes. Made once, never retried:
+    # every call makes a new link.
+    def create_link(end_customer_id:, platform:, return_url:, timeout_ms: nil)
+      body = Names.camel_keys(end_customer_id: end_customer_id, platform: platform, return_url: return_url)
+      @client.call(:create_connection_link, body, policy: @client.one_attempt, timeout_ms: timeout_ms)
+    end
+
+    # Whether one end customer is connected on one platform. The id travels
+    # in the path, so it is checked here first: a bad one is refused as the
+    # server would refuse it, and never becomes a wrong route.
+    def get(end_customer_id:, platform:, timeout_ms: nil)
+      Checks.end_customer_id!(end_customer_id)
+      Checks.platform!(platform)
+      @client.call(:get_connection, end_customer_id, platform, timeout_ms: timeout_ms)
+    end
+  end
+end