@loopstack/github-module 0.2.0 → 0.2.2

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 (2) hide show
  1. package/README.md +86 -5
  2. package/package.json +8 -3
package/README.md CHANGED
@@ -1,16 +1,54 @@
1
1
  # @loopstack/github-module
2
2
 
3
- GitHub integration for the Loopstack automation framework. Provides a GitHub OAuth provider and 25 tools across 7 domains: repositories, issues, pull requests, content/git ops, actions, search, and users/orgs.
3
+ > GitHub integration for the [Loopstack AI](https://loopstack.ai) automation framework.
4
+
5
+ This module provides a GitHub OAuth 2.0 provider implementation and 25 tools across 7 domains for interacting with GitHub APIs. It registers a GitHub OAuth provider with `@loopstack/oauth-module`, enabling GitHub authentication in any Loopstack workflow, and provides tools for repositories, issues, pull requests, content/git ops, actions, search, and users/orgs.
6
+
7
+ ## Overview
8
+
9
+ The GitHub Module includes a **provider implementation** for `@loopstack/oauth-module`. It implements the `OAuthProviderInterface` and self-registers with the `OAuthProviderRegistry` on startup. Once registered, the generic OAuth workflow can handle `provider: 'github'` automatically.
10
+
11
+ By using this module, you'll be able to:
12
+
13
+ - Authenticate users with their GitHub account via OAuth 2.0
14
+ - Manage repositories, branches, issues, and pull requests programmatically
15
+ - Read and write file content, list directories, and inspect commits
16
+ - Trigger and monitor GitHub Actions workflow runs
17
+ - Search code, repositories, and issues across GitHub
18
+ - Access user profiles and organization memberships
4
19
 
5
20
  ## Installation
6
21
 
7
- ```bash
8
- loopstack add @loopstack/github-module
22
+ See [SETUP.md](./SETUP.md) for installation and setup instructions.
23
+
24
+ This module requires `@loopstack/oauth-module` as a peer dependency.
25
+
26
+ ## How It Works
27
+
28
+ ### Provider Registration
29
+
30
+ The `GitHubOAuthProvider` implements `OnModuleInit` and registers itself with the `OAuthProviderRegistry` at startup:
31
+
32
+ ```typescript
33
+ onModuleInit(): void {
34
+ this.providerRegistry.register(this);
35
+ }
9
36
  ```
10
37
 
11
- ## Configuration
38
+ After registration, the generic `OAuthWorkflow` from `@loopstack/oauth-module` can handle authentication for `provider: 'github'`.
39
+
40
+ ### Provider Details
41
+
42
+ | Property | Value |
43
+ | --------------- | --------------------------------------------- |
44
+ | `providerId` | `'github'` |
45
+ | `defaultScopes` | `repo`, `user`, `workflow`, `read:org` |
46
+ | Auth endpoint | `https://github.com/login/oauth/authorize` |
47
+ | Token endpoint | `https://github.com/login/oauth/access_token` |
12
48
 
13
- Set the following environment variables:
49
+ > **Note:** GitHub OAuth tokens do not expire and do not support refresh. The `refreshToken()` method throws an error.
50
+
51
+ ### Environment Variables
14
52
 
15
53
  ```env
16
54
  GITHUB_CLIENT_ID=your_client_id
@@ -65,3 +103,46 @@ GITHUB_OAUTH_REDIRECT_URI=/oauth/callback
65
103
 
66
104
  - **GitHubGetAuthenticatedUserTool** — Get authenticated user profile
67
105
  - **GitHubListUserOrgsTool** — List user organizations
106
+
107
+ ## Usage in Workflows
108
+
109
+ Once registered, any workflow can trigger GitHub authentication by launching the OAuth workflow with `provider: 'github'`:
110
+
111
+ ```typescript
112
+ @InjectWorkflow() oAuth: OAuthWorkflow;
113
+
114
+ // In a transition method:
115
+ const result = await this.oAuth.run(
116
+ { provider: 'github', scopes: ['repo', 'read:org', 'workflow'] },
117
+ { alias: 'oAuth', callback: { transition: 'authCompleted' } },
118
+ );
119
+
120
+ await this.repository.save(
121
+ LinkDocument,
122
+ {
123
+ label: 'GitHub authentication required',
124
+ workflowId: result.workflowId,
125
+ embed: true,
126
+ expanded: true,
127
+ },
128
+ { id: `link_${result.workflowId}` },
129
+ );
130
+ ```
131
+
132
+ See `@loopstack/oauth-module` and `@loopstack/github-oauth-example` for complete usage examples.
133
+
134
+ ## Dependencies
135
+
136
+ - `@loopstack/oauth-module` — Provides `OAuthProviderRegistry`, `OAuthProviderInterface`, and `OAuthTokenSet`
137
+
138
+ ## About
139
+
140
+ Author: [Jakob Klippel](https://www.linkedin.com/in/jakob-klippel/)
141
+
142
+ License: Apache-2.0
143
+
144
+ ### Additional Resources
145
+
146
+ - [Loopstack Documentation](https://loopstack.ai/docs)
147
+ - [Getting Started with Loopstack](https://loopstack.ai/docs/getting-started)
148
+ - For more examples see the [Loopstack Registry](https://loopstack.ai/registry)
package/package.json CHANGED
@@ -9,7 +9,7 @@
9
9
  "module",
10
10
  "oauth"
11
11
  ],
12
- "version": "0.2.0",
12
+ "version": "0.2.2",
13
13
  "license": "Apache-2.0",
14
14
  "author": {
15
15
  "name": "Jakob Klippel",
@@ -30,7 +30,7 @@
30
30
  "watch": "nest build --watch"
31
31
  },
32
32
  "dependencies": {
33
- "@loopstack/oauth-module": "^0.2.0",
33
+ "@loopstack/oauth-module": "^0.2.2",
34
34
  "zod": "^4.3.6"
35
35
  },
36
36
  "files": [
@@ -46,7 +46,12 @@
46
46
  "rootDir": "src",
47
47
  "testRegex": ".*\\.spec\\.ts$",
48
48
  "transform": {
49
- "^.+\\.ts$": "ts-jest"
49
+ "^.+\\.ts$": [
50
+ "ts-jest",
51
+ {
52
+ "tsconfig": "tsconfig.spec.json"
53
+ }
54
+ ]
50
55
  },
51
56
  "collectCoverageFrom": [
52
57
  "**/*.(t|j)s"