linear_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 87b5a9b41c84b4044ca5462cd2570eb31d8c6aa35aaaa85dfac2f19be4e8da41
+  data.tar.gz: 9ebe3adfea20b1eef397fd295a9cefb1914a92b4e1d8806e617aa72c17cf6be2
+SHA512:
+  metadata.gz: a0ae7497191bbd81967090e3854ace3069851e606059e0027e4e7957dc3a5a1eadf50b90d6be13152116954d86964f1a9a5f00a7e35866ac5f3df35af10bd268
+  data.tar.gz: 42b7cc949edaba299a73f4d7207c76ab4b29bde6f031cf4a447610be95c3e2e14faf378248823e9d6a2466f226642be7823539c7f0edd73a1bf7c6c59b442780

data/.gitignore

@@ -0,0 +1,5 @@
+/.env
+*.gem
+/pkg/
+/.bundle/
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Lançamento inicial: `LinearClient::Client` com `teams`, `viewer`, `my_issues`, `create_issue` e `create_comment`.

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lenio Ferretto
+
+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,110 @@
+# linear_client
+
+Cliente Ruby puro para a [API GraphQL do Linear](https://developers.linear.app/docs/graphql/working-with-the-graphql-api) — sem gems externas, apenas a stdlib (`net/http`, `uri`, `json`).
+
+Não há SDK oficial para Ruby; este projeto preenche essa lacuna com uma interface simples para criar issues, comentar e consultar dados no Linear.
+
+## Instalação
+
+```bash
+gem install linear_client
+```
+
+ou no Gemfile:
+
+```ruby
+gem "linear_client"
+```
+
+## Configuração
+
+1. Gere uma API key pessoal no Linear em `Settings > Account > Security > API keys`.
+2. Exporte a chave como variável de ambiente (nunca hardcode no código):
+
+```bash
+export LINEAR_API_KEY="lin_api_xxxxxxxx"
+```
+
+> Trate a API key como uma senha: não a compartilhe, não a commit em arquivos versionados, e revogue/gere outra se ela vazar.
+
+## Uso
+
+```ruby
+require "linear_client"
+
+client = LinearClient::Client.new
+# ou, explicitamente:
+client = LinearClient::Client.new(api_key: "lin_api_xxxxxxxx")
+```
+
+### Descobrir times
+
+```ruby
+client.teams
+# => [{"id"=>"...", "name"=>"Engineering", "key"=>"ENG"}, ...]
+```
+
+### Criar um card e comentar
+
+```ruby
+result = client.create_issue(team_id: "TEAM_ID", title: "Bug no login", description: "Detalhes...")
+issue_id = result.dig("issue", "id")
+
+client.create_comment(issue_id: issue_id, body: "Já reproduzi, investigando.")
+```
+
+### Listar issues atribuídas a você
+
+```ruby
+client.my_issues.each { |i| puts "#{i['identifier']} [#{i['state']['name']}] #{i['title']}" }
+```
+
+### Dados do usuário autenticado
+
+```ruby
+client.viewer
+# => {"name"=>"...", "email"=>"..."}
+```
+
+## Referência da API
+
+| Método | Descrição | Retorno |
+|---|---|---|
+| `teams` | Lista os times do workspace (`id`, `name`, `key`) | `Array<Hash>` |
+| `viewer` | Nome e e-mail do dono da API key | `Hash` |
+| `my_issues` | Issues atribuídas ao dono da API key, com prioridade, datas, estado e time | `Array<Hash>` |
+| `create_issue(team_id:, title:, description: nil)` | Cria um card num time | `Hash` com `"success"` e `"issue"` (`id`, `identifier`, `title`, `url`) |
+| `create_comment(issue_id:, body:)` | Comenta num card existente | `Hash` com `"success"` e `"comment"` (`id`, `url`) |
+
+Todos os métodos lançam `LinearClient::Client::Error` se a API retornar erros GraphQL.
+
+## Testes
+
+Suíte em RSpec, com [WebMock](https://github.com/bblimke/webmock) simulando as respostas da API (nenhum teste bate na rede real):
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Scripts de exemplo
+
+```bash
+# Lista os times e cria um card de teste no time indicado pelo key (ex: ENG)
+ruby examples/create_issue.rb ENG
+
+# Lista as issues atribuídas a você
+ruby examples/my_issues.rb
+
+# Exporta viewer + issues atribuídas para JSON
+ruby examples/report.rb caminho/para/saida.json
+```
+
+## Notas de segurança
+
+- A API key vai no header `Authorization` (sem prefixo `Bearer`), conforme exigido pela API do Linear.
+- Nunca dê commit em arquivos `.env` ou qualquer arquivo com a chave em texto puro — este repositório já ignora `.env` via `.gitignore`.
+
+## Licença
+
+[MIT](LICENSE)

data/Rakefile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/create_issue.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+require_relative "../lib/linear_client"
+
+client = LinearClient::Client.new
+
+teams = client.teams
+puts "Times disponiveis:"
+teams.each { |t| puts "  #{t['key']} (#{t['name']}) -> id: #{t['id']}" }
+
+team_key = ARGV.first || teams.first.fetch("key")
+team = teams.find { |t| t.fetch("key") == team_key }
+raise "Time '#{team_key}' nao encontrado" unless team
+
+team_id = team.fetch("id")
+
+result = client.create_issue(
+  team_id: team_id,
+  title: "Card de teste criado via Ruby",
+  description: "Criado pelo script examples/create_issue.rb"
+)
+issue = result.fetch("issue")
+puts "Issue criada: #{issue['identifier']} - #{issue['url']}"
+
+client.create_comment(issue_id: issue.fetch("id"), body: "Primeiro comentario via API.")
+puts "Comentario adicionado."

data/examples/my_issues.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+require_relative "../lib/linear_client"
+
+client = LinearClient::Client.new
+issues = client.my_issues
+
+if issues.empty?
+  puts "Nenhuma issue atribuida a voce."
+else
+  issues.each do |issue|
+    puts "#{issue['identifier']} [#{issue['team']['key']} / #{issue['state']['name']}] #{issue['title']} -> #{issue['url']}"
+  end
+end

data/examples/report.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+require_relative "../lib/linear_client"
+require "json"
+
+client = LinearClient::Client.new
+viewer = client.viewer
+issues = client.my_issues
+
+output = { viewer: viewer, issues: issues }
+path = ARGV.first || "/tmp/linear_report_data.json"
+File.write(path, JSON.pretty_generate(output))
+puts "Dados salvos em #{path} (#{issues.size} issues)"

data/lib/linear_client/client.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module LinearClient
+  # Cliente minimo para a API GraphQL do Linear (https://api.linear.app/graphql).
+  # Nao ha SDK oficial para Ruby, entao falamos GraphQL diretamente via Net::HTTP.
+  class Client
+    ENDPOINT = "https://api.linear.app/graphql"
+
+    class Error < StandardError; end
+
+    def initialize(api_key: ENV["LINEAR_API_KEY"])
+      raise ArgumentError, "LINEAR_API_KEY nao configurada" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+    end
+
+    # team_id: id do time no Linear (veja #teams para descobrir)
+    def create_issue(team_id:, title:, description: nil)
+      query = <<~GRAPHQL
+        mutation IssueCreate($input: IssueCreateInput!) {
+          issueCreate(input: $input) {
+            success
+            issue { id identifier title url }
+          }
+        }
+      GRAPHQL
+
+      data = execute(query, input: { teamId: team_id, title: title, description: description })
+      data.fetch("issueCreate")
+    end
+
+    def create_comment(issue_id:, body:)
+      query = <<~GRAPHQL
+        mutation CommentCreate($input: CommentCreateInput!) {
+          commentCreate(input: $input) {
+            success
+            comment { id url }
+          }
+        }
+      GRAPHQL
+
+      data = execute(query, input: { issueId: issue_id, body: body })
+      data.fetch("commentCreate")
+    end
+
+    # Issues atribuidas ao dono da API key
+    def my_issues
+      query = <<~GRAPHQL
+        query MyIssues {
+          viewer {
+            assignedIssues {
+              nodes {
+                id
+                identifier
+                title
+                url
+                priority
+                createdAt
+                updatedAt
+                completedAt
+                state { name type }
+                team { key }
+              }
+            }
+          }
+        }
+      GRAPHQL
+
+      execute(query).dig("viewer", "assignedIssues", "nodes")
+    end
+
+    def viewer
+      query = <<~GRAPHQL
+        query Viewer {
+          viewer { name email }
+        }
+      GRAPHQL
+
+      execute(query).fetch("viewer")
+    end
+
+    # Util para descobrir os teamIds disponiveis no workspace
+    def teams
+      query = <<~GRAPHQL
+        query Teams {
+          teams { nodes { id name key } }
+        }
+      GRAPHQL
+
+      execute(query).dig("teams", "nodes")
+    end
+
+    private
+
+    def execute(query, **variables)
+      uri = URI.parse(ENDPOINT)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = @api_key
+      request.body = { query: query, variables: variables }.to_json
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
+      payload = JSON.parse(response.body)
+
+      raise Error, payload["errors"].to_s if payload["errors"] && !payload["errors"].empty?
+
+      payload.fetch("data")
+    end
+  end
+end

data/lib/linear_client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LinearClient
+  VERSION = "0.1.0"
+end

data/lib/linear_client.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "linear_client/version"
+require_relative "linear_client/client"

data/linear_client.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/linear_client/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "linear_client"
+  spec.version     = LinearClient::VERSION
+  spec.authors     = ["Lenio Ferretto"]
+  spec.email       = ["ferretto@users.noreply.github.com"]
+
+  spec.summary     = "Cliente Ruby puro para a API GraphQL do Linear"
+  spec.description = "Cliente minimalista, sem dependencias externas, para criar issues, " \
+                      "comentar e consultar dados no Linear (linear.app) via sua API GraphQL."
+  spec.homepage    = "https://github.com/ferretto/linear_client"
+  spec.license     = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|\.github)/}) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "webmock", "~> 3.26"
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: linear_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lenio Ferretto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+description: Cliente minimalista, sem dependencias externas, para criar issues, comentar
+  e consultar dados no Linear (linear.app) via sua API GraphQL.
+email:
+- ferretto@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- examples/create_issue.rb
+- examples/my_issues.rb
+- examples/report.rb
+- lib/linear_client.rb
+- lib/linear_client/client.rb
+- lib/linear_client/version.rb
+- linear_client.gemspec
+homepage: https://github.com/ferretto/linear_client
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ferretto/linear_client
+  changelog_uri: https://github.com/ferretto/linear_client/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Cliente Ruby puro para a API GraphQL do Linear
+test_files: []