@andesine/sdk 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## 0.7.0
+
+- `auth.getIdentity` returns `client` (ID and registered name) for OAuth access tokens.
+- Webhook events have an `actor`: the member, API key, extension, or app (OAuth client ID and
+  registered name, with the member) that made the change, or `null` for changes by Andesine.
+- OAuth for MCP clients: the authorization server supports the authorization code flow with
+  PKCE and dynamic client registration, with the scopes `andesine:read` and `andesine:write`.
+  `auth.getIdentity` returns `scopes` and `workspaceID` for such tokens.
+- `auth.getIdentity` returns the `permissions` of an API key, and `instance.get` returns
+  `appURL`, the web app URL (entries open at `{appURL}/{workspaceID}/{entryID}`).
+- `versions.create` takes an optional `document`: ProseMirror JSON checked against the editor
+  and the entry's collection schema. The version has the new reason `import`, and the
+  current content does not change.
+- `entries.get` returns `hash`, the hash of the current content, comparable to version hashes.
+- Add `entries.move` and `collections.move` (API key permissions `entries` and
+  `collections`). Without `order`, a moved entry keeps its position in the same collection
+  and goes last in a new one.
+- `entries.update` replaces the content with `document` and `expectedHash`, the hash of the
+  content it replaces. Only the changed blocks change, so live edits elsewhere are kept. A
+  different current hash returns the new error `CONTENT_HASH_MISMATCH` (409) with the current
+  `hash`. Current content without a version is first saved as an `auto` version, and `version`
+  also saves the new content as a `manual` version. Use `name` or `document`, not both. The
+  result is `{ hash, version }`; before, it was empty.
+- `entries.create` takes an optional `document` in place of `name`; its title sets the name.
+- MDX content: `entries.get`, `versions.get`, and `content.get` take `contentFormat: "mdx"`
+  and then also return the content as MDX in `mdx`: the title as H1, properties as
+  `<Property name value />` elements in their position, fragments as `<Fragment name>`
+  elements, and images as `asset:<assetID>` references (delivery URLs in published content).
+  `entries.create`, `entries.update`, and `versions.create` take `mdx` in place of `document`;
+  frontmatter properties are also read. Fields match by name or key. Node IDs and attributes
+  that MDX doesn't hold are kept from the current content. Invalid MDX returns the new error
+  `CONTENT_FORMAT_INVALID` (400) with the line and column.
+- `Fragment` and `Property` are reserved element names; content writes with them return
+  `CONTENT_SCHEMA_INVALID`.
+- `entries.update` takes `operations`, applied in order with all or none applied:
+  `replaceText` (`find` must occur once in one block's MDX), `replaceBlock`, `insertBlocks`
+  (`before`, `after`, or `position` with an optional `fragment`), `deleteBlocks`, and `setField`
+  (a property value, or MDX for a fragment). Anchors come from `entries.get` with
+  `contentFormat: "blocks"`, which returns the blocks with IDs, fragment keys, and MDX.
+  `expectedHash` is optional with operations; `name` can be combined with them. A missing or
+  ambiguous anchor returns the new error `CONTENT_OPERATION_INVALID` (409) with the operation
+  `index` and `reason`.
+- Internal links: link marks can point to entries with `entry:<entryID>`, and an optional
+  `#anchor`. Content writes also accept `entry:<path>` (a path or slug path) and store the entry
+  ID; a link to a missing entry returns the new error `CONTENT_LINK_INVALID` (409).
+  `entries.get` and `versions.get` return `references`: the path, slug path, title, and
+  collection of each linked entry, or `available: false` for deleted and unreadable entries.
+  MDX and blocks show links by slug path. Published content resolves links to the entry's slug
+  path in the snapshot, and removes links to entries that aren't published (the text stays).
+- Images follow content: content writes attach the `asset:<assetID>` images they newly
+  reference (the caller must be able to read each image and update the entry), so
+  `assets.attach` is no longer part of the public API. `entries.update` and `versions.create`
+  also import image URLs in MDX and wait until the images are ready; an image that fails or is
+  still processing returns the new error `CONTENT_IMAGE_UNAVAILABLE` (409). `entries.create`
+  accepts only `asset:` images. To remove an image, remove it from the content.
+- `entries.create` takes `path`: a full name path. Missing parent collections are created with
+  exact names; a name already used at the path returns `CONTENT_NAME_CONFLICT`.
+- Target collections by path: `entries.create` and `entries.move` take `collectionPath` or
+  `collectionSlugPath` in place of `collectionID`, `collections.create` takes `parentPath` or
+  `parentSlugPath`, `collections.move` takes `newParentPath` or `newParentSlugPath` (`/` is the
+  top level), and `publishing.getChannelContent` takes `collectionPath` or `collectionSlugPath`.
+  These select existing collections only.
+- Preconditions: `expectedName` on `entries.update` and `collections.update`,
+  `expectedCollectionID` on `entries.move`, and `expectedParentID` on `collections.move`. A
+  different current value returns the new error `CONTENT_PRECONDITION_FAILED` (409) with the
+  current value.
+- `Idempotency-Key` header on `entries.create`, `entries.update`, and `versions.create`: a
+  repeated request returns the first result for 24 hours (with `Idempotent-Replayed: true`).
+  The same key with a different body returns `IDEMPOTENCY_KEY_REUSED` (422), and a repeat while
+  the first request runs returns `IDEMPOTENCY_KEY_IN_PROGRESS` (409). The SDK sends a generated
+  key for these operations unless `headers` has one, and `retries` now also applies to them, including a retry that
+  arrives while the first attempt still runs (`IDEMPOTENCY_KEY_IN_PROGRESS`, with
+  `Retry-After: 1`).
+- Add `entries.bulkUpdate`: the items of `entries.update` for many entries in one call (a name
+  without content is written as the title). All items are checked before any content changes,
+  and all or none apply; errors name the failing item. Supports `Idempotency-Key`.
+- Add `entries.bulkMove`: the items of `entries.move` in one call, all or none. Moves that need a
+  schema migration aren't supported; use `entries.move` for them.
+- Add `publishing.updateChannel`: renames a channel; its code doesn't change.
+- `entries.create` takes `fields`: property values and fragment MDX by field name or key.
+- `entries.get` returns the content of a document that is open in the editor, including edits
+  that aren't saved yet, so its `hash` matches what content writes compare against.
+
 ## 0.6.0
 
 - No changes; versioned with the other public Andesine packages.

package/README.md

@@ -176,9 +176,17 @@ request execution, response reading, and retry delays. Supply `signal` per call
 for cancellation.
 
 Retries are **disabled by default**. Set `retries: 2` on the client or a call to
-allow up to two retries of GET requests. Reads retry network `TypeError` failures
-and HTTP 429, 500, 502, 503, and 504. They respect `Retry-After`, otherwise use
-increasing delays with jitter. Writes are never retried automatically.
+allow up to two retries of GET requests and idempotent writes. They retry network
+`TypeError` failures and HTTP 429, 500, 502, 503, and 504. They respect
+`Retry-After`, otherwise use increasing delays with jitter. Other writes are never
+retried automatically.
+
+Idempotent writes (`entries.create`, `entries.update`, and `versions.create`) send
+an `Idempotency-Key` header, generated for each call unless you supply one in
+`headers`. The server applies a key once and returns the first result for 24 hours,
+so retries can't apply a write twice. A retry that arrives while the first attempt
+still runs gets `IDEMPOTENCY_KEY_IN_PROGRESS` and is retried after `Retry-After`. Supply your own key to make a write safe
+across separate calls, for example after a process restart.
 
 ```ts
 await client.entries.get(

package/WEBHOOKS.md

@@ -275,6 +275,13 @@ or restricted resources can become unavailable. Publication snapshot references
 can expire under the workspace policy; webhooks do not pin snapshots. Handle
 missing references explicitly.
 
+Each event has an `actor`: who made the change. It is a member (`memberID`), an
+API key (`keyID`), an extension (`extensionID`), or an app such as an MCP client
+(`clientID`, the `name` that the app registered, and the authorizing `memberID`).
+It is `null` for changes by Andesine itself, and for editor saves that combine
+several people's edits. App names are chosen by the app; don't use them for
+access decisions. An extension's own webhooks don't receive its changes.
+
 ## Rotation, replay, and recovery
 
 Normal rotation returns a new secret once and signs with both old and new keys

package/dist/{client-DioqVOxl.js → client-D7hqNIEY.js}

@@ -124,16 +124,6 @@ const createResources = (request) => ({
 			binary: false,
 			anonymous: false
 		}),
-		attach: operation(request, {
-			method: "post",
-			path: "/assets/{assetID}/attachments",
-			pathParams: ["assetID"],
-			queryParams: [],
-			body: true,
-			multipart: false,
-			binary: false,
-			anonymous: false
-		}),
 		register: operation(request, {
 			method: "post",
 			path: "/assets/uploads",
@@ -187,6 +177,7 @@ const createResources = (request) => ({
 	}) },
 	entries: {
 		create: operation(request, {
+			idempotent: true,
 			method: "post",
 			path: "/entries",
 			pathParams: [],
@@ -217,6 +208,7 @@ const createResources = (request) => ({
 			anonymous: false
 		}),
 		update: operation(request, {
+			idempotent: true,
 			method: "put",
 			path: "/entries/{id}",
 			pathParams: ["id"],
@@ -226,6 +218,37 @@ const createResources = (request) => ({
 			binary: false,
 			anonymous: false
 		}),
+		bulkUpdate: operation(request, {
+			idempotent: true,
+			method: "post",
+			path: "/entries/bulk/update",
+			pathParams: [],
+			queryParams: [],
+			body: true,
+			multipart: false,
+			binary: false,
+			anonymous: false
+		}),
+		move: operation(request, {
+			method: "post",
+			path: "/entries/{id}/move",
+			pathParams: ["id"],
+			queryParams: [],
+			body: true,
+			multipart: false,
+			binary: false,
+			anonymous: false
+		}),
+		bulkMove: operation(request, {
+			method: "post",
+			path: "/entries/bulk/move",
+			pathParams: [],
+			queryParams: [],
+			body: true,
+			multipart: false,
+			binary: false,
+			anonymous: false
+		}),
 		get: operation(request, {
 			method: "get",
 			path: "/entries/get",
@@ -234,7 +257,8 @@ const createResources = (request) => ({
 				"id",
 				"path",
 				"slugPath",
-				"expectedSchemaHash"
+				"expectedSchemaHash",
+				"contentFormat"
 			],
 			body: false,
 			multipart: false,
@@ -395,6 +419,16 @@ const createResources = (request) => ({
 			binary: false,
 			anonymous: false
 		}),
+		move: operation(request, {
+			method: "post",
+			path: "/collections/{id}/move",
+			pathParams: ["id"],
+			queryParams: [],
+			body: true,
+			multipart: false,
+			binary: false,
+			anonymous: false
+		}),
 		list: operation(request, {
 			method: "get",
 			path: "/collections/list",
@@ -494,7 +528,8 @@ const createResources = (request) => ({
 				"slugPath",
 				"expectedSchemaHash",
 				"channel",
-				"snapshotID"
+				"snapshotID",
+				"contentFormat"
 			],
 			body: false,
 			multipart: false,
@@ -1148,12 +1183,26 @@ const createResources = (request) => ({
 			method: "get",
 			path: "/publishing/channels/{channel}/content",
 			pathParams: ["channel"],
-			queryParams: ["collectionID"],
+			queryParams: [
+				"collectionID",
+				"collectionPath",
+				"collectionSlugPath"
+			],
 			body: false,
 			multipart: false,
 			binary: false,
 			anonymous: false
 		}),
+		updateChannel: operation(request, {
+			method: "put",
+			path: "/publishing/channels/{code}",
+			pathParams: ["code"],
+			queryParams: [],
+			body: true,
+			multipart: false,
+			binary: false,
+			anonymous: false
+		}),
 		deleteChannel: operation(request, {
 			method: "delete",
 			path: "/publishing/channels/{code}",
@@ -1177,6 +1226,7 @@ const createResources = (request) => ({
 	}) },
 	versions: {
 		create: operation(request, {
+			idempotent: true,
 			method: "post",
 			path: "/entries/{entryID}/versions",
 			pathParams: ["entryID"],
@@ -1200,7 +1250,7 @@ const createResources = (request) => ({
 			method: "get",
 			path: "/versions/{id}",
 			pathParams: ["id"],
-			queryParams: ["expectedSchemaHash"],
+			queryParams: ["expectedSchemaHash", "contentFormat"],
 			body: false,
 			multipart: false,
 			binary: false,
@@ -1274,6 +1324,10 @@ const retryDelay = (attempt, response) => {
 	if (Number.isFinite(date)) return Math.max(0, date - Date.now());
 	return Math.min(1e3 * 2 ** attempt, 3e4) + Math.random() * 250;
 };
+const isInProgressWrite = async (request, response) => {
+	if (response.status !== 409 || !request.headers.has("Idempotency-Key")) return false;
+	return (await response.clone().json().catch(() => null))?.code === "IDEMPOTENCY_KEY_IN_PROGRESS";
+};
 const fetchWithRetries = async (fetcher, request, retries) => {
 	const signal = request.signal;
 	for (let attempt = 0;; attempt += 1) {
@@ -1286,13 +1340,14 @@ const fetchWithRetries = async (fetcher, request, retries) => {
 			await wait(retryDelay(attempt), signal);
 			continue;
 		}
-		if (attempt >= retries || ![
+		const retryable = [
 			429,
 			500,
 			502,
 			503,
 			504
-		].includes(response.status)) return response;
+		].includes(response.status) || await isInProgressWrite(request, response);
+		if (attempt >= retries || !retryable) return response;
 		const delay = retryDelay(attempt, response);
 		await response.body?.cancel();
 		await wait(delay, signal);
@@ -1343,6 +1398,7 @@ const createClient = (config = {}) => {
 		new Headers(options.headers).forEach((value, key) => headers.set(key, value));
 		if (definition.streaming && !headers.has("Accept")) headers.set("Accept", "text/event-stream");
 		if (credential && !definition.anonymous) headers.set("Authorization", `Bearer ${credential}`);
+		if (definition.idempotent && !headers.has("Idempotency-Key")) headers.set("Idempotency-Key", crypto.randomUUID());
 		const timer = timeout > 0 ? setTimeout(() => controller.abort(new DOMException("Request timed out", "TimeoutError")), timeout) : void 0;
 		let streamOwnsRequest = false;
 		try {
@@ -1361,7 +1417,7 @@ const createClient = (config = {}) => {
 					else if (item !== void 0) form.append(key, typeof item === "string" ? item : JSON.stringify(item));
 					return form;
 				} : void 0,
-				fetch: (request) => fetchWithRetries(fetcher, request, definition.method === "get" ? retries : 0)
+				fetch: (request) => fetchWithRetries(fetcher, request, definition.method === "get" || definition.idempotent ? retries : 0)
 			});
 			const response = result.response;
 			if (response.status === 304) {
@@ -1421,4 +1477,4 @@ const createClient = (config = {}) => {
 //#endregion
 export { paginate as n, paginatePages as r, createClient as t };
 
-//# sourceMappingURL=client-DioqVOxl.js.map
+//# sourceMappingURL=client-D7hqNIEY.js.map