ask-linear 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +16 -0
  3. data/README.md +37 -106
  4. data/lib/ask/linear/version.rb +1 -1
  5. metadata +11 -7
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: af9c693884b1bc9022c1cd4cdbe4c63d41329c382ece5b789bf845c8cec8dc87
4
- data.tar.gz: 9d0d8ea95505b06494319ab80e5f43da5bc38b3372bc834bc6804a57c592b950
3
+ metadata.gz: 0b12985d48989c2ffb0010522917d67f0cdd8d8b17f2c1546bc15d722a6ca77f
4
+ data.tar.gz: 61ca78718de318a6dcf702892b844b25d8ec556f434b1abb9696df3112205e69
5
5
  SHA512:
6
- metadata.gz: 07bc57b565a5d434a008b9446a59326896a1d0e721a9212fd84f8b26bb3bfcdbb9dc40626680428c27f14db557457658af6fbbc1643121b50098d2f44d12f274
7
- data.tar.gz: c4e00fa504dbf5809db5e3d95d006b1e1373f71247b48d85229b7b52fc44a122be19e2ef3c2865904df1f62d744a9a1bd0b18cbf2b6000e52721d2ea97e1b469
6
+ metadata.gz: 42986d29827ba1a947af69efcaab259160bd739d6c1dc4d3c4ced22f5045e4d602a96eeddb7bae1009b94374255b304d742e920193bed8e850955fdc19a31986
7
+ data.tar.gz: 53e0cfdfe1a01cfbfd80b3d43303a88af48fa45f23ed93b87570aa2c7bd300e85c7bdf1727353a92654f44c52ffe973fe6529bd036b58d8a16d1a8ebe5365311
data/CHANGELOG.md ADDED
@@ -0,0 +1,16 @@
1
+ ## [0.1.2] - 2026-06-25
2
+
3
+ ### Changed
4
+ - Gemspec validation test. Infrastructure: rubocop, overcommit, bin/setup, CI matrix.
5
+ # Changelog
6
+
7
+ ## [0.1.1] - 2026-06-21
8
+
9
+ ### Added
10
+
11
+ - Initial release of `ask-linear` — Linear service context for the ask-rb ecosystem.
12
+ - **context.rb** — Metadata constants for AI system prompts: `DESCRIPTION`, `DOCS_URL`, `GRAPHQL_URL`, `AUTH_NAME`, `AUTH_HOW`, `GEM_NAME`, `GEM_DOCS`, `QUICK_START`
13
+ - **client.rb** — `Ask::Linear.client` returns an authenticated GraphQL client via `Ask::Auth.resolve(:linear_api_key)`. Uses Faraday to send GraphQL queries to the Linear API at `https://api.linear.app/graphql`. Wraps client in `ClientProxy` to convert `Faraday::UnauthorizedError` (HTTP 401) to `Ask::Auth::InvalidCredential`.
14
+ - **error_guide.rb** — `Ask::Linear::Errors` with rate limit info, HTTP status code descriptions, and GraphQL error extension guidance for agents.
15
+ - **Dependencies:** `ask-auth ~> 0.1`, `faraday ~> 2.0`
16
+ - **Testing:** 26 tests, 62 assertions covering context constants, client auth flow, and error guide lookups.
data/README.md CHANGED
@@ -1,8 +1,12 @@
1
1
  # ask-linear
2
2
 
3
- Linear service context for AI agents in the ask-rb ecosystem.
3
+ [![Gem Version](https://badge.fury.io/rb/ask-linear.svg)](https://badge.fury.io/rb/ask-linear)
4
4
 
5
- Provides an authenticated GraphQL client, metadata constants for system prompts, and a structured error guide for common Linear API issues.
5
+ Linear service context for AI agents in the ask-rb ecosystem. It provides an
6
+ authenticated GraphQL client for the Linear API, metadata constants for
7
+ system prompts, and a structured error guide for common Linear API issues.
8
+
9
+ ## Installation
6
10
 
7
11
  ```ruby
8
12
  gem "ask-linear"
@@ -10,8 +14,6 @@ gem "ask-linear"
10
14
 
11
15
  ## Quick Start
12
16
 
13
- ### Get an authenticated client
14
-
15
17
  ```ruby
16
18
  require "ask-linear"
17
19
 
@@ -33,121 +35,50 @@ result = client.query(
33
35
  )
34
36
  ```
35
37
 
36
- The client is a thin wrapper over Faraday that sends GraphQL queries to `https://api.linear.app/graphql`. Wrapped in a proxy that converts `Faraday::UnauthorizedError` (HTTP 401) into `Ask::Auth::InvalidCredential` with actionable error messages.
37
-
38
- ### Authentication
39
-
40
- The client resolves a Linear API key via `Ask::Auth.resolve(:linear_api_key)`. API keys can be provided through any configured auth provider:
41
-
42
- 1. **Environment variable:** `LINEAR_API_KEY`
43
- 2. **Credentials file:** `~/.ask/credentials.yml`
44
- 3. **Rails credentials:** `Rails.application.credentials.linear_api_key`
45
- 4. **OAuth / Database:** Custom providers
46
-
47
- Generate an API key at [linear.app/settings/api](https://linear.app/settings/api).
48
-
49
- ## Context Constants
50
-
51
- Use these constants to build system prompts for AI agents:
52
-
53
- | Constant | Value |
54
- |---|---|
55
- | `Ask::Linear::DESCRIPTION` | "Linear — issue tracking, project management, roadmaps, sprints" |
56
- | `Ask::Linear::DOCS_URL` | https://developers.linear.app/docs |
57
- | `Ask::Linear::GRAPHQL_URL` | https://api.linear.app/graphql |
58
- | `Ask::Linear::AUTH_NAME` | `:linear_api_key` |
59
- | `Ask::Linear::AUTH_HOW` | "https://linear.app/settings/api — generate a personal API key" |
60
- | `Ask::Linear::GEM_NAME` | `"faraday"` |
61
- | `Ask::Linear::QUICK_START` | Copy-paste Ruby code snippet with common GraphQL operations |
38
+ ## Authentication
62
39
 
63
- ## Error Guide
40
+ `Ask::Linear.client` resolves an API key via
41
+ `Ask::Auth.resolve(:linear_api_key)`. Set it in your environment:
64
42
 
65
- `Ask::Linear::Errors` provides structured knowledge for agents:
66
-
67
- ```ruby
68
- # Look up GraphQL error extension codes
69
- Ask::Linear::Errors.for("AUTHENTICATION_ERROR")
70
- # => { message: "...", action: "..." }
71
-
72
- # Describe HTTP status codes
73
- Ask::Linear::Errors.status_code_description(401)
74
- # => "Unauthorized — API key is missing, invalid, or revoked."
75
-
76
- # Rate limit info
77
- Ask::Linear::Errors::RATE_LIMIT[:authenticated]
78
- # => "100 requests per minute per API key"
79
-
80
- # Pagination guidance
81
- Ask::Linear::Errors::PAGINATION[:cursor_based]
82
- # => "Linear uses cursor-based pagination with first/after or last/before arguments."
43
+ ```bash
44
+ export LINEAR_API_KEY=your_api_key_here
83
45
  ```
84
46
 
85
- ### Supported Error Codes
86
-
87
- | Extension Code | When It Occurs |
88
- |---|---|
89
- | `AUTHENTICATION_ERROR` | Missing, invalid, or revoked API key |
90
- | `FORBIDDEN` | API key lacks permission for the resource |
91
- | `NOT_FOUND` | Resource doesn't exist or is inaccessible |
92
- | `RATE_LIMITED` | API rate limit exceeded (100 req/min/key) |
93
- | `INPUT_VALIDATION_ERROR` | Input data fails validation |
94
- | `DUPLICATE_INPUT` | Resource with same data already exists |
95
- | `INTERNAL_ERROR` | Linear server error |
96
- | `USER_SUSPENDED` | Authenticated user account is suspended |
97
- | `WORKSPACE_SUSPENDED` | Workspace is suspended or deactivated |
98
-
99
- ## Client API
100
-
101
- ### `Ask::Linear.client`
47
+ Or add it to `~/.ask/credentials.yml`:
102
48
 
103
- Returns an authenticated `Ask::Linear::Client` wrapped in a `ClientProxy` that catches 401 errors.
104
-
105
- ### `client.query(gql, variables = {})`
106
-
107
- Executes a GraphQL query or mutation against the Linear API.
108
-
109
- **Arguments:**
110
- - `gql` (String) — The GraphQL query or mutation string
111
- - `variables` (Hash) — Variables to interpolate into the query (optional)
112
-
113
- **Returns:** Hash with `"data"` key containing the response
114
-
115
- **Raises:**
116
- - `Ask::Auth::MissingCredential` if no API key is configured
117
- - `Ask::Auth::InvalidCredential` if the API key returns 401
118
- - `RuntimeError` if the API returns GraphQL errors
119
-
120
- ### Example: Common Operations
121
-
122
- ```ruby
123
- client = Ask::Linear.client
49
+ ```yaml
50
+ linear_api_key: your_api_key_here
51
+ ```
124
52
 
125
- # List teams
126
- teams = client.query("query { teams { nodes { id key name } } }")
53
+ Credentials can also come from Rails credentials, a database, or an OAuth
54
+ provider, depending on your `ask-auth` configuration. Generate a personal API
55
+ key at [linear.app/settings/api](https://linear.app/settings/api).
127
56
 
128
- # List my assigned issues
129
- my_issues = client.query("query { viewer { assignedIssues { nodes { id identifier title state { name } } } } }")
57
+ ## Key entry points
130
58
 
131
- # Get workflow states for a team
132
- states = client.query("query($teamId: String!) { team(id: $teamId) { states { nodes { id name type } } } }",
133
- teamId: "TEAM_ID")
59
+ - `Ask::Linear.client` - an authenticated `Ask::Linear::Client` that wraps
60
+ Faraday and sends GraphQL queries to `https://api.linear.app/graphql`.
61
+ Auth failures (HTTP 401) are converted into
62
+ `Ask::Auth::InvalidCredential`.
63
+ - `client.query(gql, variables = {})` - execute a GraphQL query or mutation.
64
+ Returns the parsed response body, or raises `RuntimeError` if Linear
65
+ returns GraphQL errors.
66
+ - `Ask::Linear::Errors` - structured error knowledge for agents: GraphQL
67
+ extension code lookup, HTTP status descriptions, rate limit and pagination
68
+ guidance.
69
+ - `Ask::Linear::DESCRIPTION`, `DOCS_URL`, `GRAPHQL_URL`, `AUTH_NAME`,
70
+ `GEM_NAME`, and `QUICK_START` - metadata constants for system prompts.
134
71
 
135
- # Update issue state
136
- result = client.query(
137
- "mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { id identifier state { name } } } }",
138
- { id: "ISSUE_ID", input: { stateId: "STATE_ID" } }
139
- )
72
+ ## Full documentation
140
73
 
141
- # Add comment
142
- result = client.query(
143
- "mutation($input: CommentCreateInput!) { commentCreate(input: $input) { success comment { id body } } }",
144
- { input: { issueId: "ISSUE_ID", body: "Working on this" } }
145
- )
146
- ```
74
+ The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
75
+ [Services: Linear](https://ask-rb.github.io/ask-docs/services/linear) covers
76
+ ask-linear in depth, including the client API, error guide, and constants.
77
+ API reference: https://ask-rb.github.io/ask-docs/reference/api.
147
78
 
148
79
  ## Development
149
80
 
150
- ```bash
81
+ ```
151
82
  bundle install
152
83
  bundle exec rake test
153
84
  ```
data/lib/ask/linear/version.rb CHANGED
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Ask
4
4
  module Linear
5
- VERSION = '0.1.1'
5
+ VERSION = '0.1.3'
6
6
  end
7
7
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ask-linear
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.1
4
+ version: 0.1.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Kaka Ruto
@@ -13,16 +13,16 @@ dependencies:
13
13
  name: ask-auth
14
14
  requirement: !ruby/object:Gem::Requirement
15
15
  requirements:
16
- - - "~>"
16
+ - - ">="
17
17
  - !ruby/object:Gem::Version
18
- version: '0.1'
18
+ version: 0.3.2
19
19
  type: :runtime
20
20
  prerelease: false
21
21
  version_requirements: !ruby/object:Gem::Requirement
22
22
  requirements:
23
- - - "~>"
23
+ - - ">="
24
24
  - !ruby/object:Gem::Version
25
- version: '0.1'
25
+ version: 0.3.2
26
26
  - !ruby/object:Gem::Dependency
27
27
  name: faraday
28
28
  requirement: !ruby/object:Gem::Requirement
@@ -101,6 +101,7 @@ executables: []
101
101
  extensions: []
102
102
  extra_rdoc_files: []
103
103
  files:
104
+ - CHANGELOG.md
104
105
  - LICENSE
105
106
  - README.md
106
107
  - lib/ask-linear.rb
@@ -112,7 +113,10 @@ files:
112
113
  homepage: https://github.com/ask-rb/ask-linear
113
114
  licenses:
114
115
  - MIT
115
- metadata: {}
116
+ metadata:
117
+ homepage_uri: https://github.com/ask-rb/ask-linear
118
+ source_code_uri: https://github.com/ask-rb/ask-linear
119
+ changelog_uri: https://github.com/ask-rb/ask-linear/blob/master/CHANGELOG.md
116
120
  rdoc_options: []
117
121
  require_paths:
118
122
  - lib
@@ -127,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
127
131
  - !ruby/object:Gem::Version
128
132
  version: '0'
129
133
  requirements: []
130
- rubygems_version: 4.0.3
134
+ rubygems_version: 4.0.18
131
135
  specification_version: 4
132
136
  summary: Linear service context for the ask-rb ecosystem
133
137
  test_files: []