linear_api 0.3.0

data/lib/linear_api/cache_sync.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module LinearApi
+  class CacheSync
+    class << self
+      def sync_all
+        new.sync_all
+      end
+
+      def import_from_json(json_path)
+        new.import_from_json(json_path)
+      end
+    end
+
+    def sync_all
+      {
+        labels: sync_labels,
+        projects: sync_projects,
+        states: sync_states,
+        users: sync_users
+      }
+    end
+
+    def sync_labels
+      result = LinearApi.client.list_labels
+      return { success: false, error: result.error } unless result.success?
+
+      count = 0
+      result.data.each do |label|
+        category = extract_category(label.name)
+        CachedMetadata.upsert_from_api(
+          type: 'label',
+          linear_id: label.id,
+          name: label.name,
+          key: label.name,
+          color: label.color,
+          category: category,
+          raw_data: label.to_h
+        )
+        count += 1
+      end
+
+      { success: true, count: count }
+    end
+
+    def sync_projects
+      result = LinearApi.client.list_projects
+      return { success: false, error: result.error } unless result.success?
+
+      count = 0
+      result.data.each do |project|
+        key = project.name.parameterize.underscore
+        CachedMetadata.upsert_from_api(
+          type: 'project',
+          linear_id: project.id,
+          name: project.name,
+          key: key,
+          state_type: project.state,
+          raw_data: project.to_h
+        )
+        count += 1
+      end
+
+      { success: true, count: count }
+    end
+
+    def sync_states
+      result = LinearApi.client.list_states
+      return { success: false, error: result.error } unless result.success?
+
+      count = 0
+      result.data.each do |state|
+        key = state['name'].parameterize.underscore
+        CachedMetadata.upsert_from_api(
+          type: 'state',
+          linear_id: state['id'],
+          name: state['name'],
+          key: key,
+          color: state['color'],
+          state_type: state['type'],
+          raw_data: state
+        )
+        count += 1
+      end
+
+      { success: true, count: count }
+    end
+
+    def sync_users
+      result = LinearApi.client.list_users
+      return { success: false, error: result.error } unless result.success?
+
+      count = 0
+      result.data.each do |user|
+        key = user['email']&.split('@')&.first || user['name'].parameterize.underscore
+        CachedMetadata.upsert_from_api(
+          type: 'user',
+          linear_id: user['id'],
+          name: user['name'],
+          key: key,
+          raw_data: user
+        )
+        count += 1
+      end
+
+      { success: true, count: count }
+    end
+
+    # Import from linear.json file
+    def import_from_json(json_path)
+      data = JSON.parse(File.read(json_path))
+      counts = { labels: 0, projects: 0, states: 0, users: 0 }
+
+      # Import labels
+      import_labels_from_json(data['labels'], counts)
+
+      # Import projects
+      data['projects']&.each do |key, project|
+        CachedMetadata.upsert_from_api(
+          type: 'project',
+          linear_id: project['id'],
+          name: project['name'],
+          key: key,
+          state_type: project['state'],
+          raw_data: project
+        )
+        counts[:projects] += 1
+      end
+
+      # Import workflow states
+      data['workflow_states']&.each do |key, state|
+        CachedMetadata.upsert_from_api(
+          type: 'state',
+          linear_id: state['id'],
+          name: state['name'],
+          key: key,
+          state_type: state['type'],
+          raw_data: state
+        )
+        counts[:states] += 1
+      end
+
+      # Import users
+      data['users']&.each do |key, user|
+        CachedMetadata.upsert_from_api(
+          type: 'user',
+          linear_id: user['id'],
+          name: user['name'],
+          key: key,
+          raw_data: user
+        )
+        counts[:users] += 1
+      end
+
+      counts
+    end
+
+    private
+
+    def extract_category(label_name)
+      return nil unless label_name.include?(':')
+
+      label_name.split(':').first
+    end
+
+    def import_labels_from_json(labels_data, counts)
+      return unless labels_data
+
+      labels_data.each do |category, labels|
+        labels.each do |_key, label|
+          CachedMetadata.upsert_from_api(
+            type: 'label',
+            linear_id: label['id'],
+            name: label['name'],
+            key: label['name'],
+            color: label['color'],
+            category: category,
+            raw_data: label
+          )
+          counts[:labels] += 1
+        end
+      end
+    end
+  end
+end

data/lib/linear_api/client.rb

@@ -0,0 +1,519 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module LinearApi
+  # GraphQL client for Linear API
+  class Client
+    API_ENDPOINT = 'https://api.linear.app/graphql'
+
+    attr_reader :api_key, :team_id
+
+    def initialize(api_key:, team_id: nil)
+      @api_key = api_key
+      @team_id = team_id
+    end
+
+    # Execute a GraphQL query
+    #
+    # @param query [String] GraphQL query string
+    # @param variables [Hash] Query variables
+    # @return [Result] Result object with data or error
+    def query(query, variables: {})
+      response = connection.post do |req|
+        req.body = { query: query, variables: variables }.to_json
+      end
+
+      handle_response(response)
+    rescue Faraday::Error => e
+      Result.new(success: false, error: "Network error: #{e.message}")
+    end
+
+    # Create a new issue
+    #
+    # @param title [String] Issue title
+    # @param description [String] Issue description (markdown)
+    # @param options [Hash] Additional options (priority, label_ids, project_id, etc.)
+    # @return [Result] Result with created issue
+    def create_issue(title:, description: nil, **options)
+      input = build_issue_input(title: title, description: description, **options)
+
+      result = query(Issue::CREATE_MUTATION, variables: { input: input })
+      return result if result.failure?
+
+      issue_data = result.data.dig('issueCreate', 'issue')
+      Result.new(
+        success: result.data.dig('issueCreate', 'success'),
+        data: Issue.new(issue_data),
+        raw_response: result.raw_response
+      )
+    end
+
+    # Update an existing issue
+    #
+    # @param id [String] Issue ID
+    # @param options [Hash] Fields to update
+    # @return [Result] Result with updated issue
+    def update_issue(id:, **options)
+      input = options.transform_keys { |k| camelize(k) }
+
+      result = query(Issue::UPDATE_MUTATION, variables: { id: id, input: input })
+      return result if result.failure?
+
+      issue_data = result.data.dig('issueUpdate', 'issue')
+      Result.new(
+        success: result.data.dig('issueUpdate', 'success'),
+        data: Issue.new(issue_data),
+        raw_response: result.raw_response
+      )
+    end
+
+    # Get issue by identifier (e.g., "TOS-123")
+    #
+    # @param identifier [String] Issue identifier
+    # @return [Result] Result with issue
+    def get_issue(identifier)
+      result = query(Issue::SEARCH_QUERY, variables: { term: identifier })
+      return result if result.failure?
+
+      issues = result.data.dig('searchIssues', 'nodes') || []
+      if issues.empty?
+        Result.new(success: false, error: "Issue not found: #{identifier}")
+      else
+        Result.new(success: true, data: Issue.new(issues.first), raw_response: result.raw_response)
+      end
+    end
+
+    # List issues for the team
+    #
+    # @param filter [Hash] Filter options
+    # @param limit [Integer] Max issues to return
+    # @return [Result] Result with array of issues
+    def list_issues(filter: nil, limit: 50)
+      variables = { teamId: team_id, first: limit }
+      variables[:filter] = filter if filter
+
+      result = query(Issue::LIST_QUERY, variables: variables)
+      return result if result.failure?
+
+      issues = (result.data.dig('team', 'issues', 'nodes') || []).map { |i| Issue.new(i) }
+      Result.new(success: true, data: issues, raw_response: result.raw_response)
+    end
+
+    # Add a comment to an issue
+    #
+    # @param issue_id [String] Issue ID
+    # @param body [String] Comment body (markdown)
+    # @return [Result] Result with comment
+    def add_comment(issue_id:, body:)
+      result = query(Issue::ADD_COMMENT_MUTATION, variables: { issueId: issue_id, body: body })
+      return result if result.failure?
+
+      Result.new(
+        success: result.data.dig('commentCreate', 'success'),
+        data: result.data.dig('commentCreate', 'comment'),
+        raw_response: result.raw_response
+      )
+    end
+
+    # 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
+
+    # List projects for the team
+    #
+    # @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)
+      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 })
+      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),
+        raw_response: result.raw_response
+      )
+    end
+
+    # 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
+
+    # 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
+
+    # ==========================================================================
+    # Convenience Methods for Common Operations
+    # ==========================================================================
+
+    # Move an issue to a different state
+    #
+    # @param id [String] Issue ID
+    # @param state_id [String] Target state ID
+    # @return [Result] Result with updated issue
+    def move_to_state(id:, state_id:)
+      update_issue(id: id, state_id: state_id)
+    end
+
+    # Add labels to an issue (appends to existing)
+    #
+    # @param id [String] Issue ID
+    # @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?
+
+      current_ids = issue_result.data.labels.map { |l| l['id'] }
+      new_ids = (current_ids + label_ids).uniq
+
+      update_issue(id: id, label_ids: new_ids)
+    end
+
+    # Remove labels from an issue
+    #
+    # @param id [String] Issue ID
+    # @param label_ids [Array<String>] Label IDs to remove
+    # @return [Result] Result with updated issue
+    def remove_labels(id:, label_ids:)
+      issue_result = get_issue_by_id(id)
+      return issue_result if issue_result.failure?
+
+      current_ids = issue_result.data.labels.map { |l| l['id'] }
+      new_ids = current_ids - label_ids
+
+      update_issue(id: id, label_ids: new_ids)
+    end
+
+    # Assign issue to a user
+    #
+    # @param id [String] Issue ID
+    # @param assignee_id [String] User ID (nil to unassign)
+    # @return [Result] Result with updated issue
+    def assign(id:, assignee_id:)
+      update_issue(id: id, assignee_id: assignee_id)
+    end
+
+    # Link a GitHub PR to an issue
+    #
+    # @param issue_id [String] Issue ID
+    # @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 })
+      return result if result.failure?
+
+      Result.new(
+        success: result.data.dig('attachmentLinkURL', 'success'),
+        data: result.data.dig('attachmentLinkURL', 'attachment'),
+        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 })
+      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)
+    #
+    # @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 if result.failure?
+
+      Result.new(
+        success: result.data.dig('issueArchive', 'success'),
+        data: { archived: true },
+        raw_response: result.raw_response
+      )
+    end
+
+    # Unarchive an issue
+    #
+    # @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 if result.failure?
+
+      Result.new(
+        success: result.data.dig('issueUnarchive', 'success'),
+        data: { archived: false },
+        raw_response: result.raw_response
+      )
+    end
+
+    # Create a new label
+    #
+    # @param name [String] Label name (e.g., "type:bug", "area:sync")
+    # @param color [String] Hex color (e.g., "#ff0000")
+    # @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 })
+      return result if result.failure?
+
+      label_data = result.data.dig('issueLabelCreate', 'issueLabel')
+      Result.new(
+        success: result.data.dig('issueLabelCreate', 'success'),
+        data: Label.new(label_data),
+        raw_response: result.raw_response
+      )
+    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.headers['Content-Type'] = 'application/json'
+        f.headers['Authorization'] = api_key
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response)
+      data = JSON.parse(response.body)
+
+      if data['errors']
+        error_message = data['errors'].map { |e| e['message'] }.join(', ')
+        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
+      Result.new(success: false, error: "Invalid JSON: #{e.message}")
+    end
+
+    def build_issue_input(title:, description: nil, **options)
+      input = { title: title, teamId: team_id }
+      input[:description] = description if description
+
+      # Map Ruby snake_case to GraphQL camelCase
+      options.each do |key, value|
+        input[camelize(key)] = value
+      end
+
+      input
+    end
+
+    def camelize(key)
+      key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }.to_sym
+    end
+  end
+end