Merge pull request #1 from seamapi/v1

Add SeamWebhook

Author: razor-x

.c8rc.json

@@ -2,7 +2,6 @@
   "exclude": [
     "**/index.ts",
     "package/**/*.ts",
-    "examples/**/*.ts",
     "**/*.test.ts",
     "ava.config.js"
   ],

README.md

@@ -7,17 +7,112 @@ Webhook SDK for the Seam API written in TypeScript.
 
 ## Description
 
-TODO
+[Seam] makes it easy to integrate IoT devices with your applications.
+This is an official SDK for the Seam API.
+Please refer to the official [Seam Docs] to get started.
+
+The Seam API implements webhooks using [Svix].
+This SDK exports a thin wrapper around the svix package
+Use it to parse and validate Seam webhook events
+with full TypeScript support for Seam event types.
+
+Refer to the [Svix docs on Consuming Webhooks] for
+an in-depth guide on best-practices for handling webhooks
+in your application.
+
+[Seam]: https://www.seam.co/
+[Seam Docs]: https://docs.seam.co/latest/
+[Svix]: https://www.svix.com/
+[Svix docs on Consuming Webhooks]: https://docs.svix.com/receiving/introduction
 
 ## Installation
 
+_This is a low-level package meant for applications and libraries with particular dependency requirements.
+Before using this package, ensure you understand the installation and updating instructions.
+This SDK is entirely contained in the [seamapi] package. Seam recommends using that package instead
+for simpler dependency management._
+
 Add this as a dependency to your project using [npm] with
 
 ```
 $ npm install @seamapi/webhook
 ```
 
 [npm]: https://www.npmjs.com/
+[seamapi]: https://www.npmjs.com/package/seamapi
+
+### Optional Peer Dependencies for TypeScript
+
+This package has optional peer dependencies for TypeScript users.
+Recent versions of npm will automatically install peer dependencies by default.
+For those users, no additional steps are necessary for full TypeScript support,
+however users should still explicitly install the latest types (see the next section).
+
+Other package managers require peer dependencies to be added manually.
+Refer to any warnings generated by your package manager
+about missing peer dependencies and install them as needed.
+Refer to the next section for keeping the types updated.
+
+#### Keeping up with the latest types
+
+This package depends on [seamapi-types] for the latest TypeScript types.
+New versions of this SDK are generally not released when new types are published.
+Unless your project frequently runs a blanket `npm update`,
+the types will become outdated with the Seam API over time.
+Thus, users of this package should explicitly install the types with
+
+```
+$ npm install -D seamapi-types
+```
+
+and update them when consuming new API features with
+
+```
+$ npm install -D seamapi-types
+```
+
+[seamapi-types]: https://github.com/seamapi/seamapi-types/
+
+## Usage
+
+First, create a webhook using the Seam API or Seam Console
+and obtain a Seam webhook secret.
+
+_This example is for [Express], see the [Svix docs for more examples in specific frameworks](https://docs.svix.com/receiving/verifying-payloads/how)._
+
+```js
+import { SeamWebhook } from '@seamapi/webhook'
+import express from 'express'
+import bodyParser from 'body-parser'
+
+import { storeEvent } from './store-event.js'
+
+const app = express()
+
+const webhook = new SeamWebhook(process.env.SEAM_WEBHOOK_SECRET)
+
+app.post(
+  '/webhook',
+  bodyParser.raw({ type: 'application/json' }),
+  (req, res) => {
+    let data
+    try {
+      data = webhook.verify(payload, headers)
+    } catch {
+      return res.status(400).send()
+    }
+
+    storeEvent(data, (err) => {
+      if (err != null) {
+        return res.status(500).send()
+      }
+      res.status(204).send()
+    })
+  },
+)
+```
+
+[Express]: https://expressjs.com/
 
 ## Development and Testing