linear_api 0.3.2 → 0.5.1

data/lib/linear_api/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'faraday'
+require 'faraday/retry'
 require 'json'
 
 module LinearApi
@@ -8,11 +9,22 @@ module LinearApi
   class Client
     API_ENDPOINT = 'https://api.linear.app/graphql'
 
+    # Default timeouts (seconds)
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 15
+
+    # Retry configuration
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_INTERVAL = 0.5
+
     attr_reader :api_key, :team_id
 
-    def initialize(api_key:, team_id: nil)
+    def initialize(api_key:, team_id: nil, open_timeout: nil, read_timeout: nil, max_retries: nil)
       @api_key = api_key
       @team_id = team_id
+      @open_timeout = open_timeout || DEFAULT_OPEN_TIMEOUT
+      @read_timeout = read_timeout || DEFAULT_READ_TIMEOUT
+      @max_retries = max_retries || DEFAULT_MAX_RETRIES
     end
 
     # Execute a GraphQL query
@@ -20,16 +32,28 @@ module LinearApi
     # @param query [String] GraphQL query string
     # @param variables [Hash] Query variables
     # @return [Result] Result object with data or error
-    def query(query, variables: {})
+    def query(query_str, variables: {})
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      LinearApi.logger.debug { "LinearApi: executing query #{query_str.lines.first&.strip}" }
+
       response = connection.post do |req|
-        req.body = { query: query, variables: variables }.to_json
+        req.body = { query: query_str, variables: variables }.to_json
       end
 
+      elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(1)
+      LinearApi.logger.debug { "LinearApi: response #{response.status} in #{elapsed}ms" }
+
       handle_response(response)
     rescue Faraday::Error => e
+      LinearApi.logger.error { "LinearApi: network error: #{e.class} - #{e.message}" }
       Result.new(success: false, error: "Network error: #{e.message}")
     end
 
+    # ==========================================================================
+    # Issue Operations
+    # ==========================================================================
+
     # Create a new issue
     #
     # @param title [String] Issue title
@@ -69,15 +93,29 @@ module LinearApi
       )
     end
 
-    # Get issue by identifier (e.g., "TOS-123")
+    # Get issue by identifier (e.g., "TOS-123") using direct filter query
     #
-    # @param identifier [String] Issue identifier
+    # Parses the identifier into team key and issue number, then filters
+    # using the `number` and `team.key` fields on IssueFilter (Linear's
+    # GraphQL schema does not expose an `identifier` filter).
+    #
+    # @param identifier [String] Issue identifier (e.g., "TOS-123")
     # @return [Result] Result with issue
     def get_issue(identifier)
-      result = query(Issue::SEARCH_QUERY, variables: { term: identifier })
+      team_key, number = parse_identifier(identifier)
+      unless team_key && number
+        return Result.new(success: false, error: "Invalid identifier format: #{identifier} (expected TEAM-123)")
+      end
+
+      filter = {
+        number: { eq: number },
+        team: { key: { eq: team_key } }
+      }
+
+      result = query(Issue::GET_BY_IDENTIFIER_QUERY, variables: { filter: filter })
       return result if result.failure?
 
-      issues = result.data.dig('searchIssues', 'nodes') || []
+      issues = result.data.dig('issues', 'nodes') || []
       if issues.empty?
         Result.new(success: false, error: "Issue not found: #{identifier}")
       else
@@ -85,6 +123,19 @@ module LinearApi
       end
     end
 
+    # Search issues by text query (full-text search)
+    #
+    # @param term [String] Search term
+    # @param limit [Integer] Max results
+    # @return [Result] Result with array of issues
+    def search_issues(term:, limit: 10)
+      result = query(Issue::SEARCH_QUERY, variables: { term: term, first: limit })
+      return result if result.failure?
+
+      issues = (result.data.dig('searchIssues', 'nodes') || []).map { |i| Issue.new(i) }
+      Result.new(success: true, data: issues, raw_response: result.raw_response)
+    end
+
     # List issues for the team
     #
     # @param filter [Hash] Filter options
@@ -101,6 +152,39 @@ module LinearApi
       Result.new(success: true, data: issues, raw_response: result.raw_response)
     end
 
+    # List all issues with automatic pagination
+    #
+    # @param filter [Hash] Filter options
+    # @param batch_size [Integer] Items per page
+    # @yield [Issue] Each issue as it's fetched (optional)
+    # @return [Result] Result with array of all issues
+    def list_all_issues(filter: nil, batch_size: 50, &block)
+      all_issues = []
+      cursor = nil
+
+      loop do
+        variables = { teamId: team_id, first: batch_size }
+        variables[:filter] = filter if filter
+        variables[:after] = cursor if cursor
+
+        result = query(Issue::LIST_PAGINATED_QUERY, variables: variables)
+        return result if result.failure?
+
+        nodes = (result.data.dig('team', 'issues', 'nodes') || []).map { |i| Issue.new(i) }
+        nodes.each do |issue|
+          block&.call(issue)
+          all_issues << issue
+        end
+
+        page_info = result.data.dig('team', 'issues', 'pageInfo')
+        break unless page_info&.dig('hasNextPage')
+
+        cursor = page_info['endCursor']
+      end
+
+      Result.new(success: true, data: all_issues)
+    end
+
     # Add a comment to an issue
     #
     # @param issue_id [String] Issue ID
@@ -117,89 +201,88 @@ module LinearApi
       )
     end
 
-    # Get team info
+    # Get issue by UUID (not identifier)
     #
-    # @return [Result] Result with team data
-    def get_team
-      result = query(Team::GET_QUERY, variables: { teamId: team_id })
+    # @param id [String] Issue UUID
+    # @return [Result] Result with issue
+    def get_issue_by_id(id)
+      result = query(Issue::GET_BY_ID_QUERY, variables: { id: id })
       return result if result.failure?
 
-      team_data = result.data['team']
-      Result.new(success: true, data: Team.new(team_data), raw_response: result.raw_response)
+      issue_data = result.data['issue']
+      if issue_data.nil?
+        Result.new(success: false, error: "Issue not found: #{id}")
+      else
+        Result.new(success: true, data: Issue.new(issue_data), raw_response: result.raw_response)
+      end
     end
 
-    # List projects for the team
+    # Batch fetch issues by IDs (avoids N+1 API calls)
     #
-    # @return [Result] Result with array of projects
-    def list_projects
-      result = query(Project::LIST_QUERY, variables: { teamId: team_id })
+    # @param ids [Array<String>] Issue UUIDs
+    # @return [Result] Result with array of issues
+    def batch_get_issues(ids:)
+      result = query(Issue::BATCH_GET_QUERY, variables: { filter: { id: { in: ids } } })
       return result if result.failure?
 
-      projects = (result.data.dig('team', 'projects', 'nodes') || []).map { |p| Project.new(p) }
-      Result.new(success: true, data: projects, raw_response: result.raw_response)
+      issues = (result.data.dig('issues', 'nodes') || []).map { |i| Issue.new(i) }
+      Result.new(success: true, data: issues, raw_response: result.raw_response)
     end
 
-    # Create a new project
+    # Archive an issue (soft delete)
     #
-    # @param name [String] Project name
-    # @param description [String] Optional project description
-    # @param color [String] Optional hex color (e.g., "#0052CC")
-    # @return [Result] Result with created project
-    def create_project(name:, description: nil, color: nil)
-      create_project_mutation = <<~GRAPHQL
-        mutation CreateProject($input: ProjectCreateInput!) {
-          projectCreate(input: $input) {
-            success
-            project {
-              id
-              name
-              description
-              url
-              color
-            }
-          }
-        }
-      GRAPHQL
-
-      input = { name: name, teamIds: [team_id] }
-      input[:description] = description if description
-      input[:color] = color if color
-
-      result = query(create_project_mutation, variables: { input: input })
+    # @param id [String] Issue ID
+    # @return [Result] Result with success status
+    def archive_issue(id:)
+      result = query(Issue::ARCHIVE_MUTATION, variables: { id: id })
       return result if result.failure?
 
-      project_data = result.data.dig('projectCreate', 'project')
       Result.new(
-        success: result.data.dig('projectCreate', 'success'),
-        data: Project.new(project_data),
+        success: result.data.dig('issueArchive', 'success'),
+        data: { archived: true },
         raw_response: result.raw_response
       )
     end
 
-    # List labels for the team
+    # Unarchive an issue
     #
-    # @return [Result] Result with array of labels
-    def list_labels
-      result = query(Label::LIST_QUERY, variables: { teamId: team_id })
+    # @param id [String] Issue ID
+    # @return [Result] Result with success status
+    def unarchive_issue(id:)
+      result = query(Issue::UNARCHIVE_MUTATION, variables: { id: id })
       return result if result.failure?
 
-      labels = (result.data.dig('team', 'labels', 'nodes') || []).map { |l| Label.new(l) }
-      Result.new(success: true, data: labels, raw_response: result.raw_response)
+      Result.new(
+        success: result.data.dig('issueUnarchive', 'success'),
+        data: { archived: false },
+        raw_response: result.raw_response
+      )
     end
 
-    # Get workflow states for the team
+    # Create a sub-issue (child issue)
     #
-    # @return [Result] Result with array of states
-    def list_states
-      result = query(Team::STATES_QUERY, variables: { teamId: team_id })
+    # @param parent_id [String] Parent issue ID
+    # @param title [String] Sub-issue title
+    # @param options [Hash] Additional options
+    # @return [Result] Result with created sub-issue
+    def create_sub_issue(parent_id:, title:, **options)
+      create_issue(title: title, parent_id: parent_id, **options)
+    end
+
+    # Get sub-issues for an issue
+    #
+    # @param parent_id [String] Parent issue ID
+    # @return [Result] Result with array of sub-issues
+    def list_sub_issues(parent_id:)
+      result = query(Issue::SUB_ISSUES_QUERY, variables: { id: parent_id })
       return result if result.failure?
 
-      states = result.data.dig('team', 'states', 'nodes') || []
-      Result.new(success: true, data: states, raw_response: result.raw_response)
+      children = (result.data.dig('issue', 'children', 'nodes') || []).map { |i| Issue.new(i) }
+      Result.new(success: true, data: children, raw_response: result.raw_response)
     end
 
     # ==========================================================================
-    # Convenience Methods for Common Operations
+    # Convenience Methods for Common Issue Operations
     # ==========================================================================
 
     # Move an issue to a different state
@@ -217,7 +300,6 @@ module LinearApi
     # @param label_ids [Array<String>] Label IDs to add
     # @return [Result] Result with updated issue
     def add_labels(id:, label_ids:)
-      # First get current labels
       issue_result = get_issue_by_id(id)
       return issue_result if issue_result.failure?
 
@@ -257,19 +339,7 @@ module LinearApi
     # @param pr_url [String] GitHub PR URL
     # @return [Result] Result with attachment
     def link_pr(issue_id:, pr_url:)
-      mutation = <<~GRAPHQL
-        mutation LinkPR($issueId: String!, $url: String!) {
-          attachmentLinkURL(issueId: $issueId, url: $url) {
-            success
-            attachment {
-              id
-              url
-            }
-          }
-        }
-      GRAPHQL
-
-      result = query(mutation, variables: { issueId: issue_id, url: pr_url })
+      result = query(Issue::LINK_PR_MUTATION, variables: { issueId: issue_id, url: pr_url })
       return result if result.failure?
 
       Result.new(
@@ -279,79 +349,112 @@ module LinearApi
       )
     end
 
+    # ==========================================================================
+    # Team Operations
+    # ==========================================================================
+
+    # Get team info
+    #
+    # @return [Result] Result with team data
+    def get_team
+      result = query(Team::GET_QUERY, variables: { teamId: team_id })
+      return result if result.failure?
+
+      team_data = result.data['team']
+      Result.new(success: true, data: Team.new(team_data), raw_response: result.raw_response)
+    end
+
+    # Get workflow states for the team
+    #
+    # @return [Result] Result with array of states
+    def list_states
+      result = query(Team::STATES_QUERY, variables: { teamId: team_id })
+      return result if result.failure?
+
+      states = result.data.dig('team', 'states', 'nodes') || []
+      Result.new(success: true, data: states, raw_response: result.raw_response)
+    end
+
     # List team members for assignment
     #
     # @return [Result] Result with array of users
     def list_users
-      users_query = <<~GRAPHQL
-        query ListUsers($teamId: String!) {
-          team(id: $teamId) {
-            members {
-              nodes {
-                id
-                name
-                email
-                displayName
-                active
-              }
-            }
-          }
-        }
-      GRAPHQL
-
-      result = query(users_query, variables: { teamId: team_id })
+      result = query(Team::USERS_QUERY, variables: { teamId: team_id })
       return result if result.failure?
 
       users = result.data.dig('team', 'members', 'nodes') || []
       Result.new(success: true, data: users, raw_response: result.raw_response)
     end
 
-    # Archive an issue (soft delete)
+    # Fetch all team metadata in a single API call (labels, projects, states, users)
     #
-    # @param id [String] Issue ID
-    # @return [Result] Result with success status
-    def archive_issue(id:)
-      archive_mutation = <<~GRAPHQL
-        mutation ArchiveIssue($id: String!) {
-          issueArchive(id: $id) {
-            success
-          }
-        }
-      GRAPHQL
-
-      result = query(archive_mutation, variables: { id: id })
+    # @return [Result] Result with hash of { labels:, projects:, states:, users: }
+    def fetch_all_metadata
+      result = query(Team::ALL_METADATA_QUERY, variables: { teamId: team_id })
       return result if result.failure?
 
-      Result.new(
-        success: result.data.dig('issueArchive', 'success'),
-        data: { archived: true },
-        raw_response: result.raw_response
-      )
+      team = result.data['team']
+      data = {
+        labels: (team.dig('labels', 'nodes') || []).map { |l| Label.new(l) },
+        projects: (team.dig('projects', 'nodes') || []).map { |p| Project.new(p) },
+        states: team.dig('states', 'nodes') || [],
+        users: team.dig('members', 'nodes') || []
+      }
+      Result.new(success: true, data: data, raw_response: result.raw_response)
     end
 
-    # Unarchive an issue
+    # ==========================================================================
+    # Project Operations
+    # ==========================================================================
+
+    # List projects for the team
     #
-    # @param id [String] Issue ID
-    # @return [Result] Result with success status
-    def unarchive_issue(id:)
-      unarchive_mutation = <<~GRAPHQL
-        mutation UnarchiveIssue($id: String!) {
-          issueUnarchive(id: $id) {
-            success
-          }
-        }
-      GRAPHQL
-
-      result = query(unarchive_mutation, variables: { id: id })
+    # @return [Result] Result with array of projects
+    def list_projects
+      result = query(Project::LIST_QUERY, variables: { teamId: team_id })
       return result if result.failure?
 
+      projects = (result.data.dig('team', 'projects', 'nodes') || []).map { |p| Project.new(p) }
+      Result.new(success: true, data: projects, raw_response: result.raw_response)
+    end
+
+    # Create a new project
+    #
+    # @param name [String] Project name
+    # @param description [String] Optional project description
+    # @param color [String] Optional hex color (e.g., "#0052CC")
+    # @return [Result] Result with created project
+    def create_project(name:, description: nil, color: nil)
+      input = { name: name, teamIds: [team_id] }
+      input[:description] = description if description
+      input[:color] = color if color
+
+      result = query(Project::CREATE_MUTATION, variables: { input: input })
+      return result if result.failure?
+
+      project_data = result.data.dig('projectCreate', 'project')
       Result.new(
-        success: result.data.dig('issueUnarchive', 'success'),
-        data: { archived: false },
+        success: result.data.dig('projectCreate', 'success'),
+        data: Project.new(project_data),
         raw_response: result.raw_response
       )
     end
 
+    # ==========================================================================
+    # Label Operations
+    # ==========================================================================
+
+    # List labels for the team
+    #
+    # @return [Result] Result with array of labels
+    def list_labels
+      result = query(Label::LIST_QUERY, variables: { teamId: team_id })
+      return result if result.failure?
+
+      labels = (result.data.dig('team', 'labels', 'nodes') || []).map { |l| Label.new(l) }
+      Result.new(success: true, data: labels, raw_response: result.raw_response)
+    end
+
     # Create a new label
     #
     # @param name [String] Label name (e.g., "type:bug", "area:sync")
@@ -359,25 +462,11 @@ module LinearApi
     # @param description [String] Optional description
     # @return [Result] Result with created label
     def create_label(name:, color: nil, description: nil)
-      create_label_mutation = <<~GRAPHQL
-        mutation CreateLabel($input: IssueLabelCreateInput!) {
-          issueLabelCreate(input: $input) {
-            success
-            issueLabel {
-              id
-              name
-              color
-              description
-            }
-          }
-        }
-      GRAPHQL
-
       input = { name: name, teamId: team_id }
       input[:color] = color if color
       input[:description] = description if description
 
-      result = query(create_label_mutation, variables: { input: input })
+      result = query(Label::CREATE_MUTATION, variables: { input: input })
       return result if result.failure?
 
       label_data = result.data.dig('issueLabelCreate', 'issueLabel')
@@ -388,99 +477,22 @@ module LinearApi
       )
     end
 
-    # Create a sub-issue (child issue)
-    #
-    # @param parent_id [String] Parent issue ID
-    # @param title [String] Sub-issue title
-    # @param options [Hash] Additional options
-    # @return [Result] Result with created sub-issue
-    def create_sub_issue(parent_id:, title:, **options)
-      create_issue(title: title, parent_id: parent_id, **options)
-    end
-
-    # Get sub-issues for an issue
-    #
-    # @param parent_id [String] Parent issue ID
-    # @return [Result] Result with array of sub-issues
-    def list_sub_issues(parent_id:)
-      sub_issues_query = <<~GRAPHQL
-        query GetSubIssues($id: String!) {
-          issue(id: $id) {
-            children {
-              nodes {
-                id
-                identifier
-                title
-                state {
-                  id
-                  name
-                }
-                priority
-              }
-            }
-          }
-        }
-      GRAPHQL
-
-      result = query(sub_issues_query, variables: { id: parent_id })
-      return result if result.failure?
-
-      children = (result.data.dig('issue', 'children', 'nodes') || []).map { |i| Issue.new(i) }
-      Result.new(success: true, data: children, raw_response: result.raw_response)
-    end
-
-    # Get issue by UUID (not identifier)
-    #
-    # @param id [String] Issue UUID
-    # @return [Result] Result with issue
-    def get_issue_by_id(id)
-      issue_query = <<~GRAPHQL
-        query GetIssueById($id: String!) {
-          issue(id: $id) {
-            id
-            identifier
-            title
-            description
-            url
-            priority
-            state {
-              id
-              name
-              type
-            }
-            labels {
-              nodes {
-                id
-                name
-              }
-            }
-            assignee {
-              id
-              name
-            }
-            project {
-              id
-              name
-            }
-          }
-        }
-      GRAPHQL
-
-      result = query(issue_query, variables: { id: id })
-      return result if result.failure?
-
-      issue_data = result.data['issue']
-      if issue_data.nil?
-        Result.new(success: false, error: "Issue not found: #{id}")
-      else
-        Result.new(success: true, data: Issue.new(issue_data), raw_response: result.raw_response)
-      end
-    end
-
     private
 
     def connection
       @connection ||= Faraday.new(url: API_ENDPOINT) do |f|
+        f.options.timeout = @read_timeout
+        f.options.open_timeout = @open_timeout
+        f.request :retry, max: @max_retries,
+                          interval: DEFAULT_RETRY_INTERVAL,
+                          backoff_factor: 2,
+                          exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed],
+                          retry_statuses: [500, 502, 503],
+                          retry_block: lambda { |env, _opts, retries, exc|
+                            LinearApi.logger.warn do
+                              "LinearApi: retry #{retries}/#{@max_retries} after #{exc&.class || "HTTP #{env&.status}"}"
+                            end
+                          }
         f.headers['Content-Type'] = 'application/json'
         f.headers['Authorization'] = api_key
         f.adapter Faraday.default_adapter
@@ -488,15 +500,24 @@ module LinearApi
     end
 
     def handle_response(response)
+      # Check for rate limiting
+      if response.status == 429
+        retry_after = response.headers['retry-after']&.to_i
+        LinearApi.logger.warn { "LinearApi: rate limited, retry after #{retry_after || 'unknown'}s" }
+        raise RateLimitError.new("Rate limited by Linear API. Retry after #{retry_after || 60}s", retry_after: retry_after)
+      end
+
       data = JSON.parse(response.body)
 
       if data['errors']
         error_message = data['errors'].map { |e| e['message'] }.join(', ')
+        LinearApi.logger.error { "LinearApi: GraphQL error: #{error_message}" }
         return Result.new(success: false, error: error_message, raw_response: data)
       end
 
       Result.new(success: true, data: data['data'], raw_response: data)
     rescue JSON::ParserError => e
+      LinearApi.logger.error { "LinearApi: invalid JSON response: #{e.message}" }
       Result.new(success: false, error: "Invalid JSON: #{e.message}")
     end
 
@@ -512,6 +533,17 @@ module LinearApi
       input
     end
 
+    # Parse an identifier like "TOS-123" into ["TOS", 123]
+    #
+    # @param identifier [String] e.g. "TOS-123"
+    # @return [Array(String, Integer), Array(nil, nil)] team key and number, or nils
+    def parse_identifier(identifier)
+      match = identifier&.match(/\A([A-Za-z]+)-(\d+)\z/)
+      return [nil, nil] unless match
+
+      [match[1].upcase, match[2].to_i]
+    end
+
     def camelize(key)
       key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }.to_sym
     end

data/lib/linear_api/engine.rb

@@ -19,6 +19,7 @@ module LinearApi
       # Auto-configure from environment variables if not already set
       LinearApi.api_key ||= ENV['LINEAR_API_KEY']
       LinearApi.team_id ||= ENV['LINEAR_TEAM_ID']
+      LinearApi.workspace_slug ||= ENV['LINEAR_WORKSPACE_SLUG']
     end
   end
 end