@ryusenkei/maezae 0.10.0 → 0.12.0

package/README.md

@@ -21,6 +21,7 @@ maezae の SDK（導入先のサイト向け）
 - 鍵: 媒体の管理画面の「設定 → 連携」で発行した API の鍵
 - 1件の形: `{ id, ...項目, _meta: { created_at, updated_at, published_at } }`、published_at は公開の管理がある型だけ（0.7.0 から）
 - 一覧: 本文の種類の項目を含めない、本文は1件の取得か `/bundle` で
+- 契約の版: パス `/content/v1` と、すべての応答のヘッダー `x-cms-version: 1`。非互換の変更はバージョン（版）を上げて行う（#495）
 
 ```ts
 import { createDeliveryClient } from '@ryusenkei/maezae/delivery';
@@ -54,6 +55,46 @@ const body = (await request.json()) as PublishCheckRequest;
 
 - Webhook の重複: 失敗した送信は同じ本文で再送する。本文の `id`（イベントの ID）を処理済みとして保存し、同じ `id` は処理せずに 2xx を返す
 
+## Webhook の本文と契約の版
+
+本文の `version` は契約の版（今は1だけ）。非互換の変更はバージョン（版）を上げて行う（#495）
+
+```json
+{ "version": 1, "id": "evt_…", "event": "published", "type": "column", "item": { "id": "…", "title": "…" }, "by": "…", "at": "2026-11-12T00:00:00.000Z" }
+```
+
+- `event`: `submitted`（レビューの依頼）・`published`（公開）・`unpublished`（非公開）・`rejected`（差し戻し）。型は `type`（型の ID）で判断する（型の ID を変えても `event` は変わらない）
+- `id`: イベントの ID（再送しても同じ値、重複の除去に使用）、`item`: 行の ID と題、`by`: 操作した人の表示名、`at`: 出来事の日時
+- 拡張機能の出来事（例: お問い合わせの `contact.received`）: `{ version: 1, id, event: "contact.received", data, at }`（接頭辞はモジュールの ID で型の ID ではない）
+- 購読: 管理画面の「設定 → 連携」で、送る出来事と対象の型を別々に選ぶ。編集の出来事は「選んだ出来事 × 選んだ型」で届く
+
+```ts
+import type { WebhookBody } from '@ryusenkei/maezae/integrations';
+
+const body = (await request.json()) as WebhookBody;
+if (body.type === 'part' && body.event === 'published') await revalidatePart(body.item.id);
+```
+
+### 受け手の移行（0.11.0 以前の形から）
+
+0.12.0 で旧い形（`event` が `<型の ID>.<出来事>`、0.11.0 の版1）と版2を廃止し、`event` と `type` を分けた形だけを版1とした（まだ導入先がないため移行の期間なし）
+
+1. SDK を 0.12.0 にする。`WebhookBodyV1`・`WebhookBodyV2` は廃止、`WebhookBody` が唯一の形（`event` は `WebhookAction`）
+2. 受け手の分岐を `body.type` と `body.event`（`published` など）に直してデプロイ。`event` の `.` を分ける処理は消す
+3. 管理画面の「設定 → 連携」の「テストの送信」と「送信の記録」で受け手の成功を確かめる。CMS の更新の前に失敗した送信の再送も、新しい形で届く（migration で本文を揃えた）
+
+### microCMS の Webhook との対応
+
+キーの名前は maezae の語彙のまま（`type` を2つの意味で使わない）
+
+| microCMS | maezae | 備考 |
+| --- | --- | --- |
+| `service` | （なし） | 送信先の URL と署名の鍵が媒体ごと |
+| `api`（API のエンドポイント名） | `type`（型の ID） | |
+| `type`（`new`・`edit`・`delete`） | `event`（`submitted`・`published`・`unpublished`・`rejected`） | データの変更の出来事（作成・更新・削除）は #494の決定（3）で追加の予定 |
+| `id`（コンテンツ ID） | `item.id` | maezae の `id` はイベントの ID（重複の除去に使用） |
+| `contents`（前後の全内容） | `item`（ID と題） | 中身の選択は #494の決定（3）で追加の予定、今は配信 API で取得 |
+
 ## 外の画面の受け手
 
 - 鍵: 媒体の管理画面の「設定 → 連携」の外の画面の登録ごとの署名の鍵

package/dist/types/access/src/handoff.d.ts

@@ -0,0 +1,29 @@
+import type { LoginAuth } from './oidc.js';
+/** セッションの Cookie の名前（https は __Host- の接頭辞） */
+export declare const sessionCookieName: (url: URL) => string;
+/** セッションの Cookie の Set-Cookie の値（maxAgeSec が0は削除） */
+export declare const sessionCookie: (url: URL, value: string, maxAgeSec: number) => string;
+/** リクエストの Cookie の値（なければ null） */
+export declare const cookieValue: (request: Request, name: string) => string | null;
+/** セッションの値（なし・署名の不一致・期限切れは null） */
+export declare const openSession: <T>(request: Request, secret: string) => Promise<T | null>;
+/** 引き継ぎのログインの設定 */
+export type HandoffLoginOptions = Readonly<{
+    /** Cookie の署名の鍵 */
+    secret: string;
+    /** manage のログインの URL（例: https://example.com/manage/login） */
+    loginUrl: string;
+    /** トークンを消して使い、メールアドレスを返す（使えないトークンは null、host は CMS のホスト名） */
+    consume(token: string, host: string): Promise<string | null>;
+    /** 入り口のパスの頭（既定 /auth） */
+    basePath?: string;
+    /** セッションの秒数（既定は12時間） */
+    sessionTtlSec?: number;
+}>;
+/** manage からの引き継ぎのログイン */
+export declare function handoffLogin({ secret, loginUrl, consume, basePath, sessionTtlSec }: HandoffLoginOptions): LoginAuth;
+/**
+ * 2つのログインを順に試す（emailOf は first が null なら second、入り口とログアウトは first）
+ * - 用途: 引き継ぎのログインへの移行の間、Access の JWT も受け付ける
+ */
+export declare function eitherLogin(first: LoginAuth, second: LoginAuth): LoginAuth;

package/dist/types/access/src/index.d.ts

@@ -1,5 +1,6 @@
 export { accessJwtOptions, type FetchCerts, type JwtClaims, type JwtOptions, verifyAccessJwt, verifyJwt } from './jwt.js';
-export { emailOfClaims, type LoginAuth, oidcLogin, type OidcLoginOptions, tokenAuth, type TokenAuthOptions } from './oidc.js';
+export { cookieValue, eitherLogin, handoffLogin, type HandoffLoginOptions, openSession, sessionCookie, sessionCookieName } from './handoff.js';
+export { emailOfClaims, type LoginAuth, oidcLogin, type OidcLoginOptions, safeNext, tokenAuth, type TokenAuthOptions } from './oidc.js';
 export { type EdgeSpan, type EdgeSpanOptions, type EdgeSpanStatus, sampleRateOf, startEdgeSpan, withEdgeSpan } from './span.js';
 export { openValue, sealValue, SIGNED_HEADERS, signedHeaders, type SigningSecrets, signParts, type SignedParts, verifyParts, verifyRequest, type VerifyRequestOptions } from './signed.js';
 export { childTraceContext, formatTraceparent, newSpanId, newTraceId, parseTraceparent, type TraceContext, TRACEPARENT_HEADER } from './traceparent.js';

package/dist/types/analytics/src/index.d.ts

@@ -1,4 +1,4 @@
 export { recordView, type Classify, type Dataset } from './record.js';
 export { syncCron } from './schedule.js';
-export { analyticsEngine, type DailyRow, fixedSource, type Source, projectDaily, type ProjectSource } from './source.js';
+export { analyticsEngine, type DailyRow, fixedSource, type Source, projectDaily, type ProjectSource, renamedSource } from './source.js';
 export { readDaily, syncDaily } from './store.js';

package/dist/types/analytics/src/source.d.ts

@@ -30,4 +30,6 @@ export type ProjectSource = {
 export declare function projectDaily(options: Omit<AnalyticsEngineOptions, 'project'>): ProjectSource;
 /** 集計済みの行の読み込み元（定期の集計で全媒体の問い合わせ結果を媒体ごとに受け渡し、daily は since 以降の行） */
 export declare const fixedSource: (rows: readonly DailyRow[]) => Source;
+/** 種類を付け替えた読み込み元（renames は旧の種類 → 今の種類、付け替えで重なった行は閲覧数を合計） */
+export declare function renamedSource(source: Source, renames: Readonly<Record<string, string>>): Source;
 export {};

package/dist/types/cms-contract/src/index.d.ts

@@ -15,6 +15,7 @@ export { CONFIG_FORMAT, type ConfigBundle, type ConfigPreview } from './transfer
 export { IMPORT_ITEMS_MAX, IMPORT_PROBLEM_LABELS, IMPORT_PROBLEMS, type ImportIdChange, type ImportIdConflict, importIdOf, type ImportIdPlan, type ImportImage, type ImportItem, type ImportItemReport, type ImportProblem, type ImportProblemCode, type ImportReport, importReportOf, mergeImportReports, planImportIds, sourceOf } from './import.js';
 export { EMBED_CONTEXT_NEXT_PARAM, EMBED_CONTEXT_PARAM, EMBED_CONTEXT_TTL_SEC, EMBED_MESSAGES, EMBED_PLACEMENTS, type EmbedContext, type EmbedEntry, type EmbedMessage, type EmbedPlacement, type ExternalScreen } from './embeds.js';
 export { type ExternalFunction, FUNCTION_HOOK_LABELS, FUNCTION_HOOKS, functionEventLabel, functionEventOf, type FunctionHook, type FunctionOnError, type FunctionRequest, type PublishCheckRequest, type PublishCheckResponse, type SaveCheckRequest, type SaveCheckResponse } from './functions.js';
-export { parseWebhookEvent, type Webhook, WEBHOOK_ACTION_LABELS, type WebhookBody, WEBHOOK_ACTIONS, type WebhookAction, type WebhookDelivery, type WebhookEvent, webhookEventLabel, webhookEventOf, type WebhookKind } from './webhooks.js';
+export { isWebhookAction, parseWebhookEvent, type Webhook, WEBHOOK_ACTION_LABELS, type WebhookBody, WEBHOOK_ACTIONS, type WebhookAction, type WebhookDelivery, type WebhookEvent, webhookEventLabel, webhookEventOf, type WebhookKind, type WebhookModuleBody, type WebhookSubscription, webhookSubscriptionLabel, WEBHOOK_VERSION, type WebhookVersion } from './webhooks.js';
+export { CONTRACT_VERSION_HEADER, DELIVERY_VERSION } from './versions.js';
 export { type SavedView, VIEW_ACTIONS, type ViewAction, type ViewDefinition } from './views.js';
 export { canManageSettings, isSettingsTarget, managedAreasOf, SETTINGS_AREA_LABELS, SETTINGS_AREAS, type SettingsArea, settingsTarget } from './settings.js';

package/dist/types/cms-contract/src/modules.d.ts

@@ -56,6 +56,8 @@ export type ModuleManifest<S = Readonly<Record<string, never>>> = Readonly<{
     settingFields?: readonly SettingField[];
     /** フィールドの宣言（設定値から作成、例: 種類で決まる名義） */
     fieldRules?(settings: S): readonly FieldRule[];
+    /** 型の id を値に持つ設定値のキー（型の id の変更で書き換え、値は id の文字列か配列） */
+    typeSettings?: readonly string[];
     /** 拡張機能が送る Webhook の出来事（キーは出来事の名前 <対象>.<操作>、値は表示名、設定の「連携」で選択） */
     webhookEvents?: Readonly<Record<string, string>>;
 }>;
@@ -91,6 +93,7 @@ export type ModuleBase = Readonly<{
     fieldRules: readonly FieldRule[];
     messages: TargetMessages;
     webhookEvents: Readonly<Record<string, string>>;
+    typeSettings: readonly string[];
 }>;
 /** 組み立てたモジュール（共通の定義と、側ごとの内容） */
 export type ModuleInstance<P> = ModuleBase & P;

package/dist/types/cms-contract/src/transfer.d.ts

@@ -29,8 +29,12 @@ export type ConfigBundle = Readonly<{
 }>;
 /** スキーマと設定の読み込みの確認（schema はスキーマの変更、ほかは追加と更新の件数） */
 export type ConfigPreview = Readonly<{
+    /** kind は変更の種類、type は型の id、value は型の id の変更の旧の id（型の id の変更の候補の選択に使用） */
     schema: readonly Readonly<{
         id: string;
+        kind: string;
+        type: string;
+        value?: string;
         level: 'safe' | 'confirm' | 'forbidden';
         message: string;
         count: number | null;

package/dist/types/cms-contract/src/versions.d.ts

@@ -0,0 +1,4 @@
+/** 配信 API の版（パス /content/v1） */
+export declare const DELIVERY_VERSION = 1;
+/** 配信 API の応答で契約の版を示すヘッダー */
+export declare const CONTRACT_VERSION_HEADER = "x-cms-version";

package/dist/types/cms-contract/src/webhooks.d.ts

@@ -2,23 +2,34 @@
 export declare const WEBHOOK_ACTIONS: readonly ["submitted", "published", "unpublished", "rejected"];
 /** 送れる操作 */
 export type WebhookAction = (typeof WEBHOOK_ACTIONS)[number];
-/** 送れる出来事（編集機能を持つ型の <型の id>.<操作> と、拡張機能が宣言した出来事） */
+/** Webhook の契約の版（本文の version） */
+export declare const WEBHOOK_VERSION = 1;
+/** Webhook の契約の版 */
+export type WebhookVersion = typeof WEBHOOK_VERSION;
+/** サーバーの内側の出来事のキー（編集の出来事は <型の id>.<操作>、拡張機能の出来事は宣言の名前） */
 export type WebhookEvent = `${string}.${string}`;
+/** 購読する出来事（操作か拡張機能の出来事の名前） */
+export type WebhookSubscription = WebhookAction | WebhookEvent;
 /** 操作の表示名（画面の選択肢と、Slack の文） */
 export declare const WEBHOOK_ACTION_LABELS: Readonly<Record<WebhookAction, string>>;
-/** 型と操作の出来事 */
+/** 送れる操作か */
+export declare const isWebhookAction: (value: string) => value is WebhookAction;
+/** 型と操作の出来事のキー */
 export declare const webhookEventOf: (type: string, action: WebhookAction) => WebhookEvent;
-/** 出来事の型と操作（形が不正なら null） */
+/** 出来事のキーの型と操作（編集の出来事でなければ null） */
 export declare function parseWebhookEvent(event: string): Readonly<{
     type: string;
     action: WebhookAction;
 }> | null;
-/** 出来事の表示名（types は型の id と表示名で型の表示名と操作の表示名、moduleEvents は拡張機能の出来事の表示名） */
+/** 出来事のキーの表示名（types は型の id と表示名で型の表示名と操作の表示名、moduleEvents は拡張機能の出来事の表示名） */
 export declare function webhookEventLabel(event: string, types: Readonly<Record<string, string>>, moduleEvents?: Readonly<Record<string, string>>): string;
+/** 購読する出来事の表示名（操作か拡張機能の出来事） */
+export declare const webhookSubscriptionLabel: (subscription: string, moduleEvents?: Readonly<Record<string, string>>) => string;
 /** Webhook の形式 */
 export type WebhookKind = 'json' | 'slack';
 /**
  * Webhook（url・secret は末尾だけを伏せずに返す、secret の null は署名なし）
+ * - events: 購読する出来事（操作と拡張機能の出来事）、types: 購読する型の id（編集の出来事は events の操作 × types）
  * - previousSecret: 鍵の移行の期間の古い鍵の末尾、期間の外は null
  * - lastStatus: 最新の送信で返った HTTP の状態、送れなかったときは0
  */
@@ -29,19 +40,23 @@ export type Webhook = Readonly<{
     url: string;
     secret: string | null;
     previousSecret: string | null;
-    events: readonly WebhookEvent[];
+    events: readonly WebhookSubscription[];
+    types: readonly string[];
     enabled: boolean;
     lastStatus: number | null;
     lastAt: string | null;
 }>;
 /**
  * json の形式の本文（編集機能を持つ型の出来事、署名はヘッダー x-cms-signature で登録ごとの鍵）
+ * - version: 契約の版（1）
  * - id: イベントの ID（再送しても同じ値、受け手は処理済みの id を捨てて重複を除く）
+ * - event: 操作、type: 型の id
  * - item: 行の ID と題、by: 操作した人の表示名、at: 出来事の日時（ISO 8601、再送しても同じ値）
  */
 export type WebhookBody = Readonly<{
+    version: WebhookVersion;
     id: string;
-    event: WebhookEvent;
+    event: WebhookAction;
     type: string;
     item: Readonly<{
         id: string;
@@ -50,7 +65,15 @@ export type WebhookBody = Readonly<{
     by: string;
     at: string;
 }>;
-/** 送信の記録（attempt は何回目の送信か、retryAt は次の再送の予定の日時、再送なしは null） */
+/** json の形式の拡張機能の出来事の本文（event は宣言の名前、data はモジュールの値） */
+export type WebhookModuleBody = Readonly<{
+    version: WebhookVersion;
+    id: string;
+    event: WebhookEvent;
+    data: Readonly<Record<string, unknown>>;
+    at: string;
+}>;
+/** 送信の記録（event は出来事のキー、attempt は何回目の送信か、retryAt は次の再送の予定の日時、再送なしは null） */
 export type WebhookDelivery = Readonly<{
     id: number;
     source: 'webhook' | 'function';

package/dist/types/model/src/changes.d.ts

@@ -2,8 +2,8 @@ import { type ContentModel } from './model.js';
 /** 変更の扱い */
 export type ChangeLevel = 'safe' | 'confirm' | 'forbidden';
 /** 変更の種類 */
-export type ChangeKind = 'type-added' | 'type-removed' | 'type-changed' | 'format-changed' | 'publishing-changed' | 'publishing-removed' | 'fixed-changed' | 'field-added' | 'field-removed' | 'field-changed' | 'field-type-changed' | 'field-key-reused' | 'required-added' | 'constraint-tightened' | 'option-added' | 'option-removed' | 'component-added' | 'component-changed' | 'component-removed';
-/** スキーマの1つの変更（id は確認と置き換え先の指定で使用する識別子、path は項目の key を `.` で連結、value は削除した選択肢の値） */
+export type ChangeKind = 'type-added' | 'type-removed' | 'type-renamed' | 'type-rename-invalid' | 'type-changed' | 'format-changed' | 'publishing-changed' | 'publishing-removed' | 'fixed-changed' | 'field-added' | 'field-removed' | 'field-changed' | 'field-type-changed' | 'field-key-reused' | 'required-added' | 'constraint-tightened' | 'option-added' | 'option-removed' | 'component-added' | 'component-changed' | 'component-removed';
+/** スキーマの1つの変更（id は確認と置き換え先の指定で使用する識別子、path は項目の key を `.` で連結、value は削除した選択肢の値・型の旧の id） */
 export type SchemaChange = Readonly<{
     id: string;
     level: ChangeLevel;
@@ -13,9 +13,18 @@ export type SchemaChange = Readonly<{
     value?: string;
     message: string;
 }>;
-/** 差分の条件（history は保存済みの版より古い過去の版） */
+/**
+ * 差分の条件
+ * - history: 保存済みの版より古い過去の版
+ * - renames: 型の id の変更（旧の id → 新しい id）
+ * - takenIds: 行が残る型の id（削除した型の行、id の変更先に不可）
+ */
 export type DiffOptions = Readonly<{
     history?: readonly ContentModel[];
+    renames?: Readonly<Record<string, string>>;
+    takenIds?: readonly string[];
 }>;
 /** 保存済みの版 prev から新しい定義 next への変更（型の順、項目の順） */
 export declare function diffSchema(prev: ContentModel, next: ContentModel, options?: DiffOptions): SchemaChange[];
+/** 型の id を from から to に変えた定義（型の id と、すべての型の参照の to） */
+export declare const renameType: (model: ContentModel, from: string, to: string) => ContentModel;

package/dist/types/model/src/index.d.ts

@@ -3,7 +3,7 @@ export { assetRefSchema, cropSchema, hotspotSchema, mediaSchema, type Asset, typ
 export { coverPosition, coverStart, cropRect, croppedHotspot, objectPosition, stillOf, type CropRect } from './image.js';
 export { IMAGE_TYPE, VIDEO_TYPE } from './media.js';
 export { IMAGE_SIZE_MAX, imageParamsOf, mediaExtOf, mediaMimeOf, mediaPathOf, parseMediaPath, withImageParams, type ImageParams, type MediaPath } from './mediaUrl.js';
-export { diffSchema, type ChangeKind, type ChangeLevel, type DiffOptions, type SchemaChange } from './changes.js';
+export { diffSchema, renameType, type ChangeKind, type ChangeLevel, type DiffOptions, type SchemaChange } from './changes.js';
 export { dateRoleFieldsOf, primaryTypeOf, requiredPrimaryTypeOf, SOURCES_FIELD, sourceIdsOf, sourcesFieldOf, sourceTypeOf, type SourcesField } from './capabilities.js';
 export { appliesTo, checkFields, fieldsFor } from './check.js';
 export { deliveredFields, emptyValues, pickValues, referencedIds, referencesOf, valueFieldsOf } from './values.js';

package/dist/types/sdk/src/integrations.d.ts

@@ -3,6 +3,6 @@ import { type EmbedContext } from '../../cms-contract/src/index.js';
 export { openValue, SIGNED_HEADERS, verifyRequest } from '../../access/src/index.js';
 export type { SigningSecrets, VerifyRequestOptions } from '../../access/src/index.js';
 export { EMBED_CONTEXT_NEXT_PARAM, EMBED_CONTEXT_PARAM, EMBED_MESSAGES, FUNCTION_HOOKS } from '../../cms-contract/src/index.js';
-export type { EmbedContext, EmbedMessage, FunctionHook, FunctionRequest, PublishCheckRequest, PublishCheckResponse, SaveCheckRequest, SaveCheckResponse, WebhookAction, WebhookBody, WebhookEvent } from '../../cms-contract/src/index.js';
+export type { EmbedContext, EmbedMessage, FunctionHook, FunctionRequest, PublishCheckRequest, PublishCheckResponse, SaveCheckRequest, SaveCheckResponse, WebhookAction, WebhookBody, WebhookEvent, WebhookModuleBody, WebhookVersion } from '../../cms-contract/src/index.js';
 /** 外の画面の URL の文脈（クエリ ctx と、鍵の移行の期間の ctx_next のどちらかが鍵で開けば文脈、なければ null） */
 export declare function openEmbedContext(secret: SigningSecrets, url: string | URL, now?: number): Promise<EmbedContext | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryusenkei/maezae",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "maezae の導入先のサイト向けの SDK（配信 API の取得・本文の型・プレビューの署名・手元の開発の配信 API）",
   "license": "UNLICENSED",
   "author": "RYUSENKEI",