leash-sdk 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ccdeebdeeb2eea92794836b7ae51f02cc1c048a3912483c8c410e662184c5f4
-  data.tar.gz: 9626c0261ec8d76cd14323b290c558be5df6707b0c7cdb6a7cc780feaeeee079
+  metadata.gz: 991269a688009e2da61021438552591bb13fc0e7190bfd829305cdaec602cbc3
+  data.tar.gz: 5078e8cdf009cc6143763ccb797e217c475102c823b00eef424ba3d344e41ce3
 SHA512:
-  metadata.gz: 03d22fe090135500591a41e86aadb0fe90409a0b572f43d9671362ce989737e9f238a987d4665e6a32a0d1197c1e9fb21b97039e836cfc2d1d28cea9cf4938a3
-  data.tar.gz: 5a0c39178994eff5875f52793d772b52cc0f0304d0c17bd63e6f7fce742909b8ff373ec2545a121f30c4762d0712bb5bcbb09e23e7147c43f43e77294af00485
+  metadata.gz: 9b7a6a7f0959a9ecfcdaf609f6d4c934bb417d4d453ca34a3ace8b730e18339eeb53807be07d6948c298a75867ceb36c29fa021baa557770ca5fb863c7368d77
+  data.tar.gz: 40e7ab7d68eed14ee29481cea25e669b957cb88e977c316b0f7e887c4fac93ebffbfc4c5df9308bc1cce885ff02841abe8329c2877e0128ad1bfc332c6425b91

data/Gemfile

@@ -5,3 +5,4 @@ source "https://rubygems.org"
 gemspec
 
 gem "minitest", ">= 5.0"
+gem "rake", ">= 13.0"

data/README.md

@@ -1,79 +1,196 @@
 # Leash SDK for Ruby
 
-Ruby SDK for Leash-hosted integrations.
+Server-side Ruby SDK for the [Leash](https://leash.build) platform. One client gives you:
 
-Use it to call Gmail, Google Calendar, Google Drive, and custom provider actions through the Leash platform proxy.
+- the authenticated user off the request
+- runtime env-var resolution from the Leash secret-source registry
+- typed integrations (Gmail, Google Calendar, Google Drive, Linear)
+- a generic escape hatch for any provider on the platform
+
+Framework-agnostic: works with **Rails**, **Sinatra**, **Hanami**, or plain **Rack** — no framework gems required.
 
 ## Installation
 
+Add to your `Gemfile`:
+
 ```ruby
 gem "leash-sdk"
 ```
 
-or:
+…or install directly:
 
 ```bash
 gem install leash-sdk
 ```
 
-## Quick Start
+Requires Ruby `>= 2.7` (Ruby `3.0+` recommended — 2.7 is EOL since 2023-03; system macOS Ruby 2.6.x is below the floor and will need a newer Ruby via rbenv/asdf/homebrew). The only runtime dependency is [`jwt`](https://rubygems.org/gems/jwt).
+
+## Setup
+
+Set the platform API key in your environment:
+
+```bash
+export LEASH_API_KEY=lsk_live_...
+```
+
+The constructor reads `LEASH_API_KEY` automatically; you can also pass `api_key:` explicitly.
+
+## Usage
+
+### Rails
 
 ```ruby
-require "leash"
+# app/controllers/inbox_controller.rb
+class InboxController < ApplicationController
+  def index
+    leash = Leash.new(request: request)
+
+    if leash.auth.authenticated?
+      @user = leash.auth.user                           # Leash::User or nil
+      @messages = leash.integrations.gmail.list_messages(max_results: 10)
+    else
+      redirect_to "/login"
+    end
+  end
+end
+```
 
-client = Leash::Integrations.new(
-  auth_token: ENV["LEASH_AUTH_TOKEN"],
-  api_key: ENV["LEASH_API_KEY"]
-)
+### Sinatra
+
+```ruby
+require "sinatra"
+require "leash"
 
-if client.connected?("gmail")
-  messages = client.gmail.list_messages(max_results: 5)
-  puts messages
-else
-  puts client.connect_url("gmail", return_url: "https://myapp.example.com/settings")
+get "/me" do
+  leash = Leash.new(request: request)
+  user = leash.auth.user
+  halt 401 unless user
+  user.to_h.to_json
 end
 ```
 
-## Default Platform URL
+### Plain Rack
 
-- `https://leash.build`
+```ruby
+class MyApp
+  def call(env)
+    leash = Leash.new(request: env)        # Rack `env` hash works directly
+    secret = leash.env.get("OPENAI_API_KEY")
+    [200, {}, [secret ? "ok" : "missing"]]
+  end
+end
+```
 
-## Features
+## What you get
 
-- Gmail
-- Google Calendar
-- Google Drive
-- connection status lookup
-- connect URL generation
-- generic provider calls
-- custom integration calls
-- app env fetch and caching
+### `leash.auth`
 
-## Server Auth
+```ruby
+user = leash.auth.user                     # Leash::User or nil — never raises
+leash.auth.authenticated?                  # Boolean
+```
 
-The SDK includes helpers for authenticating users on the server side by reading
-the `leash-auth` cookie set by the Leash platform.
+### `leash.env`
 
 ```ruby
-# Rails / Sinatra
-user = Leash::Auth.get_user(request)
-# => #<Leash::User id="usr_123" email="alice@example.com" name="Alice">
+key = leash.env.get("OPENAI_API_KEY")      # String or nil (nil = not declared)
+fresh = leash.env.get("STRIPE_KEY", fresh: true)
+many = leash.env.get_many(["A", "B"])      # { "A" => "...", "B" => nil }
 ```
 
-## MCP Calls
+Per-instance TTL cache: 60 seconds. Pass `fresh: true` to bypass the cache for one read.
+
+### `leash.integrations`
 
-Execute MCP-backed tools through the platform:
+Typed providers:
 
 ```ruby
-result = client.run_mcp(package: "@some/mcp-package", tool: "tool-name", args: { key: "value" })
+# Gmail
+leash.integrations.gmail.list_messages(max_results: 5)
+leash.integrations.gmail.get_message("msg-id")
+leash.integrations.gmail.send_message(to: "a@b.com", subject: "Hi", body: "Hello")
+leash.integrations.gmail.search_messages("from:x@y.com")
+leash.integrations.gmail.list_labels
+leash.integrations.gmail.get_profile
+
+# Google Calendar (also addressable as leash.integrations.google_calendar)
+leash.integrations.calendar.list_calendars
+leash.integrations.calendar.list_events(time_min: "2026-01-01T00:00:00Z")
+leash.integrations.calendar.create_event(
+  summary: "Standup",
+  start: { "dateTime" => "2026-05-15T10:00:00Z" },
+  end_time: { "dateTime" => "2026-05-15T10:30:00Z" }
+)
+leash.integrations.calendar.get_event("evt-1")
+
+# Google Drive (also addressable as leash.integrations.google_drive)
+leash.integrations.drive.list_files(query: "name contains 'q'")
+leash.integrations.drive.get_file("file-id")
+leash.integrations.drive.download_file("file-id")
+leash.integrations.drive.create_folder("Receipts", parent_id: "p-1")
+leash.integrations.drive.upload_file(name: "x.txt", content: "data", mime_type: "text/plain")
+leash.integrations.drive.delete_file("file-id")
+leash.integrations.drive.search_files("invoice")
+
+# Linear
+leash.integrations.linear.list_issues(state_type: "started")
+leash.integrations.linear.get_issue("LEA-123")
+leash.integrations.linear.create_issue(team_id: "t-1", title: "Build it")
+leash.integrations.linear.update_issue("LEA-123", priority: 1)
+leash.integrations.linear.add_comment("LEA-123", "ship it")
+leash.integrations.linear.list_teams
+leash.integrations.linear.list_projects
 ```
 
-## Notes
+Generic escape hatch for any platform-registered provider (Slack, GitHub, HubSpot, Jira, …):
+
+```ruby
+leash.integrations.provider("slack").call("post_message",
+                                            body: { "channel" => "#general", "text" => "hi" })
+```
+
+## Errors
+
+Every call raises a `Leash::Error` (or one of its subclasses) on failure:
+
+| Class                            | Raised when                                |
+|----------------------------------|--------------------------------------------|
+| `Leash::UnauthorizedError`       | platform returned 401 (missing/invalid creds) |
+| `Leash::ConnectionRequiredError` | 403 (provider not connected for this user) |
+| `Leash::UpgradeRequiredError`    | 402 (feature gated behind a higher plan)   |
+| `Leash::KeyNotDeclaredError`     | manually raised for env mis-declarations   |
+| `Leash::NetworkError`            | transport-level failures (DNS, refused, timeout) |
+| `Leash::Error`                   | base class — also raised for generic 4xx/5xx |
+
+Every error carries `code`, `message`, `action`, `see_also`, `status`, and (where present) `connect_url`.
+
+For convenience, the 0.3 aliases `Leash::NotConnectedError` and `Leash::PlanBlockError` are still available.
 
-- `auth_token` should be a valid Leash platform JWT
-- `api_key` is optional, but useful for app-scoped access
-- OAuth token handling remains a platform concern
+## Authentication precedence
+
+The constructor inspects the request in this order:
+
+1. **`LEASH_API_KEY` env var** (or explicit `api_key:` constructor arg) — server-only, never request-bound.
+2. **`Authorization: Bearer <jwt>`** header on the request — used by `auth.user` and as an env-read fallback when no API key is present. **Never** forwarded on integration POSTs.
+3. **`leash-auth` cookie** on the request — the standard browser → deployed-app session.
+
+The Bearer-token → env fallback is intentional so CLI/agent flows can read env-vars with a user JWT when no app key is provisioned. The same JWT is **never** sent on integration POSTs because the platform's `verifyToken()` rejects it before the API-key check runs, producing a misleading 401.
+
+## What's NOT in 0.4 yet
+
+- `create_dev_auth_handler` / `attach_local_dev_handler` — there's no Rack-side equivalent shipped in 0.4. (The TS SDK has a `Leash.createDevAuthHandler` for Next.js routes.) If you need a Ruby local-dev cookie-exchange flow, open an issue.
+- Legacy `LeashIntegrations` class — the 0.3 `Leash::Integrations.new(auth_token: ..., api_key: ...)` constructor and its `gmail` / `calendar` / `drive` accessors have been replaced by `Leash.new(request: ...)` + the namespaced `.integrations` accessor. The TS SDK dropped the equivalent class in 0.4 too.
+- Browser-mode usage — server-only in 0.4.
+
+If you're upgrading from 0.3.x, the `Leash::Auth.get_user(request)` helper and the `Leash::User` / `Leash::Error` / `Leash::NotConnectedError` / `Leash::TokenExpiredError` classes are kept for backwards compatibility.
+
+## Testing
+
+```bash
+bundle install
+bundle exec rake test
+```
 
 ## License
 
-Apache-2.0
+Apache 2.0.

data/leash-sdk.gemspec

@@ -8,11 +8,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Leash"]
   spec.email         = ["hello@leash.build"]
 
-  spec.summary       = "Ruby SDK for the Leash platform integrations API"
-  spec.description   = "Access Gmail, Google Calendar, Google Drive, and more through the Leash platform proxy. No API keys needed -- uses your Leash auth token."
+  spec.summary       = "Unified Ruby SDK for the Leash platform — auth, env, integrations."
+  spec.description   = "Server-side Leash client. Resolve the request user, read app env-vars at runtime, and call platform integrations (Gmail, Google Calendar, Google Drive, Linear, plus a generic escape hatch). Framework-agnostic — works with Rails, Sinatra, Hanami, or plain Rack."
   spec.homepage      = "https://github.com/leash-build/leash-sdk-ruby"
   spec.license       = "Apache-2.0"
-  spec.required_ruby_version = ">= 3.0"
+  spec.required_ruby_version = ">= 2.7"
 
   spec.metadata["homepage_uri"]    = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -22,4 +22,6 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "jwt", ">= 2.7"
+
+  spec.add_development_dependency "minitest", ">= 5.0"
 end

data/lib/leash/auth.rb

@@ -2,68 +2,46 @@
 
 require "jwt"
 require_relative "errors"
+require_relative "types"
 
 module Leash
-  # Raised when authentication fails (missing cookie, invalid/expired token, etc.)
-  class AuthError < Error
-    def initialize(message = "Authentication failed")
-      super(message, code: "auth_error")
-    end
-  end
-
-  # Simple value object representing an authenticated Leash user.
-  class User
-    attr_reader :id, :email, :name, :picture
-
-    # @param id [String]
-    # @param email [String]
-    # @param name [String, nil]
-    # @param picture [String, nil]
-    def initialize(id:, email:, name: nil, picture: nil)
-      @id = id
-      @email = email
-      @name = name
-      @picture = picture
-    end
-
-    def ==(other)
-      other.is_a?(User) &&
-        id == other.id &&
-        email == other.email &&
-        name == other.name &&
-        picture == other.picture
-    end
-  end
-
-  # Framework-agnostic server auth helper.
+  # Cookie + Bearer-token + JWT extraction across Ruby web frameworks.
+  #
+  # Mirrors the multi-framework strategy in `leash-sdk-ts/src/server/auth.ts`
+  # and `leash-sdk-python/leash/auth.py`. Designed to never raise during
+  # extraction — `extract_cookie` / `extract_bearer_token` return `nil` on
+  # any unexpected request shape so callers can branch cleanly.
   #
-  # Works with any request object that exposes either:
-  #   - request.cookies (Hash) — Rack / Rails / Sinatra
-  #   - request.env['HTTP_COOKIE'] or request.get_header('HTTP_COOKIE') — raw Rack env
+  # Supported request shapes (0.4):
+  #   * Rack hash (`{"rack.input" => …, "HTTP_COOKIE" => …}`)
+  #   * Rails `ActionDispatch::Request` (`request.cookies`, `request.headers`)
+  #   * Sinatra `Sinatra::Request` (`request.cookies`, `request.env`)
+  #   * Hanami request (responds to `:get_header`)
+  #   * Anything quacking with `.cookies` / `.env` / `.headers` / `.get_header`
   #
-  # Does NOT require rails, sinatra, or rack.
+  # Does NOT require rails, sinatra, rack, or hanami — only stdlib + jwt.
   module Auth
     COOKIE_NAME = "leash-auth"
+    AUTH_HEADER = "authorization"
 
     module_function
 
-    # Read the leash-auth JWT from the request, decode it, and return a {Leash::User}.
+    # ------------------------------------------------------------------
+    # Public helpers (kept stable from 0.3)
+    # ------------------------------------------------------------------
+
+    # Decode the request's leash-auth cookie into a {Leash::User}.
     #
-    # @param request [#cookies, #env, #get_header] any Rack-like request object
-    # @return [Leash::User]
-    # @raise [Leash::AuthError] when the cookie is missing or the token is invalid/expired
+    # @raise [Leash::AuthError] when the cookie is missing / invalid / expired.
     def get_user(request)
-      token = extract_token(request)
+      token = extract_cookie(request)
       raise AuthError, "Missing leash-auth cookie" if token.nil? || token.empty?
 
       payload = decode_token(token)
       build_user(payload)
     end
 
-    # Check whether the request carries a valid leash-auth cookie.
-    #
-    # @param request [#cookies, #env, #get_header]
-    # @return [Boolean]
+    # True when {get_user} would return a user.
     def authenticated?(request)
       get_user(request)
       true
@@ -71,52 +49,220 @@ module Leash
       false
     end
 
-    # @api private
+    # ------------------------------------------------------------------
+    # Extraction primitives
+    # ------------------------------------------------------------------
+
+    # Return the named cookie value off any request shape, or `nil`.
+    # Never raises — returns `nil` on unexpected shapes.
+    def extract_cookie(request, name = COOKIE_NAME)
+      return nil if request.nil?
+
+      from_cookie_jar(request, name) || from_cookie_header(request, name)
+    rescue StandardError
+      nil
+    end
+
+    # Backwards-compat alias for the 0.3 internal method name.
     def extract_token(request)
-      # Strategy 1: request.cookies hash (Rack / Rails / Sinatra)
-      if request.respond_to?(:cookies)
-        cookies = request.cookies
-        if cookies.is_a?(Hash)
-          value = cookies[COOKIE_NAME] || cookies[COOKIE_NAME.to_sym]
-          return value if value
+      extract_cookie(request)
+    end
+
+    # Return the JWT off `Authorization: Bearer …` if present, else `nil`.
+    # Never raises.
+    def extract_bearer_token(request)
+      return nil if request.nil?
+
+      raw = header_lookup(request, AUTH_HEADER)
+      return nil unless raw.is_a?(String)
+
+      parts = raw.split(/\s+/, 2)
+      return nil unless parts.length == 2
+
+      scheme, token = parts
+      return nil unless scheme.downcase == "bearer"
+
+      stripped = token.strip
+      return nil if stripped.empty?
+
+      stripped
+    rescue StandardError
+      nil
+    end
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    # @api private
+    def from_cookie_jar(request, name)
+      return nil unless request.respond_to?(:cookies)
+
+      cookies = request.cookies
+      return nil if cookies.nil?
+
+      if cookies.respond_to?(:[])
+        value = nil
+        begin
+          value = cookies[name]
+        rescue StandardError
+          value = nil
+        end
+        if value.nil? && cookies.respond_to?(:fetch)
+          begin
+            value = cookies.fetch(name.to_sym, nil)
+          rescue StandardError
+            value = nil
+          end
         end
+        normalised = normalise_cookie_value(value)
+        return normalised unless normalised.nil?
       end
 
-      # Strategy 2: raw Cookie header from env or get_header
+      nil
+    end
+
+    # @api private
+    def from_cookie_header(request, name)
       raw = nil
-      if request.respond_to?(:env) && request.env.is_a?(Hash)
-        raw = request.env["HTTP_COOKIE"]
-      end
-      if raw.nil? && request.respond_to?(:get_header)
-        begin
-          raw = request.get_header("HTTP_COOKIE")
+
+      if request.respond_to?(:env)
+        env = begin
+          request.env
         rescue StandardError
           nil
         end
+        if env.is_a?(Hash)
+          raw = env["HTTP_COOKIE"] || env["rack.cookie"] || env["cookie"]
+        end
       end
 
-      parse_cookie_header(raw) if raw
+      if raw.nil? && request.is_a?(Hash)
+        raw = request["HTTP_COOKIE"] ||
+              request["rack.cookie"] ||
+              request["cookie"] ||
+              request[:cookie]
+      end
+
+      if raw.nil?
+        raw = header_lookup(request, "cookie")
+      end
+
+      return nil unless raw.is_a?(String) && !raw.empty?
+
+      parse_cookie_header(raw, name)
     end
 
     # @api private
-    def parse_cookie_header(header)
+    def parse_cookie_header(header, name = COOKIE_NAME)
       return nil if header.nil?
 
       header.split(";").each do |pair|
-        key, value = pair.strip.split("=", 2)
-        return value if key == COOKIE_NAME
+        k, v = pair.strip.split("=", 2)
+        next unless k == name
+
+        return v.nil? ? nil : v
       end
       nil
     end
 
+    # @api private
+    def normalise_cookie_value(value)
+      return nil if value.nil?
+      return value if value.is_a?(String) && !value.empty?
+      return value.value if value.respond_to?(:value) && value.value.is_a?(String)
+
+      begin
+        candidate = value["value"]
+        return candidate if candidate.is_a?(String) && !candidate.empty?
+      rescue StandardError
+        nil
+      end
+      nil
+    end
+
+    # @api private
+    # Case-insensitive header lookup against any mapping or headers-like object.
+    def header_lookup(request, name)
+      lname = name.downcase
+
+      # Direct `headers` accessor (Rails / Rack / Hanami)
+      if request.respond_to?(:headers)
+        h = begin
+          request.headers
+        rescue StandardError
+          nil
+        end
+        if h
+          # Try common variants
+          [name, lname, "HTTP_#{name.upcase.tr('-', '_')}"].each do |key|
+            begin
+              val = h[key]
+              return val if val.is_a?(String) && !val.empty?
+            rescue StandardError
+              next
+            end
+          end
+          if h.respond_to?(:each)
+            begin
+              h.each do |k, v|
+                return v if k.respond_to?(:downcase) && k.downcase == lname && v.is_a?(String)
+              end
+            rescue StandardError
+              # fall through
+            end
+          end
+        end
+      end
+
+      # `get_header` accessor (Rack::Request / Hanami)
+      if request.respond_to?(:get_header)
+        begin
+          val = request.get_header("HTTP_#{name.upcase.tr('-', '_')}")
+          return val if val.is_a?(String) && !val.empty?
+        rescue StandardError
+          # ignore
+        end
+        begin
+          val = request.get_header(name)
+          return val if val.is_a?(String) && !val.empty?
+        rescue StandardError
+          # ignore
+        end
+      end
+
+      # Raw `env` hash (Rack)
+      if request.respond_to?(:env)
+        env = begin
+          request.env
+        rescue StandardError
+          nil
+        end
+        if env.is_a?(Hash)
+          val = env["HTTP_#{name.upcase.tr('-', '_')}"]
+          return val if val.is_a?(String) && !val.empty?
+        end
+      end
+
+      # Caller passed a plain Hash of headers / env directly
+      if request.is_a?(Hash)
+        ["HTTP_#{name.upcase.tr('-', '_')}", name, lname, name.capitalize].each do |key|
+          val = request[key]
+          return val if val.is_a?(String) && !val.empty?
+        end
+      end
+
+      nil
+    end
+
     # @api private
     def decode_token(token)
       secret = ENV["LEASH_JWT_SECRET"]
-      if secret && !secret.empty?
-        decoded = JWT.decode(token, secret, true, algorithms: ["HS256"])
-      else
-        decoded = JWT.decode(token, nil, false)
-      end
+      decoded = if secret && !secret.empty?
+                  JWT.decode(token, secret, true, algorithms: ["HS256"])
+                else
+                  JWT.decode(token, nil, false)
+                end
       decoded.first
     rescue JWT::ExpiredSignature
       raise AuthError, "Token has expired"
@@ -126,12 +272,12 @@ module Leash
 
     # @api private
     def build_user(payload)
-      id = payload["id"] || payload["sub"]
+      id = payload["id"] || payload["sub"] || payload["userId"]
       email = payload["email"]
       raise AuthError, "Token payload missing required fields (id/sub, email)" unless id && email
 
       User.new(
-        id: id,
+        id: id.to_s,
         email: email,
         name: payload["name"],
         picture: payload["picture"]