linear_api 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6a4003a10fb0279c739bb5cadef86f1d953ada25452b33bc274cc50c1ac14df9
+  data.tar.gz: 5b1e90306471473e8983634c34ea0d4543ab9fd987be9e9917da10d88ae68731
+SHA512:
+  metadata.gz: cfec50c4d35241ed7923ae427a55702e970aaa734d5d2cfd3d51ca7a07cf9667908a5084a997418faff6d56f64b3196f6908bd28296003d53cad0ccdfcfd07d9
+  data.tar.gz: 58171286e1925c8b665b1be6f09c5525761a7708abe8390c53b3897bff2bae12f206df8a7ca117fa7da8deb389bad906a70ec8bcad0027120b3e1b1d8484fbdf

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-02-02
+
+### Added
+
+- `list_users` - List team members for assignment
+- `archive_issue` - Archive (soft delete) an issue
+- `unarchive_issue` - Restore an archived issue
+- `create_label` - Create new labels programmatically
+- `create_sub_issue` - Create child issues
+- `list_sub_issues` - List children of an issue
+
+## [0.1.0] - 2026-02-01
+
+### Added
+
+- Initial release
+- `LinearApi::Client` for GraphQL API communication
+- Issue management: create, update, get, list
+- Comment support for issues
+- Project and label listing
+- Workflow state querying
+- `LinearApi::Result` for consistent response handling
+- RSpec test suite with WebMock

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheOwnerStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,371 @@
+# LinearApi
+
+A Ruby gem for interacting with the [Linear](https://linear.app) GraphQL API. Create, update, and query issues, projects, and labels programmatically. Includes a Rails Engine for automatic error tracking with deduplication.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'linear_api', path: '../linear'
+# Or from GitHub:
+gem 'linear_api', git: 'https://github.com/dan1d/linear_api.git'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+For Rails applications, run the migrations:
+
+```bash
+bin/rails linear_api:install:migrations
+bin/rails db:migrate
+```
+
+## Configuration
+
+```ruby
+require 'linear_api'
+
+LinearApi.configure do |config|
+  config.api_key = ENV['LINEAR_API_KEY']
+  config.team_id = 'your-team-id'  # e.g., 'cfe09c0a-dcae-4cf9-be66-621d00798fcf'
+end
+```
+
+## Usage
+
+### Create an Issue
+
+```ruby
+result = LinearApi.client.create_issue(
+  title: 'Bug: Login fails with special characters',
+  description: '## Problem\n\nUsers cannot login when password contains @',
+  priority: 2,  # 1=Urgent, 2=High, 3=Medium, 4=Low
+  label_ids: ['752f6bfb-9943-4dde-8d36-63b43c34c12f']  # type:bug
+)
+
+if result.success?
+  puts "Created: #{result.data.identifier}"  # => "TOS-123"
+  puts "URL: #{result.data.url}"
+else
+  puts "Error: #{result.error}"
+end
+```
+
+### Get an Issue
+
+```ruby
+result = LinearApi.client.get_issue('TOS-123')
+
+if result.success?
+  issue = result.data
+  puts "Title: #{issue.title}"
+  puts "State: #{issue.state_name}"
+  puts "Labels: #{issue.label_names.join(', ')}"
+end
+```
+
+### Update an Issue
+
+```ruby
+# Update state
+result = LinearApi.client.update_issue(
+  id: 'issue-uuid',
+  state_id: 'state-uuid'
+)
+
+# Add labels
+result = LinearApi.client.update_issue(
+  id: 'issue-uuid',
+  label_ids: ['label-1', 'label-2']
+)
+```
+
+### Add a Comment
+
+```ruby
+result = LinearApi.client.add_comment(
+  issue_id: 'issue-uuid',
+  body: '## QA Results\n\n✅ All tests passed'
+)
+```
+
+### List Issues
+
+```ruby
+result = LinearApi.client.list_issues(limit: 50)
+
+result.data.each do |issue|
+  puts "#{issue.identifier}: #{issue.title} [#{issue.state_name}]"
+end
+```
+
+### List Labels
+
+```ruby
+result = LinearApi.client.list_labels
+
+result.data.each do |label|
+  puts "#{label.name}: #{label.id}"
+end
+```
+
+### Projects
+
+```ruby
+# List all projects
+result = LinearApi.client.list_projects
+
+result.data.each do |project|
+  puts "#{project.name}: #{project.id}"
+end
+
+# Create a project
+result = LinearApi.client.create_project(
+  name: 'Test Coverage and Automation',
+  description: 'Track QA automation and test coverage improvements',
+  color: '#4338ca'
+)
+
+if result.success?
+  puts "Created project: #{result.data.name}"
+  puts "URL: #{result.data.url}"
+end
+
+# Add an issue to a project
+result = LinearApi.client.create_issue(
+  title: 'Add integration tests for payment flow',
+  description: '## Objective\n\nImprove test coverage for payment processing',
+  project_id: 'project-uuid',
+  priority: 2
+)
+```
+
+### Get Workflow States
+
+```ruby
+result = LinearApi.client.list_states
+
+result.data.each do |state|
+  puts "#{state['name']} (#{state['type']}): #{state['id']}"
+end
+```
+
+### List Team Members (for Assignment)
+
+```ruby
+result = LinearApi.client.list_users
+
+result.data.each do |user|
+  puts "#{user['name']} (#{user['email']}): #{user['id']}"
+end
+
+# Assign to a user
+LinearApi.client.assign(id: issue.id, assignee_id: 'user-uuid')
+```
+
+### Archive/Unarchive Issues
+
+```ruby
+# Archive (soft delete)
+LinearApi.client.archive_issue(id: 'issue-uuid')
+
+# Restore
+LinearApi.client.unarchive_issue(id: 'issue-uuid')
+```
+
+### Create Labels
+
+```ruby
+result = LinearApi.client.create_label(
+  name: 'priority:critical',
+  color: '#ff0000',
+  description: 'Critical priority issues'
+)
+
+puts "Created label: #{result.data.id}"
+```
+
+### Sub-Issues
+
+```ruby
+# Create a sub-issue
+result = LinearApi.client.create_sub_issue(
+  parent_id: 'parent-issue-uuid',
+  title: 'Sub-task: Write tests',
+  priority: 3
+)
+
+# List sub-issues
+children = LinearApi.client.list_sub_issues(parent_id: 'parent-issue-uuid')
+children.data.each do |child|
+  puts "#{child.identifier}: #{child.title}"
+end
+```
+
+## Direct GraphQL Queries
+
+For advanced use cases, execute raw GraphQL:
+
+```ruby
+query = <<~GRAPHQL
+  query {
+    viewer {
+      name
+      email
+    }
+  }
+GRAPHQL
+
+result = LinearApi.client.query(query)
+puts result.data['viewer']['name']
+```
+
+## Error Handling
+
+```ruby
+result = LinearApi.client.create_issue(title: 'Test')
+
+case result
+when ->(r) { r.success? }
+  # Handle success
+  puts result.data.identifier
+when ->(r) { r.failure? }
+  # Handle error
+  puts "Error: #{result.error}"
+end
+```
+
+## Rails Engine (Auto-Tracking)
+
+The gem includes a Rails Engine for automatic error tracking with deduplication. Errors with the same fingerprint are grouped together instead of creating duplicate issues.
+
+### Setup
+
+```bash
+# Create the auto-tracking project and label in Linear
+bin/rails linear:setup
+
+# Sync labels, projects, and states from Linear
+bin/rails linear:sync_cache
+```
+
+### Track Errors Automatically
+
+```ruby
+# In your service or job
+class DailySalesReportJob < ApplicationJob
+  def perform(account)
+    # ... generate report ...
+  rescue StandardError => e
+    # Track the error in Linear
+    LinearApi::IssueTracker.track_error(
+      exception: e,
+      context: { date: Date.current, account_id: account.id },
+      source: account,
+      labels: [:bug, :sync]
+    )
+    raise # Re-raise after tracking
+  end
+end
+```
+
+### Track Custom Issues
+
+```ruby
+# Create a tracked issue (not from an exception)
+LinearApi::IssueTracker.track_issue(
+  title: 'Missing API credentials for merchant',
+  description: "Merchant #{merchant.name} has invalid Clover credentials",
+  context: { merchant_id: merchant.id },
+  source: merchant,
+  labels: [:bug, :area_sync]
+)
+```
+
+### How Deduplication Works
+
+1. Each error generates a fingerprint based on exception class, message, and backtrace
+2. If an open issue exists with the same fingerprint, a comment is added instead
+3. Once an issue is marked "Done" or "Canceled", new occurrences create a fresh issue
+
+### Rake Tasks
+
+```bash
+# Setup auto-tracking project and label
+bin/rails linear:setup
+
+# Sync metadata from Linear API
+bin/rails linear:sync_cache
+
+# Refresh local issue states (check if resolved)
+bin/rails linear:refresh_issues
+
+# Show cache statistics
+bin/rails linear:stats
+
+# Export cached metadata to JSON
+bin/rails linear:export_cache
+```
+
+### Cached Metadata
+
+The engine caches Linear metadata locally for fast lookups:
+
+```ruby
+# Find a label by name
+label = LinearApi::CachedMetadata.labels.find_by(name: 'type:bug')
+
+# Get all projects
+projects = LinearApi::CachedMetadata.projects.pluck(:name, :linear_id)
+
+# Resolve label ID from key
+bug_id = LinearApi::CachedMetadata.resolve_label_id('type:bug')
+```
+
+### Synced Issues
+
+Track which issues have been created:
+
+```ruby
+# Find all unresolved tracked issues
+open_issues = LinearApi::SyncedIssue.unresolved
+
+# Find issues for a specific source
+account_issues = LinearApi::SyncedIssue.where(
+  source_type: 'CloverAccount',
+  source_id: account.id
+)
+
+# Check if an issue is still open
+issue = LinearApi::SyncedIssue.find_by(identifier: 'TOS-123')
+puts issue.open? # => true/false
+puts issue.linear_url # => "https://linear.app/theownerstack/issue/TOS-123"
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run tests with VCR recording (hits live API)
+VCR_RECORD=1 bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Run all checks
+bundle exec rake
+```
+
+## License
+
+MIT License. See LICENSE.txt.

data/app/models/linear_api/application_record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module LinearApi
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name_prefix = 'linear_api_'
+  end
+end

data/app/models/linear_api/cached_metadata.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module LinearApi
+  class CachedMetadata < ApplicationRecord
+    TYPES = %w[label project state user].freeze
+
+    validates :metadata_type, presence: true, inclusion: { in: TYPES }
+    validates :linear_id, presence: true, uniqueness: { scope: :metadata_type }
+
+    # Type scopes
+    scope :labels, -> { where(metadata_type: 'label') }
+    scope :projects, -> { where(metadata_type: 'project') }
+    scope :states, -> { where(metadata_type: 'state') }
+    scope :users, -> { where(metadata_type: 'user') }
+
+    # Category scopes for labels
+    scope :by_category, ->(cat) { where(category: cat) }
+    scope :type_labels, -> { labels.by_category('type') }
+    scope :area_labels, -> { labels.by_category('area') }
+    scope :priority_labels, -> { labels.by_category('priority') }
+
+    # State type scopes
+    scope :completed_states, -> { states.where(state_type: 'completed') }
+    scope :active_states, -> { states.where(state_type: %w[unstarted started]) }
+
+    class << self
+      # Common label lookups
+      def bug_label_id
+        labels.find_by(key: 'type:bug')&.linear_id
+      end
+
+      def feature_label_id
+        labels.find_by(key: 'type:feature')&.linear_id
+      end
+
+      def sync_label_id
+        labels.find_by(key: 'area:sync')&.linear_id
+      end
+
+      def infrastructure_label_id
+        labels.find_by(key: 'area:infrastructure')&.linear_id
+      end
+
+      def critical_priority_id
+        labels.find_by(key: 'priority:critical')&.linear_id
+      end
+
+      def high_priority_id
+        labels.find_by(key: 'priority:high')&.linear_id
+      end
+
+      # State lookups
+      def backlog_state_id
+        states.find_by(key: 'backlog')&.linear_id
+      end
+
+      def todo_state_id
+        states.find_by(key: 'todo')&.linear_id
+      end
+
+      def in_progress_state_id
+        states.find_by(key: 'in_progress')&.linear_id
+      end
+
+      def done_state_id
+        states.find_by(key: 'done')&.linear_id
+      end
+
+      # Project lookups
+      def daily_operations_project_id
+        projects.find_by(key: 'daily_operations')&.linear_id
+      end
+
+      def tech_debt_project_id
+        projects.find_by(key: 'tech_debt')&.linear_id
+      end
+
+      # Resolve symbolic label to ID
+      def resolve_label_id(label)
+        case label
+        when :bug then bug_label_id
+        when :feature then feature_label_id
+        when :sync then sync_label_id
+        when :infrastructure then infrastructure_label_id
+        when :critical then critical_priority_id
+        when :high then high_priority_id
+        when String then label # Already an ID
+        else
+          labels.find_by(key: label.to_s)&.linear_id
+        end
+      end
+
+      # Upsert from API data
+      def upsert_from_api(type:, linear_id:, name:, **attrs)
+        find_or_initialize_by(metadata_type: type, linear_id: linear_id).tap do |record|
+          record.assign_attributes(name: name, **attrs)
+          record.save!
+        end
+      end
+    end
+  end
+end

data/app/models/linear_api/synced_issue.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module LinearApi
+  class SyncedIssue < ApplicationRecord
+    validates :linear_id, presence: true, uniqueness: true
+    validates :fingerprint, presence: true
+
+    # Source polymorphism (without actual belongs_to for flexibility)
+    scope :for_source, ->(type, id) { where(source_type: type.to_s, source_id: id.to_s) }
+    scope :by_fingerprint, ->(fp) { where(fingerprint: fp) }
+
+    # State scopes
+    scope :unresolved, -> { where.not(state_name: %w[Done Canceled Duplicate]) }
+    scope :resolved, -> { where(state_name: 'Done') }
+    scope :open, -> { where(state_name: %w[Backlog Todo]) }
+    scope :in_progress, -> { where(state_name: ['In Progress', 'In Review', 'QA']) }
+
+    # Time scopes
+    scope :recent, -> { where('created_at > ?', 7.days.ago) }
+    scope :stale, -> { unresolved.where('synced_at < ?', 1.day.ago) }
+
+    # Check if this issue is still open in Linear
+    def open?
+      !%w[Done Canceled Duplicate].include?(state_name)
+    end
+
+    def resolved?
+      state_name == 'Done'
+    end
+
+    # Sync state from Linear
+    def refresh_from_linear!
+      result = LinearApi.client.get_issue_by_id(linear_id)
+      return false unless result.success?
+
+      update!(
+        state_name: result.data.state_name,
+        title: result.data.title,
+        priority: result.data.priority,
+        synced_at: Time.current
+      )
+      true
+    end
+
+    # Build Linear URL
+    def linear_url
+      "https://linear.app/theownerstack/issue/#{identifier}"
+    end
+
+    # Parse metadata JSON
+    def parsed_metadata
+      return {} unless metadata
+
+      metadata.is_a?(String) ? JSON.parse(metadata) : metadata
+    rescue JSON::ParserError
+      {}
+    end
+
+    class << self
+      # Find existing open issue for this fingerprint
+      def find_open_for_fingerprint(fingerprint)
+        by_fingerprint(fingerprint).unresolved.order(created_at: :desc).first
+      end
+
+      # Check if we should create a new issue or add to existing
+      def should_create_new?(fingerprint)
+        find_open_for_fingerprint(fingerprint).nil?
+      end
+
+      # Refresh all stale issues
+      def refresh_stale_issues!
+        stale.find_each(&:refresh_from_linear!)
+      end
+    end
+  end
+end

data/db/migrate/20260204000001_create_linear_api_cached_metadata.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateLinearApiCachedMetadata < ActiveRecord::Migration[7.0]
+  def change
+    create_table :linear_api_cached_metadata do |t|
+      t.string :metadata_type, null: false # "label", "project", "state", "user"
+      t.string :linear_id, null: false
+      t.string :name
+      t.string :key # For lookup (e.g., "type:bug", "area:sync", "backlog")
+      t.string :color
+      t.string :category # For labels: "type", "area", "priority", "qa"
+      t.string :state_type # For states: "backlog", "unstarted", "started", "completed", "canceled"
+      t.json :raw_data
+
+      t.timestamps
+    end
+
+    add_index :linear_api_cached_metadata, %i[metadata_type linear_id], unique: true, name: 'idx_linear_cached_metadata_type_id'
+    add_index :linear_api_cached_metadata, %i[metadata_type key], name: 'idx_linear_cached_metadata_type_key'
+    add_index :linear_api_cached_metadata, :category
+  end
+end

data/db/migrate/20260204000002_create_linear_api_synced_issues.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class CreateLinearApiSyncedIssues < ActiveRecord::Migration[7.0]
+  def change
+    create_table :linear_api_synced_issues do |t|
+      t.string :linear_id, null: false
+      t.string :identifier # TOS-123
+      t.string :title
+      t.string :state_name
+      t.integer :priority
+      t.string :source_type # "AccountLinking", "DailySalesReport", etc.
+      t.string :source_id # ID of the related record
+      t.string :fingerprint, null: false # For deduplication
+      t.json :metadata # Extra context (date, error details, etc.)
+      t.datetime :synced_at
+
+      t.timestamps
+    end
+
+    add_index :linear_api_synced_issues, :linear_id, unique: true
+    add_index :linear_api_synced_issues, :identifier
+    add_index :linear_api_synced_issues, :fingerprint
+    add_index :linear_api_synced_issues, %i[source_type source_id], name: 'idx_linear_synced_issues_source'
+    add_index :linear_api_synced_issues, :state_name
+  end
+end