@ampless/plugin-webhook 0.2.0-alpha.2 → 0.2.0-alpha.21

package/README.ja.md

@@ -0,0 +1,106 @@
+> English: [README.md](./README.md)
+> 
+
+# @ampless/plugin-webhook
+
+ampless イベントを 1 つ以上の外部 URL に POST で通知します。
+
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。
+
+**untrusted** Lambda で実行されます — アウトバウンド HTTPS 呼び出しのみ行い、AWS データには一切触れないため、Webhook 受信先が侵害されても CMS への侵入口にはなりません。
+
+## インストール
+
+```bash
+npm install @ampless/plugin-webhook@alpha
+```
+
+## 設定
+
+`cms.config.ts` に記述します：
+
+```ts
+import webhookPlugin from '@ampless/plugin-webhook'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    webhookPlugin({
+      endpoints: [
+        {
+          url: 'https://example.com/hooks/ampless',
+          secret: process.env.WEBHOOK_SECRET,
+          events: ['content.published', 'content.unpublished', 'content.deleted'],
+        },
+        {
+          url: 'https://discord.com/api/webhooks/.../...',
+          // secret なし — Discord は署名を検証しない
+          events: ['content.published'],
+        },
+      ],
+    }),
+  ],
+})
+```
+
+| オプション | デフォルト | 備考 |
+|---|---|---|
+| `endpoints[].url` | 必須 | POST 先の HTTPS エンドポイント |
+| `endpoints[].secret` | なし | 設定時、本文を HMAC-SHA-256 で署名して `X-Ampless-Signature` ヘッダーで送信 |
+| `endpoints[].events` | すべての `content.*` | このエンドポイントを発火するイベント種別を絞り込む |
+| `endpoints[].headers` | `{}` | 全リクエストにマージされる追加ヘッダー |
+| `endpoints[].timeoutMs` | `5000` | リクエストごとのタイムアウト |
+| `url`（トップレベル） | なし | 単一エンドポイントのショートカット。`endpoints: [{ url, secret }]` と同等 |
+| `secret`（トップレベル） | なし | トップレベルの `url` と対で使用 |
+
+## リクエスト形式
+
+```http
+POST /hooks/ampless HTTP/1.1
+Host: example.com
+Content-Type: application/json
+X-Ampless-Event: content.published
+X-Ampless-Signature: sha256=<hex>
+
+{
+  "type": "content.published",
+  "payload": {
+    "siteId": "default",
+    "postId": "post-001",
+    "slug": "hello",
+    "title": "Hello",
+    "status": "published",
+    "publishedAt": "2026-04-30T00:00:00.000Z",
+    "tags": ["intro"]
+  },
+  "timestamp": "2026-04-30T00:00:01.000Z"
+}
+```
+
+## 署名の検証（Node.js）
+
+```ts
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+function verify(rawBody: string, signatureHeader: string, secret: string): boolean {
+  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
+  const a = Buffer.from(expected)
+  const b = Buffer.from(signatureHeader)
+  if (a.length !== b.length) return false
+  return timingSafeEqual(a, b)
+}
+```
+
+HMAC は必ず JSON パース前の**生のリクエストボディ**に対して計算し、定数時間比較を使用してください。
+
+## リトライ動作
+
+いずれかのエンドポイントが 2xx 以外のレスポンスを返した場合（またはタイムアウトした場合）、プラグインは例外を投げます。トラストレベルプロセッサーの Lambda が SQS に再スローし、デッドレターキューに移動するまで最大 3 回リトライされます。同じイベントが複数回配信される可能性があるため、冪等な受信側を推奨します。
+
+## 発火するイベント
+
+- `content.created` — 新規投稿（任意のステータス）
+- `content.published` — ステータスが `draft` → `published` に変化、または公開済み投稿が挿入された
+- `content.unpublished` — ステータスが `published` → `draft` に変化、または公開済み投稿が削除された
+- `content.updated` — 任意の MODIFY（公開 / 非公開への遷移時にも `published` / `unpublished` と同時に発火）
+- `content.deleted` — 投稿が削除された

package/README.md

@@ -1,3 +1,6 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+
 # @ampless/plugin-webhook
 
 POST ampless events to one or more external URLs.

package/dist/index.d.ts

@@ -29,16 +29,13 @@ interface WebhookEndpoint {
     timeoutMs?: number;
 }
 interface WebhookPluginOptions {
-    endpoints?: WebhookEndpoint[];
-    /** Backwards-compatible single-endpoint shortcut. */
-    url?: string;
-    secret?: string;
+    endpoints: WebhookEndpoint[];
 }
 /**
  * Webhook plugin. Posts a JSON envelope to one or more external URLs
  * whenever a subscribed event fires. Runs in the untrusted Lambda — it
  * needs no AWS data access, only outbound HTTPS.
  */
-declare function webhookPlugin(options?: WebhookPluginOptions): AmplessPlugin;
+declare function webhookPlugin(options: WebhookPluginOptions): AmplessPlugin;
 
 export { type WebhookEndpoint, type WebhookPluginOptions, webhookPlugin as default, signPayload };

package/dist/index.js

@@ -15,8 +15,8 @@ var ALL_CONTENT_EVENTS = [
   "content.unpublished",
   "content.deleted"
 ];
-function webhookPlugin(options = {}) {
-  const endpoints = normalizeEndpoints(options);
+function webhookPlugin(options) {
+  const endpoints = options.endpoints;
   const subscribed = /* @__PURE__ */ new Set();
   for (const ep of endpoints) {
     const events = ep.events ?? ALL_CONTENT_EVENTS;
@@ -35,12 +35,6 @@ function webhookPlugin(options = {}) {
     hooks
   });
 }
-function normalizeEndpoints(options) {
-  const list = [];
-  if (options.url) list.push({ url: options.url, secret: options.secret });
-  if (options.endpoints) list.push(...options.endpoints);
-  return list;
-}
 async function dispatch(endpoints, event) {
   const body = JSON.stringify({
     type: event.type,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ampless/plugin-webhook",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.21",
   "description": "Webhook plugin for ampless — POST events to external URLs",
   "license": "MIT",
   "type": "module",
@@ -25,7 +25,7 @@
   "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook#readme",
   "bugs": "https://github.com/heavymoons/ampless/issues",
   "dependencies": {
-    "ampless": "0.2.0-alpha.2"
+    "ampless": "1.0.0-alpha.21"
   },
   "keywords": [
     "ampless",