@hostwebhook/node 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,167 @@
+# @hostwebhook/node
+
+Official Node.js SDK for [HostWebhook](https://hostwebhook.com) — verify webhook signatures and send webhooks through the platform.
+
+## Install
+
+```sh
+npm install @hostwebhook/node
+```
+
+Requires Node.js 18+.
+
+## Verify Webhook Signatures
+
+HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity and prevent replay attacks.
+
+### Express
+
+```ts
+import express from 'express';
+import { expressMiddleware } from '@hostwebhook/node';
+
+const app = express();
+
+app.post('/webhooks',
+  express.raw({ type: 'application/json' }),
+  expressMiddleware(process.env.SIGNING_SECRET!),
+  (req, res) => {
+    const payload = JSON.parse(req.body.toString());
+    // process payload...
+    res.json({ received: true });
+  },
+);
+```
+
+> **Important:** Use `express.raw()` so `req.body` is a Buffer, not parsed JSON.
+
+### NestJS
+
+```ts
+import { Controller, Post, UseGuards, Req } from '@nestjs/common';
+import { createNestGuard } from '@hostwebhook/node';
+
+const WebhookGuard = createNestGuard(process.env.SIGNING_SECRET!);
+
+@Controller('webhooks')
+export class WebhooksController {
+  @Post()
+  @UseGuards(WebhookGuard)
+  handle(@Req() req: Request) {
+    return { received: true };
+  }
+}
+```
+
+### Fastify
+
+```ts
+import Fastify from 'fastify';
+import { fastifyHook } from '@hostwebhook/node';
+
+const app = Fastify();
+app.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => done(null, body));
+
+app.post('/webhooks', {
+  preHandler: fastifyHook(process.env.SIGNING_SECRET!),
+}, (req, reply) => {
+  reply.send({ received: true });
+});
+```
+
+### Manual Verification
+
+```ts
+import { verify, VerificationError } from '@hostwebhook/node';
+
+try {
+  verify(rawBody, request.headers, secret);
+  // signature valid
+} catch (err) {
+  if (err instanceof VerificationError) {
+    // invalid — reject the request
+  }
+}
+```
+
+Options: `verify(payload, headers, secret, { maxAgeSec: 300 })` — default 300s (5 min). Set `0` to disable replay protection.
+
+## Send Webhooks
+
+Send webhook payloads through HostWebhook for reliable delivery with retries and monitoring.
+
+### Class-based
+
+```ts
+import { HostWebhook } from '@hostwebhook/node';
+
+const hw = new HostWebhook({ token: 'your_ingress_token' });
+
+const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
+```
+
+### Batch
+
+```ts
+const results = await hw.sendBatch([
+  { event: 'user.signup', userId: '1' },
+  { event: 'user.signup', userId: '2' },
+]);
+```
+
+### Standalone Function
+
+```ts
+import { send } from '@hostwebhook/node';
+
+const { eventId } = await send(
+  { token: 'your_ingress_token' },
+  { event: 'test', data: 'hello' },
+);
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | `string` | *required* | Endpoint ingress token |
+| `baseUrl` | `string` | `https://api.hostwebhook.com` | API base URL |
+| `signingSecret` | `string` | — | Signs outgoing requests with HMAC-SHA256 |
+| `defaultHeaders` | `Record<string, string>` | — | Headers added to every request |
+| `timeoutMs` | `number` | `10000` | Request timeout in ms |
+
+## Error Handling
+
+```ts
+import { SendError, VerificationError } from '@hostwebhook/node';
+
+// Send errors
+try {
+  await hw.send(payload);
+} catch (err) {
+  if (err instanceof SendError) {
+    console.log(err.statusCode, err.responseBody);
+  }
+}
+
+// Verification errors
+try {
+  verify(body, headers, secret);
+} catch (err) {
+  if (err instanceof VerificationError) {
+    console.log(err.message);
+  }
+}
+```
+
+## Signature Format
+
+```
+X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>
+```
+
+HMAC computed as: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`
+
+## License
+
+MIT

package/llms.txt

@@ -0,0 +1,167 @@
+# @hostwebhook/node
+
+> Official HostWebhook Node.js SDK — verify webhook signatures and send webhooks through the platform.
+
+## Install
+
+npm install @hostwebhook/node
+
+## Verify Signatures (receiving webhooks)
+
+HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity.
+
+### Express
+
+```ts
+import express from 'express';
+import { expressMiddleware } from '@hostwebhook/node';
+
+const app = express();
+app.post('/webhooks',
+  express.raw({ type: 'application/json' }),
+  expressMiddleware(process.env.SIGNING_SECRET!),
+  (req, res) => {
+    const payload = JSON.parse(req.body.toString());
+    // process payload...
+    res.json({ received: true });
+  },
+);
+```
+
+IMPORTANT: Use `express.raw()` so `req.body` is a Buffer, not parsed JSON.
+
+### NestJS
+
+```ts
+import { Controller, Post, UseGuards, Req } from '@nestjs/common';
+import { createNestGuard } from '@hostwebhook/node';
+
+const WebhookGuard = createNestGuard(process.env.SIGNING_SECRET!);
+
+@Controller('webhooks')
+export class WebhooksController {
+  @Post()
+  @UseGuards(WebhookGuard)
+  handle(@Req() req: Request) {
+    return { received: true };
+  }
+}
+```
+
+### Fastify
+
+```ts
+import Fastify from 'fastify';
+import { fastifyHook } from '@hostwebhook/node';
+
+const app = Fastify();
+app.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => done(null, body));
+
+app.post('/webhooks', {
+  preHandler: fastifyHook(process.env.SIGNING_SECRET!),
+}, (req, reply) => {
+  reply.send({ received: true });
+});
+```
+
+### Manual verification
+
+```ts
+import { verify, VerificationError } from '@hostwebhook/node';
+
+try {
+  verify(rawBody, request.headers, secret);
+  // signature is valid
+} catch (err) {
+  if (err instanceof VerificationError) {
+    // invalid signature — reject
+  }
+}
+```
+
+verify(payload, headers, secret, options?) — throws VerificationError if invalid.
+VerifyOptions: { maxAgeSec?: number } — default 300 (5 min). Set 0 to disable replay protection.
+
+## Send Webhooks (sending through HostWebhook)
+
+### Class-based client
+
+```ts
+import { HostWebhook } from '@hostwebhook/node';
+
+const hw = new HostWebhook({ token: 'your_ingress_token' });
+
+// Send a single event
+const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
+
+// Send multiple events in parallel
+const results = await hw.sendBatch([
+  { event: 'user.signup', userId: '1' },
+  { event: 'user.signup', userId: '2' },
+]);
+```
+
+### Standalone function (no class needed)
+
+```ts
+import { send } from '@hostwebhook/node';
+
+const { eventId } = await send(
+  { token: 'your_ingress_token' },
+  { event: 'test', data: 'hello' },
+);
+```
+
+## Configuration
+
+HostWebhookConfig: {
+  token: string (required — your endpoint's ingress token),
+  baseUrl?: string (default: https://api.hostwebhook.com),
+  signingSecret?: string (optional — signs outgoing requests with HMAC-SHA256),
+  defaultHeaders?: Record<string, string>,
+  timeoutMs?: number (default: 10000),
+}
+
+SendOptions: {
+  headers?: Record<string, string>,
+  contentType?: string (default: application/json),
+  rawBody?: string | Buffer (skip JSON.stringify, send raw),
+}
+
+SendResult: { eventId: string }
+
+## Signature Format
+
+Header: `X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>`
+HMAC computed as: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`
+
+## Error Handling
+
+```ts
+import { SendError, VerificationError } from '@hostwebhook/node';
+
+// SendError — thrown when API returns non-2xx
+try {
+  await hw.send(payload);
+} catch (err) {
+  if (err instanceof SendError) {
+    console.log(err.statusCode, err.responseBody);
+  }
+}
+
+// VerificationError — thrown when signature is invalid
+try {
+  verify(body, headers, secret);
+} catch (err) {
+  if (err instanceof VerificationError) {
+    console.log(err.message); // e.g. "Signature mismatch"
+  }
+}
+```
+
+## Exports
+
+Functions: verify, expressMiddleware, createNestGuard, fastifyHook, send
+Classes: HostWebhook, SendError, VerificationError
+Types: VerifyOptions, HostWebhookConfig, SendOptions, SendResult, WebhookHeaders
+Helpers: parseHeaders (extract webhook metadata from headers)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/node",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Official HostWebhook SDK — verify signatures, parse headers, and send webhooks",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -13,7 +13,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "llms.txt"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",