linear_api 0.3.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f5dbd45da7e5e461fd1f9c04b5b94d859b74a85f8be4b2818f2cb418597ed83
-  data.tar.gz: d082eb5a92d5343d8eb5be7e41ebefa1c17aa20ecb347139dbe98c1a9fb533d9
+  metadata.gz: bfd85fc80770e0982a5791d46f49fb4406b356b9e9fa43be79a9af61d21e791b
+  data.tar.gz: 30b5161cf27bdb0a43d8f15a22f32693db5b75c018a07aa5860329b2898a01b7
 SHA512:
-  metadata.gz: 01feecb156624a79c91954ba5527948e962ff6d64e9a8aaa2906e4afb633bf62e82527c8a6a9c75444782ec383b0918828c77ffb80e9ac68b08abe68c168859e
-  data.tar.gz: 861150c54a6f3af9964af691dce4a43bb7cfcc48a6f8963ba82f5f7e76762f0b7ee5d94193f6f76283978713e4968d0aae56ae8c93cbc87845bb0a329a7f1056
+  metadata.gz: f6cd9e24591ae9ce4a807f7fb5758d8b759aa9a8f0b3e0c47fcdc600c55aba984781119c6319c58573370a69837761fe1bac307f052e019147007968b90080a8
+  data.tar.gz: be806327bb48559330ace30e6981146cbb7fcc27ad060027644951da7caa846dd9ee284c413625e684c74522a0bbaed6c3bba60594094f1144230903bcf0ae27

data/CHANGELOG.md

@@ -5,6 +5,52 @@ 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.5.0] - 2026-02-07
+
+### Added
+
+- **Connection timeouts**: Faraday now has 5s open timeout and 15s read timeout (prevents hung Puma threads)
+- **Automatic retry**: `faraday-retry` middleware retries on 500/502/503 and network errors (3 retries with exponential backoff)
+- **Rate limit handling**: HTTP 429 responses now raise `RateLimitError` with `retry_after` attribute
+- **Thread-safe client**: `LinearApi.client` and `reset_client!` are now protected by a `Mutex`
+- **Configurable logger**: `LinearApi.logger` with automatic Rails.logger detection; all API calls, errors, and retries are logged
+- **Pagination support**: `list_all_issues` method with cursor-based pagination and optional block yielding
+- **`search_issues` method**: Explicit full-text search (separated from `get_issue` which now uses direct filter)
+- **`batch_get_issues` method**: Fetch multiple issues by ID in a single API call (avoids N+1)
+- **`fetch_all_metadata` method**: Single GraphQL query to fetch labels, projects, states, and users at once
+- **`due_date` and `estimate` fields**: Added to `Issue` model and all queries
+- **`value!` method on `Result`**: Returns data on success, raises `LinearApi::Error` on failure
+- **Health check**: `LinearApi.healthy?` method and `linear:health` rake task
+- **Configurable workspace slug**: `LinearApi.workspace_slug` / `LINEAR_WORKSPACE_SLUG` env var for `SyncedIssue#linear_url`
+- **Sensitive key redaction**: `IssueTracker` now redacts keys matching password/secret/token/api_key patterns from issue descriptions
+- **CacheSync spec**: Full test coverage for `CacheSync` class
+- **Network failure tests**: Tests for HTTP 429, timeouts, malformed JSON responses
+
+### Changed
+
+- **BREAKING**: `Result` no longer delegates methods via `method_missing`. Use `result.data.method` or `result.value!.method` instead
+- **BREAKING**: `get_issue('TOS-123')` now uses a direct filter query (`issues(filter: { identifier: { eq: ... } })`) instead of full-text search. This prevents false positives (e.g., "TOS-1" matching "TOS-10"). Use `search_issues(term:)` for fuzzy search.
+- `CacheSync.sync_all` now fetches all metadata in a **single batched API call** (was 4 separate calls)
+- `SyncedIssue.refresh_stale_issues!` now uses **batch fetch** (was N+1 individual API calls)
+- `IssueTracker` now memoizes auto-tracked project/label IDs in memory after first resolution
+- `IssueTracker.track_error` and `track_issue` now rescue all errors and return failure Result (never lets tracking failures propagate)
+- All inline GraphQL queries moved from `Client` to their respective model classes as constants
+- Rake task `export_cache` now fetches team key from API instead of hardcoding `'TOS'`
+- Rake task helper methods moved to `self.` class methods to avoid polluting global scope
+- `faraday-retry` added as a runtime dependency
+
+### Fixed
+
+- `SyncedIssue#linear_url` no longer hardcodes `theownerstack` workspace slug
+- `RateLimitError` now includes `retry_after` attribute (was defined but never raised)
+
+## [0.4.0] - 2026-02-06
+
+### Changed
+
+- **BREAKING (dependency)**: Rails moved from runtime to development dependency. The core client (`Client`, `Result`, `Issue`, `Project`, `Label`, `Team`) now only requires `faraday`. Rails Engine, `CacheSync`, and `IssueTracker` are still loaded automatically when Rails is present via `defined?(Rails::Engine)` guard.
+- This allows non-Rails projects (e.g., standalone gems, CLI tools) to use `linear_api` without pulling in all of Rails.
+
 ## [0.3.1] - 2026-02-06
 
 ### Added

data/README.md

@@ -7,9 +7,7 @@ A Ruby gem for interacting with the [Linear](https://linear.app) GraphQL API. Cr
 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'
+gem 'linear_api'
 ```
 
 Then run:
@@ -18,6 +16,12 @@ Then run:
 bundle install
 ```
 
+Or install it directly:
+
+```bash
+gem install linear_api
+```
+
 For Rails applications, run the migrations:
 
 ```bash
@@ -33,6 +37,8 @@ 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'
+  config.workspace_slug = 'your-workspace'  # Used for building issue URLs (default: 'theownerstack')
+  config.logger = Rails.logger  # Optional: defaults to Rails.logger or stdout
 end
 ```
 
@@ -45,7 +51,9 @@ 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
+  label_ids: ['752f6bfb-9943-4dde-8d36-63b43c34c12f'],
+  due_date: '2026-03-01',  # ISO 8601 date
+  estimate: 3  # Story points
 )
 
 if result.success?
@@ -54,11 +62,16 @@ if result.success?
 else
   puts "Error: #{result.error}"
 end
+
+# Or use value! to raise on failure:
+issue = LinearApi.client.create_issue(title: 'Bug').value!
+puts issue.identifier
 ```
 
 ### Get an Issue
 
 ```ruby
+# Direct lookup by identifier (exact match)
 result = LinearApi.client.get_issue('TOS-123')
 
 if result.success?
@@ -66,6 +79,18 @@ if result.success?
   puts "Title: #{issue.title}"
   puts "State: #{issue.state_name}"
   puts "Labels: #{issue.label_names.join(', ')}"
+  puts "Due: #{issue.due_date}"
+  puts "Estimate: #{issue.estimate}"
+end
+```
+
+### Search Issues (Full-Text)
+
+```ruby
+result = LinearApi.client.search_issues(term: 'login bug', limit: 10)
+
+result.data.each do |issue|
+  puts "#{issue.identifier}: #{issue.title}"
 end
 ```
 
@@ -97,11 +122,31 @@ result = LinearApi.client.add_comment(
 ### List Issues
 
 ```ruby
+# Simple list (up to 50)
 result = LinearApi.client.list_issues(limit: 50)
 
 result.data.each do |issue|
   puts "#{issue.identifier}: #{issue.title} [#{issue.state_name}]"
 end
+
+# List ALL issues with automatic pagination
+result = LinearApi.client.list_all_issues(batch_size: 50) do |issue|
+  # Optional: process each issue as it's fetched
+  puts "Fetched: #{issue.identifier}"
+end
+
+puts "Total: #{result.data.length}"
+```
+
+### Batch Fetch Issues
+
+```ruby
+# Fetch multiple issues in a single API call (avoids N+1)
+result = LinearApi.client.batch_get_issues(ids: ['uuid-1', 'uuid-2', 'uuid-3'])
+
+result.data.each do |issue|
+  puts "#{issue.identifier}: #{issue.state_name}"
+end
 ```
 
 ### List Labels
@@ -168,6 +213,20 @@ end
 LinearApi.client.assign(id: issue.id, assignee_id: 'user-uuid')
 ```
 
+### Fetch All Metadata (Single API Call)
+
+```ruby
+# Fetch labels, projects, states, and users in one batched call
+result = LinearApi.client.fetch_all_metadata
+
+if result.success?
+  puts "Labels: #{result.data[:labels].length}"
+  puts "Projects: #{result.data[:projects].length}"
+  puts "States: #{result.data[:states].length}"
+  puts "Users: #{result.data[:users].length}"
+end
+```
+
 ### Archive/Unarchive Issues
 
 ```ruby
@@ -230,14 +289,31 @@ puts result.data['viewer']['name']
 ```ruby
 result = LinearApi.client.create_issue(title: 'Test')
 
-case result
-when ->(r) { r.success? }
-  # Handle success
+if result.success?
   puts result.data.identifier
-when ->(r) { r.failure? }
-  # Handle error
+else
   puts "Error: #{result.error}"
 end
+
+# Or use value! to raise on failure (good for scripts)
+begin
+  issue = LinearApi.client.create_issue(title: 'Test').value!
+  puts issue.identifier
+rescue LinearApi::Error => e
+  puts "Failed: #{e.message}"
+rescue LinearApi::RateLimitError => e
+  puts "Rate limited, retry after #{e.retry_after}s"
+end
+```
+
+## Health Check
+
+```ruby
+if LinearApi.healthy?
+  puts "Linear API is reachable"
+else
+  puts "Cannot connect to Linear"
+end
 ```
 
 ## Rails Engine (Auto-Tracking)
@@ -247,10 +323,13 @@ The gem includes a Rails Engine for automatic error tracking with deduplication.
 ### Setup
 
 ```bash
+# Verify Linear API connectivity
+bin/rails linear:health
+
 # Create the auto-tracking project and label in Linear
 bin/rails linear:setup
 
-# Sync labels, projects, and states from Linear
+# Sync labels, projects, and states from Linear (single batched API call)
 bin/rails linear:sync_cache
 ```
 
@@ -262,7 +341,7 @@ class DailySalesReportJob < ApplicationJob
   def perform(account)
     # ... generate report ...
   rescue StandardError => e
-    # Track the error in Linear
+    # Track the error in Linear (never raises, returns Result)
     LinearApi::IssueTracker.track_error(
       exception: e,
       context: { date: Date.current, account_id: account.id },
@@ -287,6 +366,21 @@ LinearApi::IssueTracker.track_issue(
 )
 ```
 
+### Security: Sensitive Data Redaction
+
+`IssueTracker` automatically redacts context values whose keys match sensitive patterns (password, secret, token, api_key, credential, authorization):
+
+```ruby
+LinearApi::IssueTracker.track_error(
+  exception: e,
+  context: {
+    account_id: 123,          # Included as-is
+    api_key: 'sk_live_xxx',   # Redacted to '[REDACTED]'
+    user_email: 'user@test.com'  # Included as-is
+  }
+)
+```
+
 ### How Deduplication Works
 
 1. Each error generates a fingerprint based on exception class, message, and backtrace
@@ -296,13 +390,16 @@ LinearApi::IssueTracker.track_issue(
 ### Rake Tasks
 
 ```bash
+# Verify API connectivity
+bin/rails linear:health
+
 # Setup auto-tracking project and label
 bin/rails linear:setup
 
-# Sync metadata from Linear API
+# Sync metadata from Linear API (single batched call)
 bin/rails linear:sync_cache
 
-# Refresh local issue states (check if resolved)
+# Refresh local issue states (batched, checks if resolved)
 bin/rails linear:refresh_issues
 
 # Show cache statistics
@@ -344,9 +441,18 @@ account_issues = LinearApi::SyncedIssue.where(
 # 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"
+puts issue.linear_url # => "https://linear.app/your-workspace/issue/TOS-123"
 ```
 
+## Resilience Features
+
+- **Connection timeouts**: 5s connect, 15s read (configurable per-client)
+- **Automatic retries**: 3 retries with exponential backoff on 500/502/503 and network errors
+- **Rate limit detection**: HTTP 429 raises `RateLimitError` with `retry_after`
+- **Thread safety**: Module-level client access is protected by `Mutex`
+- **Logging**: All API calls, retries, and errors logged via configurable `LinearApi.logger`
+- **Silent error tracking**: `IssueTracker.track_error` never raises -- returns failure `Result` and logs
+
 ## Development
 
 ```bash

data/app/models/linear_api/synced_issue.rb

@@ -42,9 +42,10 @@ module LinearApi
       true
     end
 
-    # Build Linear URL
+    # Build Linear URL using configurable workspace slug
     def linear_url
-      "https://linear.app/theownerstack/issue/#{identifier}"
+      slug = LinearApi.workspace_slug || 'theownerstack'
+      "https://linear.app/#{slug}/issue/#{identifier}"
     end
 
     # Parse metadata JSON
@@ -67,9 +68,42 @@ module LinearApi
         find_open_for_fingerprint(fingerprint).nil?
       end
 
-      # Refresh all stale issues
+      # Refresh all stale issues using batch API call (avoids N+1)
       def refresh_stale_issues!
-        stale.find_each(&:refresh_from_linear!)
+        stale_issues = stale.to_a
+        return if stale_issues.empty?
+
+        LinearApi.logger.info { "LinearApi: refreshing #{stale_issues.size} stale issues" }
+
+        # Batch fetch from Linear API in groups of 50
+        stale_issues.each_slice(50) do |batch|
+          ids = batch.map(&:linear_id)
+          result = LinearApi.client.batch_get_issues(ids: ids)
+
+          unless result.success?
+            LinearApi.logger.error { "LinearApi: batch refresh failed: #{result.error}" }
+            # Fall back to individual refresh for this batch
+            batch.each(&:refresh_from_linear!)
+            next
+          end
+
+          # Index fetched issues by ID for O(1) lookup
+          fetched = result.data.index_by(&:id)
+
+          batch.each do |synced|
+            linear_issue = fetched[synced.linear_id]
+            if linear_issue
+              synced.update!(
+                state_name: linear_issue.state_name,
+                title: linear_issue.title,
+                priority: linear_issue.priority,
+                synced_at: Time.current
+              )
+            else
+              LinearApi.logger.warn { "LinearApi: issue #{synced.identifier} not found in Linear (may be deleted)" }
+            end
+          end
+        end
       end
     end
   end

data/lib/linear_api/cache_sync.rb

@@ -12,98 +12,57 @@ module LinearApi
       end
     end
 
+    # Sync all metadata in a single API call (instead of 4 separate calls)
     def sync_all
+      LinearApi.logger.info { 'LinearApi: syncing all metadata from Linear API' }
+
+      result = LinearApi.client.fetch_all_metadata
+      unless result.success?
+        LinearApi.logger.error { "LinearApi: metadata sync failed: #{result.error}" }
+        return {
+          labels: { success: false, error: result.error },
+          projects: { success: false, error: result.error },
+          states: { success: false, error: result.error },
+          users: { success: false, error: result.error }
+        }
+      end
+
+      metadata = result.data
       {
-        labels: sync_labels,
-        projects: sync_projects,
-        states: sync_states,
-        users: sync_users
+        labels: sync_labels_from_data(metadata[:labels]),
+        projects: sync_projects_from_data(metadata[:projects]),
+        states: sync_states_from_data(metadata[:states]),
+        users: sync_users_from_data(metadata[:users])
       }
     end
 
+    # Individual sync methods (for targeted refresh)
     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 }
+      sync_labels_from_data(result.data)
     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 }
+      sync_projects_from_data(result.data)
     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 }
+      sync_states_from_data(result.data)
     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 }
+      sync_users_from_data(result.data)
     end
 
     # Import from linear.json file
@@ -157,6 +116,83 @@ module LinearApi
 
     private
 
+    def sync_labels_from_data(labels)
+      count = 0
+      labels.each do |label|
+        category = extract_category(label.is_a?(Label) ? label.name : label['name'])
+        CachedMetadata.upsert_from_api(
+          type: 'label',
+          linear_id: label.is_a?(Label) ? label.id : label['id'],
+          name: label.is_a?(Label) ? label.name : label['name'],
+          key: label.is_a?(Label) ? label.name : label['name'],
+          color: label.is_a?(Label) ? label.color : label['color'],
+          category: category,
+          raw_data: label.is_a?(Label) ? label.to_h : label
+        )
+        count += 1
+      end
+
+      { success: true, count: count }
+    end
+
+    def sync_projects_from_data(projects)
+      count = 0
+      projects.each do |project|
+        name = project.is_a?(Project) ? project.name : project['name']
+        key = name.parameterize.underscore
+        CachedMetadata.upsert_from_api(
+          type: 'project',
+          linear_id: project.is_a?(Project) ? project.id : project['id'],
+          name: name,
+          key: key,
+          state_type: project.is_a?(Project) ? project.state : project['state'],
+          raw_data: project.is_a?(Project) ? project.to_h : project
+        )
+        count += 1
+      end
+
+      { success: true, count: count }
+    end
+
+    def sync_states_from_data(states)
+      count = 0
+      states.each do |state|
+        name = state.is_a?(Hash) ? state['name'] : state.name
+        key = name.parameterize.underscore
+        CachedMetadata.upsert_from_api(
+          type: 'state',
+          linear_id: state.is_a?(Hash) ? state['id'] : state.id,
+          name: name,
+          key: key,
+          color: state.is_a?(Hash) ? state['color'] : state.color,
+          state_type: state.is_a?(Hash) ? state['type'] : state.type,
+          raw_data: state.is_a?(Hash) ? state : state.to_h
+        )
+        count += 1
+      end
+
+      { success: true, count: count }
+    end
+
+    def sync_users_from_data(users)
+      count = 0
+      users.each do |user|
+        name = user.is_a?(Hash) ? user['name'] : user.name
+        email = user.is_a?(Hash) ? user['email'] : user.email
+        key = email&.split('@')&.first || name.parameterize.underscore
+        CachedMetadata.upsert_from_api(
+          type: 'user',
+          linear_id: user.is_a?(Hash) ? user['id'] : user.id,
+          name: name,
+          key: key,
+          raw_data: user.is_a?(Hash) ? user : user.to_h
+        )
+        count += 1
+      end
+
+      { success: true, count: count }
+    end
+
     def extract_category(label_name)
       return nil unless label_name.include?(':')