ask-linear 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cdf635069d34d0554d7e73ff22a0b589627ab59ace75b8376cfff7b11a502d5
-  data.tar.gz: 81cc288e84cb63fb8b622032adbdc911844cbe29097d2b99f5d0a19548fc8f69
+  metadata.gz: af9c693884b1bc9022c1cd4cdbe4c63d41329c382ece5b789bf845c8cec8dc87
+  data.tar.gz: 9d0d8ea95505b06494319ab80e5f43da5bc38b3372bc834bc6804a57c592b950
 SHA512:
-  metadata.gz: 75e4a052079f42fdb445fcaea78010597c19708a5872a399c970b0f28f72c0ce77a76c0b6df4fe9d2c5681a060cff28cba750fd8de999e6438f745297c7ce87f
-  data.tar.gz: e4e4cb88175a66383b416409f85e05ad2661168f28df182dd82c230429d3ec1b2fef341886f12255a3434af258d74bfc1a40beeff104298f6e4d59b53bbcd631
+  metadata.gz: 07bc57b565a5d434a008b9446a59326896a1d0e721a9212fd84f8b26bb3bfcdbb9dc40626680428c27f14db557457658af6fbbc1643121b50098d2f44d12f274
+  data.tar.gz: c4e00fa504dbf5809db5e3d95d006b1e1373f71247b48d85229b7b52fc44a122be19e2ef3c2865904df1f62d744a9a1bd0b18cbf2b6000e52721d2ea97e1b469

data/lib/ask/linear/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/retry"
 require "ask/auth"
 
 module Ask
@@ -14,6 +15,7 @@ module Ask
     # Configuration:
     # - +read_timeout+: +30+ seconds
     # - +open_timeout+: +10+ seconds
+    # - +retry+: up to 3 retries on 429 (rate-limit) and 5xx (server) errors
     #
     # @example
     #   client = Ask::Linear.client
@@ -43,6 +45,11 @@ module Ask
         @api_key = api_key
         @connection = Faraday.new(url: BASE_URL) do |f|
           f.request :json
+          f.request :retry, max: 3,
+                            interval: 1.0,
+                            max_interval: 10.0,
+                            backoff_factor: 2.0,
+                            retry_statuses: [429, 500, 502, 503]
           f.response :json
           f.response :raise_error
           f.options.read_timeout = 30

data/lib/ask/linear/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Linear
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end
 end

data/lib/ask/skills/linear.use_linear/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: linear.use_linear
+description: How to navigate the Linear API with GraphQL — explore the schema, build queries, paginate, and handle errors
+---
+
+Use this skill when you need to interact with Linear — managing issues, teams,
+projects, sprints, or workflows. Unlike other service gems, Linear uses a raw
+GraphQL API — there's no convenience client for each endpoint.
+
+## Step 1: Get the Client
+
+```ruby
+client = Ask::Linear.client
+```
+
+This returns a `Faraday`-based client that sends HTTP POST to
+`https://api.linear.app/graphql`. It expects a valid Linear API key resolved
+via `Ask::Auth.resolve(:linear_api_key)`.
+
+If you get an auth error, read `Ask::Linear::Context::AUTH_HOW` for API key setup.
+
+## Step 2: Explore the Context
+
+The gem ships with structured context you should reference:
+
+```ruby
+Ask::Linear::Context::DOCS_URL       # Linear developer docs
+Ask::Linear::Context::GRAPHQL_URL    # GraphQL endpoint (for introspection)
+Ask::Linear::Context::QUICK_START    # Query/mutation examples
+```
+
+The `QUICK_START` constant has working examples for teams, issues, and mutations.
+
+## Step 3: Use GraphQL Introspection to Discover the Schema
+
+Since Linear is GraphQL, you can introspect the schema to discover types,
+queries, and mutations:
+
+```ruby
+# List all query fields
+result = client.query("
+  query {
+    __schema {
+      queryType {
+        fields {
+          name
+          description
+        }
+      }
+    }
+  }
+")
+```
+
+For a specific type:
+```ruby
+result = client.query("
+  query {
+    __type(name: \"Issue\") {
+      name
+      fields {
+        name
+        type {
+          name
+          kind
+        }
+      }
+    }
+  }
+")
+```
+
+For finding all mutations:
+```ruby
+result = client.query("
+  query {
+    __schema {
+      mutationType {
+        fields {
+          name
+          args { name type { name } }
+        }
+      }
+    }
+  }
+")
+```
+
+## Step 4: Common Query Patterns
+
+**List teams:**
+```ruby
+client.query("query { teams { nodes { id key name } } }")
+```
+
+**List issues for a team:**
+```ruby
+client.query("query { team(id: \"TEAM_ID\") { issues(first: 50) { nodes { id identifier title state { name } priority } } } }")
+```
+
+**Get issue details:**
+```ruby
+client.query("query($id: String!) { issue(id: $id) { id identifier title description url assignee { name } } }", { id: "ISSUE_ID" })
+```
+
+**Create an issue:**
+```ruby
+client.query("mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }", { input: { teamId: "TEAM_ID", title: "New issue", description: "Description" } })
+```
+
+**Search issues:**
+```ruby
+client.query("query { issues(filter: { title: { contains: \"search term\" } }) { nodes { id identifier title } } }")
+```
+
+## Step 5: Variable Syntax
+
+Linear's GraphQL API requires exact type names. Use introspection (`__type`)
+to find available input types. Variables are passed as a hash:
+
+```ruby
+client.query("query($id: String!) { issue(id: $id) { id title } }", { id: "abc123" })
+```
+
+The second argument is variables — it's passed as the second parameter to
+Faraday's `post`.
+
+## Step 6: Authentication & Common Errors
+
+For error guidance, use:
+
+```ruby
+Ask::Linear::Errors.for("AUTHENTICATION_ERROR")
+Ask::Linear::Errors.status_code_description(429)
+Ask::Linear::Errors::PAGINATION
+```
+
+Common scenarios:
+- **401**: API key invalid or revoked → generate new key at Linear settings
+- **429**: Rate limited (100 req/min per key) → wait and retry
+- **GraphQL errors**: Query returns 200 with `errors` array → check field names
+- **INPUT_VALIDATION_ERROR**: Wrong argument types → check schema for exact types
+
+## Step 7: Pagination
+
+Linear uses cursor-based connection pagination:
+
+```ruby
+# Get first page
+page = client.query("query { issues(first: 50) { nodes { id title } pageInfo { hasNextPage endCursor } } }")
+# Next page:
+page = client.query("query($cursor: String) { issues(first: 50, after: $cursor) { nodes { id title } pageInfo { hasNextPage endCursor } } }", { cursor: page.data.issues.pageInfo.endCursor }) while page.data.issues.pageInfo.hasNextPage
+```
+
+Use `first`/`after` for forward pagination, `last`/`before` for backward.
+
+## Step 8: Fallback Strategy
+
+1. Check `Ask::Linear::Context::DOCS_URL` for documentation
+2. Use GraphQL introspection to discover the schema
+3. Linear's API returns helpful error messages — read the `errors` array
+4. For complex queries, build them incrementally — start simple, add fields

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-linear
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +108,7 @@ files:
 - lib/ask/linear/context.rb
 - lib/ask/linear/error_guide.rb
 - lib/ask/linear/version.rb
+- lib/ask/skills/linear.use_linear/SKILL.md
 homepage: https://github.com/ask-rb/ask-linear
 licenses:
 - MIT