@ryusenkei/maezae 0.14.0 → 0.16.0

package/README.md

@@ -97,6 +97,37 @@ const cards = await client.page<Card>('/post', { limit: 20, fields, filter: { ti
 const one = await client.find<Card>('/post/p1', listParams({ fields }));
 ```
 
+## 変更の一覧（0.16.0 から）
+
+`GET /content/v1/changes?since=<cursor>&limit=N` は、型をまたいだ行の変更を順に返す。検索や静的なビルドのために導入先が自分の側へ写すときの土台で、Webhook の取りこぼし（再送は約55時間半で止まる）もここで回収する
+
+```json
+{ "changes": [{ "type": "post", "id": "p1", "change": "upsert", "event": "published", "at": "2026-11-12T00:00:00.000Z" }], "next": "…", "more": false }
+```
+
+- `since` なしは初回の全件の取得。公開中の全行を `event: "snapshot"` で返し、終わったら記録の続きに移る
+- `change` は取得した時点の状態。`upsert` の行は配信 API で取り直し、`delete` の行は手元から消す。同じ行が何度も現れるので、行ごとに最後の状態で上書きする
+- `event` は記録の出来事（`created`・`updated`・`deleted`・`published`・`unpublished`）。予約の公開は、公開日時を過ぎてから `published` で現れる
+- `next` は変更がなくても返る。保存して次回の `since` に渡す。`more` が `true` ならすぐに続きを読む
+- `limit` は1〜1000（既定は100）
+- 記録は30日で消える。それより古い `since` は410（`code: "cursor_expired"`）を返すので、`since` なしで取り直す
+- 公開の管理がある型の下書きの行の編集と、メディアは記録しない
+
+`readChanges` は `more` がなくなるまで読み、ページごとに `apply` を呼んで次回の `since` を返す
+
+```ts
+import { createDeliveryClient, DeliveryError, readChanges } from '@ryusenkei/maezae/delivery';
+
+try {
+  since = await readChanges(client, since, async ({ changes }) => {
+    for (const c of changes) c.change === 'upsert' ? await upsert(c.type, c.id) : await remove(c.type, c.id);
+  });
+} catch (e) {
+  if (e instanceof DeliveryError && e.status === 410) since = null; // 次回は全件から
+  else throw e;
+}
+```
+
 ## 回数の制限
 
 - 対象は公開のエンドポイント（`https://api.maezae.app/<媒体>/content/v1/…`）だけ。上限は媒体と API の鍵ごとに1分で600回で、データセンターごとの近似で数える
@@ -147,6 +178,15 @@ if (!(await verifyRequest(env.CMS_FUNCTION_SECRET, request, { header: SIGNED_HEA
 const body = (await request.json()) as PublishCheckRequest;
 ```
 
+- 検査だけの実行: 提出・公開前の検査（`publish_check`）の本文の `dryRun` が `true` なら、提出・公開をせずに結果だけを見る依頼（MCP の `check_entry` など、0.15.0）
+  - 行は書きかけでもよい。返した `problems` は提出・公開を止めず、人と AI に見せるだけ
+  - 重い検査（引用の照合など）を `dryRun` のときだけ足してよい。時間切れ（1件3秒）は同じ
+  - `problems` の `message` はそのまま AI と画面に出るため、秘密の値・内部の URL を含めない
+
+```ts
+if (body.hook === 'publish_check' && body.dryRun) problems.push(...(await verifyQuotes(body.values)));
+```
+
 - Webhook の重複: 失敗した送信は同じ本文で再送する。本文の `id`（イベントの ID）を処理済みとして保存し、同じ `id` は処理せずに 2xx を返す
 
 ## Webhook の本文と契約の版

package/dist/delivery.js

@@ -91,6 +91,21 @@ function memoryDeliveryCache(maxEntries = 500) {
 		}
 	};
 }
+// src/delivery/changes.ts
+/**
+* since から more がなくなるまで読み、ページごとに apply を呼ぶ（戻り値は次回の since）
+* - apply が成功してから次のページへ進む（失敗したら例外で止まり、保存済みの since から再開できる）
+* - 410（保存の期間を過ぎた cursor）: DeliveryError、since を null にして全件から取り直す
+*/
+async function readChanges(client, since, apply, { limit } = {}) {
+	let cursor = since;
+	for (;;) {
+		const page = await client.changes(cursor, limit === void 0 ? {} : { limit });
+		await apply(page);
+		cursor = page.next;
+		if (!page.more) return cursor;
+	}
+}
 // src/delivery/query.ts
 const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 const OPS = [
@@ -211,11 +226,20 @@ function createDeliveryClient(delivery, { drafts = false, at } = {}) {
 			partial: res.headers.has("x-partial")
 		};
 	};
+	/**
+	* 変更の一覧の1ページ（since は前回の next、null は全件の取得から）
+	* - 410（保存の期間を過ぎた cursor）は DeliveryError、since なしで取り直す
+	*/
+	const changes = (since, { limit } = {}) => get("/changes", {
+		...since ? { since } : {},
+		...limit !== void 0 ? { limit: String(limit) } : {}
+	});
 	return {
 		find,
 		get,
 		page,
-		prefetch
+		prefetch,
+		changes
 	};
 }
 // ../model/src/mediaUrl.ts
@@ -408,4 +432,4 @@ function createDeliveryClock(timeZone) {
 		})
 	};
 }
-export { DELIVERY_PATH, DeliveryError, cachedDelivery, createDeliveryClient, createDeliveryClock, deliveredImageUrl, fieldOf, imageParamsOf, limitOf, listParams, mediaOf, memoryDeliveryCache, optionLabels, pagePath, parseMediaPath, subPath, withImageParams };
+export { DELIVERY_PATH, DeliveryError, cachedDelivery, createDeliveryClient, createDeliveryClock, deliveredImageUrl, fieldOf, imageParamsOf, limitOf, listParams, mediaOf, memoryDeliveryCache, optionLabels, pagePath, parseMediaPath, readChanges, subPath, withImageParams };

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

@@ -24,6 +24,6 @@ export type HandoffLoginOptions = Readonly<{
 export declare function handoffLogin({ secret, loginUrl, consume, basePath, sessionTtlSec }: HandoffLoginOptions): LoginAuth;
 /**
  * 2つのログインを順に試す（emailOf は first が null なら second、入り口とログアウトは first）
- * - 用途: 引き継ぎのログインへの移行の間、Access の JWT も受け付ける
+ * - 用途: 引き継ぎのログインに加えて、運営者のログイン（apps/api の operator.ts）を受け付ける
  */
 export declare function eitherLogin(first: LoginAuth, second: LoginAuth): LoginAuth;

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

@@ -40,6 +40,7 @@ export declare const ERROR_STATUS: {
     readonly article_editing: 409;
     readonly invalid_state: 409;
     readonly unpublish_first: 409;
+    readonly cursor_expired: 410;
     readonly body_too_large: 413;
     readonly rate_limited: 429;
     readonly upstream_failed: 502;

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

@@ -48,12 +48,17 @@ export type SaveCheckResponse = Readonly<{
     }>[];
     values?: Readonly<Record<string, unknown>>;
 }>;
-/** 提出・公開前の検査の本文（stage は submit か publish、values は保存済みの行の値、id はテストの呼び出しだけ null） */
+/**
+ * 提出・公開前の検査の本文
+ * - stage: submit か publish（検査だけの実行は次に進む段階）、values: 保存済みの行の値、id: テストの呼び出しだけ null
+ * - dryRun: 検査だけの実行なら true（提出・公開の点検では省略）
+ */
 export type PublishCheckRequest = Readonly<{
     hook: 'publish_check';
     type: string;
     id: string | null;
     stage: 'submit' | 'publish';
+    dryRun?: true;
     values: Readonly<Record<string, unknown>>;
     user: Readonly<{
         id: string;

package/dist/types/sdk/src/delivery/changes.d.ts

@@ -0,0 +1,23 @@
+import type { DeliveryClient } from './client.js';
+/** 変更の一覧の1件（at は配信 API に現れた日時、`ISO 8601` の UTC） */
+export type Change = Readonly<{
+    type: string;
+    id: string;
+    change: 'upsert' | 'delete';
+    event: 'created' | 'updated' | 'deleted' | 'published' | 'unpublished' | 'snapshot';
+    at: string;
+}>;
+/** 変更の一覧の1ページ */
+export type ChangesPage = Readonly<{
+    changes: readonly Change[];
+    next: string;
+    more: boolean;
+}>;
+/**
+ * since から more がなくなるまで読み、ページごとに apply を呼ぶ（戻り値は次回の since）
+ * - apply が成功してから次のページへ進む（失敗したら例外で止まり、保存済みの since から再開できる）
+ * - 410（保存の期間を過ぎた cursor）: DeliveryError、since を null にして全件から取り直す
+ */
+export declare function readChanges(client: Pick<DeliveryClient, 'changes'>, since: string | null, apply: (page: ChangesPage) => Promise<void> | void, { limit }?: {
+    limit?: number;
+}): Promise<string>;

package/dist/types/sdk/src/delivery/client.d.ts

@@ -1,5 +1,6 @@
 import type { ContentType } from '../../../model/src/index.js';
 import { type ListQuery, type Page } from './query.js';
+import type { ChangesPage } from './changes.js';
 /** 配信 API のパスの前半 */
 export declare const DELIVERY_PATH = "/content/v1";
 /** 配信 API への接続（path は /content/v1 から始まるパスとクエリ） */
@@ -57,6 +58,9 @@ export declare function createDeliveryClient(delivery: Delivery, { drafts, at }?
     prefetch: (paths: readonly string[], { ifNoneMatch }?: {
         ifNoneMatch?: string;
     }) => Promise<Prefetched>;
+    changes: (since: string | null, { limit }?: {
+        limit?: number;
+    }) => Promise<ChangesPage>;
 };
 /** 配信 API の読み取り（createDeliveryClient の戻り値） */
 export type DeliveryClient = ReturnType<typeof createDeliveryClient>;

package/dist/types/sdk/src/delivery/index.d.ts

@@ -1,4 +1,5 @@
 export { cachedDelivery, memoryDeliveryCache, type DeliveryCache } from './cache.js';
+export { readChanges, type Change, type ChangesPage } from './changes.js';
 export { createDeliveryClient, DELIVERY_PATH, DeliveryError, subPath, type BundleResult, type Delivery, type DeliveryClient, type Prefetched } from './client.js';
 export { deliveredImageUrl, mediaOf, type ImageUrl, type MediaOf } from './media.js';
 export { imageParamsOf, parseMediaPath, withImageParams, type ImageParams, type MediaPath } from '../../../model/src/index.js';

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

@@ -1,2 +1,2 @@
-export { cachedDelivery, createDeliveryClient, createDeliveryClock, deliveredImageUrl, DELIVERY_PATH, DeliveryError, fieldOf, imageParamsOf, limitOf, listParams, mediaOf, memoryDeliveryCache, optionLabels, pagePath, parseMediaPath, subPath, withImageParams } from './delivery/index.js';
-export type { BundleResult, DeliveredAsset, Delivery, DeliveryCache, DeliveryClient, DeliveryClock, FieldValue, ImageParams, ImageUrl, Item, ItemMeta, ItemOf, FieldPath, ListFilter, ListQuery, MediaOf, MediaPath, Page, Prefetched, Selected } from './delivery/index.js';
+export { cachedDelivery, createDeliveryClient, createDeliveryClock, deliveredImageUrl, DELIVERY_PATH, DeliveryError, fieldOf, imageParamsOf, limitOf, listParams, mediaOf, memoryDeliveryCache, optionLabels, pagePath, parseMediaPath, readChanges, subPath, withImageParams } from './delivery/index.js';
+export type { BundleResult, Change, ChangesPage, DeliveredAsset, Delivery, DeliveryCache, DeliveryClient, DeliveryClock, FieldValue, ImageParams, ImageUrl, Item, ItemMeta, ItemOf, FieldPath, ListFilter, ListQuery, MediaOf, MediaPath, Page, Prefetched, Selected } from './delivery/index.js';

package/package.json

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