leash-sdk 0.3.1 → 0.4.0

data/lib/leash/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "auth"
+require_relative "env"
+require_relative "errors"
+require_relative "integrations"
+require_relative "transport"
+require_relative "types"
+
+module Leash
+  DEFAULT_PLATFORM_URL = "https://leash.build"
+
+  # Unified Leash client — namespaces for `auth`, `env`, `integrations`.
+  # Ruby mirror of `leash-sdk-ts/src/leash.ts` and `leash-sdk-python/leash/client.py`.
+  #
+  # Construction is server-only in 0.4 and requires a request object:
+  #
+  #   leash = Leash.new(request: request)        # Rails / Sinatra / Hanami / Rack hash
+  #   user = leash.auth.user                     # Leash::User or nil
+  #   key  = leash.env.get("OPENAI_API_KEY")     # String or nil
+  #   msgs = leash.integrations.gmail.list_messages(max_results: 5)
+  #
+  # Authentication precedence (mirror TS / Python / Go exactly):
+  #
+  #   1. `LEASH_API_KEY` env var (or explicit `api_key:` constructor arg)
+  #   2. `Authorization: Bearer <jwt>` header on the request — used for
+  #      `auth.user` AND as an env-read fallback (when no API key), but
+  #      NEVER forwarded on integration POSTs
+  #   3. `leash-auth` cookie from the request
+  #
+  # The Bearer fallback for env reads is documented here per the Go-reviewer
+  # callout: when the constructor sees no `LEASH_API_KEY` but does see an
+  # inbound `Authorization: Bearer …`, the bearer JWT is used as the API key
+  # for the platform's `/api/apps/me/secrets/[key]` endpoint. The bearer is
+  # still suppressed on integration POSTs (Critical #1 in the 0.4 plan).
+  class Client
+    # @return [Leash::Integrations::Namespace]
+    attr_reader :integrations
+
+    # @return [Leash::Env]
+    attr_reader :env
+
+    # @return [Auth]
+    attr_reader :auth
+
+    # @return [String]
+    attr_reader :platform_url
+
+    # @param request [Object, Hash] any Rack-conforming request (Rails
+    #   `ActionDispatch::Request`, Sinatra `Sinatra::Request`, Hanami,
+    #   a plain Rack `env` hash, or anything quacking with `.cookies` / `.env`).
+    # @param platform_url [String, nil] override the platform base URL.
+    #   Defaults to `LEASH_PLATFORM_URL` env var or `https://leash.build`.
+    # @param api_key [String, nil] explicit `LEASH_API_KEY` override.
+    # @param transport [Leash::Transport, nil] inject a transport (handy for
+    #   tests). When omitted, a default `Net::HTTP`-backed transport is built.
+    def initialize(request:, platform_url: nil, api_key: nil, transport: nil)
+      if request.nil?
+        raise Error.new(
+          "Leash requires a request object in server environments.",
+          code: "NO_REQUEST_SERVER_CONSTRUCT",
+          action: "Pass request: req to Leash.new in your route handler.",
+          see_also: "https://leash.build/docs/sdk"
+        )
+      end
+
+      @request = request
+      @platform_url = (platform_url || ENV["LEASH_PLATFORM_URL"] || DEFAULT_PLATFORM_URL)
+                      .to_s.sub(%r{/+\z}, "")
+
+      # Auth precedence: explicit api_key > LEASH_API_KEY env > bearer header > cookie.
+      env_api_key = ENV["LEASH_API_KEY"]
+      env_api_key = nil if env_api_key && env_api_key.empty?
+      @explicit_api_key = api_key || env_api_key
+
+      @bearer_token = Auth.extract_bearer_token(request)
+      @cookie_value = Auth.extract_cookie(request)
+
+      # Bearer→env fallback: when no app key is present, the inbound user
+      # JWT is used to authenticate env reads to the platform. NEVER used
+      # as `X-API-Key` on integration POSTs (see Transport docstring).
+      @env_api_key = @explicit_api_key || @bearer_token
+
+      @transport = transport || Transport.new(
+        platform_url: @platform_url,
+        api_key: @explicit_api_key,
+        cookie_value: @cookie_value
+      )
+
+      @auth = AuthFacade.new(request)
+      @env = Env.new(
+        platform_url: @platform_url,
+        api_key: @env_api_key,
+        transport: @transport
+      )
+      @integrations = Integrations::Namespace.new(@transport)
+    end
+
+    # @api private — exposed so tests can introspect resolved credentials.
+    attr_reader :bearer_token, :cookie_value, :explicit_api_key
+
+    # `leash.auth` — sync, non-throwing wrapper around {Leash::Auth.get_user}.
+    class AuthFacade
+      def initialize(request)
+        @request = request
+      end
+
+      # @return [Leash::User, nil] the authenticated user, or `nil` when not
+      #   authenticated. Never raises — swallows decode errors so handlers can
+      #   branch with a clean `if user.nil?`.
+      #
+      # Note: this method reads ONLY the `leash-auth` cookie from the request.
+      # `Authorization: Bearer <jwt>` headers are deliberately NOT used for
+      # identity resolution here — they're reserved for env-fetch fallback +
+      # CLI/agent flows. To get the user from a Bearer token, you'd hit
+      # `/api/auth/me` directly with that token.
+      def user
+        Leash::Auth.get_user(@request)
+      rescue Leash::AuthError
+        nil
+      rescue StandardError
+        nil
+      end
+
+      # @return [Boolean]
+      def authenticated?
+        !user.nil?
+      end
+    end
+  end
+
+  # `Leash.new(...)` is the idiomatic Ruby entry point. We delegate to
+  # `Client.new` so the module-level constant `Leash` stays a module
+  # (necessary because `Leash::Auth`, `Leash::Error`, etc. all live under it).
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

data/lib/leash/env.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+require_relative "errors"
+
+module Leash
+  # `leash.env` namespace — runtime env-var fetcher with a per-instance
+  # 60 s TTL cache. Mirrors the TS `leash.env.get` / `leash.env.getMany`
+  # surface and the Python `EnvNamespace` behaviour (`Optional[str]` — Ruby
+  # returns `nil` for HTTP 404 instead of raising, so callers can branch
+  # naturally).
+  class Env
+    CACHE_TTL_S = 60
+
+    attr_reader :platform_url
+
+    def initialize(platform_url:, api_key:, transport:)
+      @platform_url = platform_url.to_s.sub(%r{/+\z}, "")
+      @api_key = api_key
+      @transport = transport
+      @cache = {}
+    end
+
+    # Resolve a single env-var value.
+    #
+    # @param key [String] the env-var name (uppercase by convention)
+    # @param fresh [Boolean] skip the TTL cache for this call; the freshly
+    #   fetched value is still written back to the cache
+    # @return [String, nil] the value, or `nil` when the platform reports the
+    #   key as not declared / not found
+    # @raise [Leash::Error] for auth / invalid-key / plan / platform errors
+    def get(key, fresh: false)
+      now = monotonic_now
+      unless fresh
+        entry = @cache[key]
+        return entry[:value] if entry && entry[:expires_at] > now
+      end
+
+      value = fetch_one(key)
+      @cache[key] = { value: value, expires_at: now + CACHE_TTL_S }
+      value
+    end
+
+    # Bulk variant — resolve multiple keys sequentially against the shared
+    # TTL cache.
+    #
+    # @return [Hash{String => String, nil}]
+    def get_many(keys)
+      result = {}
+      keys.each { |k| result[k] = get(k) }
+      result
+    end
+
+    # @api private — for tests / introspection.
+    def clear_cache!
+      @cache.clear
+    end
+
+    private
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def fetch_one(key)
+      raise NoApiKeyError unless @api_key
+
+      # Use path-style percent-encoding (TS `encodeURIComponent` semantics):
+      # spaces become %20, not + (CGI.escape's form-encoding default).
+      encoded = CGI.escape(key).gsub("+", "%20")
+      url = "#{@platform_url}/api/apps/me/secrets/#{encoded}"
+
+      # Env reads use `Authorization: Bearer <api_key>` — matches the platform
+      # contract for /api/apps/me/secrets/[key] (see leash.ts line 299 + 303).
+      response = @transport.get_json(url, headers: {
+        "Authorization" => "Bearer #{@api_key}"
+      })
+
+      status = response.respond_to?(:code) ? response.code.to_i : 0
+      body = parse_json(response.respond_to?(:body) ? response.body : nil)
+
+      case status
+      when 400
+        raise Error.new(
+          "Invalid env-var key: '#{key}'.",
+          code: "INVALID_KEY",
+          action: "Env-var names must match /^[A-Za-z_][A-Za-z0-9_]*$/ and be no longer than 100 characters.",
+          see_also: "https://leash.build/docs/sdk",
+          status: 400
+        )
+      when 401
+        raise UnauthorizedError.new(
+          "Missing or invalid LEASH_API_KEY.",
+          action: "Mint a fresh API key at /dashboard/organization.",
+          see_also: "https://leash.build/dashboard/organization",
+          status: 401
+        )
+      when 402
+        required_plan = body.is_a?(Hash) ? body["requiredPlan"] : nil
+        suffix = required_plan ? " (requiredPlan: #{required_plan})" : ""
+        raise UpgradeRequiredError.new(
+          "leash.env.get requires the Growth plan or above#{suffix}.",
+          action: "Upgrade at https://leash.build/dashboard/billing.",
+          see_also: "https://leash.build/dashboard/billing",
+          status: 402
+        )
+      when 404
+        # Ruby idiom: return nil for missing keys instead of raising so
+        # callers can branch with `if value.nil?`. Mirrors Python.
+        return nil
+      when 502
+        platform_error = body.is_a?(Hash) ? body["error"] : nil
+        raise Error.new(
+          platform_error || "Secret source resync failed on the platform side.",
+          code: "SOURCE_RESYNC_FAILED",
+          action: "Check your secret source configuration in the Leash dashboard.",
+          see_also: "https://leash.build/dashboard",
+          status: 502
+        )
+      end
+
+      if status >= 400
+        raise Error.new(
+          "Unexpected response from platform: HTTP #{status}",
+          code: "ENV_FETCH_ERROR",
+          action: "Check the Leash platform status and your configuration.",
+          see_also: "https://leash.build/docs/sdk",
+          status: status
+        )
+      end
+
+      value = body.is_a?(Hash) ? body["value"] : nil
+      unless value.is_a?(String)
+        raise Error.new(
+          "Platform returned an unexpected response shape for key '#{key}'.",
+          code: "ENV_FETCH_ERROR",
+          action: "Check the Leash platform status and your configuration.",
+          see_also: "https://leash.build/docs/sdk",
+          status: status
+        )
+      end
+      value
+    end
+
+    def parse_json(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    class NoApiKeyError < Error
+      def initialize
+        super(
+          "LEASH_API_KEY is required to call leash.env.get().",
+          code: "NO_API_KEY",
+          action: "Set LEASH_API_KEY in your environment or pass api_key: ... to Leash.new.",
+          see_also: "https://leash.build/dashboard/organization"
+        )
+      end
+    end
+  end
+end

data/lib/leash/errors.rb

@@ -1,34 +1,126 @@
 # frozen_string_literal: true
 
 module Leash
-  # Base error class for all Leash SDK errors.
+  # Structured error type raised by every Leash SDK call site.
   #
-  # @attr_reader [String, nil] code the error code from the platform
-  # @attr_reader [String, nil] connect_url the OAuth connect URL (present when provider is not connected)
+  # Mirrors `leash-sdk-ts/src/errors.ts` and Python's `leash.errors.LeashError`.
+  # The `code` field is the stable machine-readable identifier consumers should
+  # switch on; `message` is the human-readable line; `action` and `see_also`
+  # are optional remediation hints.
+  #
+  # Known codes (kept in sync with leash-sdk-ts):
+  #   - NO_API_KEY
+  #   - NO_REQUEST_SERVER_CONSTRUCT
+  #   - BROWSER_MODE_UNSUPPORTED
+  #   - UNAUTHORIZED
+  #   - NO_AUTH_CONTEXT
+  #   - INTEGRATION_NOT_ENABLED
+  #   - INTEGRATION_ERROR
+  #   - UPGRADE_REQUIRED
+  #   - PLAN_BLOCK
+  #   - CONNECTION_REQUIRED
+  #   - NETWORK_ERROR
+  #   - KEY_NOT_DECLARED
+  #   - INVALID_KEY
+  #   - SOURCE_RESYNC_FAILED
+  #   - ENV_FETCH_ERROR
   class Error < StandardError
-    attr_reader :code, :connect_url
+    attr_reader :code, :action, :see_also, :status, :cause
 
-    # @param message [String] human-readable error message
-    # @param code [String, nil] machine-readable error code
-    # @param connect_url [String, nil] URL to initiate OAuth connection
-    def initialize(message, code: nil, connect_url: nil)
+    def initialize(message, code: nil, action: nil, see_also: nil, status: nil,
+                   cause: nil, connect_url: nil)
       super(message)
+      @message = message
       @code = code
+      @action = action
+      @see_also = see_also
+      @status = status
+      @cause = cause
       @connect_url = connect_url
     end
+
+    # Compatibility shim — the 0.3 surface exposed `connect_url`.
+    def connect_url
+      @connect_url
+    end
+
+    # Override `message` to return our stored value — avoids Exception#message
+    # falling back to `to_s` and recursing infinitely.
+    def message
+      @message
+    end
+
+    def to_s
+      out = +"x #{@message}"
+      out << "\n  Fix: #{@action}" if @action
+      out << "\n  See: #{@see_also}" if @see_also
+      out
+    end
+  end
+
+  # 402 from the platform — feature requires a higher plan.
+  class UpgradeRequiredError < Error
+    def initialize(message = "This feature requires a higher plan.", **opts)
+      opts[:code] ||= "UPGRADE_REQUIRED"
+      super(message, **opts)
+    end
+  end
+
+  # Alias kept for the surface contract described in the 0.4 plan
+  # (`Leash::PlanBlockError`). Same class as `UpgradeRequiredError`.
+  PlanBlockError = UpgradeRequiredError
+
+  # 403 from the platform — provider not connected for the current user.
+  class ConnectionRequiredError < Error
+    def initialize(message = "Integration not connected.", **opts)
+      opts[:code] ||= "INTEGRATION_NOT_ENABLED"
+      super(message, **opts)
+    end
+  end
+
+  # 404 on env.get — env-var key isn't declared / not found.
+  class KeyNotDeclaredError < Error
+    def initialize(message = "Key is not declared.", **opts)
+      opts[:code] ||= "KEY_NOT_DECLARED"
+      super(message, **opts)
+    end
+  end
+
+  # 401 from the platform — missing / invalid credentials.
+  class UnauthorizedError < Error
+    def initialize(message = "Unauthorized.", **opts)
+      opts[:code] ||= "UNAUTHORIZED"
+      super(message, **opts)
+    end
   end
 
-  # Raised when the provider is not connected for the current user.
-  class NotConnectedError < Error
-    def initialize(message = "Integration not connected", connect_url: nil)
-      super(message, code: "not_connected", connect_url: connect_url)
+  # Transport-level failure (DNS, refused connection, timeout, …).
+  class NetworkError < Error
+    def initialize(message = "Failed to reach the Leash platform.", **opts)
+      opts[:code] ||= "NETWORK_ERROR"
+      super(message, **opts)
     end
   end
 
-  # Raised when the OAuth token has expired and needs to be refreshed.
+  # Backwards-compat alias for the 0.3 surface — kept so existing user code
+  # `rescue Leash::NotConnectedError` keeps working.
+  NotConnectedError = ConnectionRequiredError
+
   class TokenExpiredError < Error
-    def initialize(message = "Token expired", connect_url: nil)
-      super(message, code: "token_expired", connect_url: connect_url)
+    def initialize(message = "Token expired.", **opts)
+      # Legacy code casing — kept as snake_case to preserve 0.3 behavior for
+      # callers matching on err.code. New errors use SCREAMING_SNAKE.
+      opts[:code] ||= "token_expired"
+      super(message, **opts)
+    end
+  end
+
+  # Raised by `Leash::Auth.get_user` when the leash-auth cookie is missing /
+  # invalid. `Leash#auth.user` returns `nil` instead so it never raises.
+  class AuthError < Error
+    def initialize(message = "Authentication failed", **opts)
+      opts[:code] ||= "NO_AUTH_CONTEXT"
+      super(message, **opts)
     end
   end
 end

data/lib/leash/integrations/base.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Leash
+  module Integrations
+    # @api private
+    # Internal base class — wraps a {Leash::Transport} bound to a provider id.
+    class Base
+      PROVIDER = nil
+
+      def initialize(transport)
+        @transport = transport
+      end
+
+      private
+
+      def call(action, params = nil)
+        @transport.call(self.class::PROVIDER, action, params)
+      end
+
+      # Drop nil values from a hash so we never send `{"foo":null}` payloads
+      # — mirrors the Python provider behaviour. Uses Hash#compact (Ruby 2.4+).
+      def compact_params(hash)
+        hash.compact
+      end
+    end
+
+    # Generic escape hatch — call any provider action without a typed wrapper.
+    # Returned by `leash.integrations.provider(name)`.
+    class Caller
+      def initialize(transport, name)
+        @transport = transport
+        @name = name
+      end
+
+      # Invoke `<provider>/<action>` with an optional JSON body.
+      #
+      # @param action [String] the wire action (e.g. `'post_message'`)
+      # @param body [Hash, nil] JSON body forwarded to the platform
+      def call(action, body: nil)
+        @transport.call(@name, action, body)
+      end
+
+      attr_reader :name
+    end
+  end
+end

data/lib/leash/integrations/calendar.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Leash
+  module Integrations
+    # `leash.integrations.calendar` — mirrors TS `leash.integrations.calendar`.
+    # Wire provider id is `google_calendar` (also aliased as
+    # `leash.integrations.google_calendar`).
+    class Calendar < Base
+      PROVIDER = "google_calendar"
+
+      def list_calendars
+        call("list-calendars")
+      end
+
+      # @param calendar_id [String, nil]
+      # @param time_min [String, nil] ISO 8601 timestamp
+      # @param time_max [String, nil] ISO 8601 timestamp
+      # @param max_results [Integer, nil]
+      # @param query [String, nil]
+      # @param single_events [Boolean, nil]
+      # @param order_by [String, nil]
+      def list_events(calendar_id: nil, time_min: nil, time_max: nil,
+                      max_results: nil, query: nil, single_events: nil,
+                      order_by: nil)
+        params = compact_params(
+          "calendarId" => calendar_id,
+          "timeMin" => time_min,
+          "timeMax" => time_max,
+          "maxResults" => max_results,
+          "query" => query,
+          "singleEvents" => single_events,
+          "orderBy" => order_by
+        )
+        call("list-events", params.empty? ? nil : params)
+      end
+
+      # `end_time:` keyword is used here (not `end:`) to avoid clashing with
+      # the Ruby `end` keyword — but the wire payload uses `"end"`.
+      def create_event(summary:, start:, end_time: nil, **rest)
+        # Backward-compat: accept `:end` if callers pass it via a hash splat.
+        end_time = rest.delete(:end) if end_time.nil? && rest.key?(:end)
+
+        params = {
+          "summary" => summary,
+          "start" => start,
+          "end" => end_time
+        }
+        params["calendarId"] = rest[:calendar_id] if rest[:calendar_id]
+        params["description"] = rest[:description] if rest[:description]
+        params["location"] = rest[:location] if rest[:location]
+        params["attendees"] = rest[:attendees] if rest[:attendees]
+        call("create-event", params)
+      end
+
+      def get_event(event_id, calendar_id: nil)
+        params = { "eventId" => event_id }
+        params["calendarId"] = calendar_id unless calendar_id.nil?
+        call("get-event", params)
+      end
+    end
+  end
+end

data/lib/leash/integrations/drive.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Leash
+  module Integrations
+    # `leash.integrations.drive` — mirrors TS `leash.integrations.drive`.
+    # Wire provider id is `google_drive` (also aliased as
+    # `leash.integrations.google_drive`).
+    class Drive < Base
+      PROVIDER = "google_drive"
+
+      def list_files(query: nil, max_results: nil, folder_id: nil)
+        params = compact_params(
+          "query" => query,
+          "maxResults" => max_results,
+          "folderId" => folder_id
+        )
+        call("list-files", params.empty? ? nil : params)
+      end
+
+      def get_file(file_id)
+        call("get-file", { "fileId" => file_id })
+      end
+
+      def download_file(file_id)
+        call("download-file", { "fileId" => file_id })
+      end
+
+      def create_folder(name, parent_id: nil)
+        params = { "name" => name }
+        params["parentId"] = parent_id unless parent_id.nil?
+        call("create-folder", params)
+      end
+
+      def upload_file(name:, content:, mime_type:, parent_id: nil)
+        params = { "name" => name, "content" => content, "mimeType" => mime_type }
+        params["parentId"] = parent_id unless parent_id.nil?
+        call("upload-file", params)
+      end
+
+      def delete_file(file_id)
+        call("delete-file", { "fileId" => file_id })
+      end
+
+      def search_files(query, max_results: nil)
+        params = { "query" => query }
+        params["maxResults"] = max_results unless max_results.nil?
+        call("search-files", params)
+      end
+    end
+  end
+end

data/lib/leash/integrations/gmail.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Leash
+  module Integrations
+    # `leash.integrations.gmail` — mirrors TS `leash.integrations.gmail`.
+    class Gmail < Base
+      PROVIDER = "gmail"
+
+      # @param query [String, nil] Gmail search query
+      # @param max_results [Integer, nil]
+      # @param label_ids [Array<String>, nil]
+      # @param page_token [String, nil]
+      def list_messages(query: nil, max_results: nil, label_ids: nil, page_token: nil)
+        params = compact_params(
+          "query" => query,
+          "maxResults" => max_results,
+          "labelIds" => label_ids,
+          "pageToken" => page_token
+        )
+        call("list-messages", params.empty? ? nil : params)
+      end
+
+      # @param message_id [String]
+      # @param format ['full','metadata','minimal','raw']
+      def get_message(message_id, format: "full")
+        call("get-message", { "messageId" => message_id, "format" => format })
+      end
+
+      # @param to [String]
+      # @param subject [String]
+      # @param body [String]
+      # @param cc [String, nil]
+      # @param bcc [String, nil]
+      def send_message(to:, subject:, body:, cc: nil, bcc: nil)
+        params = compact_params(
+          "to" => to, "subject" => subject, "body" => body, "cc" => cc, "bcc" => bcc
+        )
+        call("send-message", params)
+      end
+
+      # @param query [String]
+      # @param max_results [Integer, nil]
+      def search_messages(query, max_results: nil)
+        params = { "query" => query }
+        params["maxResults"] = max_results unless max_results.nil?
+        call("search-messages", params)
+      end
+
+      def list_labels
+        call("list-labels")
+      end
+
+      def get_profile
+        call("get-profile")
+      end
+    end
+  end
+end