From 51b4f5c8c86abac36430e21a7ba8ea5443a1c1dd Mon Sep 17 00:00:00 2001 From: Lorenzo <49939356+lorenzocb@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:20:29 +0000 Subject: [PATCH 1/5] Plan OneNote Graph write contract fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Empty commit to open the draft PR that carries the plan. The implementation follows in later commits. 👾 Generated with [Letta Code](https://letta.com) Co-Authored-By: Letta Code From a29e5d9f7ae254ccd66fb96908423049d81160d1 Mon Sep 17 00:00:00 2001 From: Lorenzo <49939356+lorenzocb@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:30:40 +0000 Subject: [PATCH 2/5] Correct OneNote page create and update contracts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Graph's generated OpenAPI document declares a JSON onenotePage body for POST .../onenote/.../pages. Graph accepts only raw text/html or multipart/form-data with a Presentation part, and rejects JSON with HTTP 415. The same document omits the documented PATCH page update on .../pages/{id}/content and declares an octet-stream PUT instead. The Graph adapter now corrects these path items in microsoftGraphKeepPathItem, next to the existing octet-stream response normalization: 1. Page create takes text/html (first, so it is the default) or multipart/form-data with a required text/html Presentation part. 2. Page content gains PATCH with a JSON array of patch commands and a 204 response. Its operationId derives from the GET operationId, and its permissions come from the generated PUT. 3. The generated PUT stays callable for existing callers, but is marked deprecated and loses its link to the PATCH-only docs, so tool selection prefers the documented update. The slice generator and the runtime compile share this function, so new slices carry the fix, and an integration that refreshes its spec gets corrected tools even from a slice published before the fix. Non-OneNote paths and the onenotePatchContent action are unchanged. 👾 Generated with [Letta Code](https://letta.com) Co-Authored-By: Letta Code --- .changeset/onenote-page-write-contracts.md | 5 + .../openapi/src/providers/microsoft/graph.ts | 178 ++++- .../src/providers/microsoft/onenote.test.ts | 663 ++++++++++++++++++ 3 files changed, 845 insertions(+), 1 deletion(-) create mode 100644 .changeset/onenote-page-write-contracts.md create mode 100644 packages/plugins/openapi/src/providers/microsoft/onenote.test.ts diff --git a/.changeset/onenote-page-write-contracts.md b/.changeset/onenote-page-write-contracts.md new file mode 100644 index 0000000000..e0909e89d8 --- /dev/null +++ b/.changeset/onenote-page-write-contracts.md @@ -0,0 +1,5 @@ +--- +"@executor-js/plugin-openapi": patch +--- + +Correct the Microsoft Graph OneNote page write contracts. Page create (`POST .../onenote/.../pages`) now sends raw `text/html` by default, or `multipart/form-data` with a required `Presentation` part, instead of the JSON body that Graph rejects with HTTP 415. Page update adds the documented `PATCH .../pages/{id}/content` operation, which takes a JSON array of patch commands and returns `204`. The generated octet-stream `PUT` on that path stays available but is marked deprecated. The correction applies to every OneNote root (`/me`, `/users`, `/groups`, `/sites`) and nested section form, when slices are generated and when a Graph spec is compiled. Existing integrations pick up the corrected tools when they refresh their spec. diff --git a/packages/plugins/openapi/src/providers/microsoft/graph.ts b/packages/plugins/openapi/src/providers/microsoft/graph.ts index 7b38921a35..2b71119065 100644 --- a/packages/plugins/openapi/src/providers/microsoft/graph.ts +++ b/packages/plugins/openapi/src/providers/microsoft/graph.ts @@ -629,6 +629,180 @@ const normalizeMicrosoftGraphContentPathItem = ( return changed ? next : pathItem; }; +// OneNote page writes. Graph's generated OpenAPI document models these from +// the OData entity model, which does not match the documented REST contract: +// - `POST .../pages` declares a JSON `onenotePage` body, but Graph accepts only +// raw `text/html` or `multipart/form-data` with a `Presentation` part +// (https://learn.microsoft.com/graph/api/section-post-pages) and rejects JSON +// with HTTP 415. +// - `.../pages/{id}/content` lacks the documented `PATCH` update (a JSON array +// of patch commands, `204 No Content`; +// https://learn.microsoft.com/graph/api/page-update). It declares an +// octet-stream `PUT` instead, which the update docs do not describe. +// The patterns cover `/me`, `/users/{id}`, `/groups/{id}`, and `/sites/{id}`, +// plus every nested section form Graph generates. +const GRAPH_ID_SEGMENT = String.raw`\{[^/}]+\}`; +const ONENOTE_ROOT = String.raw`^(?:/(?:v1\.0|beta))?/(?:me|(?:users|groups|sites)/${GRAPH_ID_SEGMENT})/onenote/`; +const ONENOTE_SECTION = String.raw`(?:(?:notebooks/${GRAPH_ID_SEGMENT}/)?(?:sectionGroups/${GRAPH_ID_SEGMENT}/)?sections/${GRAPH_ID_SEGMENT}/)?`; +const ONENOTE_PAGES_PATH = new RegExp(`${ONENOTE_ROOT}${ONENOTE_SECTION}pages$`); +const ONENOTE_PAGE_CONTENT_PATH = new RegExp( + `${ONENOTE_ROOT}${ONENOTE_SECTION}pages/${GRAPH_ID_SEGMENT}/content$`, +); + +const ONENOTE_HTML_DESCRIPTION = + "Page content as a well-formed XHTML document. The title element sets the page title."; + +const oneNoteCreatePageRequestBody = (): Record => ({ + description: + "Send the page HTML as a raw text/html body (default). Use multipart/form-data to " + + "include images or files: the required Presentation part holds the page HTML, and " + + "each other part holds binary data that the HTML references as name:.", + required: true, + content: { + "text/html": { + schema: { type: "string", description: ONENOTE_HTML_DESCRIPTION }, + }, + "multipart/form-data": { + schema: { + type: "object", + required: ["Presentation"], + properties: { + Presentation: { type: "string", description: ONENOTE_HTML_DESCRIPTION }, + }, + additionalProperties: { type: "string", format: "binary" }, + }, + encoding: { Presentation: { contentType: "text/html" } }, + }, + }, +}); + +const oneNotePatchPageContentOperation = ( + template: Record, + writeTemplate: Record | undefined, +): Record => { + // Permissions come from the generated write operation (the PUT), never from + // the read operation the operationId is derived from. + const writePermissions = writeTemplate + ? Object.fromEntries( + ["security", "x-ms-permissions"].flatMap((key) => + writeTemplate[key] !== undefined ? [[key, writeTemplate[key]]] : [], + ), + ) + : {}; + // `me.onenote.GetPagesContent` -> `me.onenote.PatchPagesContent`: unique per + // path, and distinct from the generated PUT's `...UpdatePagesContent`. + const templateOperationId = + typeof template.operationId === "string" ? template.operationId : undefined; + const derivedOperationId = templateOperationId?.replace( + /\.(?:Get|Update)PagesContent$/, + ".PatchPagesContent", + ); + // Never reuse the template's id: an unrecognized shape gets no operationId + // and the extractor names the tool from method and path instead. + const operationId = derivedOperationId !== templateOperationId ? derivedOperationId : undefined; + return { + ...(Array.isArray(template.tags) ? { tags: template.tags } : {}), + summary: "Update page", + description: + "Update the content of a OneNote page with an array of patch commands. Each command " + + "targets an element (#, a generated id, body, or title) and appends, inserts, " + + "prepends, or replaces HTML content.", + externalDocs: { + description: "Find more info here", + url: "https://learn.microsoft.com/graph/api/page-update?view=graph-rest-1.0", + }, + ...(operationId ? { operationId } : {}), + ...writePermissions, + requestBody: { + description: "Patch commands to apply to the page, in order.", + required: true, + content: { + "application/json": { + schema: { + type: "array", + items: { + type: "object", + required: ["target", "action"], + properties: { + target: { + type: "string", + description: + "The element to update: #, the generated id of the element, or the body or title keyword.", + }, + // Inline lowercase enums: the documented wire values. The + // generated component enums are PascalCase. + action: { + type: "string", + enum: ["append", "insert", "prepend", "replace", "delete"], + description: "The action to perform on the target element.", + }, + position: { + type: "string", + enum: ["after", "before"], + description: + "Where to add the content relative to the target element. Default: after.", + }, + content: { + type: "string", + description: "Well-formed HTML to add to the page.", + }, + }, + }, + }, + }, + }, + }, + responses: { + "204": { description: "No Content" }, + "4XX": { $ref: "#/components/responses/error" }, + "5XX": { $ref: "#/components/responses/error" }, + }, + "x-ms-docs-operation-type": "operation", + }; +}; + +const normalizeMicrosoftGraphOneNotePathItem = ( + path: string, + pathItem: Record, +): Record => { + if (ONENOTE_PAGES_PATH.test(path)) { + const post = pathItem.post; + if (!isRecord(post)) return pathItem; + return { ...pathItem, post: { ...post, requestBody: oneNoteCreatePageRequestBody() } }; + } + + if (ONENOTE_PAGE_CONTENT_PATH.test(path)) { + const next: Record = { ...pathItem }; + const template = isRecord(pathItem.get) + ? pathItem.get + : isRecord(pathItem.put) + ? pathItem.put + : undefined; + if (!isRecord(pathItem.patch) && template) { + next.patch = oneNotePatchPageContentOperation( + template, + isRecord(pathItem.put) ? pathItem.put : undefined, + ); + } + // Keep the generated octet-stream PUT for existing callers, but mark it + // deprecated and drop its link to the PATCH-only update docs so tool + // selection prefers the documented update. + if (isRecord(pathItem.put)) { + const { externalDocs: _externalDocs, ...put } = pathItem.put; + next.put = { + ...put, + summary: "Replace page content (undocumented)", + description: + "Generated media upload that the OneNote update docs do not describe. Use the PATCH operation on this path to update a page.", + deprecated: true, + }; + } + return next; + } + + return pathItem; +}; + export const fetchMicrosoftGraphOpenApiSpec = Effect.fn("Microsoft.fetchGraphOpenApiSpec")( function* (specUrl: string) { const client = yield* HttpClient.HttpClient; @@ -726,7 +900,9 @@ export const microsoftGraphKeepPathItem = (selection: { tagPrefixes: selection.tagPrefixes, selectedScopes, }); - return kept ? normalizeMicrosoftGraphContentPathItem(kept) : null; + return kept + ? normalizeMicrosoftGraphOneNotePathItem(path, normalizeMicrosoftGraphContentPathItem(kept)) + : null; }; }; diff --git a/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts new file mode 100644 index 0000000000..a7b19ecda3 --- /dev/null +++ b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts @@ -0,0 +1,663 @@ +// OneNote page write contracts. Graph's generated OpenAPI document declares a +// JSON body for page create and omits the documented PATCH page update; the +// Graph adapter corrects both. These tests cover the spec correction itself, +// the published slice, and the runtime path an existing integration takes +// when it re-fetches an uncorrected slice (`updateSpec`): the stored tool +// schemas and the wire requests the invoker sends. +// +// The published service emulators have no OneNote surface, so the runtime +// cases serve a synthetic Graph-shaped slice and capture requests through an +// in-memory HttpClient, as the other Graph adapter tests do. + +import { describe, expect, it } from "@effect/vitest"; +import { Effect, Layer, Match, Schema } from "effect"; +import { + HttpClient, + HttpClientRequest, + HttpClientResponse, + type HttpBody, +} from "effect/unstable/http"; +import { JSON_SCHEMA, dump as dumpYamlDocument } from "js-yaml"; + +import { AuthTemplateSlug, ConnectionName, IntegrationSlug, ToolAddress } from "@executor-js/sdk"; +import { createExecutor } from "@executor-js/sdk"; +import { makeTestConfig, memoryCredentialsPlugin } from "@executor-js/sdk/testing"; +import { openApiPlugin } from "@executor-js/plugin-openapi"; + +import { microsoftGraphKeepPathItem } from "./graph"; +import { + MICROSOFT_AUTH_TEMPLATE_SLUG, + microsoftGraphExactPathsForPresetIds, + microsoftGraphPathPrefixesForPresetIds, + microsoftGraphTagPrefixesForPresetIds, +} from "./presets"; +import { buildGraphSliceDocument, parseGraphSourceDocument } from "./slice-build"; +import { microsoftGraphSliceUrl } from "./slices"; +import { microsoftGraphAdapter } from "./spec-format-adapter"; + +type Json = Record; + +const isRecord = (value: unknown): value is Json => + value !== null && typeof value === "object" && !Array.isArray(value); + +const record = (value: unknown): Json => { + expect(isRecord(value)).toBe(true); + return value as Json; +}; + +// --------------------------------------------------------------------------- +// Synthetic Graph-shaped source (uncorrected, as Graph generates it) +// --------------------------------------------------------------------------- + +const ROOTS = [ + { path: "/me", prefix: "me" }, + { path: "/users/{user-id}", prefix: "users" }, + { path: "/groups/{group-id}", prefix: "groups" }, + { path: "/sites/{site-id}", prefix: "sites" }, +] as const; + +const SECTION_FORMS = [ + { path: "", prefix: "" }, + { path: "/sections/{onenoteSection-id}", prefix: ".sections" }, + { + path: "/notebooks/{notebook-id}/sections/{onenoteSection-id}", + prefix: ".notebooks.sections", + }, + { + path: "/sectionGroups/{sectionGroup-id}/sections/{onenoteSection-id}", + prefix: ".sectionGroups.sections", + }, + { + path: "/notebooks/{notebook-id}/sectionGroups/{sectionGroup-id}/sections/{onenoteSection-id}", + prefix: ".notebooks.sectionGroups.sections", + }, +] as const; + +interface OneNoteVariant { + readonly pagesPath: string; + readonly contentPath: string; + readonly actionPath: string; + readonly operationPrefix: string; +} + +const VARIANTS: readonly OneNoteVariant[] = ROOTS.flatMap((root) => + SECTION_FORMS.map((form) => { + const pagesPath = `${root.path}/onenote${form.path}/pages`; + return { + pagesPath, + contentPath: `${pagesPath}/{onenotePage-id}/content`, + actionPath: `${pagesPath}/{onenotePage-id}/onenotePatchContent`, + operationPrefix: `${root.prefix}.onenote${form.prefix}`, + }; + }), +); + +const errorResponses = { + "4XX": { $ref: "#/components/responses/error" }, + "5XX": { $ref: "#/components/responses/error" }, +}; + +const delegated = (scope: string) => [{ azureAdDelegated: [scope] }]; + +const pagesPathItem = (operationPrefix: string): Json => ({ + get: { + tags: ["onenote"], + operationId: `${operationPrefix}.ListPages`, + security: delegated("Notes.Read"), + responses: { + "2XX": { + description: "Retrieved collection", + content: { + "application/json": { + schema: { $ref: "#/components/schemas/microsoft.graph.onenotePageCollectionResponse" }, + }, + }, + }, + ...errorResponses, + }, + }, + post: { + tags: ["onenote"], + summary: "Create page", + operationId: `${operationPrefix}.CreatePages`, + security: delegated("Notes.Create"), + requestBody: { + description: "New navigation property", + content: { + "application/json": { + schema: { $ref: "#/components/schemas/microsoft.graph.onenotePage" }, + }, + }, + required: true, + }, + responses: { + "2XX": { + description: "Created navigation property.", + content: { + "application/json": { + schema: { $ref: "#/components/schemas/microsoft.graph.onenotePage" }, + }, + }, + }, + ...errorResponses, + }, + }, +}); + +const contentPathItem = (operationPrefix: string): Json => ({ + get: { + tags: ["onenote"], + operationId: `${operationPrefix}.GetPagesContent`, + security: delegated("Notes.Read"), + responses: { + "2XX": { + description: "Retrieved media content", + content: { "application/octet-stream": { schema: { type: "string", format: "binary" } } }, + }, + ...errorResponses, + }, + }, + put: { + tags: ["onenote"], + summary: "Update page", + externalDocs: { + description: "Find more info here", + url: "https://learn.microsoft.com/graph/api/page-update?view=graph-rest-1.0", + }, + operationId: `${operationPrefix}.UpdatePagesContent`, + security: delegated("Notes.ReadWrite"), + requestBody: { + content: { "application/octet-stream": { schema: { type: "string", format: "binary" } } }, + required: true, + }, + responses: { "204": { description: "Success" }, ...errorResponses }, + }, + parameters: [ + { + name: "onenotePage-id", + in: "path", + required: true, + schema: { type: "string" }, + "x-ms-docs-key-type": "onenotePage", + }, + ], +}); + +const actionPathItem = (operationPrefix: string): Json => ({ + post: { + tags: ["onenote"], + summary: "Invoke action onenotePatchContent", + operationId: `${operationPrefix}.pages.onenotePage.onenotePatchContent`, + security: delegated("Notes.ReadWrite"), + requestBody: { + content: { + "application/json": { + schema: { + type: "object", + properties: { + commands: { + type: "array", + items: { $ref: "#/components/schemas/microsoft.graph.onenotePatchContentCommand" }, + }, + }, + }, + }, + }, + required: true, + }, + responses: { "204": { description: "Success" }, ...errorResponses }, + "x-ms-docs-operation-type": "action", + }, +}); + +const DRIVE_CONTENT_PATH = "/drives/{drive-id}/items/{driveItem-id}/content"; + +const driveContentPathItem = (): Json => ({ + put: { + tags: ["drives.driveItem"], + summary: "Update content for the navigation property items in drives", + operationId: "drives.UpdateItemsContent", + security: delegated("Files.ReadWrite"), + requestBody: { + content: { "application/octet-stream": { schema: { type: "string", format: "binary" } } }, + required: true, + }, + responses: { "204": { description: "Success" }, ...errorResponses }, + }, +}); + +const graphSourceDocument = (): Json => { + const paths: Json = {}; + for (const variant of VARIANTS) { + paths[variant.pagesPath] = pagesPathItem(variant.operationPrefix); + paths[variant.contentPath] = contentPathItem(variant.operationPrefix); + paths[variant.actionPath] = actionPathItem(variant.operationPrefix); + } + paths[DRIVE_CONTENT_PATH] = driveContentPathItem(); + return { + openapi: "3.0.4", + info: { title: "Microsoft Graph Fixture", version: "v1.0" }, + servers: [{ url: "https://graph.microsoft.com/v1.0" }], + paths, + components: { + responses: { + error: { + description: "error", + content: { + "application/json": { + schema: { $ref: "#/components/schemas/microsoft.graph.ODataErrors.ODataError" }, + }, + }, + }, + }, + securitySchemes: { + azureAdDelegated: { + type: "oauth2", + flows: { + authorizationCode: { + authorizationUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize", + tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token", + scopes: { "Notes.ReadWrite": "Read and write notebooks" }, + }, + }, + }, + }, + schemas: { + "microsoft.graph.onenotePage": { + type: "object", + properties: { id: { type: "string" }, title: { type: "string", nullable: true } }, + }, + "microsoft.graph.onenotePageCollectionResponse": { + type: "object", + properties: { + value: { + type: "array", + items: { $ref: "#/components/schemas/microsoft.graph.onenotePage" }, + }, + }, + }, + "microsoft.graph.onenotePatchContentCommand": { + type: "object", + required: ["@odata.type"], + properties: { + action: { $ref: "#/components/schemas/microsoft.graph.onenotePatchActionType" }, + content: { type: "string", nullable: true }, + target: { type: "string" }, + "@odata.type": { type: "string" }, + }, + }, + "microsoft.graph.onenotePatchActionType": { + type: "string", + enum: ["Replace", "Append", "Delete", "Insert", "Prepend"], + }, + "microsoft.graph.ODataErrors.ODataError": { + type: "object", + properties: { error: { type: "object" } }, + }, + }, + }, + }; +}; + +const toBlockYaml = (document: Json): string => + dumpYamlDocument(document, { noRefs: true, lineWidth: -1, schema: JSON_SCHEMA }); + +const onenoteKeepPathItem = () => + microsoftGraphKeepPathItem({ + coversFullGraph: false, + presetIds: ["onenote"], + customScopes: [], + exactPaths: microsoftGraphExactPathsForPresetIds(["onenote"]), + pathPrefixes: microsoftGraphPathPrefixesForPresetIds(["onenote"]), + tagPrefixes: microsoftGraphTagPrefixesForPresetIds(["onenote"]), + }); + +const fullGraphKeepPathItem = () => + microsoftGraphKeepPathItem({ + coversFullGraph: true, + presetIds: [], + customScopes: [], + exactPaths: [], + pathPrefixes: [], + tagPrefixes: [], + }); + +const sourcePaths = (): Json => record(graphSourceDocument().paths); + +// --------------------------------------------------------------------------- +// Spec correction +// --------------------------------------------------------------------------- + +const expectCorrectedCreate = (post: Json, operationPrefix: string) => { + expect(post.operationId).toBe(`${operationPrefix}.CreatePages`); + expect(post.security).toEqual(delegated("Notes.Create")); + const requestBody = record(post.requestBody); + expect(requestBody.required).toBe(true); + const content = record(requestBody.content); + // text/html first: the invoker sends the first media type by default. + expect(Object.keys(content)).toEqual(["text/html", "multipart/form-data"]); + expect(record(record(content["text/html"]).schema).type).toBe("string"); + const multipart = record(content["multipart/form-data"]); + expect(multipart.schema).toMatchObject({ + type: "object", + required: ["Presentation"], + properties: { Presentation: { type: "string" } }, + additionalProperties: { type: "string", format: "binary" }, + }); + expect(multipart.encoding).toEqual({ Presentation: { contentType: "text/html" } }); + // Responses stay as generated. + expect(Object.keys(record(post.responses))).toEqual(["2XX", "4XX", "5XX"]); +}; + +const expectAddedPatch = (patch: Json, operationPrefix: string) => { + expect(patch.operationId).toBe(`${operationPrefix}.PatchPagesContent`); + // Write permissions from the generated PUT, not the GET's read scope. + expect(patch.security).toEqual(delegated("Notes.ReadWrite")); + const content = record(record(patch.requestBody).content); + expect(Object.keys(content)).toEqual(["application/json"]); + expect(record(content["application/json"]).schema).toMatchObject({ + type: "array", + items: { + type: "object", + required: ["target", "action"], + properties: { + target: { type: "string" }, + action: { enum: ["append", "insert", "prepend", "replace", "delete"] }, + position: { enum: ["after", "before"] }, + content: { type: "string" }, + }, + }, + }); + expect(record(patch.responses)["204"]).toEqual({ description: "No Content" }); +}; + +describe("OneNote page write contract correction", () => { + it("corrects create and adds PATCH update for every root and nested section form", () => { + const keep = onenoteKeepPathItem(); + const paths = sourcePaths(); + expect(VARIANTS).toHaveLength(20); + + for (const variant of VARIANTS) { + const pages = keep(variant.pagesPath, record(paths[variant.pagesPath])); + expect(pages, variant.pagesPath).not.toBeNull(); + expectCorrectedCreate(record(pages!.post), variant.operationPrefix); + // The list operation is untouched. + expect(pages!.get).toEqual(record(paths[variant.pagesPath]).get); + + const content = keep(variant.contentPath, record(paths[variant.contentPath])); + expect(content, variant.contentPath).not.toBeNull(); + expectAddedPatch(record(content!.patch), variant.operationPrefix); + expect(content!.get).toEqual(record(paths[variant.contentPath]).get); + expect(content!.parameters).toEqual(record(paths[variant.contentPath]).parameters); + + // The generated PUT stays callable but deprecated, without the + // PATCH-only update docs link. + const put = record(content!.put); + expect(put.deprecated).toBe(true); + expect(put.externalDocs).toBeUndefined(); + expect(put.operationId).toBe(`${variant.operationPrefix}.UpdatePagesContent`); + expect(put.requestBody).toEqual(record(record(paths[variant.contentPath]).put).requestBody); + + // The undocumented action stays exactly as generated. + const action = keep(variant.actionPath, record(paths[variant.actionPath])); + expect(action).toEqual(paths[variant.actionPath]); + } + }); + + it("applies the same correction to full-graph selections", () => { + const keep = fullGraphKeepPathItem(); + const paths = sourcePaths(); + const variant = VARIANTS[0]!; + expectCorrectedCreate( + record(keep(variant.pagesPath, record(paths[variant.pagesPath]))!.post), + variant.operationPrefix, + ); + expectAddedPatch( + record(keep(variant.contentPath, record(paths[variant.contentPath]))!.patch), + variant.operationPrefix, + ); + }); + + it("leaves non-OneNote content PUT operations unchanged", () => { + const keep = fullGraphKeepPathItem(); + const driveItem = record(sourcePaths()[DRIVE_CONTENT_PATH]); + expect(keep(DRIVE_CONTENT_PATH, driveItem)).toEqual(driveContentPathItem()); + }); + + it("is idempotent over an already corrected path item", () => { + const keep = onenoteKeepPathItem(); + const paths = sourcePaths(); + for (const variant of VARIANTS) { + for (const path of [variant.pagesPath, variant.contentPath, variant.actionPath]) { + const once = keep(path, record(paths[path])); + expect(keep(path, once!), path).toEqual(once); + } + } + }); + + it("keeps a PATCH operation that the source already declares", () => { + const keep = onenoteKeepPathItem(); + const variant = VARIANTS[0]!; + const declared = { operationId: "upstream.PatchContent", responses: {} }; + const corrected = keep(variant.contentPath, { + ...record(sourcePaths()[variant.contentPath]), + patch: declared, + }); + expect(corrected!.patch).toEqual(declared); + }); + + it("builds an onenote slice with unique operationIds and resolvable refs", () => { + const doc = parseGraphSourceDocument(toBlockYaml(graphSourceDocument())); + expect(doc).not.toBeNull(); + const slice = buildGraphSliceDocument(doc!, ["onenote"]); + const sliceDoc = parseGraphSourceDocument(slice.specText)!; + const paths = record(sliceDoc.paths); + + expect(Object.keys(paths)).not.toContain(DRIVE_CONTENT_PATH); + expect(Object.keys(paths)).toHaveLength(VARIANTS.length * 3); + for (const variant of VARIANTS) { + expectCorrectedCreate(record(record(paths[variant.pagesPath]).post), variant.operationPrefix); + expectAddedPatch(record(record(paths[variant.contentPath]).patch), variant.operationPrefix); + } + + const operationIds = Object.values(paths).flatMap((pathItem) => + Object.values(record(pathItem)) + .filter(isRecord) + .map((operation) => operation.operationId) + .filter((id): id is string => typeof id === "string"), + ); + expect(new Set(operationIds).size).toBe(operationIds.length); + + const refs = new Set(); + const collect = (value: unknown): void => { + if (Array.isArray(value)) value.forEach(collect); + else if (isRecord(value)) + for (const [key, inner] of Object.entries(value)) { + if (key === "$ref" && typeof inner === "string") refs.add(inner); + else collect(inner); + } + }; + collect(sliceDoc); + expect(refs.size).toBeGreaterThan(0); + for (const ref of refs) { + const [, , section, name] = ref.split("/"); + expect(record(record(sliceDoc.components)[section!])[name!], ref).toBeDefined(); + } + }); +}); + +// --------------------------------------------------------------------------- +// Runtime: stored tool schemas and wire requests +// --------------------------------------------------------------------------- + +interface CapturedRequest { + readonly method: string; + readonly url: string; + readonly contentType: string; + readonly body: string; +} + +// Encode the request body the way a fetch transport would put it on the wire. +const readBody = ( + body: HttpBody.HttpBody, +): Promise<{ readonly contentType: string; readonly text: string }> => + Match.value(body).pipe( + Match.tag("Uint8Array", (bytes) => + Promise.resolve({ + contentType: bytes.contentType, + text: new TextDecoder().decode(bytes.body), + }), + ), + Match.tag("FormData", (form) => { + const encoded = new Response(form.formData); + return encoded.text().then((text) => ({ + contentType: encoded.headers.get("content-type") ?? "", + text, + })); + }), + // The OneNote calls under test never stream; an unexpected body records as empty. + Match.tag("Empty", "Raw", "Stream", () => Promise.resolve({ contentType: "", text: "" })), + Match.exhaustive, + ); + +const decodeJsonArray = Schema.decodeUnknownSync( + Schema.fromJsonString(Schema.Array(Schema.Unknown)), +); + +const ONENOTE_SLICE_URL = microsoftGraphSliceUrl("onenote"); + +const graphHttpClientLayer = (sliceText: () => string, captured: CapturedRequest[]) => + Layer.succeed(HttpClient.HttpClient)( + HttpClient.make((request: HttpClientRequest.HttpClientRequest) => + Effect.gen(function* () { + if (request.url === ONENOTE_SLICE_URL) { + return HttpClientResponse.fromWeb( + request, + new Response(sliceText(), { + status: 200, + headers: { "content-type": "application/yaml" }, + }), + ); + } + const body = yield* Effect.promise(() => readBody(request.body)); + captured.push({ + method: request.method, + url: request.url, + contentType: request.headers["content-type"] ?? body.contentType, + body: body.text, + }); + const created = request.method === "POST"; + return HttpClientResponse.fromWeb( + request, + created + ? new Response(JSON.stringify({ id: "page-1", title: "Test page" }), { + status: 201, + headers: { "content-type": "application/json" }, + }) + : new Response(null, { status: 204 }), + ); + }), + ), + ); + +const PAGE_HTML = + "Test page

Hello

"; + +describe("OneNote page writes through the OpenAPI plugin", () => { + it.effect( + "re-fetching an uncorrected slice stores corrected tools and sends the documented wire shapes", + () => + Effect.gen(function* () { + // The slice as published before the correction: the published asset + // carries the generated (wrong) request bodies. + const uncorrectedSlice = toBlockYaml(graphSourceDocument()); + const captured: CapturedRequest[] = []; + const executor = yield* createExecutor( + makeTestConfig({ + plugins: [ + openApiPlugin({ + httpClientLayer: graphHttpClientLayer(() => uncorrectedSlice, captured), + specFormats: [microsoftGraphAdapter], + }), + memoryCredentialsPlugin(), + ], + }), + ); + + yield* executor.openapi.addSpec({ + spec: { kind: "url", url: ONENOTE_SLICE_URL }, + specFormat: "microsoft-graph", + slug: "onenote_fixture", + }); + // An existing integration refreshes its tools from the same URL. + const updated = yield* executor.openapi.updateSpec("onenote_fixture"); + expect(updated.removedTools).toEqual([]); + + yield* executor.connections.create({ + owner: "org", + name: ConnectionName.make("main"), + integration: IntegrationSlug.make("onenote_fixture"), + template: AuthTemplateSlug.make(MICROSOFT_AUTH_TEMPLATE_SLUG), + value: "test-access-token", + }); + + const tools = yield* executor.tools.list(); + const toolNamed = (suffix: string) => { + const tool = tools.find((candidate) => + String(candidate.address).startsWith("tools.onenote_fixture.") + ? String(candidate.address).endsWith(suffix) + : false, + ); + expect(tool, suffix).toBeDefined(); + return ToolAddress.make(String(tool!.address)); + }; + const createTool = toolNamed(".onenote.meOnenoteSectionsCreatePages"); + const patchTool = toolNamed(".onenote.meOnenotePatchPagesContent"); + + const createSchema = yield* executor.tools.schema(createTool); + expect(createSchema?.inputSchema).toMatchObject({ + properties: { body: { type: "string" } }, + }); + const patchSchema = yield* executor.tools.schema(patchTool); + expect(patchSchema?.inputSchema).toMatchObject({ + properties: { body: { type: "array" } }, + }); + + // Create with the default media type: raw HTML. + yield* executor.execute(createTool, { + "onenoteSection-id": "section-1", + body: PAGE_HTML, + }); + // Create with multipart: the Presentation part is text/html. + yield* executor.execute(createTool, { + "onenoteSection-id": "section-1", + contentType: "multipart/form-data", + body: { Presentation: PAGE_HTML }, + }); + // Update with a bare JSON array of patch commands; Graph answers 204. + const commands = [{ target: "body", action: "append", content: "

More

" }]; + yield* executor.execute(patchTool, { "onenotePage-id": "page-1", body: commands }); + + expect(captured).toHaveLength(3); + const [htmlCreate, multipartCreate, patch] = captured; + + expect(htmlCreate!.method).toBe("POST"); + expect(htmlCreate!.url).toBe( + "https://graph.microsoft.com/v1.0/me/onenote/sections/section-1/pages", + ); + expect(htmlCreate!.contentType).toMatch(/^text\/html/); + expect(htmlCreate!.body).toBe(PAGE_HTML); + + expect(multipartCreate!.method).toBe("POST"); + expect(multipartCreate!.contentType).toMatch(/^multipart\/form-data; boundary=/); + expect(multipartCreate!.body).toMatch( + /name="Presentation"[\s\S]*Content-Type: text\/html[\s\S]*Test page<\/title>/i, + ); + + expect(patch!.method).toBe("PATCH"); + expect(patch!.url).toBe("https://graph.microsoft.com/v1.0/me/onenote/pages/page-1/content"); + expect(patch!.contentType).toMatch(/^application\/json/); + expect(decodeJsonArray(patch!.body)).toEqual(commands); + }), + ); +}); From 7625f6e533151d60e4097c1a3a5c4d57ac69b006 Mon Sep 17 00:00:00 2001 From: Lorenzo <49939356+lorenzocb@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:31:41 +0000 Subject: [PATCH 3/5] Correct a OneNote PATCH the source already declares MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first version kept a declared PATCH on page content unchanged. A declared PATCH can carry a generated OData shape, so the documented contract now always applies. A declared operationId is kept, so its tool name stays stable and a second pass stays identical. 👾 Generated with [Letta Code](https://letta.com) Co-Authored-By: Letta Code <noreply@letta.com> --- .../openapi/src/providers/microsoft/graph.ts | 18 +++++++++++++---- .../src/providers/microsoft/onenote.test.ts | 20 +++++++++++++++---- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/packages/plugins/openapi/src/providers/microsoft/graph.ts b/packages/plugins/openapi/src/providers/microsoft/graph.ts index 2b71119065..ee86c2f354 100644 --- a/packages/plugins/openapi/src/providers/microsoft/graph.ts +++ b/packages/plugins/openapi/src/providers/microsoft/graph.ts @@ -778,11 +778,21 @@ const normalizeMicrosoftGraphOneNotePathItem = ( : isRecord(pathItem.put) ? pathItem.put : undefined; - if (!isRecord(pathItem.patch) && template) { - next.patch = oneNotePatchPageContentOperation( - template, - isRecord(pathItem.put) ? pathItem.put : undefined, + // Always apply the documented PATCH contract, even over a PATCH the source + // declares (it could carry a generated OData shape). A declared PATCH keeps + // its operationId, so its tool name stays stable; this also keeps a second + // pass over a corrected path item identical. + const existingPatch = isRecord(pathItem.patch) ? pathItem.patch : undefined; + const operationTemplate = template ?? existingPatch; + if (operationTemplate) { + const corrected = oneNotePatchPageContentOperation( + operationTemplate, + isRecord(pathItem.put) ? pathItem.put : existingPatch, ); + next.patch = + typeof existingPatch?.operationId === "string" + ? { ...corrected, operationId: existingPatch.operationId } + : corrected; } // Keep the generated octet-stream PUT for existing callers, but mark it // deprecated and drop its link to the PATCH-only update docs so tool diff --git a/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts index a7b19ecda3..5cec5984af 100644 --- a/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts +++ b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts @@ -435,15 +435,27 @@ describe("OneNote page write contract correction", () => { } }); - it("keeps a PATCH operation that the source already declares", () => { + it("corrects a PATCH that the source declares and keeps its operationId", () => { const keep = onenoteKeepPathItem(); const variant = VARIANTS[0]!; - const declared = { operationId: "upstream.PatchContent", responses: {} }; + const declared = { + operationId: `${variant.operationPrefix}.PatchPagesContent`, + requestBody: { + content: { + "application/json": { + schema: { $ref: "#/components/schemas/microsoft.graph.onenotePage" }, + }, + }, + }, + responses: { "2XX": { description: "Success" } }, + }; const corrected = keep(variant.contentPath, { ...record(sourcePaths()[variant.contentPath]), - patch: declared, + patch: { ...declared, operationId: "upstream.PatchContent" }, }); - expect(corrected!.patch).toEqual(declared); + const patch = record(corrected!.patch); + expect(patch.operationId).toBe("upstream.PatchContent"); + expectAddedPatch({ ...patch, operationId: declared.operationId }, variant.operationPrefix); }); it("builds an onenote slice with unique operationIds and resolvable refs", () => { From 8f346aeb443895bfd6753643c64e16d8a6c8a76b Mon Sep 17 00:00:00 2001 From: Lorenzo <49939356+lorenzocb@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:33:08 +0000 Subject: [PATCH 4/5] Test OneNote multipart file parts on the wire MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A multipart page create can carry files in parts that the page HTML references by name. The invoker already sends a ToolFile value under any part name as a file part, so the test now covers that, and the request body description tells callers to pass files that way. 👾 Generated with [Letta Code](https://letta.com) Co-Authored-By: Letta Code <noreply@letta.com> --- .../openapi/src/providers/microsoft/graph.ts | 3 ++- .../src/providers/microsoft/onenote.test.ts | 18 ++++++++++++++++-- 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/packages/plugins/openapi/src/providers/microsoft/graph.ts b/packages/plugins/openapi/src/providers/microsoft/graph.ts index ee86c2f354..52bb3a9466 100644 --- a/packages/plugins/openapi/src/providers/microsoft/graph.ts +++ b/packages/plugins/openapi/src/providers/microsoft/graph.ts @@ -656,7 +656,8 @@ const oneNoteCreatePageRequestBody = (): Record<string, unknown> => ({ description: "Send the page HTML as a raw text/html body (default). Use multipart/form-data to " + "include images or files: the required Presentation part holds the page HTML, and " + - "each other part holds binary data that the HTML references as name:<part-name>.", + "each other part is a file (pass a ToolFile value under the part name) that the HTML " + + "references as name:<part-name>.", required: true, content: { "text/html": { diff --git a/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts index 5cec5984af..a93e3f4146 100644 --- a/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts +++ b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts @@ -640,11 +640,22 @@ describe("OneNote page writes through the OpenAPI plugin", () => { "onenoteSection-id": "section-1", body: PAGE_HTML, }); - // Create with multipart: the Presentation part is text/html. + // Create with multipart: the Presentation part is text/html, and an + // extra part carries a file that the HTML references by part name. yield* executor.execute(createTool, { "onenoteSection-id": "section-1", contentType: "multipart/form-data", - body: { Presentation: PAGE_HTML }, + body: { + Presentation: PAGE_HTML, + image1: { + _tag: "ToolFile", + name: "image1.png", + mimeType: "image/png", + encoding: "base64", + data: Buffer.from("png-bytes").toString("base64"), + byteLength: 9, + }, + }, }); // Update with a bare JSON array of patch commands; Graph answers 204. const commands = [{ target: "body", action: "append", content: "<p>More</p>" }]; @@ -665,6 +676,9 @@ describe("OneNote page writes through the OpenAPI plugin", () => { expect(multipartCreate!.body).toMatch( /name="Presentation"[\s\S]*Content-Type: text\/html[\s\S]*<title>Test page<\/title>/i, ); + expect(multipartCreate!.body).toMatch( + /name="image1"; filename="image1.png"[\s\S]*Content-Type: image\/png[\s\S]*png-bytes/i, + ); expect(patch!.method).toBe("PATCH"); expect(patch!.url).toBe("https://graph.microsoft.com/v1.0/me/onenote/pages/page-1/content"); From 4dbb0a91fdac0d9458a64b6b8971eac07919935f Mon Sep 17 00:00:00 2001 From: Lorenzo <49939356+lorenzocb@users.noreply.github.com> Date: Mon, 16 Nov 2026 17:34:02 +0000 Subject: [PATCH 5/5] Take OneNote PATCH permissions only from the PUT MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A declared PATCH could carry a read-only scope, and the corrected update kept it when the path had no PUT. Permissions now come only from the generated PUT. The PATCH description also covers the delete action, which takes no content. 👾 Generated with [Letta Code](https://letta.com) Co-Authored-By: Letta Code <noreply@letta.com> --- .../plugins/openapi/src/providers/microsoft/graph.ts | 9 +++++---- .../openapi/src/providers/microsoft/onenote.test.ts | 2 ++ 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/packages/plugins/openapi/src/providers/microsoft/graph.ts b/packages/plugins/openapi/src/providers/microsoft/graph.ts index 52bb3a9466..1d87cafdd8 100644 --- a/packages/plugins/openapi/src/providers/microsoft/graph.ts +++ b/packages/plugins/openapi/src/providers/microsoft/graph.ts @@ -682,7 +682,7 @@ const oneNotePatchPageContentOperation = ( writeTemplate: Record<string, unknown> | undefined, ): Record<string, unknown> => { // Permissions come from the generated write operation (the PUT), never from - // the read operation the operationId is derived from. + // the read operation the operationId is derived from or a declared PATCH. const writePermissions = writeTemplate ? Object.fromEntries( ["security", "x-ms-permissions"].flatMap((key) => @@ -707,7 +707,7 @@ const oneNotePatchPageContentOperation = ( description: "Update the content of a OneNote page with an array of patch commands. Each command " + "targets an element (#<data-id>, a generated id, body, or title) and appends, inserts, " + - "prepends, or replaces HTML content.", + "prepends, or replaces HTML content, or deletes the element.", externalDocs: { description: "Find more info here", url: "https://learn.microsoft.com/graph/api/page-update?view=graph-rest-1.0", @@ -745,7 +745,8 @@ const oneNotePatchPageContentOperation = ( }, content: { type: "string", - description: "Well-formed HTML to add to the page.", + description: + "Well-formed HTML to add to the page. Required for every action except delete.", }, }, }, @@ -788,7 +789,7 @@ const normalizeMicrosoftGraphOneNotePathItem = ( if (operationTemplate) { const corrected = oneNotePatchPageContentOperation( operationTemplate, - isRecord(pathItem.put) ? pathItem.put : existingPatch, + isRecord(pathItem.put) ? pathItem.put : undefined, ); next.patch = typeof existingPatch?.operationId === "string" diff --git a/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts index a93e3f4146..cc76600f2e 100644 --- a/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts +++ b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts @@ -440,6 +440,8 @@ describe("OneNote page write contract correction", () => { const variant = VARIANTS[0]!; const declared = { operationId: `${variant.operationPrefix}.PatchPagesContent`, + // A read-only scope on a declared PATCH must not survive. + security: delegated("Notes.Read"), requestBody: { content: { "application/json": {