ask-linear 0.1.2 → 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 (4) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +37 -106
  3. data/lib/ask/linear/version.rb +1 -1
  4. metadata +4 -4
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b2d2cc4fa5d5715fdfbf074dfd3e6c64a758e65f5387ab97cf5a07c4aac6ab35
4
- data.tar.gz: 2be587d1288bba6f5acae2b011c71a74c70d4f9d7f7b0831fd2df98e611a46e5
3
+ metadata.gz: 0b12985d48989c2ffb0010522917d67f0cdd8d8b17f2c1546bc15d722a6ca77f
4
+ data.tar.gz: 61ca78718de318a6dcf702892b844b25d8ec556f434b1abb9696df3112205e69
5
5
  SHA512:
6
- metadata.gz: 15b294da6df23b368b697fc8594e5e6e5fb5a81c3175c8486b24e34b69a22675a336eafb2ac1178eff154415b985d71e7d173276b585a5ff3e3e2602ca660b43
7
- data.tar.gz: 9f03b1c574e47f71fd445c80d2a36100ecaaa83ed426c5ef78cbac5237a4ff70ac2e43de1e5eca863a91ec06175e4b7cf6c41138b75ec97ad668c30a43384ac9
6
+ metadata.gz: 42986d29827ba1a947af69efcaab259160bd739d6c1dc4d3c4ced22f5045e4d602a96eeddb7bae1009b94374255b304d742e920193bed8e850955fdc19a31986
7
+ data.tar.gz: 53e0cfdfe1a01cfbfd80b3d43303a88af48fa45f23ed93b87570aa2c7bd300e85c7bdf1727353a92654f44c52ffe973fe6529bd036b58d8a16d1a8ebe5365311
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.2'
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.2
4
+ version: 0.1.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Kaka Ruto
@@ -15,14 +15,14 @@ dependencies:
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
@@ -131,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
131
131
  - !ruby/object:Gem::Version
132
132
  version: '0'
133
133
  requirements: []
134
- rubygems_version: 4.0.3
134
+ rubygems_version: 4.0.18
135
135
  specification_version: 4
136
136
  summary: Linear service context for the ask-rb ecosystem
137
137
  test_files: []