backlex 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01f91fb97df5e3be829a139e6f6b8ca5ed6db3ff6964e23fbe98993f88aaca36
+  data.tar.gz: 9846419c9ad1c7b62322a311538a2c88e0dbd2aa579f418c865602d07c268fcf
+SHA512:
+  metadata.gz: 9253fd5739603b9ae274ef5d80a401d7b2e18a88cffe9aaeec8fd25407be4a128cac8ae4d81fc73bb76a73ae58a19d0106300305bb271cf3df779cebc0654886
+  data.tar.gz: 56c161ee05698e5c476bb8bd1c17975baf6bd4d937e6bf1793e61241030707909c55cf0fb7cfd147a3dbf2fae4a99a5432f31a2b5d6fe2f1e4bcb94a0d50eecc

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work, excluding
+          those notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Furkan Kınyas
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,120 @@
+# backlex — Ruby SDK
+
+Official Ruby client for the backlex API. A thin wrapper over the same REST + SSE
+surface the TypeScript SDK (`@backlex/client`) speaks — CRUD, a fluent query
+builder, auth, realtime, and storage. **Zero runtime dependencies** (stdlib
+`net/http` + `json`).
+
+Part of backlex's multi-language SDK effort; follows the **hybrid** model:
+hand-written ergonomic layer here, optional OpenAPI-generated models underneath.
+
+```bash
+gem install backlex   # not yet published
+```
+
+## Quickstart
+
+```ruby
+require "backlex"
+F = Backlex::Filter
+
+client = Backlex::Client.new("https://api.example.com", api_key: "pak_...")
+
+# CRUD
+created = client.from("posts").create({ "title" => "Hello" })
+client.from("posts").update(created["data"]["id"], { "title" => "Edited" })
+client.from("posts").delete(created["data"]["id"])
+
+# Fluent query builder → compiles to canonical JSON (same wire format as every other SDK)
+rows = client.from("orders").query
+             .where(F.and_(
+                      F.eq("status", "active"),
+                      F.gte("total", 100),
+                      F.rel("customer", F.eq("tier", "gold")),   # -> "customer.tier"
+                      F.gte("placed_at", F.now(sub: { "months" => 1 }))
+                    ))
+             .select("id", "total", "customer.name")
+             .order_by("-placed_at", "id")
+             .limit(50)
+             .list
+```
+
+Ruby keywords are suffixed with `_`: `and_`, `or_`, `not_`, `in_`.
+
+## Auth
+
+```ruby
+# Server-to-server: Backlex::Client.new(url, api_key: "pak_...") — bearer on every call.
+
+# App mode — end-users of a workspace:
+client = Backlex::Client.new(url, workspace: "myapp")
+res = client.auth.sign_in("user@example.com", "secret")  # token auto-captured
+token = client.auth.token                                 # persist this
+# later: Backlex::Client.new(url, workspace: "myapp", token: token)
+client.auth.sign_out
+```
+
+`client.auth.providers` returns the public auth surface. `sign_in_social` and
+`sign_in_magic_link` are also available.
+
+## Realtime (SSE)
+
+```ruby
+sub = client.subscribe("items:posts", ->(ev) { puts "#{ev['event']}: #{ev['data']}" })
+# ... runs on a background thread, auto-reconnects ...
+sub.close
+```
+
+## Storage
+
+```ruby
+client.storage.put("avatars/me.png", bytes, content_type: "image/png")
+data = client.storage.download("avatars/me.png")
+client.storage.list("avatars/")
+client.storage.delete("avatars/me.png")
+```
+
+## Errors
+
+Every non-2xx response (and transport failures) raise `Backlex::Error` with
+`#status`, `#code`, `#details`:
+
+```ruby
+begin
+  client.from("missing").list
+rescue Backlex::Error => e
+  raise unless e.status == 404
+end
+```
+
+## Hybrid codegen
+
+For **typed models**, generate them from the OpenAPI spec the server ships — no
+Ruby-specific wire format is introduced:
+
+```bash
+openapi-generator generate \
+  -i apps/web/src/server/lib/openapi-static.generated.json \
+  -g ruby -o sdks/ruby/generated
+```
+
+## Develop
+
+```bash
+cd sdks/ruby
+ruby -Ilib test/query_test.rb     # offline: query-builder contract
+ruby -Ilib test/client_test.rb    # offline: WEBrick HTTP-layer contract
+```
+
+## Parity with the TS SDK
+
+| TS (`@backlex/client`)     | Ruby (`Backlex`)                              |
+| -------------------------- | --------------------------------------------- |
+| `createClient(opts)`       | `Backlex::Client.new(url, api_key:/workspace:/token:)` |
+| `client.from(slug)`        | `client.from(slug)`                           |
+| `.query().where(f => ...)` | `.query.where(Filter.and_(...))`              |
+| `f.eq / and / rel / now`   | `Filter.eq / and_ / rel / now`                |
+| `.orderBy().withMeta()`    | `.order_by.with_meta`                         |
+| `client.subscribe(ch, cb)` | `client.subscribe(ch, cb)` → `.close`         |
+| `auth.signIn / getToken`   | `client.auth.sign_in / token`                 |
+| `BacklexError`             | `Backlex::Error`                              |

data/lib/backlex/auth.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Backlex
+  # Auth surface. In app mode (workspace set) calls target that workspace's own
+  # auth pool ("/api/t/<slug>/auth/..."); otherwise the control plane.
+  class Auth
+    def initialize(client)
+      @client = client
+    end
+
+    def sign_up(email, password, name = nil)
+      body = { "email" => email, "password" => password }
+      body["name"] = name if name
+      capture(@client.request("POST", "#{base}/sign-up/email", body))
+    end
+
+    def sign_in(email, password)
+      capture(@client.request("POST", "#{base}/sign-in/email", { "email" => email, "password" => password }))
+    end
+
+    # Begin an OAuth sign-in; navigate the user to the returned URL.
+    def sign_in_social(provider, callback_url: nil, error_callback_url: nil)
+      body = { "provider" => provider, "disableRedirect" => true }
+      body["callbackURL"] = callback_url if callback_url
+      body["errorCallbackURL"] = error_callback_url if error_callback_url
+      @client.request("POST", "#{base}/sign-in/social", body)
+    end
+
+    # Send a one-time sign-in link by email.
+    def sign_in_magic_link(email, callback_url: nil)
+      body = { "email" => email }
+      body["callbackURL"] = callback_url if callback_url
+      @client.request("POST", "#{base}/sign-in/magic-link", body)
+    end
+
+    # Email a one-time numeric code (requires the email-otp provider). +type+ is
+    # "sign-in" (default), "email-verification" or "forget-password". Complete a
+    # sign-in with #sign_in_email_otp.
+    def send_verification_otp(email, type: "sign-in")
+      @client.request("POST", "#{base}/email-otp/send-verification-otp", { "email" => email, "type" => type })
+    end
+
+    # Complete an email-OTP sign-in with the code from #send_verification_otp. In
+    # app mode the returned session token is captured.
+    def sign_in_email_otp(email, otp)
+      capture(@client.request("POST", "#{base}/sign-in/email-otp", { "email" => email, "otp" => otp }))
+    end
+
+    # Clear the session; in app mode also drops the captured token.
+    # Send a password-reset email. +redirect_to+ is the link target.
+    def request_password_reset(email, redirect_to: nil)
+      body = { "email" => email }
+      body["redirectTo"] = redirect_to if redirect_to
+      @client.request("POST", "#{base}/request-password-reset", body)
+    end
+
+    # Complete a reset with the token from the email and a new password.
+    def reset_password(new_password, token)
+      @client.request("POST", "#{base}/reset-password", { "newPassword" => new_password, "token" => token })
+    end
+
+    # Mint a fresh access JWT from the stored session token (app mode).
+    def refresh
+      @client.request("POST", "#{base}/token/refresh", { "refreshToken" => @client.app_token })
+    end
+
+    # Change the signed-in user's password (requires the current password).
+    def change_password(new_password, current_password, revoke_other_sessions: false)
+      @client.request("POST", "#{base}/change-password", {
+                        "newPassword" => new_password,
+                        "currentPassword" => current_password,
+                        "revokeOtherSessions" => revoke_other_sessions
+                      })
+    end
+
+    # Update the signed-in user's profile (e.g. name / image).
+    def update_user(attributes)
+      @client.request("POST", "#{base}/update-user", attributes)
+    end
+
+    # Send an email-verification link.
+    def send_verification_email(email, callback_url: nil)
+      body = { "email" => email }
+      body["callbackURL"] = callback_url if callback_url
+      @client.request("POST", "#{base}/send-verification-email", body)
+    end
+
+    def sign_out
+      @client.request("POST", "#{base}/sign-out")
+      @client.app_token = nil if workspace?
+    end
+
+    # Current session payload, or { "user" => nil }.
+    def session
+      @client.request("GET", "#{base}/get-session")
+    end
+
+    # List the signed-in user's active sessions (one row per device/login).
+    def list_sessions
+      @client.request("GET", "#{base}/list-sessions")
+    end
+
+    # Revoke one session by its +token+ (from #list_sessions).
+    def revoke_session(token)
+      @client.request("POST", "#{base}/revoke-session", { "token" => token })
+    end
+
+    # Revoke every session except the current one (sign out other devices).
+    def revoke_other_sessions
+      @client.request("POST", "#{base}/revoke-other-sessions")
+    end
+
+    # Revoke all sessions, including the current one.
+    def revoke_sessions
+      @client.request("POST", "#{base}/revoke-sessions")
+    end
+
+    # Public auth surface (provider list + policy flags).
+    def providers
+      @client.request("GET", "#{base}/providers")["data"]
+    end
+
+    # Current workspace session token (app mode); persist and restore via Client.new(token:).
+    def token
+      @client.app_token
+    end
+
+    # Restore a workspace session token (app mode).
+    def token=(value)
+      @client.app_token = value
+    end
+
+    private
+
+    def workspace?
+      !(@client.workspace.nil? || @client.workspace.empty?)
+    end
+
+    def base
+      workspace? ? "/api/t/#{URI.encode_www_form_component(@client.workspace)}/auth" : "/api/auth"
+    end
+
+    def capture(result)
+      @client.app_token = result["token"] if workspace? && result.is_a?(Hash) && result["token"]
+      result
+    end
+  end
+end

data/lib/backlex/client.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Backlex
+  # The official Ruby client for the backlex API — a thin, typed wrapper over the
+  # same REST + SSE surface the TypeScript SDK (@backlex/client) speaks. Three auth
+  # modes: server key, workspace app mode (token capture), or cookie session.
+  class Client
+    attr_reader :workspace
+    attr_accessor :app_token
+
+    def initialize(url, api_key: nil, workspace: nil, token: nil, tenant: nil)
+      @url = url.chomp("/")
+      @api_key = api_key
+      @workspace = workspace
+      @app_token = token
+      @tenant = tenant
+    end
+
+    # CRUD handle for a collection.
+    def from(slug)
+      Collection.new(self, slug)
+    end
+
+    def auth
+      @auth ||= Auth.new(self)
+    end
+
+    def storage
+      @storage ||= Storage.new(self)
+    end
+
+    # Subscribe to a realtime channel (e.g. "items:posts"). Returns a Subscription;
+    # #close unsubscribes. on_error may be nil.
+    def subscribe(channel, on_event, on_error = nil)
+      Subscription.new(self, "#{@url}/api/realtime/#{channel}/subscribe", on_event, on_error)
+    end
+
+    # Raw escape hatch — issues a JSON request with auth headers applied.
+    def request(method, path, body = nil)
+      uri = URI(@url + path)
+      req = build_request(method, uri)
+      req["Content-Type"] = "application/json"
+      req.body = JSON.generate(body) unless body.nil?
+      auth_header(req)
+      res = send_request(uri, req)
+      code = res.code.to_i
+      raise Backlex::Error.from(code, res.body) if code < 200 || code >= 300
+      return nil if code == 204 || res.body.nil? || res.body.empty?
+
+      JSON.parse(res.body)
+    end
+
+    # Raw-body upload (storage). Returns the parsed JSON response.
+    def put_raw(path, body, content_type)
+      uri = URI(@url + path)
+      req = Net::HTTP::Put.new(uri)
+      req["Content-Type"] = content_type if content_type
+      req.body = body
+      auth_header(req)
+      res = send_request(uri, req)
+      code = res.code.to_i
+      raise Backlex::Error.from(code, res.body) if code < 200 || code >= 300
+
+      res.body.nil? || res.body.empty? ? nil : JSON.parse(res.body)
+    end
+
+    # Raw byte download (storage). Returns the response body string.
+    def get_raw(path)
+      uri = URI(@url + path)
+      req = Net::HTTP::Get.new(uri)
+      auth_header(req)
+      res = send_request(uri, req)
+      code = res.code.to_i
+      raise Backlex::Error.new(code, "UNKNOWN", "HTTP #{code}") if code < 200 || code >= 300
+
+      res.body
+    end
+
+    def auth_header(req)
+      if @api_key
+        req["Authorization"] = "Bearer #{@api_key}"
+      elsif @app_token
+        req["Authorization"] = "Bearer #{@app_token}"
+      end
+      req["X-Backlex-Tenant"] = @tenant if @tenant
+    end
+
+    # Serialize a ListQuery hash into a URL query string (mirrors buildSearch in
+    # index.ts). The filter is compact JSON, percent-encoded exactly once.
+    def self.build_search(query)
+      return "" if query.nil?
+
+      parts = []
+      if query[:filter] && !query[:filter].empty?
+        parts << "filter=#{URI.encode_www_form_component(JSON.generate(query[:filter]))}"
+      end
+      # sort/fields may be absent when a hand-built query (e.g. one(id, expand:)) is
+      # passed rather than a full builder-produced ListQuery — default to [].
+      parts << "sort=#{URI.encode_www_form_component(query[:sort].join(','))}" unless (query[:sort] || []).empty?
+      parts << "fields=#{URI.encode_www_form_component(query[:fields].join(','))}" unless (query[:fields] || []).empty?
+      unless (query[:expand] || []).empty?
+        parts << "expand=#{URI.encode_www_form_component(query[:expand].join(','))}"
+      end
+      parts << "limit=#{query[:limit]}" unless query[:limit].nil?
+      parts << "offset=#{query[:offset]}" unless query[:offset].nil?
+      parts << "meta=#{URI.encode_www_form_component(query[:meta])}" if query[:meta]
+      parts << "locale=#{URI.encode_www_form_component(query[:locale])}" if query[:locale]
+      parts << "q=#{URI.encode_www_form_component(query[:q])}" if query[:q]
+      parts.empty? ? "" : "?#{parts.join('&')}"
+    end
+
+    private
+
+    def build_request(method, uri)
+      case method.upcase
+      when "GET"    then Net::HTTP::Get.new(uri)
+      when "POST"   then Net::HTTP::Post.new(uri)
+      when "PATCH"  then Net::HTTP::Patch.new(uri)
+      when "PUT"    then Net::HTTP::Put.new(uri)
+      when "DELETE" then Net::HTTP::Delete.new(uri)
+      else raise ArgumentError, "unsupported method #{method}"
+      end
+    end
+
+    def send_request(uri, req)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.request(req)
+    rescue StandardError => e
+      raise Backlex::Error.new(0, "NETWORK", e.message)
+    end
+  end
+end

data/lib/backlex/collection.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Backlex
+  # A CRUD handle for one collection. Obtain via client.from("slug").
+  class Collection
+    def initialize(client, slug)
+      @client = client
+      @slug = slug
+    end
+
+    def list(query = nil)
+      @client.request("GET", "/api/items/#{@slug}#{Client.build_search(query)}")
+    end
+
+    # Fluent builder that compiles to a ListQuery.
+    def query
+      QueryBuilder.new(method(:list))
+    end
+
+    # Single-function aggregate (count/sum/avg/min/max), optionally grouped.
+    # body = { "agg" => "sum", "field" => "price", "groupBy" => "status" }
+    def aggregate(body)
+      @client.request("POST", "/api/items/#{@slug}/aggregate", body)
+    end
+
+    # query may carry expand/locale, the same params the list endpoint accepts.
+    def one(id, query = nil)
+      @client.request("GET", "/api/items/#{@slug}/#{id}#{Client.build_search(query)}")
+    end
+
+    def create(data)
+      @client.request("POST", "/api/items/#{@slug}", data)
+    end
+
+    def update(id, patch)
+      @client.request("PATCH", "/api/items/#{@slug}/#{id}", patch)
+    end
+
+    def delete(id)
+      @client.request("DELETE", "/api/items/#{@slug}/#{id}")
+    end
+
+    # Flip a versioned item to published.
+    def publish(id)
+      @client.request("POST", "/api/items/#{@slug}/#{id}/publish")
+    end
+
+    # Flip a versioned item back to draft.
+    def unpublish(id)
+      @client.request("POST", "/api/items/#{@slug}/#{id}/publish?unpublish=1")
+    end
+  end
+end

data/lib/backlex/error.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Backlex
+  # A non-2xx response from the backlex API (or a transport failure), mirroring
+  # the TS SDK's BacklexError. The API returns errors as
+  # `{ "error": { "code", "message", "details"? } }`; callers branch on #status /
+  # #code rather than parsing strings.
+  class Error < StandardError
+    attr_reader :status, :code, :details
+
+    def initialize(status, code, message, details = nil)
+      super(message)
+      @status = status
+      @code = code
+      @details = details
+    end
+
+    # Parse the `{ "error": {...} }` envelope from a response body.
+    def self.from(status, body)
+      code = "UNKNOWN"
+      message = "HTTP #{status}"
+      details = nil
+      unless body.nil? || body.empty?
+        begin
+          env = JSON.parse(body)
+          err = env["error"]
+          if err.is_a?(Hash)
+            code = err["code"] if err["code"]
+            message = err["message"] if err["message"]
+            details = err["details"]
+          end
+        rescue JSON::ParserError
+          # non-JSON error body — keep the generic message
+        end
+      end
+      new(status, code, message, details)
+    end
+  end
+end

data/lib/backlex/filter.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Backlex
+  # Static condition constructors — a Ruby port of the leaf/logical helpers in
+  # query.ts. Compose them and pass to QueryBuilder#where. Everything compiles to
+  # the canonical JSON Condition the REST API speaks.
+  #
+  #   rows = client.from("orders").query
+  #     .where(Backlex::Filter.and_(
+  #       Backlex::Filter.eq("status", "active"),
+  #       Backlex::Filter.gte("total", 100),
+  #       Backlex::Filter.rel("customer", Backlex::Filter.eq("tier", "gold")), # -> "customer.tier"
+  #       Backlex::Filter.gte("placed_at", Backlex::Filter.now(sub: { "months" => 1 })),
+  #     ))
+  #     .select("id", "total", "customer.name")
+  #     .order_by("-placed_at", "id")
+  #     .limit(50)
+  #     .list
+  module Filter
+    module_function
+
+    def leaf(field, op, value)
+      { field => { op => value } }
+    end
+
+    def eq(f, v); leaf(f, "_eq", v); end
+    def neq(f, v); leaf(f, "_neq", v); end
+    def gt(f, v); leaf(f, "_gt", v); end
+    def gte(f, v); leaf(f, "_gte", v); end
+    def lt(f, v); leaf(f, "_lt", v); end
+    def lte(f, v); leaf(f, "_lte", v); end
+    def in_(f, vs); leaf(f, "_in", vs); end
+    def nin(f, vs); leaf(f, "_nin", vs); end
+    def between(f, lo, hi); leaf(f, "_between", [lo, hi]); end
+    def is_null(f, is_null = true); leaf(f, "_null", is_null); end
+    def empty(f); leaf(f, "_empty", true); end
+    def nempty(f); leaf(f, "_nempty", true); end
+    def contains(f, v); leaf(f, "_contains", v); end
+    def icontains(f, v); leaf(f, "_icontains", v); end
+    def starts_with(f, v); leaf(f, "_starts_with", v); end
+    def ends_with(f, v); leaf(f, "_ends_with", v); end
+
+    def and_(*conds); { "$and" => conds }; end
+    def or_(*conds); { "$or" => conds }; end
+    def not_(cond); { "$not" => cond }; end
+
+    # Traverse a relation one hop: every leaf key produced by +conds+ is prefixed
+    # with "head.". Multiple conds are ANDed first.
+    def rel(head, *conds)
+      inner = conds.length == 1 ? conds[0] : { "$and" => conds }
+      prefix_keys(inner, head)
+    end
+
+    # Relative-date value, e.g. Filter.now(sub: { "months" => 1 }).
+    def now(add: nil, sub: nil)
+      opts = {}
+      opts["add"] = add if add
+      opts["sub"] = sub if sub
+      { "$now" => opts }
+    end
+
+    def prefix_keys(cond, head)
+      return { "$and" => cond["$and"].map { |c| prefix_keys(c, head) } } if cond["$and"].is_a?(Array)
+      return { "$or" => cond["$or"].map { |c| prefix_keys(c, head) } } if cond["$or"].is_a?(Array)
+      return { "$not" => prefix_keys(cond["$not"], head) } if cond["$not"].is_a?(Hash)
+
+      out = {}
+      cond.each { |k, v| out["#{head}.#{k}"] = v }
+      out
+    end
+
+    # Turn any accepted filter shape into the canonical Condition: handles
+    # $and/$or/$not (and their _ aliases) and implicit equality
+    # ({ "status" => "active" } -> { "status" => { "_eq" => "active" } }). Idempotent.
+    def normalize(raw)
+      return {} unless raw.is_a?(Hash)
+
+      a = raw["$and"] || raw["_and"]
+      return { "$and" => a.map { |c| normalize(c) } } if a.is_a?(Array)
+
+      o = raw["$or"] || raw["_or"]
+      return { "$or" => o.map { |c| normalize(c) } } if o.is_a?(Array)
+
+      if raw.key?("$not") || raw.key?("_not")
+        return { "$not" => normalize(raw["$not"] || raw["_not"]) }
+      end
+
+      out = {}
+      raw.each do |k, v|
+        out[k] =
+          if v.is_a?(Hash) && comparison?(v) then v
+          elsif v.is_a?(Hash) then v # unknown object shape — pass through
+          else { "_eq" => v }
+          end
+      end
+      out
+    end
+
+    def comparison?(hash)
+      !hash.empty? && hash.keys.all? { |k| k.to_s.start_with?("_") }
+    end
+  end
+end

data/lib/backlex/query_builder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Backlex
+  # Chainable builder that compiles to a ListQuery hash and runs it.
+  class QueryBuilder
+    def initialize(list_fn)
+      @list_fn = list_fn
+      @q = { filter: nil, sort: [], fields: [], expand: [], limit: nil, offset: nil, meta: nil, locale: nil, q: nil }
+    end
+
+    def where(cond)
+      @q[:filter] = Filter.normalize(cond)
+      self
+    end
+
+    # Replace the filter with a raw canonical condition (escape hatch).
+    def filter(cond)
+      @q[:filter] = Filter.normalize(cond)
+      self
+    end
+
+    def select(*fields)
+      @q[:fields].concat(fields)
+      self
+    end
+
+    def order_by(*sorts)
+      @q[:sort].concat(sorts)
+      self
+    end
+
+    # Inline single-hop relations (replaces each FK with the related object).
+    def expand(*rels)
+      @q[:expand].concat(rels)
+      self
+    end
+
+    # Project i18n_text fields to one locale, or "*" for the full map.
+    def locale(loc)
+      @q[:locale] = loc
+      self
+    end
+
+    # Free-text search across readable text fields.
+    def search(text)
+      @q[:q] = text
+      self
+    end
+
+    def limit(n)
+      @q[:limit] = n
+      self
+    end
+
+    def offset(n)
+      @q[:offset] = n
+      self
+    end
+
+    # Request an extra COUNT: "filter_count", "total_count", or "*".
+    def with_meta(m)
+      @q[:meta] = m
+      self
+    end
+
+    # The assembled ListQuery hash — the canonical input the API takes.
+    def to_query
+      @q
+    end
+
+    def list
+      @list_fn.call(@q)
+    end
+  end
+end

data/lib/backlex/realtime.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Backlex
+  # Handle for an active realtime subscription. #close unsubscribes — the same
+  # contract as the TS SDK's returned unsubscribe function. The reader runs on a
+  # background thread and auto-reconnects on a dropped stream (3s back-off),
+  # replaying via Last-Event-ID.
+  class Subscription
+    def initialize(client, url, on_event, on_error)
+      @stopped = false
+      @thread = Thread.new { run(client, url, on_event, on_error) }
+    end
+
+    def close
+      @stopped = true
+      @thread&.kill
+    end
+
+    private
+
+    def run(client, url, on_event, on_error)
+      last_id = nil
+      until @stopped
+        begin
+          uri = URI(url)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+            req = Net::HTTP::Get.new(uri)
+            req["Accept"] = "text/event-stream"
+            client.auth_header(req)
+            req["Last-Event-ID"] = last_id if last_id
+            http.request(req) do |res|
+              if res.code.to_i != 200
+                on_error&.call(Backlex::Error.new(res.code.to_i, "UNKNOWN", "HTTP #{res.code}"))
+                next
+              end
+              last_id = read_stream(res, on_event, on_error, last_id)
+            end
+          end
+        rescue StandardError => e
+          on_error&.call(e) unless @stopped
+        end
+        break if @stopped
+
+        sleep 3
+      end
+    end
+
+    # Parse the SSE byte stream, buffering across chunk boundaries.
+    def read_stream(res, on_event, on_error, last_id)
+      buffer = +""
+      data = []
+      res.read_body do |chunk|
+        break if @stopped
+
+        buffer << chunk
+        while (idx = buffer.index("\n"))
+          line = buffer.slice!(0, idx + 1).chomp
+          if line.empty?
+            unless data.empty?
+              payload = data.join("\n")
+              data = []
+              begin
+                on_event.call(JSON.parse(payload))
+              rescue StandardError => e
+                on_error&.call(e)
+              end
+            end
+          elsif line.start_with?(":")
+            # comment / heartbeat
+          elsif line.start_with?("id:")
+            last_id = line[3..].strip
+          elsif line.start_with?("data:")
+            d = line[5..]
+            d = d[1..] if d.start_with?(" ")
+            data << d
+          end
+        end
+      end
+      last_id
+    end
+  end
+end

data/lib/backlex/storage.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Backlex
+  # File operations against /api/storage.
+  class Storage
+    def initialize(client)
+      @client = client
+    end
+
+    # List stored objects, optionally filtered by key prefix.
+    def list(prefix = nil)
+      path = "/api/storage"
+      path += "?prefix=#{URI.encode_www_form_component(prefix)}" if prefix && !prefix.empty?
+      @client.request("GET", path)["data"]
+    end
+
+    # Upload bytes under +key+. Pass content_type/folder_id nil to omit them.
+    def put(key, body, content_type: nil, folder_id: nil)
+      path = "/api/storage/#{URI.encode_www_form_component(key)}"
+      path += "?folderId=#{URI.encode_www_form_component(folder_id)}" if folder_id
+      @client.put_raw(path, body, content_type)
+    end
+
+    # Fetch the raw bytes for +key+.
+    def download(key)
+      @client.get_raw("/api/storage/#{URI.encode_www_form_component(key)}")
+    end
+
+    # Remove the object at +key+.
+    def delete(key)
+      @client.request("DELETE", "/api/storage/#{URI.encode_www_form_component(key)}")
+    end
+  end
+end

data/lib/backlex.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Official Ruby client for the backlex API.
+#
+#   require "backlex"
+#   client = Backlex::Client.new("https://api.example.com", api_key: "pak_...")
+#   posts = client.from("posts").query.where(Backlex::Filter.eq("published", true)).list
+module Backlex
+  VERSION = "0.0.1"
+end
+
+require_relative "backlex/error"
+require_relative "backlex/filter"
+require_relative "backlex/query_builder"
+require_relative "backlex/collection"
+require_relative "backlex/auth"
+require_relative "backlex/storage"
+require_relative "backlex/realtime"
+require_relative "backlex/client"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: backlex
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- backlex
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-17 00:00:00.000000000 Z
+dependencies: []
+description: A thin, typed wrapper over the backlex REST + SSE API. Zero runtime dependencies
+  (stdlib net/http + json).
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/backlex.rb
+- lib/backlex/auth.rb
+- lib/backlex/client.rb
+- lib/backlex/collection.rb
+- lib/backlex/error.rb
+- lib/backlex/filter.rb
+- lib/backlex/query_builder.rb
+- lib/backlex/realtime.rb
+- lib/backlex/storage.rb
+homepage: https://backlex.com
+licenses:
+- Apache-2.0
+metadata:
+  documentation_uri: https://backlex.com/docs/client-sdks
+  source_code_uri: https://github.com/backlex/backlex
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby client for the backlex API (CRUD, query builder, auth, realtime,
+  storage).
+test_files: []