leash-sdk 0.3.1 → 0.4.0

data/lib/leash/integrations/linear.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Leash
+  module Integrations
+    # `leash.integrations.linear` — mirrors TS `leash.integrations.linear`.
+    #
+    # The Linear MCP uses underscored action names on the wire (`list_issues`,
+    # `get_issue`, …) — preserved here. List responses can come back as either
+    # a bare array or an envelope hash; the SDK tolerates both shapes.
+    class Linear < Base
+      PROVIDER = "linear"
+
+      def list_issues(team_id: nil, assignee_id: nil, state_type: nil,
+                      limit: nil, cursor: nil)
+        params = compact_params(
+          "teamId" => team_id,
+          "assigneeId" => assignee_id,
+          "stateType" => state_type,
+          "limit" => limit,
+          "cursor" => cursor
+        )
+
+        raw = call("list_issues", params)
+        case raw
+        when Array
+          { "issues" => raw }
+        when Hash
+          out = { "issues" => raw["issues"] || [] }
+          out["cursor"] = raw["cursor"] if raw["cursor"]
+          out
+        else
+          { "issues" => [] }
+        end
+      end
+
+      def get_issue(id)
+        call("get_issue", { "id" => id })
+      end
+
+      def create_issue(team_id:, title:, description: nil, assignee_id: nil,
+                       priority: nil, label_ids: nil)
+        params = { "teamId" => team_id, "title" => title }
+        params["description"] = description unless description.nil?
+        params["assigneeId"] = assignee_id unless assignee_id.nil?
+        params["priority"] = priority unless priority.nil?
+        params["labelIds"] = label_ids unless label_ids.nil?
+        call("create_issue", params)
+      end
+
+      def update_issue(id, title: nil, description: nil, assignee_id: nil,
+                       priority: nil, label_ids: nil, team_id: nil)
+        params = { "id" => id }
+        params["title"] = title unless title.nil?
+        params["description"] = description unless description.nil?
+        params["assigneeId"] = assignee_id unless assignee_id.nil?
+        params["priority"] = priority unless priority.nil?
+        params["labelIds"] = label_ids unless label_ids.nil?
+        params["teamId"] = team_id unless team_id.nil?
+        call("update_issue", params)
+      end
+
+      def add_comment(issue_id, body)
+        call("add_comment", { "issueId" => issue_id, "body" => body })
+      end
+
+      def list_teams
+        raw = call("list_teams", {})
+        case raw
+        when Array then raw
+        when Hash  then raw["teams"] || []
+        else            []
+        end
+      end
+
+      def list_projects(team_id: nil)
+        params = compact_params("teamId" => team_id)
+        raw = call("list_projects", params)
+        case raw
+        when Array then raw
+        when Hash  then raw["projects"] || []
+        else            []
+        end
+      end
+    end
+  end
+end

data/lib/leash/integrations.rb

@@ -1,319 +1,43 @@
 # frozen_string_literal: true
 
-require "net/http"
-require "json"
-require "uri"
-
-require_relative "errors"
-require_relative "custom_integration"
-require_relative "gmail"
-require_relative "calendar"
-require_relative "drive"
+require_relative "integrations/base"
+require_relative "integrations/gmail"
+require_relative "integrations/calendar"
+require_relative "integrations/drive"
+require_relative "integrations/linear"
 
 module Leash
-  DEFAULT_PLATFORM_URL = "https://leash.build"
-
-  # Main client for accessing Leash platform integrations.
-  #
-  # @example
-  #   client = Leash::Integrations.new(auth_token: "your-jwt-token")
-  #   messages = client.gmail.list_messages(query: "is:unread")
-  #   events = client.calendar.list_events(time_min: "2026-04-10T00:00:00Z")
-  #   files = client.drive.list_files
-  class Integrations
-    # @param auth_token [String] the leash-auth JWT token
-    # @param platform_url [String] base URL of the Leash platform API
-    # @param api_key [String, nil] optional API key for server-to-server auth
-    def initialize(auth_token:, platform_url: DEFAULT_PLATFORM_URL, api_key: nil)
-      @auth_token = auth_token
-      @platform_url = platform_url.chomp("/")
-      @api_key = api_key || ENV["LEASH_API_KEY"]
-    end
-
-    # Gmail integration client.
-    #
-    # @return [GmailClient]
-    def gmail
-      @gmail ||= GmailClient.new(method(:call))
-    end
-
-    # Google Calendar integration client.
-    #
-    # @return [CalendarClient]
-    def calendar
-      @calendar ||= CalendarClient.new(method(:call))
-    end
-
-    # Google Drive integration client.
-    #
-    # @return [DriveClient]
-    def drive
-      @drive ||= DriveClient.new(method(:call))
-    end
-
-    # Access a custom integration by name. Returns an untyped client.
-    #
-    # @param name [String] the custom integration name
-    # @return [CustomIntegration]
-    #
-    # @example
-    #   stripe = client.integration("stripe")
-    #   charges = stripe.call("/v1/charges", method: "GET")
-    def integration(name)
-      CustomIntegration.new(name, method(:call_custom))
-    end
-
-    # Generic proxy call for any provider action.
-    #
-    # @param provider [String] integration provider name (e.g. "gmail")
-    # @param action [String] action to perform (e.g. "list-messages")
-    # @param params [Hash, nil] optional request body parameters
-    # @return [Object] the "data" field from the platform response
-    # @raise [Leash::NotConnectedError] if the provider is not connected
-    # @raise [Leash::TokenExpiredError] if the OAuth token has expired
-    # @raise [Leash::Error] if the platform returns a non-success response
-    def call(provider, action, params = nil)
-      uri = URI("#{@platform_url}/api/integrations/#{provider}/#{action}")
-
-      request = Net::HTTP::Post.new(uri)
-      request["Content-Type"] = "application/json"
-      request["Authorization"] = "Bearer #{@auth_token}"
-      request["X-API-Key"] = @api_key if @api_key
-      request.body = (params || {}).to_json
-
-      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
-        http.request(request)
-      end
-
-      data = JSON.parse(response.body)
-
-      unless data["success"]
-        raise_error(data)
-      end
-
-      data["data"]
-    end
-
-    # Check if a provider is connected for the current user.
-    #
-    # @param provider_id [String] the provider identifier (e.g. "gmail")
-    # @return [Boolean]
-    def connected?(provider_id)
-      conn = connections.find { |c| c["providerId"] == provider_id }
-      conn&.dig("status") == "active"
-    rescue StandardError
-      false
-    end
-
-    # Get connection status for all providers.
-    #
-    # @return [Array<Hash>] list of connection status hashes
-    def connections
-      uri = URI("#{@platform_url}/api/integrations/connections")
-
-      request = Net::HTTP::Get.new(uri)
-      request["Authorization"] = "Bearer #{@auth_token}"
-      request["X-API-Key"] = @api_key if @api_key
-
-      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
-        http.request(request)
-      end
-
-      data = JSON.parse(response.body)
-
-      unless data["success"]
-        raise_error(data)
-      end
-
-      data["data"] || []
-    end
-
-    # Get the URL to connect a provider (for UI buttons).
-    #
-    # @param provider_id [String] the provider identifier
-    # @param return_url [String, nil] optional URL to redirect back to after connecting
-    # @return [String] the full URL to initiate the OAuth connection flow
-    def connect_url(provider_id, return_url: nil)
-      url = "#{@platform_url}/api/integrations/connect/#{provider_id}"
-      url += "?return_url=#{URI.encode_www_form_component(return_url)}" if return_url
-      url
-    end
-
-    # Get the user's current access token for a provider -- built-in or
-    # org-registered (LEA-142). Lets you call third-party APIs directly
-    # without proxying every request through Leash. Refresh-on-expiry
-    # happens transparently on the platform side.
-    #
-    # @param provider [String] the provider slug (e.g. "slack", "gmail")
-    # @return [String] the access token
-    # @raise [Leash::NotConnectedError] if the user hasn't completed the OAuth flow
-    # @raise [Leash::TokenExpiredError] if the token is expired and cannot be refreshed
-    # @raise [Leash::Error] if the platform returns a non-success response
-    def get_access_token(provider)
-      uri = URI("#{@platform_url}/api/integrations/token")
-
-      request = Net::HTTP::Post.new(uri)
-      request["Content-Type"] = "application/json"
-      request["Authorization"] = "Bearer #{@auth_token}" if @auth_token
-      request["X-API-Key"] = @api_key if @api_key
-      request.body = { provider: provider }.to_json
-
-      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
-        http.request(request)
-      end
-
-      data = JSON.parse(response.body)
-
-      unless data["success"]
-        raise_error(data)
-      end
-
-      data["data"]["accessToken"]
-    end
-
-    # Get the resolved config for a customer-registered MCP server (LEA-143).
-    # Returns the customer's MCP URL plus auth headers (e.g. +Authorization:
-    # Bearer ...+ for bearer-auth servers) -- feed this directly into your
-    # MCP client. Leash isn't on the MCP request path.
-    #
-    # @param slug [String] the MCP server slug
-    # @return [Hash] hash with "slug", "displayName", "url", and "headers"
-    # @raise [Leash::Error] if the platform returns a non-success response
-    #   (e.g. code +unknown_mcp_server+)
-    def get_custom_mcp_config(slug)
-      uri = URI("#{@platform_url}/api/integrations/mcp-config/#{URI.encode_www_form_component(slug)}")
-
-      request = Net::HTTP::Get.new(uri)
-      request["Authorization"] = "Bearer #{@auth_token}" if @auth_token
-      request["X-API-Key"] = @api_key if @api_key
-
-      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
-        http.request(request)
-      end
-
-      data = JSON.parse(response.body)
-
-      unless data["success"]
-        raise_error(data)
-      end
-
-      data["data"]
-    end
-
-    # Call any MCP server tool directly.
-    #
-    # @param package_name [String] the npm package name of the MCP server
-    # @param tool [String] the tool name to invoke
-    # @param args [Hash] optional arguments to pass to the tool
-    # @return [Object] the "data" field from the platform response
-    # @raise [Leash::Error] if the platform returns a non-success response
-    def mcp(package_name, tool, args = {})
-      uri = URI("#{@platform_url}/api/mcp/run")
-
-      request = Net::HTTP::Post.new(uri)
-      request["Content-Type"] = "application/json"
-      request["Authorization"] = "Bearer #{@auth_token}" if @auth_token
-      request["X-API-Key"] = @api_key if @api_key
-
-      payload = { package: package_name, tool: tool }
-      payload[:args] = args unless args.nil? || args.empty?
-      request.body = payload.to_json
-
-      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
-        http.request(request)
-      end
-
-      data = JSON.parse(response.body)
-
-      unless data["success"]
-        raise_error(data)
-      end
-
-      data["data"]
-    end
-
-    # Fetch env vars from the platform. Cached after first call.
-    #
-    # @param key [String, nil] optional key to look up
-    # @return [Hash, String, nil] all env vars as a Hash, or a single value if key given
-    # @raise [Leash::Error] if the platform returns a non-success response
-    def get_env(key = nil)
-      @env_cache ||= begin
-        uri = URI("#{@platform_url}/api/apps/env")
-
-        request = Net::HTTP::Get.new(uri)
-        request["Authorization"] = "Bearer #{@auth_token}" if @auth_token
-        request["X-API-Key"] = @api_key if @api_key
-
-        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
-          http.request(request)
-        end
-
-        data = JSON.parse(response.body)
-
-        unless data["success"]
-          raise_error(data)
-        end
-
-        data["data"] || {}
-      end
-
-      key ? @env_cache[key] : @env_cache
-    end
-
-    private
-
-    # Call the custom integration proxy endpoint.
-    #
-    # @param name [String] the custom integration name
-    # @param path [String] the endpoint path to forward
-    # @param method [String] HTTP method
-    # @param body [Hash, nil] optional JSON body to forward
-    # @param headers [Hash, nil] optional extra headers to forward
-    # @return [Object] the "data" field from the platform response
-    # @raise [Leash::Error] if the platform returns a non-success response
-    def call_custom(name, path, method = "GET", body = nil, headers = nil)
-      uri = URI("#{@platform_url}/api/integrations/custom/#{name}")
-
-      payload = { path: path, method: method }
-      payload[:body] = body if body
-      payload[:headers] = headers if headers
-
-      request = Net::HTTP::Post.new(uri)
-      request["Content-Type"] = "application/json"
-      request["Authorization"] = "Bearer #{@auth_token}"
-      request["X-API-Key"] = @api_key if @api_key
-      request.body = payload.to_json
-
-      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
-        http.request(request)
-      end
-
-      data = JSON.parse(response.body)
-
-      unless data["success"]
-        raise_error(data)
-      end
-
-      data["data"]
-    end
-
-    # Map error codes to specific exception classes.
-    #
-    # @param data [Hash] the parsed error response
-    # @raise [Leash::NotConnectedError, Leash::TokenExpiredError, Leash::Error]
-    def raise_error(data)
-      message = data["error"] || "Unknown error"
-      code = data["code"]
-      connect_url = data["connectUrl"]
-
-      case code
-      when "not_connected"
-        raise NotConnectedError.new(message, connect_url: connect_url)
-      when "token_expired"
-        raise TokenExpiredError.new(message, connect_url: connect_url)
-      else
-        raise Error.new(message, code: code, connect_url: connect_url)
+  module Integrations
+    # `leash.integrations` — typed provider namespaces plus a generic
+    # `.provider(name)` escape hatch for un-typed providers (Slack, GitHub,
+    # HubSpot, Jira, …). Mirrors the TS `leash.integrations` namespace and
+    # the Python `IntegrationsNamespace`.
+    #
+    # Method aliases keep the TS provider names addressable:
+    #
+    #   leash.integrations.calendar         # canonical (matches TS shape)
+    #   leash.integrations.google_calendar  # alias for calendar
+    #   leash.integrations.drive            # canonical
+    #   leash.integrations.google_drive     # alias for drive
+    class Namespace
+      def initialize(transport)
+        @transport = transport
+        @gmail = Gmail.new(transport)
+        @calendar = Calendar.new(transport)
+        @drive = Drive.new(transport)
+        @linear = Linear.new(transport)
+      end
+
+      attr_reader :gmail, :calendar, :drive, :linear
+
+      # Aliases matching the Google-prefixed provider IDs (and platform
+      # docs that use them). Same instances as `calendar` / `drive`.
+      alias google_calendar calendar
+      alias google_drive drive
+
+      # Generic escape hatch — `leash.integrations.provider('slack').call(...)`.
+      def provider(name)
+        Caller.new(@transport, name)
       end
     end
   end

data/lib/leash/transport.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "errors"
+
+module Leash
+  # @api private
+  #
+  # Shared HTTP transport used by every integration POST. Mirrors the
+  # `_call` / `_post` private methods on the TS `Leash` class and the
+  # Python `_Transport`.
+  #
+  # Critical platform contract (Critical #1 in the 0.4 plan):
+  #
+  #   * `X-API-Key` carries the app key (`LEASH_API_KEY`)
+  #   * `Cookie: leash-auth=…` forwards the browser session
+  #
+  # The user JWT extracted from an inbound `Authorization: Bearer …` header is
+  # intentionally NOT forwarded — the TS SDK warns that the JWT path causes
+  # the platform's `verifyToken()` to reject before the X-API-Key check runs,
+  # producing a misleading 401 on every integration call. Bearer tokens are
+  # still accepted by `Leash` for other code paths (env.get fallback, future
+  # CLI flows) but never sent on integration POSTs. A negative-assertion test
+  # covers this.
+  class Transport
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_READ_TIMEOUT = 30
+
+    attr_reader :platform_url, :api_key, :cookie_value
+
+    def initialize(platform_url:, api_key: nil, cookie_value: nil,
+                   open_timeout: DEFAULT_OPEN_TIMEOUT,
+                   read_timeout: DEFAULT_READ_TIMEOUT,
+                   http_runner: nil)
+      @platform_url = platform_url.to_s.sub(%r{/+\z}, "")
+      @api_key = api_key
+      @cookie_value = cookie_value
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      # Test seam — allow injecting a custom HTTP runner block.
+      # If nil, calls go through `Net::HTTP.start`.
+      @http_runner = http_runner
+    end
+
+    # POST to `/api/integrations/{provider}/{action}` and return the parsed
+    # response body (after unwrapping `{success, data}`).
+    def call(provider, action, params = nil)
+      url = "#{@platform_url}/api/integrations/#{provider}/#{action}"
+      docs_url = "https://leash.build/docs/integrations/#{provider}"
+      post_json(url, params, docs_url: docs_url)
+    end
+
+    # @api private — used by env.rb for GET /api/apps/me/secrets/<key>.
+    def get_json(url, headers: {})
+      run_request(url, method: :get, headers: headers, body: nil)
+    end
+
+    # @api private — used by env.rb for arbitrary URLs.
+    def post_json(url, params, docs_url:)
+      headers = { "Content-Type" => "application/json" }
+      headers["X-API-Key"] = @api_key if @api_key
+      headers["Cookie"] = "leash-auth=#{@cookie_value}" if @cookie_value
+
+      body = (params.nil? ? {} : params).to_json
+      response = run_request(url, method: :post, headers: headers, body: body)
+
+      handle_response(response, docs_url: docs_url)
+    end
+
+    # @api private
+    def run_request(url, method:, headers:, body:)
+      uri = URI.parse(url)
+      request = build_request(uri, method: method, headers: headers, body: body)
+
+      if @http_runner
+        return @http_runner.call(uri, request)
+      end
+
+      use_ssl = uri.scheme == "https"
+      opts = { use_ssl: use_ssl, open_timeout: @open_timeout, read_timeout: @read_timeout }
+
+      Net::HTTP.start(uri.host, uri.port, **opts) do |http|
+        http.request(request)
+      end
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise NetworkError.new("Timed out reaching the Leash platform: #{e.message}",
+                              action: "Check your network connection and that the Leash platform is reachable.",
+                              see_also: "https://leash.build/docs/sdk",
+                              cause: e)
+    rescue SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, IOError => e
+      raise NetworkError.new(e.message,
+                              action: "Check your network connection and that the Leash platform is reachable.",
+                              see_also: "https://leash.build/docs/sdk",
+                              cause: e)
+    end
+
+    # @api private
+    def build_request(uri, method:, headers:, body:)
+      request =
+        case method
+        when :post then Net::HTTP::Post.new(uri.request_uri)
+        when :get  then Net::HTTP::Get.new(uri.request_uri)
+        else raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+
+      headers.each { |k, v| request[k] = v }
+      request.body = body if body
+
+      request
+    end
+
+    # @api private
+    def handle_response(response, docs_url:)
+      status = response.respond_to?(:code) ? response.code.to_i : 0
+      body_raw = response.respond_to?(:body) ? response.body : nil
+
+      parsed = parse_json(body_raw)
+
+      if status >= 400
+        raise_for_status(status, parsed, docs_url: docs_url)
+      end
+
+      if parsed.is_a?(Hash)
+        # Platform contract: { success, data } envelope OR raw shape.
+        if parsed["success"] == false
+          err_message = parsed["error"].is_a?(String) ? parsed["error"] : "Integration error"
+          err_code = parsed["code"].is_a?(String) ? parsed["code"] : "INTEGRATION_ERROR"
+          raise Error.new(err_message,
+                          code: err_code,
+                          action: "Check your integration configuration and try again.",
+                          see_also: docs_url,
+                          status: status,
+                          connect_url: parsed["connectUrl"])
+        end
+        return parsed["data"] if parsed.key?("data")
+
+        return parsed
+      end
+
+      parsed
+    end
+
+    # @api private
+    def parse_json(body)
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # @api private
+    def raise_for_status(status, body, docs_url:)
+      message = "HTTP #{status}"
+      if body.is_a?(Hash) && body["error"].is_a?(String)
+        message = body["error"]
+      end
+
+      case status
+      when 401
+        raise UnauthorizedError.new(message,
+                                     action: "Ensure the leash-auth cookie is present, or open your app from the Leash dashboard to get a valid session.",
+                                     see_also: "https://leash.build/docs/sdk",
+                                     status: status)
+      when 402
+        msg = (body.is_a?(Hash) && body["message"].is_a?(String) ? body["message"] : message)
+        raise UpgradeRequiredError.new(msg,
+                                        action: "Upgrade your plan at https://leash.build/dashboard/billing.",
+                                        see_also: "https://leash.build/pricing",
+                                        status: status)
+      when 403
+        raise ConnectionRequiredError.new(message,
+                                           action: "Connect the integration at /dashboard/integrations and make sure this app is on the allow-list.",
+                                           see_also: "https://leash.build/dashboard/integrations",
+                                           status: status)
+      else
+        raise Error.new(message,
+                        code: "INTEGRATION_ERROR",
+                        action: "Check your integration configuration and try again — the upstream provider returned an error.",
+                        see_also: docs_url,
+                        status: status)
+      end
+    end
+  end
+end

data/lib/leash/types.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Leash
+  # Authenticated Leash user.
+  #
+  # Mirrors the TS `LeashUser` interface — JSON fields use camelCase on the
+  # wire (`id`, `email`, `name`, `picture`), and on the Ruby side `picture` is
+  # optional. Two `LeashUser`s are equal when every attribute matches.
+  class User
+    attr_reader :id, :email, :name, :picture
+
+    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
+
+    alias eql? ==
+
+    def hash
+      [self.class, id, email, name, picture].hash
+    end
+
+    def to_h
+      h = { id: id, email: email, name: name }
+      h[:picture] = picture if picture
+      h
+    end
+  end
+
+  # Older alias — readers reaching for `Leash::LeashUser` get the same class.
+  LeashUser = User
+end

data/lib/leash/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Leash
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end