ampless 1.0.0-alpha.32 → 1.0.0-alpha.34

package/dist/index.d.ts

@@ -575,7 +575,48 @@ interface PluginMetadata {
         types?: Record<string, string>;
     };
 }
-type PluginEventHandler<T extends EventType = EventType> = (event: AmplessEvent<T>, ctx: PluginRuntimeContext) => Promise<void>;
+/**
+ * Hook return value reservation (Phase 1: type only, runtime no-op).
+ *
+ * Today's runtime (after-event SQS Lambdas) ignores the return value
+ * entirely. The type is widened so a future PR can land additive
+ * directives without breaking plugin authors who publish in the
+ * meantime. Likely first use case:
+ *
+ *   - `metrics?: Record<string, number>` — emit observability data
+ *     without touching CloudWatch SDK directly from the plugin.
+ *
+ * `cancel` / `post` rewrite-style directives are NOT enabled by this
+ * type alone — they would also require `before:*` events to be wired
+ * to plugins (currently reserved, see events.ts) and payload shapes
+ * to expose mutable bodies. This PR widens the return surface only;
+ * richer semantics need follow-on PRs.
+ *
+ * The `readonly __amplessPluginHookResult?: never` marker is a
+ * type-level nominal tag: it prevents `Promise<void | PluginHookResult>`
+ * from silently accepting unrelated promise types like
+ * `Promise<string>` or `Promise<number>`. Plugin authors do not need
+ * to set this field — it is optional and exists only to constrain
+ * what the union accepts.
+ */
+interface PluginHookResult {
+    readonly __amplessPluginHookResult?: never;
+}
+/**
+ * Async event hook handler.
+ *
+ * The return value is reserved (see `PluginHookResult`). Today's
+ * runtime ignores it — returning `undefined` (`Promise<void>`) is
+ * the canonical "no-op" and matches existing plugin code without
+ * migration. Plugins that explicitly return a `PluginHookResult`
+ * object type-check today but do not change runtime behaviour
+ * until the matching capability PR lands.
+ *
+ * Non-PluginHookResult promise types (`Promise<string>`,
+ * `Promise<number>`, etc.) are rejected at compile time by the
+ * `__amplessPluginHookResult` private marker on `PluginHookResult`.
+ */
+type PluginEventHandler<T extends EventType = EventType> = (event: AmplessEvent<T>, ctx: PluginRuntimeContext) => Promise<void | PluginHookResult>;
 /**
  * Runtime services injected into hook handlers by the Lambda processor.
  * Decoupling plugins from concrete AWS clients lets us swap implementations
@@ -1510,4 +1551,4 @@ declare function pickDefaultEntrypoint(files: readonly {
 
 declare const VERSION = "0.0.1";
 
-export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };
+export { type AmplessEvent, type AmplessPlugin, type AuthContext, type BundleExtractResult, type CacheConfig, type CacheStrategy, type Config, type ContentEventPayload, type ContentEventType, type ContentFormat, type ContentTypeDefinition, type CreatePostInput, DEFAULT_ENTRYPOINT, type DateFormat, type EventPayloadOf, type EventType, type ExtractedFile, type FieldDefinition, type FieldType, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type LocalizedString, MAX_BUNDLE_BYTES, type Media, type MediaEventPayload, type MediaEventType, type MediaMetadata, type MediaProcessingDefaults, type OgImageConfig, type OgImageFont, type OgImageRenderContext, PLUGIN_KEY_PATTERN, type Page, type PluginBooleanField, type PluginCapability, type PluginCodeField, type PluginEventHandler, type PluginHookResult, type PluginJsonField, type PluginMetadata, type PluginNumberField, type PluginPackageManifest, type PluginPublicRenderContext, type PluginRepeatableField, type PluginRepeatableSubField, type PluginRuntimeContext, type PluginSecretField, type PluginSelectField, type PluginSettingField, type PluginSettingsManifest, type PluginTextField, type PluginTextareaField, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostStatus, type PostsProvider, type PublicBodyDescriptor, type PublicHeadDescriptor, type PublicPostBodyDescriptor, type PublicPostHtmlDescriptor, type PublicPostHtmlPosition, type Role, SITE_CONFIG_PK, type ScriptStrategy, type SiteSettingsEventPayload, type SiteSettingsEventType, type StaticPostBody, type StaticPostFileMeta, type StreamEventName, TEXT_EXTENSIONS, type ThemeColorField, type ThemeField, type ThemeFieldType, type ThemeFontFamilyField, type ThemeImageField, type ThemeLengthField, type ThemeLinkListField, type ThemeManifest, type ThemeModule, type ThemeRouteContext, type ThemeSelectField, type ThemeTextField, type TrustLevel, type TrustedPluginRuntimeContext, VERSION, type ValidationIssue, bundlePrefix, createPost, decodeAwsJson, defineConfig, definePlugin, defineSchema, defineTheme, defineThemeModule, deletePost, deleteSiteSetting, detectContentEvents, encodeAwsJson, escapeXml, extractFirstImageUrl, findAbsolutePathRefs, flattenSettings, formatColorPair, formatDate, formatPublicAssetUrl, getKvStore, getPost, getPostById, getSiteSetting, hasKvStore, hasPostsProvider, isTagListUrl, isValidPluginKey, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/docs/plugin-author-guide.ja.md

@@ -563,6 +563,50 @@ React 19 はさらに、クライアントコンポーネントのレンダー
 
 投稿単位の見える出力には `publicHtmlForPost` を使ってください（Phase 6d — 上の例と §6 の `PublicPostHtmlDescriptor` 参照）。runtime が post 本文の周囲の固定スロットにサーバーサイド HTML を出すので、hydration と競合しません。
 
+---
+
+## 6a. 予約投稿とコンテンツイベント
+
+ampless は**予約投稿**をサポートしています。`status: 'published'` かつ `publishedAt` が未来の投稿は、その時刻まで公開読み出しから隠されます。`publishedAt` を過ぎると、サイトの自然なキャッシュ有効期限（デフォルト ≤ ~5 分）の範囲内で公開されます — 秒単位の正確なトリガーはありません。
+
+### イベントは保存時に発火する（`publishedAt` のタイミングではない）
+
+`content.published`（および `content.updated`）は DynamoDB Streams 経由で**投稿が保存されたとき**に emit されます。`publishedAt` が到来したときではありません。つまり、`content.published` に反応するプラグインは、投稿が未来日時の場合、**その投稿が公開される前**に実行されます。
+
+現在の投稿一覧から公開アセットを再構築する trusted プラグイン（RSS、sitemap、JSON インデックスなど）にとってはこれは問題ありません — `listPublishedPosts()` が未来日時の投稿をすでに除外しているため、再生成されたアセットはその投稿が公開されるまでリストに含まれません。
+
+一方、**外部通知プラグイン**（webhook、プッシュ通知、SNS 投稿など）には影響があります。投稿の URL が 404 を返しているまたはホームページにリダイレクトされている間に通知が配信されてしまいます。
+
+### 推奨パターン: `publishedAt` でゲートする
+
+ディスパッチの前に `event.payload.publishedAt` を確認します。投稿が未来日時の場合はスキップまたは保留します:
+
+```ts
+hooks: {
+  async 'content.published'(event, ctx) {
+    const { publishedAt } = event.payload
+
+    // 予約投稿には通知を送らない。イベントは保存時に発火するが、
+    // 投稿が公開されるのは publishedAt になってから。
+    if (publishedAt && new Date(publishedAt) > new Date()) {
+      return
+    }
+
+    // 投稿は今すぐ公開状態 — 通知しても安全。
+    await sendWebhook(event.payload, ctx)
+  },
+}
+```
+
+イベントペイロード内の `publishedAt` は UTC ISO 8601 文字列（`...Z`）です。`Date.now()` と比較する前に `new Date()` またはお好みの日付ライブラリでパースしてください。
+
+### 今後の対応
+
+`content.published` の発火を保存時ではなく `publishedAt` のタイミングに合わせる機能 — EventBridge Scheduler または DynamoDB TTL トリガー Lambda によるスケジューラーコンポーネントが必要 — は計画中の機能強化です。現リリースのスコープには含まれていません。それまでの間は上記のパターンが通知プラグインにおける推奨ガードです。
+
+オペレーター視点からの `publishedAt` セマンティクスの全体像は [`docs/scheduled-publishing.md`](https://github.com/heavymoons/ampless/blob/main/docs/scheduled-publishing.ja.md) を参照してください。
+
+---
 
 ### CSP nonce（Phase 1 予約）
 
@@ -617,7 +661,28 @@ npm 公開のスタンドアロンプラグインの場合は、`package.json#am
 
 ## 7. 非同期イベントフック
 
-`hooks` は SQS から到着したイベントを trust_level に対応する processor Lambda が受けて実行します。runtime context (`ctx`) の中身:
+`hooks` は SQS から到着したイベントを trust_level に対応する processor Lambda が受けて実行します。
+
+### 戻り値の予約
+
+`PluginEventHandler` の戻り値型は `Promise<void | PluginHookResult>`。
+runtime は現状この戻り値を完全に無視する — 既存 plugin が
+`Promise<void>` を返す形は migration 不要で動き続ける。
+`PluginHookResult` は将来の directive (最初の用例として有力:
+`metrics?: Record<string, number>` による observability emission) のた
+めの予約で、今宣言するのは forward-compatibility のヒントとして
+の扱い。注意: rewrite / cancel 系 directive は本 widening だけで
+は有効化されない — `before:*` event の plugin 配線と payload 拡張
+が別 PR で必要。
+
+`PluginHookResult` には private な `__amplessPluginHookResult`
+marker が付いており、union が `Promise<string>` / `Promise<number>`
+等の無関係な promise を silently 受け入れないようになっている —
+plugin 作者がこの marker を明示的に設定する必要は無い。
+
+### Runtime context
+
+runtime context (`ctx`) の中身:
 
 ```ts
 interface PluginRuntimeContext {

package/docs/plugin-author-guide.md

@@ -719,6 +719,72 @@ the example above and §6's `PublicPostHtmlDescriptor`). The runtime
 emits server-side HTML at fixed slots around the post body, so
 nothing races against hydration.
 
+---
+
+## 6a. Scheduled posts and content events
+
+ampless supports **scheduled publishing**: a post with `status:
+'published'` and a future `publishedAt` is hidden from all public
+reads until that time. Once `publishedAt` arrives, the post becomes
+visible within the site's natural cache window (≤ ~5 minutes by
+default) — there is no exact-time trigger.
+
+### Events fire at save time, not at `publishedAt`
+
+`content.published` (and `content.updated`) are emitted via DynamoDB
+Streams **when the post is saved**, not when `publishedAt` arrives.
+This means a plugin that reacts to `content.published` will run
+**before the post is publicly visible** when the post is future-dated.
+
+For trusted plugins that rebuild public assets from the current post
+list (RSS, sitemap, JSON indexes), this is harmless — `listPublishedPosts()`
+already filters out future-dated posts, so the regenerated asset
+simply omits the scheduled post until it goes live.
+
+For **outbound-notification plugins** (webhook, push notification,
+social post) the early fire matters: the notification will be
+delivered to subscribers while the post URL still returns 404 or
+redirects to the home page.
+
+### Recommended pattern: gate on `publishedAt`
+
+Check `event.payload.publishedAt` before dispatching. Skip or defer
+when the post is future-dated:
+
+```ts
+hooks: {
+  async 'content.published'(event, ctx) {
+    const { publishedAt } = event.payload
+
+    // Skip notification for future-scheduled posts. The event fires
+    // at save time, but the post won't be public until publishedAt.
+    if (publishedAt && new Date(publishedAt) > new Date()) {
+      return
+    }
+
+    // Post is live now — safe to notify.
+    await sendWebhook(event.payload, ctx)
+  },
+}
+```
+
+The `publishedAt` value in the event payload is a UTC ISO 8601 string
+(`...Z`). Parse it with `new Date()` or your preferred date library
+before comparing against `Date.now()`.
+
+### Future work
+
+Aligning event emission with the scheduled time — so `content.published`
+fires at `publishedAt` rather than at save time — is a planned
+enhancement. It requires a scheduler component (EventBridge Scheduler
+or a DynamoDB TTL-triggered Lambda) and is not yet in scope for the
+current release. Until then, the pattern above is the recommended
+guard for notification plugins.
+
+For a full description of `publishedAt` semantics from the operator's
+perspective, see [`docs/scheduled-publishing.md`](https://github.com/heavymoons/ampless/blob/main/docs/scheduled-publishing.md).
+
+---
 
 ### CSP nonce (Phase 1 reservation)
 
@@ -794,7 +860,28 @@ manifest and the factory return value:
 ## 7. Async event hooks
 
 `hooks` runs inside the trust_level-matched processor Lambda when an
-event arrives via SQS. The runtime context (`ctx`) carries:
+event arrives via SQS.
+
+### Return value reservation
+
+`PluginEventHandler` returns `Promise<void | PluginHookResult>`. The
+runtime currently ignores the return value entirely — existing
+plugins returning `Promise<void>` keep working without migration.
+`PluginHookResult` is reserved for a future directive (likely first:
+`metrics?: Record<string, number>` for observability emission);
+declaring it today is a forward-compatibility hint. Note: rewrite
+or cancel directives are NOT enabled by this widening alone — they
+require additional `before:*` event support and payload extensions
+in separate PRs.
+
+`PluginHookResult` carries a private `__amplessPluginHookResult`
+marker so that the union does not silently accept unrelated promise
+types (`Promise<string>` / `Promise<number>` etc.) — plugin authors
+do not need to set this field.
+
+### Runtime context
+
+The runtime context (`ctx`) carries:
 
 ```ts
 interface PluginRuntimeContext {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ampless",
-  "version": "1.0.0-alpha.32",
+  "version": "1.0.0-alpha.34",
   "description": "Serverless CMS for AWS Amplify",
   "license": "MIT",
   "type": "module",