likyly 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: daf5efd48e779542b6bf7d497ec6ec8462e2b2a061eeb85e46dc4966dffeb2dc
+  data.tar.gz: d2bdb88e7c64b614c0c2f98e65dbcca4cc8e04db43c040f14c6b569f16ea45fc
+SHA512:
+  metadata.gz: 60e458c1036fa1e5c31999b62d5689eb9ed48a1f83af1b3a36c112eebe780861fc98a1d3189378dc5bba80c48d663abf03a0e030548179e64187b9f8ba7a248d
+  data.tar.gz: 4026a30c33621ce76e57c2d2abe36cfd025173fc583aa793563bfa65fd6953110fe9d77c27ccfb133e4d300e3d54b87af8c80d2b12f6bd57f0879ab45edfc91c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LIKYLY
+
+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,287 @@
+# LIKYLY SDK for Ruby
+
+[LIKYLY](https://likyly.com) shows each visitor of your site the products they are most likely to want:
+"You may also like" on a product page, "Recommended for you" on the home page, "Complete your order" in
+the cart. It learns from what visitors actually do, and gets better as they do it.
+
+This is the official Ruby client for the LIKYLY API. Your code uses it to:
+
+1. **Send your catalog**: the products, articles or films you want recommended.
+2. **Report what visitors do**: they view a product, add it to their cart, sometimes buy it. Browsing
+   alone is useful: a visitor who never buys still teaches LIKYLY what goes together, and still gets
+   recommendations.
+3. **Ask what to show**: the products to recommend on a page, for a visitor, or both.
+4. **Report what happened to the recommendations**: which ones were shown and which were clicked. LIKYLY
+   learns which recommendations work, and you can measure what they bring in.
+
+## Install
+
+```sh
+gem install likyly
+# or in your Gemfile:
+gem "likyly"
+```
+
+Ruby 3.0 or later. No dependency (standard library `net/http` and `json`), no Rails required. Thread-safe.
+
+## Quick start
+
+### Initialize
+
+Create one client and reuse it. Use your **secret** key on your server (see [Which key?](#which-key)).
+
+```ruby
+require "likyly"
+
+# Backend only: the secret key gives access to your catalog and your users.
+likyly = Likyly::Client.new(
+  api_key: ENV.fetch("LIKYLY_SECRET_KEY")
+)
+```
+
+### Send your catalog
+
+```ruby
+# Send your catalog once (and whenever it changes). Ids are YOUR ids: SKUs, UUIDs, Shopify gids...
+likyly.items.upsert_many([
+  { item_id: "SKU-1", title: "Nike Air Max", description: "Running shoe with air cushioning",
+    properties: { "category" => "shoes", "brand" => "Nike", "price" => 129.9 } },
+  { item_id: "SKU-2", title: "Adidas Ultraboost", description: "Responsive running shoe",
+    properties: { "category" => "shoes", "brand" => "Adidas", "price" => 149 } },
+  { item_id: "SKU-3", title: "Nike Pegasus", description: "Everyday running shoe",
+    properties: { "category" => "shoes", "brand" => "Nike", "price" => 119 } }
+])
+
+# Users are optional: describe them if you want the profile to travel with their events.
+likyly.users.upsert("user_123", properties: { "country" => "FR", "segment" => "premium" })
+```
+
+Ids are your own: any string (`SKU-123`, a UUID, `gid://shopify/Product/123`). `properties` is free-form; `category` and `description` improve similarity, everything else is stored as is.
+
+### Track events
+
+```ruby
+# Tell LIKYLY what your visitors do.
+likyly.events.view(user_id: "user_123", item_id: "SKU-1")
+
+# Purchases carry an event_id: replaying the call can never count the sale twice.
+likyly.events.purchase(
+  event_id: "purchase_order_9281_SKU-1",
+  user_id: "user_123",
+  item_id: "SKU-1",
+  quantity: 1,
+  properties: { "price" => 129.9, "currency" => "EUR", "orderId" => "order_9281" }
+)
+```
+
+### Get recommendations
+
+```ruby
+# Ask what to show. You never pick an algorithm: LIKYLY chooses the best strategy for what it knows.
+recs = likyly.recommendations.get(user_id: "user_123", placement: "homepage", limit: 3)
+
+puts "strategy: #{recs.strategy}"
+recs.items.each { |item| puts "#{item.item_id} #{item.title}" }
+```
+
+You never choose an algorithm: LIKYLY picks the best strategy for what it knows about the visitor and tells you which one it used (`strategy`: `hybrid`, `content`, `collaborative`, `session` or `popular`). With no user, no session and no item you still get a useful answer: what is popular.
+
+### Placements: the recommended way
+
+```ruby
+# The recommended way: a placement ("pdp-related"...) is configured once in LIKYLY - strategy,
+# fallback, filters - and your page only says where it is and what it knows.
+related = likyly.placements.recommend(placement: "pdp-related", context: { item_id: "SKU-123", session_id: "sess_abc" }, limit: 4)
+puts "strategy used: #{related.strategy_used}"
+
+# When an anonymous visitor signs in, attach their session's history to their account.
+linked = likyly.events.identify(user_id: "user_123", session_id: "sess_abc")
+puts "linked: #{linked.linked_interactions}"
+```
+
+A placement (`pdp-related`, `home-for-you`, `cart-cross-sell`...) is configured once in LIKYLY, by your coding assistant through the MCP server or in the console: strategy, fallback, filters, how many items. Your code only names it and passes what it knows (`itemId`, `userId`, `sessionId`, ...); change the configuration later without redeploying. `identify` attaches an anonymous visitor's history to their account the moment they sign in, so their recommendations stay personal.
+
+### Close the loop
+
+```ruby
+# Send the recommendation_id back: LIKYLY measures which recommendations get seen, clicked and bought.
+first = recs.items.first
+likyly.events.impression(user_id: "user_123", item_id: first.item_id, recommendation_id: recs.recommendation_id, placement: "homepage")
+likyly.events.click(user_id: "user_123", item_id: first.item_id, recommendation_id: recs.recommendation_id, placement: "homepage")
+```
+
+Send the recommendation id back on the events that follow (`impression` when it is displayed, `click`, `add_to_cart`, `purchase`) and LIKYLY can measure which recommendations actually convert.
+
+## Which key?
+
+| | Secret key | Public key |
+|---|---|---|
+| Where | your server only | anywhere, including a web page |
+| Recommendations | yes | yes |
+| Record events | yes | yes |
+| Items and users (create, read, delete) | yes | no (`Likyly::PermissionDeniedError`) |
+| `debug` explanations | yes | no |
+
+The public key can only read recommendations and write events, so it is safe to expose. **Never put the secret key in code that ships to a browser or a mobile app.**
+
+```ruby
+# Where the code is exposed to visitors, use the PUBLIC key: it can only read recommendations and record events.
+front = Likyly::Client.new(
+  api_key: ENV.fetch("LIKYLY_PUBLIC_KEY")
+)
+
+# A visitor who is not logged in: use an anonymous session id (any string you generate and keep in a cookie).
+front.events.view(session_id: "sess_abc", item_id: "SKU-2")
+for_visitor = front.recommendations.get(session_id: "sess_abc", viewed_item_ids: ["SKU-2"], placement: "product_page", limit: 3)
+```
+
+## Events
+
+`track` is the one mechanism; `impression`, `view`, `click`, `add_to_cart`, `remove_from_cart` and `purchase` are shortcuts that call it with the matching type. Event types are **open strings**: use your own (`favorite`, `share`, `video_played`, ...) as freely as the official ones.
+
+```ruby
+# Any string is a valid event type: track what matters to your business.
+likyly.events.track("favorite", user_id: "user_123", item_id: "SKU-2", properties: { "list" => "wishlist" })
+
+# Up to 1000 events per call, each with its own type.
+likyly.events.track_many([
+  { type: "view", user_id: "user_123", item_id: "SKU-3" },
+  { type: "add_to_cart", user_id: "user_123", item_id: "SKU-3", quantity: 1 }
+])
+```
+
+- An event needs an item and a user, a session, or both (both ties the anonymous session to the user once they log in).
+- Anonymous visitors: generate a session id (any string) and keep it in a cookie; no login needed.
+- `properties` is a free-form object (price, currency, order id, ...). Its keys are stored exactly as you send them and are never renamed by the SDK.
+- `event_id` (idempotency key): replaying an event with the same id records nothing and returns `duplicate: true`. Set it on purchases, for example `purchase_<orderId>_<itemId>`.
+- `placement` is a free-form label of where something happened or will be displayed (`homepage`, `product_page`, `cart`, ...).
+
+## Advanced recommendations
+
+`recommendations.get` is the normal way. When you want to pick the strategy yourself:
+
+```ruby
+# Advanced Recommendations: one strategy at a time, when you want to choose.
+similar = likyly.recommendations.similar(item_id: "SKU-1", limit: 3)
+hybrid = likyly.recommendations.hybrid(user_id: "user_123", item_id: "SKU-1", alpha: 0.7, limit: 3)
+session = likyly.recommendations.session(viewed_item_ids: %w[SKU-1 SKU-2], limit: 3)
+```
+
+| Strategy | What it does |
+|---|---|
+| `popular` | The most popular items: the fallback for a visitor with no history |
+| `similar` | Items similar to one item (content similarity), no user needed |
+| `collaborative` | What users with similar histories liked. Needs a trained model, otherwise a not-found error |
+| `hybrid` | Similar items personalised for a user; `alpha` (0 to 1) weighs collaborative against content |
+| `session` | Recency-weighted, from `viewed item ids` or from a user's own view history (exactly one) |
+
+These endpoints carry ids in the URL path, so ids containing `/` (such as `gid://shopify/Product/1`) or, for the session list, `,` are refused with a validation error: use `recommendations.get`, which takes ids in the request body.
+
+## Errors
+
+Errors are typed (every one is a `Likyly::Error`). Catch the specific ones you care about:
+
+| Error | When |
+|---|---|
+| `Likyly::ValidationError` | The request is invalid: caught by the SDK before anything is sent, or a 422 from the API (the message names the offending fields) |
+| `Likyly::AuthenticationError` | 401: missing, invalid or revoked API key |
+| `Likyly::PermissionDeniedError` | 403: for example a public key used for a secret-key operation, or a plan limit |
+| `Likyly::NotFoundError` | 404 |
+| `Likyly::RateLimitError` | 429: see the retry-after value |
+| `Likyly::ApiError` | Any other error status from the API (the four rows above are its subtypes) |
+| `Likyly::NetworkError` | No HTTP response: DNS, connection reset, TLS |
+| `Likyly::TimeoutError` | The request timed out |
+
+Errors that come from the API carry `#status_code`, `#request_id`, `#retry_after` (seconds), `#body`. Quote the request id when you contact support.
+
+```ruby
+begin
+  likyly.items.get("does-not-exist")
+rescue Likyly::NotFoundError => e
+  puts "no such item, request #{e.request_id}"
+rescue Likyly::RateLimitError => e
+  puts "slow down, retry in #{e.retry_after} s"
+end
+```
+
+## Retries and timeouts
+
+The SDK retries transient failures for you (2 retries by default, exponential backoff from 0.5 s capped at 8 s, with full jitter):
+
+- **429**: always retried, honouring `Retry-After`. A `Retry-After` longer than 60 s is not waited for: the rate-limit error is returned instead.
+- **502, 503, 504, dropped connections and timeouts**: retried only when replaying the call is harmless: reads, upserts, deletes, events that carry an `event_id`, and batches where every event has one.
+- An event **without** an `event_id` is never retried after an ambiguous failure, so a flaky network can never record a purchase twice. Set `event_id` on events you care about and they become safe to retry.
+- Other 4xx errors are never retried.
+
+## Configuration
+
+| Setting | Option | Default |
+|---|---|---|
+| API key | `api_key:` | required |
+| Base URL | `base_url:` | `https://api.likyly.com` |
+| Catalog | `catalog:` | your only catalog |
+| Timeout | `timeout:` (seconds) | 10 |
+| Retries | `max_retries:` | 2 |
+| User-Agent suffix | `user_agent:` | none |
+| Custom HTTP | `transport:` (anything answering `call(method, url, headers, body, timeout)`) | `Net::HTTP` |
+
+```ruby
+tuned = Likyly::Client.new(
+  api_key: ENV.fetch("LIKYLY_SECRET_KEY"),
+  timeout: 5, # seconds per socket operation (default 10)
+  max_retries: 3, # automatic retries on 429 / 502 / 503 / 504 / network errors (default 2, 0 disables)
+  user_agent: "my-shop/1.4", # appended to the SDK's User-Agent
+)
+```
+
+Every method also accepts `timeout:` and `max_retries:` keywords.
+
+## API reference
+
+`key` says which API key may call it: **S** = secret key only, **P** = public or secret key.
+
+| Method | What it does | Key |
+|---|---|---|
+| `likyly.items.get` | One item by your own id | S |
+| `likyly.items.list` | One page of the catalog (`limit` / `offset`), with the catalog's total | S |
+| `likyly.items.upsert` | Create or replace an item (idempotent) | S |
+| `likyly.items.delete` | Remove an item (events already recorded for it are kept) | S |
+| `likyly.items.upsert_many` | Batch upsert, 1 to 1000 items | S |
+| `likyly.items.import` | Alias of the batch upsert above (JSON batch) | S |
+| `likyly.items.delete_many` | Batch delete, 1 to 1000 ids; unknown ids are reported, not raised | S |
+| `likyly.users.get` | One user profile | S |
+| `likyly.users.list` | One page of users (`limit` / `offset`) | S |
+| `likyly.users.upsert` | Create or replace a profile (free-form `properties`) | S |
+| `likyly.users.delete` | Erase the profile **and every event recorded for that user** | S |
+| `likyly.users.import` | Batch upsert of users, 1 to 1000 | S |
+| `likyly.events.track` | Record an event of any type (open string) | P |
+| `likyly.events.track_many` | Up to 1000 events in one call, each with its own type | P |
+| `likyly.events.impression` | The item was displayed to the visitor | P |
+| `likyly.events.view` | The visitor looked at the item | P |
+| `likyly.events.click` | The visitor clicked the item | P |
+| `likyly.events.add_to_cart` | The visitor added the item to their cart | P |
+| `likyly.events.remove_from_cart` | The visitor removed the item from their cart | P |
+| `likyly.events.purchase` | The visitor bought the item (set an event id) | P |
+| `likyly.events.identify` | An anonymous visitor signed in: attach their session's history to their user id | P |
+| `likyly.placements.recommend` | Recommendations for a named placement configured in LIKYLY (the recommended way) | P |
+| `likyly.recommendations.get` | Recommendations with the automatic strategy: user, session, item or viewed items | P |
+| `likyly.recommendations.popular` | Advanced: the most popular items | P |
+| `likyly.recommendations.similar` | Advanced: items similar to one item | P |
+| `likyly.recommendations.collaborative` | Advanced: what similar users liked (needs a trained model) | P |
+| `likyly.recommendations.hybrid` | Advanced: similar items personalised for a user (`alpha`) | P |
+| `likyly.recommendations.session` | Advanced: from viewed items or a user's view history | P |
+
+Lists are paginated with `limit` and `offset` (the API's default page is 100 items); the total is reported next to the page. Users have a batch `import` but no batch delete: the API has no such endpoint. `import` on items is an alias of the batch upsert (the CSV import is a dashboard feature).
+
+## Notes for Ruby
+
+- Rails: create one client in an initializer (`LIKYLY = Likyly::Client.new(api_key: Rails.application.credentials.likyly_secret_key)`); nothing in the gem depends on Rails.
+- Fields are `snake_case` keywords (`item_id:`, `recommendation_id:`); the keys inside `properties` are yours and are never renamed. Results are `Struct`s (`recs.items.first.item_id`).
+
+## Documentation and support
+
+- Documentation: <https://likyly.com/docs/sdk/ruby>
+- REST API reference (OpenAPI): <https://api.likyly.com/docs>
+- Package: likyly on RubyGems
+
+MIT licensed.

data/lib/likyly/client.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Likyly
+  # The LIKYLY client. Five things to know:
+  #
+  #   client.items            your catalog
+  #   client.users            your users (optional)
+  #   client.events           what visitors do
+  #   client.placements       what to show them, where (the recommended way)
+  #   client.recommendations  what to show them, one call or one strategy at a time
+  #
+  # A client holds no connection state: it is safe to share between threads.
+  class Client
+    attr_reader :items, :users, :events, :recommendations, :placements
+
+    # @param api_key [String] Two kinds: the **secret** key (backend only: items, users, everything) and the
+    #   **public** key (safe in a web page: recommendations and event tracking only). Never put the secret key
+    #   in code that ships to a browser.
+    # @param base_url [String] defaults to https://api.likyly.com
+    # @param catalog [String, nil] which of your catalogs to use, if your account has several. Omit it if you have
+    #   one: LIKYLY uses your only catalog.
+    # @param timeout [Numeric] per-request timeout in seconds (applied to connecting, writing and each read). Default 10.
+    # @param max_retries [Integer] automatic retries on transient failures (429, 502, 503, 504, dropped
+    #   connections). Default 2. Use 0 to disable.
+    # @param user_agent [String, nil] appended to the SDK's User-Agent, e.g. "my-shop/1.4"
+    # @param transport [#call, nil] replaces Net::HTTP: +call(method, url, headers, body, timeout)+ returning
+    #   +[status, headers, body]+ with lower-cased header names
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, catalog: nil, timeout: 10, max_retries: 2, user_agent: nil,
+                   transport: nil, sleeper: nil, random: nil)
+      unless api_key.is_a?(String) && !api_key.strip.empty?
+        raise ValidationError, "api_key is required (create one in your LIKYLY account)"
+      end
+
+      agent = "likyly-ruby/#{VERSION} ruby/#{RUBY_VERSION}"
+      agent = "#{agent} #{user_agent}" if user_agent
+      http = HttpCore.new(
+        api_key: api_key, base_url: base_url, catalog: catalog, timeout: timeout, max_retries: max_retries,
+        user_agent: agent, transport: transport || NetHttpTransport.new,
+        sleeper: sleeper || ->(seconds) { sleep(seconds) }, random: random || -> { rand }
+      )
+      @items = Items.new(http)
+      @users = Users.new(http)
+      @events = Events.new(http)
+      @recommendations = Recommendations.new(http)
+      @placements = Placements.new(http)
+    end
+  end
+end

data/lib/likyly/errors.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Likyly
+  # Every error the SDK raises is a Likyly::Error.
+  #
+  #   Likyly::Error
+  #   ├── ValidationError          invalid request - caught by the SDK before sending, or a 422 from the API
+  #   ├── NetworkError             no HTTP response (DNS, connection reset, ...)
+  #   ├── TimeoutError             the request timed out
+  #   └── ApiError                 the API answered with an error status
+  #       ├── AuthenticationError  401 - missing / invalid / revoked API key
+  #       ├── PermissionDeniedError 403 - e.g. a public key used for a secret-key operation, or a plan limit
+  #       ├── NotFoundError        404
+  #       └── RateLimitError       429 - see #retry_after
+  class Error < StandardError
+    # @return [Integer, nil] the HTTP status code, when the API answered
+    attr_reader :status_code
+    # @return [String, nil] the request_id of the failed call (also the X-Request-ID header) - quote it when reporting a problem
+    attr_reader :request_id
+    # @return [Numeric, nil] the Retry-After header in seconds (429/503), when present
+    attr_reader :retry_after
+    # @return [Object, nil] the parsed response body (Hash, Array or String), when there was one
+    attr_reader :body
+
+    def initialize(message = nil, status_code: nil, request_id: nil, retry_after: nil, body: nil, cause: nil)
+      super(message)
+      @status_code = status_code
+      @request_id = request_id
+      @retry_after = retry_after
+      @body = body
+      @cause_override = cause
+    end
+
+    def message
+      base = super
+      request_id ? "#{base} (request_id=#{request_id})" : base
+    end
+
+    def cause
+      @cause_override || super
+    end
+  end
+
+  # Invalid request: caught by the SDK before anything is sent (status_code is nil), or a 422 from the API.
+  class ValidationError < Error; end
+
+  # No HTTP response: DNS failure, connection refused or reset, TLS error, ...
+  class NetworkError < Error; end
+
+  # The request timed out (the client's `timeout`).
+  class TimeoutError < Error; end
+
+  # The API answered with an error status.
+  class ApiError < Error; end
+
+  # 401: missing, invalid or revoked API key.
+  class AuthenticationError < ApiError; end
+
+  # 403: e.g. a public key used for a secret-key operation, or a plan limit.
+  class PermissionDeniedError < ApiError; end
+
+  # 404.
+  class NotFoundError < ApiError; end
+
+  # 429: see #retry_after.
+  class RateLimitError < ApiError; end
+
+  # @api private
+  module Errors
+    module_function
+
+    def from_response(status, body, request_id, retry_after)
+      klass = case status
+              when 401 then AuthenticationError
+              when 403 then PermissionDeniedError
+              when 404 then NotFoundError
+              when 422 then ValidationError
+              when 429 then RateLimitError
+              else ApiError
+              end
+      message = message_of(body) || "API error (HTTP #{status})"
+      klass.new(message, status_code: status, request_id: request_id, retry_after: retry_after, body: body)
+    end
+
+    def message_of(body)
+      return nil unless body.is_a?(Hash)
+
+      detail = body["detail"]
+      case detail
+      when String then detail
+      when Array then detail.map { |d| d.is_a?(Hash) && d["msg"] ? d["msg"].to_s : d.to_s }.join("; ")
+      when nil then nil
+      else detail.to_s
+      end
+    end
+  end
+end

data/lib/likyly/http.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "time"
+require "uri"
+
+module Likyly
+  # The default transport: one Net::HTTP connection per request (thread-safe, no shared state). Anything that
+  # responds to +call(method, url, headers, body, timeout)+ and returns +[status, headers, body]+ (header names
+  # lower-cased) can replace it - see the +transport:+ client option.
+  class NetHttpTransport
+    def call(method, url, headers, body, timeout)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = http.read_timeout = http.write_timeout = timeout
+      request = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri, headers)
+      request.body = body if body
+      response = http.request(request)
+      [response.code.to_i, response.each_header.to_h { |k, v| [k.downcase, v] }, response.body.to_s.dup.force_encoding(Encoding::UTF_8)]
+    end
+  end
+
+  # The only place that talks HTTP. Every resource goes through #request: auth header, catalog parameter,
+  # timeout, retries with exponential backoff + jitter, and the error mapping.
+  # @api private
+  class HttpCore
+    RETRY_BASE = 0.5
+    RETRY_CAP = 8.0
+    # A Retry-After longer than this is not waited for: the RateLimitError is raised instead.
+    MAX_RETRY_AFTER = 60
+
+    Response = Struct.new(:status, :headers, :body) do
+      def json
+        JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise ApiError.new("the API answered with a body that is not the expected JSON: #{e.message}", status_code: status)
+      end
+    end
+
+    def initialize(api_key:, base_url:, catalog:, timeout:, max_retries:, user_agent:, transport:, sleeper:, random:)
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @catalog = catalog
+      @timeout = timeout
+      @max_retries = max_retries
+      @user_agent = user_agent
+      @transport = transport
+      @sleeper = sleeper
+      @random = random
+    end
+
+    # +idempotent+ says whether the call is safe to send again if its outcome is unknown (a timeout, a 5xx, a
+    # dropped connection): false for events without an event_id, where a blind retry could record the event twice.
+    def request(method, path, idempotent:, query: {}, body: nil, timeout: nil, max_retries: nil)
+      timeout ||= @timeout
+      max_retries ||= @max_retries
+      url = build_url(path, query)
+      payload = body.nil? ? nil : JSON.generate(body)
+      attempt = 0
+      begin
+        perform(method, url, payload, timeout)
+      rescue Error => e
+        delay = retry_delay(e, attempt, idempotent)
+        raise if delay.nil? || attempt >= max_retries
+
+        @sleeper.call(delay)
+        attempt += 1
+        retry
+      end
+    end
+
+    private
+
+    def build_url(path, query)
+      params = query.compact.map { |k, v| "#{Support.encode(k)}=#{Support.encode(v)}" }
+      params << "data_product_type=#{Support.encode(@catalog)}" if @catalog
+      "#{@base_url}#{path}#{params.empty? ? "" : "?#{params.join("&")}"}"
+    end
+
+    def perform(method, url, payload, timeout)
+      headers = { "X-API-Key" => @api_key, "Accept" => "application/json", "User-Agent" => @user_agent }
+      headers["Content-Type"] = "application/json" if payload
+      begin
+        status, response_headers, text = @transport.call(method, url, headers, payload, timeout)
+      rescue ::Timeout::Error => e
+        raise TimeoutError.new("request timed out after #{timeout}s", cause: e)
+      rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+        raise NetworkError.new("could not reach the API: #{e.message}", cause: e)
+      end
+
+      return Response.new(status, response_headers, text) if status < 400
+
+      body = begin
+        text.to_s.empty? ? nil : JSON.parse(text)
+      rescue JSON::ParserError
+        text # e.g. an HTML 502 page from a proxy
+      end
+      request_id = response_headers["x-request-id"] || (body.is_a?(Hash) ? body["request_id"]&.to_s : nil)
+      raise Errors.from_response(status, body, request_id, parse_retry_after(response_headers["retry-after"]))
+    end
+
+    def retry_delay(error, attempt, idempotent)
+      backoff = @random.call * [RETRY_CAP, RETRY_BASE * (2**attempt)].min # full jitter
+      case error
+      when ApiError, ValidationError
+        status = error.status_code
+        return nil if status.nil?
+
+        if status == 429
+          # Rejected by the rate limiter before reaching the application: nothing was processed, so retrying is safe for every request.
+          return after_header(error, backoff)
+        end
+        return nil unless idempotent # the outcome is unknown - never risk a duplicate
+
+        [502, 503, 504].include?(status) ? after_header(error, backoff) : nil
+      when NetworkError, TimeoutError
+        idempotent ? backoff : nil
+      end
+    end
+
+    def after_header(error, backoff)
+      return backoff if error.retry_after.nil?
+
+      error.retry_after <= MAX_RETRY_AFTER ? error.retry_after : nil
+    end
+
+    def parse_retry_after(value)
+      return nil if value.nil? || value.strip.empty?
+      return Float(value) if value.match?(/\A\s*\d+(\.\d+)?\s*\z/)
+
+      [Time.httpdate(value) - Time.now, 0].max
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/likyly/models.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Likyly
+  # Free-form properties (price, currency, orderId, category, ...) are plain Hashes whose keys are yours: the SDK
+  # never renames them. Hashes you read back have String keys, exactly as stored.
+
+  # A catalog entry. +item_id+ is your own identifier - any string (SKU-123, a UUID, gid://shopify/Product/123).
+  Item = Struct.new(:item_id, :title, :description, :properties, keyword_init: true)
+
+  # One page of the catalog. +total+ is the whole catalog's size (X-Total-Count), nil if the API did not report
+  # it; +limit+ is the page size you asked for (nil = the API's default).
+  ItemList = Struct.new(:items, :total, :limit, :offset, keyword_init: true)
+
+  # An optional user profile.
+  User = Struct.new(:user_id, :properties, keyword_init: true)
+
+  # One page of users.
+  UserList = Struct.new(:users, :total, :limit, :offset, keyword_init: true)
+
+  # One failed entry of a batch call.
+  BatchError = Struct.new(:index, :id, :message, keyword_init: true)
+
+  # Result of a batch call. A failing entry is reported in +errors+, it does not raise.
+  BatchResult = Struct.new(:received, :succeeded, :failed, :errors, keyword_init: true)
+
+  # Answer to a recorded event. +duplicate+ is true if this +event_id+ was already recorded - nothing was written.
+  EventResult = Struct.new(:message, :event_id, :duplicate, keyword_init: true) do
+    def duplicate?
+      duplicate == true
+    end
+  end
+
+  # Answer to events.track_many. +duplicates+ are events skipped because their +event_id+ was already recorded.
+  EventBatchResult = Struct.new(:received, :accepted, :duplicates, keyword_init: true)
+
+  # A user whose history contributed to a recommendation (debug, secret key only).
+  SimilarUser = Struct.new(:user_id, :shared_item_ids, keyword_init: true)
+
+  # Why an item was recommended.
+  Explanation = Struct.new(
+    :reason, :content_similarity, :semantic_similarity, :popularity_score, :interaction_count,
+    :interaction_label, :collaborative_score, :source_item_ids, :similar_users,
+    keyword_init: true
+  )
+
+  # One recommended item.
+  RecommendedItem = Struct.new(:item_id, :score, :title, :description, :properties, :explanation, keyword_init: true)
+
+  # What every recommendation call returns. Send +recommendation_id+ back on the impression / click /
+  # add_to_cart / purchase events for these items. +strategy+ is what LIKYLY used: hybrid, content,
+  # collaborative, session or popular.
+  RecommendationResponse = Struct.new(:recommendation_id, :strategy, :placement, :items, keyword_init: true)
+
+  # What placements.recommend returns. Send +recommendation_id+ back on the events that follow, like any
+  # recommendation. +strategy_used+ is what the placement actually used: hybrid, content, collaborative, session
+  # or popular.
+  PlacementRecommendation = Struct.new(:recommendation_id, :placement, :strategy_used, :items, keyword_init: true)
+
+  # Answer to events.identify: how many past interactions of the session are now attributed to the user.
+  IdentifyResult = Struct.new(:linked_interactions, keyword_init: true)
+
+  # @api private
+  module Wire
+    module_function
+
+    def item(w)
+      Item.new(item_id: w["item_id"], title: w["title"], description: w["description"], properties: w["properties"] || {})
+    end
+
+    def user(w)
+      User.new(user_id: w["user_id"], properties: w["properties"] || {})
+    end
+
+    def batch(w)
+      errors = (w["errors"] || []).map { |e| BatchError.new(index: e["index"], id: e["id"], message: e["message"]) }
+      BatchResult.new(received: w["received"], succeeded: w["succeeded"], failed: w["failed"], errors: errors)
+    end
+
+    def explanation(w)
+      Explanation.new(
+        reason: w["reason"], content_similarity: w["content_similarity"], semantic_similarity: w["semantic_similarity"],
+        popularity_score: w["popularity_score"], interaction_count: w["interaction_count"],
+        interaction_label: w["interaction_label"], collaborative_score: w["collaborative_score"],
+        source_item_ids: w["source_item_ids"],
+        similar_users: w["similar_users"]&.map { |u| SimilarUser.new(user_id: u["user_id"], shared_item_ids: u["shared_item_ids"] || []) }
+      )
+    end
+
+    def recommended_item(i)
+      RecommendedItem.new(
+        item_id: i["item_id"], score: i["score"], title: i["title"], description: i["description"],
+        properties: i["properties"] || {}, explanation: i["explanation"] ? explanation(i["explanation"]) : nil
+      )
+    end
+
+    def recommendation(w)
+      items = w["items"].map { |i| recommended_item(i) }
+      RecommendationResponse.new(recommendation_id: w["recommendation_id"], strategy: w["strategy"], placement: w["placement"], items: items)
+    end
+
+    def placement_recommendation(w)
+      PlacementRecommendation.new(
+        recommendation_id: w["recommendation_id"], placement: w["placement"], strategy_used: w["strategy_used"],
+        items: (w["items"] || []).map { |i| recommended_item(i) }
+      )
+    end
+  end
+end

data/lib/likyly/resources/events.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Likyly
+  # +client.events+ - what your visitors do. Works with the **public** key from a browser, or the secret key from
+  # your backend. +track+ is the one mechanism; +view+, +click+, ... are shortcuts that call it with the matching
+  # event type.
+  #
+  # An event needs an +item_id+ and a +user_id+ or a +session_id+ (or both: that ties an anonymous session to the
+  # user). Every event method also accepts +timeout:+ and +max_retries:+.
+  class Events
+    EVENT_TYPE = /\A[A-Za-z0-9_-]{1,64}\z/
+
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Records one event of any type: "view", "click", ... or your own ("favorite", "share", ...). Event types are
+    # open strings - the six helpers below are conveniences, not a closed list.
+    #
+    # @param type [String]
+    # @param item_id [String]
+    # @param user_id [String, nil]
+    # @param session_id [String, nil] anonymous visitor / browsing session - no login needed
+    # @param recommendation_id [String, nil] the +recommendation_id+ of the recommendation that surfaced this item - enables attribution
+    # @param placement [String, nil] free-form label of where this happened: "homepage", "product_page", "cart", ...
+    # @param quantity [Integer, nil]
+    # @param occurred_at [Time, String, nil] defaults to the server's time
+    # @param properties [Hash, nil] free-form; keys are yours
+    # @param event_id [String, nil] idempotency key, unique per account: replaying an event with the same +event_id+
+    #   records nothing and returns +duplicate: true+. Set it on purchases - it makes retries safe.
+    # @return [EventResult]
+    #
+    # Retries: a failed call is only retried automatically when it carries an +event_id+ (then a replay is
+    # harmless); without one, an ambiguous failure is raised rather than risking a duplicate.
+    def track(type, item_id: nil, user_id: nil, session_id: nil, recommendation_id: nil, placement: nil,
+              quantity: nil, occurred_at: nil, properties: nil, event_id: nil, timeout: nil, max_retries: nil)
+      body = event_body(item_id: item_id, user_id: user_id, session_id: session_id, recommendation_id: recommendation_id,
+                        placement: placement, quantity: quantity, occurred_at: occurred_at, properties: properties, event_id: event_id)
+      response = @http.request("POST", "/events/#{Support.encode(require_type(type))}", body: body, idempotent: !event_id.nil?,
+                                                                                            timeout: timeout, max_retries: max_retries).json
+      EventResult.new(message: response["message"], event_id: response["event_id"], duplicate: response["duplicate"] == true)
+    end
+
+    # Up to 1000 events in one call, each a Hash with its own +type:+. All-or-nothing validation.
+    # @param events [Array<Hash>] +{ type: "view", user_id:, item_id:, ... }+
+    # @return [EventBatchResult]
+    def track_many(events, timeout: nil, max_retries: nil)
+      raise ValidationError, "events must be a non-empty Array" unless events.is_a?(Array) && !events.empty?
+
+      entries = events.map do |e|
+        raise ValidationError, "each event must be a Hash" unless e.is_a?(Hash)
+
+        unknown = e.keys - BODY_KEYS - [:type]
+        raise ValidationError, "unknown event field#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
+
+        event_body(**BODY_KEYS.to_h { |k| [k, e[k]] }).merge("event_type" => require_type(e[:type]))
+      end
+      idempotent = events.all? { |e| !e[:event_id].nil? }
+      r = @http.request("POST", "/events/batch", body: { "events" => entries }, idempotent: idempotent, timeout: timeout, max_retries: max_retries).json
+      EventBatchResult.new(received: r["received"], accepted: r["accepted"], duplicates: r["duplicates"])
+    end
+
+    # The item was shown to the visitor (send the +recommendation_id+ it came with).
+    def impression(**event) = track("impression", **event)
+
+    # The visitor looked at the item (a product page, an article).
+    def view(**event) = track("view", **event)
+
+    # The visitor clicked the item.
+    def click(**event) = track("click", **event)
+
+    # The visitor added the item to their cart.
+    def add_to_cart(**event) = track("add_to_cart", **event)
+
+    # The visitor removed the item from their cart.
+    def remove_from_cart(**event) = track("remove_from_cart", **event)
+
+    # The visitor bought the item. Set +event_id+ (e.g. +"purchase_#{order_id}_#{item_id}"+) so a retry can never
+    # count the purchase twice.
+    def purchase(**event) = track("purchase", **event)
+
+    # Call right after login or signup, once you know +user_id+, with the +session_id+ the visitor was anonymous
+    # under: every past interaction of that session not yet attributed to a user is reassigned to +user_id+, so it
+    # counts as that user's history from then on. Safe to call more than once.
+    #
+    # @param user_id [String]
+    # @param session_id [String]
+    # @return [IdentifyResult]
+    def identify(user_id:, session_id:, timeout: nil, max_retries: nil)
+      body = { "user_id" => Support.require_id(user_id, "user_id"), "session_id" => Support.require_id(session_id, "session_id") }
+      # Only ever reassigns not-yet-attributed interactions: replaying it is harmless, so it is retried.
+      r = @http.request("POST", "/events/identify", body: body, idempotent: true, timeout: timeout, max_retries: max_retries).json
+      IdentifyResult.new(linked_interactions: r["linked_interactions"])
+    end
+
+    BODY_KEYS = %i[item_id user_id session_id recommendation_id placement quantity occurred_at properties event_id].freeze
+    private_constant :BODY_KEYS
+
+    private
+
+    def require_type(type)
+      return type if type.is_a?(String) && type.match?(EVENT_TYPE)
+
+      raise ValidationError, 'event type must be 1-64 characters of letters, digits, "_" or "-" (e.g. "view", "add_to_cart", "favorite")'
+    end
+
+    # +properties+ is passed through untouched: its keys are yours.
+    def event_body(item_id:, user_id:, session_id:, recommendation_id:, placement:, quantity:, occurred_at:, properties:, event_id:)
+      Support.require_id(item_id, "item_id")
+      raise ValidationError, "an event needs a user_id or a session_id (or both)" if user_id.nil? && session_id.nil?
+
+      Support.require_id(user_id, "user_id") unless user_id.nil?
+      Support.require_id(session_id, "session_id") unless session_id.nil?
+      Support.compact(
+        "event_id" => event_id, "user_id" => user_id, "session_id" => session_id, "item_id" => item_id,
+        "recommendation_id" => recommendation_id, "placement" => placement, "quantity" => quantity,
+        "occurred_at" => occurred_at.is_a?(Time) ? occurred_at.getutc.iso8601(3) : occurred_at,
+        "properties" => properties
+      )
+    end
+  end
+end

data/lib/likyly/resources/items.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Likyly
+  # +client.items+ - your catalog. Needs the **secret** API key.
+  #
+  # Every method also accepts +timeout:+ (seconds) and +max_retries:+ to override the client's for that call.
+  class Items
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # One item by your own id.
+    # @return [Item]
+    def get(item_id, timeout: nil, max_retries: nil)
+      id = Support.require_id(item_id, "item_id")
+      Wire.item(@http.request("GET", "/items/#{Support.encode(id)}", idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+
+    # One page of the catalog. Pagination is +limit+ + +offset+ (the API's default is 100 per page); +total+ is
+    # the whole catalog's size.
+    # @return [ItemList]
+    def list(limit: nil, offset: nil, timeout: nil, max_retries: nil)
+      response = @http.request("GET", "/items", query: { "limit" => limit, "offset" => offset }, idempotent: true, timeout: timeout, max_retries: max_retries)
+      ItemList.new(items: response.json.map { |w| Wire.item(w) }, total: total_of(response), limit: limit, offset: offset || 0)
+    end
+
+    # Creates the item, or replaces it if it exists - idempotent, safe to call as often as you like. The body is
+    # the whole item: fields you leave out are cleared.
+    # @param properties [Hash, nil] +category+ and +description+ feed content similarity; everything else is stored as is
+    # @return [Item]
+    def upsert(item_id, title: nil, description: nil, properties: nil, timeout: nil, max_retries: nil)
+      id = Support.require_id(item_id, "item_id")
+      body = item_body(title, description, properties)
+      Wire.item(@http.request("PUT", "/items/#{Support.encode(id)}", body: body, idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+
+    # Removes the item from the catalog. Events already recorded for it are kept.
+    # @return [nil]
+    def delete(item_id, timeout: nil, max_retries: nil)
+      id = Support.require_id(item_id, "item_id")
+      @http.request("DELETE", "/items/#{Support.encode(id)}", idempotent: true, timeout: timeout, max_retries: max_retries)
+      nil
+    end
+
+    # Batch upsert (1-1000 items) - each entry behaves like +upsert+. A failing entry is reported in +errors+.
+    # @param items [Array<Hash>] +{ item_id:, title:, description:, properties: }+
+    # @return [BatchResult]
+    def upsert_many(items, timeout: nil, max_retries: nil)
+      raise ValidationError, "items must be a non-empty Array" unless items.is_a?(Array) && !items.empty?
+
+      entries = items.map do |i|
+        raise ValidationError, "each item must be a Hash" unless i.is_a?(Hash)
+
+        item_body(i[:title], i[:description], i[:properties]).merge("item_id" => Support.require_id(i[:item_id], "item_id"))
+      end
+      # An upsert: replaying it changes nothing, so it is retried.
+      Wire.batch(@http.request("POST", "/items/import", body: { "items" => entries }, idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+
+    # Alias of {#upsert_many}: the API's +POST /items/import+ is a JSON batch upsert. (A CSV import exists only in
+    # the LIKYLY dashboard.)
+    def import(items, **options)
+      upsert_many(items, **options)
+    end
+
+    # Batch delete (1-1000 ids). Ids that don't exist are reported in +errors+.
+    # @return [BatchResult]
+    def delete_many(item_ids, timeout: nil, max_retries: nil)
+      raise ValidationError, "item_ids must be a non-empty Array" unless item_ids.is_a?(Array) && !item_ids.empty?
+
+      ids = item_ids.map { |id| Support.require_id(id, "item_id") }
+      Wire.batch(@http.request("POST", "/items/delete", body: { "item_ids" => ids }, idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+
+    private
+
+    def item_body(title, description, properties)
+      raise ValidationError, "an item needs a non-empty title" unless title.is_a?(String) && !title.empty?
+
+      Support.compact("title" => title, "description" => description, "properties" => properties)
+    end
+
+    def total_of(response)
+      value = response.headers["x-total-count"]
+      value && Integer(value, exception: false)
+    end
+  end
+end

data/lib/likyly/resources/placements.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Likyly
+  # +client.placements+ - the recommended way to ask for recommendations. A placement ("what to recommend, where,
+  # with what fallback and filters") is configured once, in LIKYLY (dashboard or MCP admin tools) - never from this
+  # SDK - and called by its slug from here on. +client.recommendations+ remains available for per-call use with no
+  # stored configuration.
+  #
+  # Works with the **public** key from a browser, or the secret key from your backend. Every method also accepts
+  # +timeout:+ and +max_retries:+ to override the client's for that call.
+  class Placements
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Recommendations for one placement. Send whatever context you have - the placement's own configuration
+    # decides the strategy, fallback and filters, not you. Send +recommendation_id+ back on the events that follow.
+    #
+    #   client.placements.recommend(placement: "pdp-related", context: { item_id: "SKU-456", user_id: "user_123" })
+    #
+    # @param placement [String] the placement's slug, e.g. "pdp-related"
+    # @param context [Hash, nil] what you know about this page view, all optional:
+    #   +item_id+ (the item being looked at), +category_id+, +collection_id+, +user_id+, +anonymous_id+ (stable
+    #   anonymous visitor id, used like +session_id+ when that is omitted), +session_id+, +cart_item_ids+ (Array),
+    #   +locale+, +custom_context+ (Hash, passed through untouched: its keys are yours)
+    # @param limit [Integer, nil] overrides the placement's own configured limit for this call
+    # @return [PlacementRecommendation]
+    def recommend(placement:, context: nil, limit: nil, timeout: nil, max_retries: nil)
+      slug = Support.require_id(placement, "placement")
+      unless limit.nil? || (limit.is_a?(Integer) && limit >= 1)
+        raise ValidationError, "limit must be a positive Integer"
+      end
+
+      body = Support.compact("context" => context_body(context), "limit" => limit)
+      # Each call mints a fresh recommendation_id: repeating it on a dropped connection is harmless, so it is retried.
+      response = @http.request("POST", "/placements/#{Support.encode(slug)}/recommend", body: body, idempotent: true,
+                                                                                         timeout: timeout, max_retries: max_retries)
+      Wire.placement_recommendation(response.json)
+    end
+
+    # Context key => wire name.
+    CONTEXT_KEYS = {
+      item_id: "current_item_id", category_id: "category_id", collection_id: "collection_id", user_id: "user_id",
+      anonymous_id: "anonymous_id", session_id: "session_id", cart_item_ids: "cart_item_ids", locale: "locale",
+      custom_context: "custom_context"
+    }.freeze
+    private_constant :CONTEXT_KEYS
+
+    private
+
+    def context_body(context)
+      return nil if context.nil?
+      raise ValidationError, "context must be a Hash" unless context.is_a?(Hash)
+
+      unknown = context.keys - CONTEXT_KEYS.keys
+      raise ValidationError, "unknown context field#{"s" if unknown.size > 1}: #{unknown.map(&:inspect).join(", ")}" unless unknown.empty?
+
+      Support.compact(CONTEXT_KEYS.to_h { |key, wire| [wire, context[key]] })
+    end
+  end
+end

data/lib/likyly/resources/recommendations.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Likyly
+  # +client.recommendations+. Use {#get}: send what you know and LIKYLY picks the best strategy. The other methods
+  # are the *Advanced Recommendations* - one strategy at a time.
+  #
+  # Every method also accepts +timeout:+ and +max_retries:+ to override the client's for that call.
+  class Recommendations
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # Recommendations for a user, an anonymous session, an item being viewed, viewed items - or nothing at all
+    # (then you get what is popular). You never choose the algorithm; +strategy+ in the response says what was used.
+    # Send +recommendation_id+ back on the events that follow.
+    #
+    # @param user_id [String, nil]
+    # @param session_id [String, nil]
+    # @param item_id [String, nil] the item being looked at (e.g. the product page)
+    # @param viewed_item_ids [Array<String>, nil] recently viewed items, oldest first
+    # @param placement [String, nil] free-form label of where the recommendations will be shown
+    # @param limit [Integer, nil] how many items to return (1-100, default 10)
+    # @param debug [Boolean] diagnostic detail in +explanation+. Secret key only.
+    # @return [RecommendationResponse]
+    def get(user_id: nil, session_id: nil, item_id: nil, viewed_item_ids: nil, placement: nil, limit: nil, debug: false,
+            timeout: nil, max_retries: nil)
+      body = Support.compact(
+        "user_id" => user_id.nil? ? nil : Support.require_id(user_id, "user_id"),
+        "session_id" => session_id.nil? ? nil : Support.require_id(session_id, "session_id"),
+        "item_id" => item_id.nil? ? nil : Support.require_id(item_id, "item_id"),
+        "viewed_item_ids" => viewed_item_ids&.map { |id| Support.require_id(id, "viewed_item_ids[]") },
+        "placement" => placement, "count" => limit, "debug" => debug ? true : nil
+      )
+      # A read: repeating it only mints another recommendation_id, so it is retried.
+      Wire.recommendation(@http.request("POST", "/getRec", body: body, idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+
+    # ---- Advanced Recommendations --------------------------------------------------------------------------
+    # One strategy at a time, for expert use. Ids travel in the URL path here, so they cannot contain "/".
+    # All of them also take +placement:+, +session_id:+ (attaches the recommendation to an anonymous session, for
+    # attribution) and +limit:+ (default 10).
+
+    # The most popular items - the fallback for a visitor with no history at all.
+    def popular(limit: nil, placement: nil, session_id: nil, timeout: nil, max_retries: nil)
+      advanced("/getRec/popular/#{Support.limit_of(limit)}", placement, session_id, {}, timeout, max_retries)
+    end
+
+    # Items similar to one item (content similarity). No user needed.
+    def similar(item_id:, limit: nil, placement: nil, session_id: nil, timeout: nil, max_retries: nil)
+      item = Support.require_path_safe_id(item_id, "item_id")
+      advanced("/getRec/content/#{Support.encode(item)}/#{Support.limit_of(limit)}", placement, session_id, {}, timeout, max_retries)
+    end
+
+    # Collaborative filtering: what users with similar histories liked. Needs a trained model.
+    def collaborative(user_id:, limit: nil, placement: nil, session_id: nil, timeout: nil, max_retries: nil)
+      user = Support.require_path_safe_id(user_id, "user_id")
+      advanced("/getRec/collaborative/#{Support.encode(user)}/#{Support.limit_of(limit)}", placement, session_id, {}, timeout, max_retries)
+    end
+
+    # Similar items, personalized for a user. +alpha+ (0-1) weighs the collaborative signal against content
+    # similarity: 0 = pure content, 1 = pure collaborative (the API's default is 0.5).
+    def hybrid(user_id:, item_id:, alpha: nil, limit: nil, placement: nil, session_id: nil, timeout: nil, max_retries: nil)
+      user = Support.require_path_safe_id(user_id, "user_id")
+      item = Support.require_path_safe_id(item_id, "item_id")
+      path = "/getRec/hybrid/#{Support.encode(user)}/#{Support.encode(item)}/#{Support.limit_of(limit)}"
+      advanced(path, placement, session_id, { "alpha" => alpha }, timeout, max_retries)
+    end
+
+    # Recency-weighted recommendations from what was viewed: pass +viewed_item_ids+ (an explicit list, oldest
+    # first) **or** +user_id+ (LIKYLY's own history of that user's views) - exactly one.
+    def session(viewed_item_ids: nil, user_id: nil, limit: nil, placement: nil, session_id: nil, timeout: nil, max_retries: nil)
+      if viewed_item_ids.nil? == user_id.nil?
+        raise ValidationError, "session needs either viewed_item_ids or user_id (exactly one)"
+      end
+
+      count = Support.limit_of(limit)
+      unless user_id.nil?
+        user = Support.require_path_safe_id(user_id, "user_id")
+        return advanced("/getRec/sessionForUser/#{Support.encode(user)}/#{count}", placement, session_id, {}, timeout, max_retries)
+      end
+
+      raise ValidationError, "viewed_item_ids must be a non-empty Array" unless viewed_item_ids.is_a?(Array) && !viewed_item_ids.empty?
+
+      ids = viewed_item_ids.map { |id| Support.require_id(id, "viewed_item_ids[]") }
+      if ids.any? { |id| id.include?(",") }
+        raise ValidationError, 'an item id containing "," cannot be sent in this endpoint\'s comma-separated list - use recommendations.get'
+      end
+
+      advanced("/getRec/session", placement, session_id, { "viewed_item_ids" => ids.join(","), "count" => count }, timeout, max_retries)
+    end
+
+    private
+
+    def advanced(path, placement, session_id, extra, timeout, max_retries)
+      # response_format=object: always the same {recommendation_id, strategy, items} envelope
+      query = { "response_format" => "object", "placement" => placement, "session_id" => session_id }.merge(extra)
+      Wire.recommendation(@http.request("GET", path, query: query, idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+  end
+end

data/lib/likyly/resources/users.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Likyly
+  # +client.users+ - optional user profiles. Needs the **secret** API key (profiles are personal data). You don't
+  # have to create a user before sending events for them.
+  class Users
+    # @api private
+    def initialize(http)
+      @http = http
+    end
+
+    # @return [User]
+    def get(user_id, timeout: nil, max_retries: nil)
+      id = Support.require_id(user_id, "user_id")
+      Wire.user(@http.request("GET", "/users/#{Support.encode(id)}", idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+
+    # One page of users. Pagination is +limit+ + +offset+; without +limit+ the API returns every user.
+    # @return [UserList]
+    def list(limit: nil, offset: nil, timeout: nil, max_retries: nil)
+      response = @http.request("GET", "/users", query: { "limit" => limit, "offset" => offset }, idempotent: true, timeout: timeout, max_retries: max_retries)
+      total = response.headers["x-total-count"]
+      UserList.new(users: response.json.map { |w| Wire.user(w) }, total: total && Integer(total, exception: false), limit: limit, offset: offset || 0)
+    end
+
+    # Creates or replaces the profile (idempotent). +properties+ is free-form: country, segment, language, ...
+    # @return [User]
+    def upsert(user_id, properties: nil, timeout: nil, max_retries: nil)
+      id = Support.require_id(user_id, "user_id")
+      body = Support.compact("properties" => properties)
+      Wire.user(@http.request("PUT", "/users/#{Support.encode(id)}", body: body, idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+
+    # Erases the user: the profile **and every event recorded for them**.
+    # @return [nil]
+    def delete(user_id, timeout: nil, max_retries: nil)
+      id = Support.require_id(user_id, "user_id")
+      @http.request("DELETE", "/users/#{Support.encode(id)}", idempotent: true, timeout: timeout, max_retries: max_retries)
+      nil
+    end
+
+    # Batch upsert (1-1000 users). A failing entry is reported in +errors+.
+    # @param users [Array<Hash>] +{ user_id:, properties: }+
+    # @return [BatchResult]
+    def import(users, timeout: nil, max_retries: nil)
+      raise ValidationError, "users must be a non-empty Array" unless users.is_a?(Array) && !users.empty?
+
+      entries = users.map do |u|
+        raise ValidationError, "each user must be a Hash" unless u.is_a?(Hash)
+
+        Support.compact("user_id" => Support.require_id(u[:user_id], "user_id"), "properties" => u[:properties])
+      end
+      Wire.batch(@http.request("POST", "/users/import", body: { "users" => entries }, idempotent: true, timeout: timeout, max_retries: max_retries).json)
+    end
+  end
+end

data/lib/likyly/support.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Likyly
+  # @api private
+  module Support
+    UNRESERVED = /[^A-Za-z0-9\-._~]/
+
+    module_function
+
+    # Percent-encodes a path segment: everything outside RFC 3986 "unreserved" (A-Z a-z 0-9 - . _ ~) becomes
+    # %XX (UTF-8), '/' included - so an id like "gid://shopify/Product/1" is one segment.
+    def encode(value)
+      value.to_s.dup.force_encoding(Encoding::BINARY).gsub(UNRESERVED) { |c| format("%%%02X", c.ord) }
+    end
+
+    # Ids are opaque, non-empty strings - never coerced (an Integer or a Symbol is refused).
+    def require_id(value, name)
+      return value if value.is_a?(String) && !value.strip.empty?
+
+      raise ValidationError, "#{name} must be a non-empty String (your own identifier, e.g. \"SKU-123\")"
+    end
+
+    # Advanced recommendation endpoints carry ids in the URL path, where '/' cannot be used.
+    def require_path_safe_id(value, name)
+      id = require_id(value, name)
+      if id.include?("/")
+        raise ValidationError,
+              "#{name} #{id.inspect} contains \"/\", which this endpoint cannot carry in its URL path - " \
+              "use recommendations.get, which takes ids in the request body"
+      end
+      id
+    end
+
+    # Drops nil values so optional fields are simply not sent.
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
+
+    def limit_of(limit)
+      limit = 10 if limit.nil?
+      raise ValidationError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit >= 1
+
+      limit
+    end
+  end
+end

data/lib/likyly/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Likyly
+  VERSION = "1.0.0"
+  DEFAULT_BASE_URL = "https://api.likyly.com"
+end

data/lib/likyly.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Official Ruby client for the LIKYLY recommendations API.
+#
+#   client = Likyly::Client.new(api_key: ENV.fetch("LIKYLY_SECRET_KEY"))
+#
+#   # Track what a visitor does
+#   client.events.view(user_id: "user_123", item_id: "SKU-456")
+#
+#   # Ask what to show them
+#   recs = client.recommendations.get(user_id: "user_123", placement: "homepage", limit: 8)
+#   recs.items.each { |item| puts item.item_id }
+#
+# There are two kinds of API key. The **secret** key is for your backend only (items, users, everything). The
+# **public** key is safe to expose in a web page but can only ask for recommendations and record events. Never
+# ship the secret key in code that runs on a visitor's device.
+module Likyly
+end
+
+require_relative "likyly/version"
+require_relative "likyly/errors"
+require_relative "likyly/support"
+require_relative "likyly/models"
+require_relative "likyly/http"
+require_relative "likyly/resources/items"
+require_relative "likyly/resources/users"
+require_relative "likyly/resources/events"
+require_relative "likyly/resources/recommendations"
+require_relative "likyly/resources/placements"
+require_relative "likyly/client"

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: likyly
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- LIKYLY
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: LIKYLY shows each visitor the products they are most likely to want ("You
+  may also like", "Recommended for you"). Send your catalog and what visitors do,
+  ask what to show. No runtime dependencies, no Rails required.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/likyly.rb
+- lib/likyly/client.rb
+- lib/likyly/errors.rb
+- lib/likyly/http.rb
+- lib/likyly/models.rb
+- lib/likyly/resources/events.rb
+- lib/likyly/resources/items.rb
+- lib/likyly/resources/placements.rb
+- lib/likyly/resources/recommendations.rb
+- lib/likyly/resources/users.rb
+- lib/likyly/support.rb
+- lib/likyly/version.rb
+homepage: https://www.likyly.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.likyly.com
+  documentation_uri: https://likyly.com/docs/sdk/ruby
+  source_code_uri: https://github.com/Likyly/likyly-recsys/tree/main/sdk/ruby
+  bug_tracker_uri: https://github.com/Likyly/likyly-recsys/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.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: Product recommendations for your site, learned from what your visitors do.
+  Official LIKYLY client.
+test_files: []