feat: Stackables Webhooks initial release (#1)

* feat: Configuration helper
* feat: Initial version of the plugin, without a loader
* feat: Initial loader interface

Author: aarne

.github/SECURITY.md

@@ -0,0 +1,27 @@
+## Security
+
+Stackables team takes the security of our software products and services extremely seriously.
+
+If you believe you have found a security vulnerability in any of our repositories, please report it to us as described below.
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please use the following email alias security@stackables.io
+
+You should receive a response within 48 hours.
+
+Please try to include as much information as possible to help us better understand the nature and scope of the possible issue. Information that will help us includes:
+
+  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+## Preferred Languages
+
+We prefer all communications to be in English, but for security we will try to do our best to understand you.

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "daily"

.github/workflows/coverage.yml

@@ -0,0 +1,23 @@
+name: Code Coverage
+
+on: [push, pull_request]
+
+jobs:
+  release:
+    name: Coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: '16'
+      - name: Install dependencies
+        run: npm install
+      - name: Run the tests
+        run: npm test -- --coverage
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v1

.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+on:
+  push:
+    branches:
+      - main
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: "16"
+      - name: Install dependencies
+        run: npm install
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm run semantic-release

.gitignore

@@ -0,0 +1,5 @@
+node_modules
+build
+coverage
+.DS_Store
+tmp

README.md

@@ -1,13 +1,90 @@
 # Stackables Webhooks
 
-GraphQL Code Generator plugin for Stackables webhooks
+GraphQL Code Generator plugin for Stackables webhooks.
+
+## Install
+
+This is a plugin for GraphQL Code Generator. [See official installation docs for more info](https://www.graphql-code-generator.com/docs/getting-started/installation).
+
+All packages should be installed as dev dependencies and are used only during development.
 
 ```bash
-npm add codegen-stackables-webhooks@beta
+# install generator cli
+npm install --save-dev @graphql-codegen/cli
+
+# required typescript plugins
+npm install --save-dev @graphql-codegen/typescript
+npm install --save-dev @graphql-codegen/typescript-operations
+
+# webhooks plugin
+npm install --save-dev codegen-stackables-webhooks@beta
+```
+
+## Configuration
+
+While GraphQL Code Generator configuration is simple we still recommend to use the [graphql configuration](https://graphql-config.com/introduction) for more universal configuration. 
+
+We also provide a simple utility to help with the verbosity. But you can always take full control when you need to.
+
+`graphql.config.js` in repository root
+
+```js
+const { getConfiguration } = require('stackables-webhooks');
+
+// Returned configuration is just a plain object
+// So if needed you can add or modify the returned setting as needed
+
+module.exports = getConfiguration({
+    generatedFile: "<string>",
+    accountSlug: "<string>",
+    introspectionToken: "<string>"
+})
+```
+
+[See full configuration options here](https://github.com/stackables/codegen-stackables-webhooks/blob/beta/docs/config.md)
+
+## Usage
+
+Generated types are easy to use with [cloudevents-router](https://github.com/stackables/cloudevents-router) package.
+
+```typescript
+import { CloudEventsRouter } from 'cloudevents-router'
+import { FragmentRegistry } from './src/generated/webhooks'
+
+const router = new CloudEventsRouter<FragmentRegistry>()
+
+router.on('stackables.webhook.v1.YourHookName', async (event) => {
+    console.log('Received typed webhook', event.data)
+})
 ```
 
----
+See more options on how to use the router with different web servers [here](https://github.com/stackables/cloudevents-router). But simplest is to just use nodejs built in web server like this:
+
+```typescript
+import http from "http"
+import { getMiddleware } from "cloudevents-router"
+
+// const router = ... 
+
+const middleware = getMiddleware(router, { path: '/' })
+const server = http.createServer(middleware)
+
+server.listen(5000);
+```
+
+## Advanced Usage
+
+- [Payload structure](https://github.com/stackables/codegen-stackables-webhooks/blob/beta/docs/advanced.md)
+- [Provided configuration](https://github.com/stackables/codegen-stackables-webhooks/blob/beta/docs/advanced.md)
+- [Callback tokens](https://github.com/stackables/codegen-stackables-webhooks/blob/beta/docs/advanced.md)
+- [Branches](https://github.com/stackables/codegen-stackables-webhooks/blob/beta/docs/advanced.md)
+
+## Deployment options
+
+You can deploy the created web service anywhere as long as its publicly accessible. **But,** You need to ensure that you validate the Stackables JWT token. [Instructions here](https://github.com/stackables/codegen-stackables-webhooks/blob/beta/docs/deploy.md)
+
+You can also use Stackables cloud to host your webhooks, in this case authentication and scaling is taken care of by us. [Instructions here](https://github.com/stackables/codegen-stackables-webhooks/blob/beta/docs/deploy.md)
 
-_Stackables service is still in closed beta, but we plan to open up for more users before the end of the year_
+## Thats it ...
 
-_For more info you can reach us at info@stackables.io_
+... happy coding :)

docs/advanced.md

@@ -0,0 +1,6 @@
+# Webhooks usage
+
+## Payload structure
+## Provided configuration
+## Callback tokens
+## Branches

docs/config.md

@@ -0,0 +1,78 @@
+## Recommended setup
+
+While GraphQL Code Generator configuration is simple we still recommend to use the [graphql configuration](https://graphql-config.com/introduction) for more universal configuration. 
+
+We also provide a simple utility to help with the verbosity. But you can always take full control when you need to.
+
+`graphql.config.js` in repository root
+
+```js
+const { getConfiguration } = require('stackables-webhooks');
+
+// Returned configuration is just a plain object
+// So if needed you can add or modify the returned setting as needed
+
+module.exports = getConfiguration({
+    generatedFile: "<string>",
+    accountSlug: "<string>",
+    introspectionToken: "<string>"
+})
+```
+
+## Manual setup
+
+See full configuration reference at https://www.graphql-code-generator.com/docs/getting-started/codegen-config
+
+Plugin requires 3 configuration settings:
+- **Graphql schema** - Your graphql schema reference
+- **Fragment loader** - Fragments in filesystem (marked with special decorator) or load fragments from stackables cloud directly
+- **Webhooks type generator** - Register plugin to generate type map for [cloudevents-router](https://github.com/stackables/cloudevents-router) package
+
+### With Fragment loader
+
+`codegen.yml` in repository root
+
+```yml
+schema: https://data.stackables.io/stackables/cloud?introspection=<token>
+documents:
+- "https://data.stackables.io/stackables/cloud?introspection=<token>":
+  loader: "stackables-webhooks/loader"
+generates:
+  ./src/cloudevents.ts:
+    plugins:
+      - typescript
+      - typescript-operations
+      - stackables-webhooks
+    config:
+      preResolveTypes: true
+      onlyOperationTypes: true
+      fragmentRegistryName: StackablesEvents
+      fragmentRegistryDirective: register
+```
+
+### Without Fragment loader
+
+`codegen.yml` in repository root
+
+```yml
+schema: https://data.stackables.io/stackables/cloud?introspection=<token>
+documents: **/*.gql
+generates:
+  ./src/cloudevents.ts:
+    plugins:
+      - typescript
+      - typescript-operations
+      - stackables-webhooks
+    config:
+      preResolveTypes: true
+      onlyOperationTypes: true
+      fragmentRegistryName: StackablesEvents
+      fragmentRegistryDirective: register
+```
+
+**If you decide to NOT load the fragments dynamically you need to define the fragments for your webhooks manually (and keep them up to date with the service). [See instructions here](https://github.com/stackables/codegen-stackables-webhooks/blob/beta/docs/fragments.md)**
+
+### Configuration options
+
+- **fragmentRegistryName:** StackablesEvents
+- **fragmentRegistryDirective:** register

docs/deploy.md

@@ -0,0 +1,4 @@
+# Deployment options
+
+## Public (JWT auth)
+## Managed

docs/fragments.md

@@ -0,0 +1,26 @@
+# Manual fragments configuration
+
+Stackables stores webhook data requirements as fragment definitions against the base entity. While in most cases the plugin will just load the fragments dynamically from the service, it is possible to define fragments manually.
+
+Fragments can be stored in any graphql document as long as the codegen configuration is set correctly to find them.
+
+`src/webhooks.gql` for example might look like this
+
+```graphql
+fragment YourWebhookName on EntityToMonitor {
+    fields
+    you
+    want {
+        to
+        receive
+    }
+}
+```
+
+For the generator plugin to consider this fragment as webhook definition we need to mark it with a special decorator (if you change the name of the decorator you need to change generator configuration to match the new name).
+
+```graphql
+fragment YourWebhookName on EntityToMonitor @register {
+    # by default generator uses @register decorator
+}
+```