ampless 1.0.0-alpha.37 → 1.0.0-alpha.39

package/dist/index.d.ts

@@ -973,7 +973,13 @@ interface PluginSettingsManifest {
 }
 interface AmplessPlugin {
     name: string;
-    /** Plugin API version. Currently 1; future versions will be additive. */
+    /**
+     * Plugin API version. Currently `1` is the only supported value.
+     * `apiVersion` is the breaking-change marker on the plugin contract;
+     * additive changes (new optional fields, new reserved capabilities)
+     * stay within `apiVersion: 1`. See the apiVersion bump policy in
+     * `docs/architecture/08-plugin-architecture.md` for the full criteria.
+     */
     apiVersion: 1;
     /**
      * Optional npm package name (e.g. `'@scope/ampless-plugin-foo'` or
@@ -1361,6 +1367,12 @@ interface Config {
      * field is absent.
      */
     cache?: CacheConfig;
+    /**
+     * Post revision-history knobs. The event-dispatcher Lambda snapshots
+     * each post save into the `PostHistory` table; this controls how long
+     * those snapshots are retained.
+     */
+    history?: HistoryConfig;
 }
 /**
  * Tunables for middleware-computed `Cache-Control`. See
@@ -1385,6 +1397,20 @@ interface CacheConfig {
      */
     deepTtlSeconds?: number;
 }
+/**
+ * Post revision-history tunables, read by the event-dispatcher Lambda
+ * (via the template shell) when snapshotting each post save.
+ */
+interface HistoryConfig {
+    /**
+     * Days to retain each post revision before DynamoDB TTL deletes it.
+     * Default 0 = keep forever (no `ttl` attribute is written). DynamoDB TTL
+     * deletes within ~48h after expiry, so effective retention is
+     * retentionDays + up to ~2 days. Changing this only affects revisions
+     * written afterward — existing rows keep their original expiry.
+     */
+    retentionDays?: number;
+}
 type Role = 'reader' | 'editor' | 'admin';
 interface AuthContext {
     userId: string;
@@ -1415,6 +1441,45 @@ interface ListOptions {
 type CreatePostInput = Omit<Post, 'postId'> & {
     postId?: string;
 };
+/**
+ * One in-memory snapshot of a Post at save time, read back from the
+ * `PostHistory` table (written by the event-dispatcher Lambda on each
+ * Post INSERT/MODIFY — see packages/backend/src/events/dispatcher.ts).
+ *
+ * `body` is already decoded from its AWSJSON wire form (the provider
+ * runs `decodeAwsJson` before handing the row up), so it matches the
+ * `Post['body']` shape for the declared `format`.
+ */
+interface PostRevision {
+    /** Deterministic id `${postId}#${revisedAt}` — unique per save. */
+    postHistoryId: string;
+    postId: string;
+    /** ISO 8601 save time. Also the `byPost` GSI sort key (newest-first). */
+    revisedAt: string;
+    title?: string;
+    slug?: string;
+    excerpt?: string;
+    format?: ContentFormat;
+    body?: unknown;
+    status?: PostStatus;
+    publishedAt?: string;
+    tags?: string[];
+    metadata?: PostMetadata;
+}
+/** Pagination options for `listPostHistory`. */
+interface ListPostHistoryOptions {
+    limit?: number;
+    nextToken?: string;
+}
+/**
+ * A page of revisions newest-first. `nextToken` feeds straight back into
+ * `ListPostHistoryOptions.nextToken` for the next page; `undefined` means
+ * no more rows.
+ */
+interface PostRevisionConnection {
+    items: PostRevision[];
+    nextToken?: string;
+}
 interface PostsProvider {
     list(opts?: ListOptions): Promise<Post[]>;
     get(slug: string): Promise<Post | null>;
@@ -1422,6 +1487,7 @@ interface PostsProvider {
     create(data: CreatePostInput): Promise<Post>;
     update(postId: string, data: Partial<Post>): Promise<Post>;
     remove(postId: string): Promise<void>;
+    listPostHistory(postId: string, options?: ListPostHistoryOptions): Promise<PostRevisionConnection>;
 }
 declare function setPostsProvider(p: PostsProvider): void;
 declare function hasPostsProvider(): boolean;
@@ -1431,6 +1497,13 @@ declare function getPostById(postId: string): Promise<Post | null>;
 declare function createPost(data: CreatePostInput): Promise<Post>;
 declare function updatePost(postId: string, data: Partial<Post>): Promise<Post>;
 declare function deletePost(postId: string): Promise<void>;
+/**
+ * List a post's revision history, newest-first. Backed by the
+ * `PostHistory` `byPost` GSI. Requires a configured provider (the dummy
+ * fallback has no history) — returns an empty connection otherwise so
+ * callers (e.g. the admin history panel) degrade gracefully.
+ */
+declare function listPostHistory(postId: string, options?: ListPostHistoryOptions): Promise<PostRevisionConnection>;
 
 interface KvItem<T = unknown> {
     pk: string;
@@ -1693,4 +1766,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 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 PluginUninstallContext, 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 HistoryConfig, type ImageDisplay, type KvItem, type KvStore, type LinkListItem, type ListOptions, type ListPostHistoryOptions, 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 PluginUninstallContext, type PluginUrlField, type Post, type PostIndexEventPayload, type PostIndexEventType, type PostMetadata, type PostRevision, type PostRevisionConnection, 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, listPostHistory, listPosts, listSiteSettings, mimeTypeFor, parseColorPair, parseLinkList, pickDefaultEntrypoint, resolveLocalized, resolvePluginSettings, resolveThemeValues, setKvStore, setPostsProvider, setSiteSetting, stringifyLinkList, stripCommonPrefix, themeSettingKey, unflattenSettings, updatePost, validateBundle, validateBundlePath, validatePluginSettingValue, validatePublicAssetKey, validateThemeValue };

package/dist/index.js

@@ -83,6 +83,10 @@ async function deletePost(postId) {
   if (!provider) throw new Error("No posts provider configured. Call setPostsProvider() first.");
   return provider.remove(postId);
 }
+async function listPostHistory(postId, options) {
+  if (!provider) return { items: [] };
+  return provider.listPostHistory(postId, options);
+}
 
 // src/kv.ts
 var store = null;
@@ -794,6 +798,7 @@ export {
   hasPostsProvider,
   isTagListUrl,
   isValidPluginKey,
+  listPostHistory,
   listPosts,
   listSiteSettings,
   mimeTypeFor,

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

@@ -172,7 +172,7 @@ export default defineConfig({
 interface AmplessPlugin {
   name: string                      // パッケージ風の識別子。例: 'analytics-ga4'
   packageName?: string              // インストール時のクロスチェック用 npm パッケージ名
-  apiVersion: 1                     // 契約が変わるときだけ bump
+  apiVersion: 1                     // 現状唯一の有効値
   trust_level: 'untrusted' | 'trusted' | 'privileged'
   instanceId?: string               // 複数インストール時の namespace
   displayName?: LocalizedString     // admin UI ラベル
@@ -201,6 +201,12 @@ interface AmplessPlugin {
 
 今日は 1 のみ。将来の互換性破壊バージョンが出たらこの数字が bump され、runtime は未知の値を黙って bind せず拒否します。
 
+**現状唯一の有効値は `apiVersion: 1` です。** literal type は他の値を compile-time に拒否し、`package.json#amplessPlugin.apiVersion` が `definePlugin()` の戻り値と異なる場合、または runtime の `SUPPORTED_API_VERSION` を超える場合、runtime は hard-throw します。
+
+Phase 1 の compat-break reservation すべて（PR #220、#222、#230、#232、#234）は `apiVersion: 1` 内に収まります。これらをプラグインで declare するかどうかは契約バージョンに影響しません。
+
+将来 `apiVersion: 2` が導入される場合は、changeset とこのガイドおよび architecture doc のセクション更新を通じてアナウンスされます。それまでは、**`apiVersion: 1` でプラグインを publish し、唯一の有効値として扱ってください**。v2 bump の trigger となるもの（ならないもの）の全基準については、architecture doc の [apiVersion bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy) セクションを参照してください。
+
 ### `instanceId`
 
 optional、デフォルトは `name`。同じプラグインを 1 サイトで複数 instance 動かせる作り (例: 2 つの GA4 measurement ID、チャットプラットフォーム毎の webhook) では、ホストに `instanceId` を指定させて各々独立した namespace を持たせる:
@@ -1218,7 +1224,7 @@ it('admin が空文字保存した場合は空配列', () => {
 
 - **パッケージ名**: `@your-scope/plugin-foo`。`@ampless/plugin-*` スコープは本モノレポから ship する公式プラグイン用に予約
 - **エントリ**: ESM のみ、default export (factory) + 設定インターフェイス (ユーザの `cms.config.ts` から型付きで引数を渡せるように) を export
-- **`apiVersion`**: 契約が変わるときだけ bump。既存フィールドの型が変わったら major、新フィールド追加なら minor (既存インストールは動き続ける)
+- **`apiVersion`**: 現状は `1` を declare してください — 唯一の有効値で、literal type が他の値を compile-time に reject します。`apiVersion` はプラグイン契約の **breaking-change marker** であって semver 風のチャンネルではありません。additive な追加 (optional field、reserved capability など) は `apiVersion: 1` 内に収まり、bump は不要です。詳細は architecture doc の [apiVersion bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy) を参照
 - **Dist-tag**: ampless 自体が alpha のうちは `@alpha`。`@latest` は ampless v1.0 まで予約
 
 参考実装:

package/docs/plugin-author-guide.md

@@ -200,7 +200,7 @@ That's it. Restart `npm run dev`, view source on any page, and the
 interface AmplessPlugin {
   name: string                      // package-like identifier, e.g. 'analytics-ga4'
   packageName?: string              // npm package name for install-time cross-check
-  apiVersion: 1                     // bump only when the contract changes
+  apiVersion: 1                     // the only valid value today
   trust_level: 'untrusted' | 'trusted' | 'privileged'
   instanceId?: string               // namespace for multi-instance installs
   displayName?: LocalizedString     // admin UI label
@@ -234,6 +234,23 @@ There's only one version today. Future breaking-change versions will
 bump this number; the runtime rejects unknown values rather than
 silently mis-binding.
 
+**Today only `apiVersion: 1` is valid.** The literal type accepts
+no other value, and the runtime hard-throws if `package.json#amplessPlugin.apiVersion`
+disagrees with what `definePlugin()` returns or exceeds the runtime's
+`SUPPORTED_API_VERSION`.
+
+All Phase 1 compat-break reservations (PRs #220, #222, #230, #232,
+#234) live within `apiVersion: 1` — declaring or not declaring them
+in your plugin does not affect the contract version.
+
+If a future `apiVersion: 2` is ever introduced, it will be announced
+through a changeset and a section update in this guide and the
+architecture doc. Until then, **publish your plugin with
+`apiVersion: 1` and treat it as the only valid value**. See the
+[apiVersion bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy)
+section in the architecture doc for the full criteria around what
+would (and would not) trigger a v2 bump.
+
 ### `instanceId`
 
 Optional, defaults to `name`. When you ship a plugin that can run
@@ -1641,9 +1658,14 @@ a normal npm package:
   monorepo.
 - **Entry**: ESM only, exports default (the factory) and the
   config interface (for typed args in user `cms.config.ts`).
-- **`apiVersion`**: bump only when the contract changes. Bump
-  major when an existing field's type changes; bump minor when you
-  add a new field (existing installs keep working).
+- **`apiVersion`**: declare `1` today — it is the only valid
+  value, and the literal type rejects others at compile time.
+  `apiVersion` is the breaking-change marker on the plugin
+  contract, not a semver-style channel: additive changes (new
+  optional fields, new reserved capabilities) stay within
+  `apiVersion: 1` and do NOT require a bump. See the [apiVersion
+  bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy)
+  in the architecture doc for the full criteria.
 - **Dist-tag**: `@alpha` while ampless itself is in alpha. The
   `@latest` tag stays reserved until ampless v1.0.
 

package/package.json

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