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..1d87cafdd8 100644 --- a/packages/plugins/openapi/src/providers/microsoft/graph.ts +++ b/packages/plugins/openapi/src/providers/microsoft/graph.ts @@ -629,6 +629,192 @@ 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 is a file (pass a ToolFile value under the part name) 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 or a declared PATCH. + 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, or deletes the element.", + 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. Required for every action except delete.", + }, + }, + }, + }, + }, + }, + }, + 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; + // 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 : undefined, + ); + 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 + // 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 +912,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..cc76600f2e --- /dev/null +++ b/packages/plugins/openapi/src/providers/microsoft/onenote.test.ts @@ -0,0 +1,691 @@ +// 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("corrects a PATCH that the source declares and keeps its operationId", () => { + const keep = onenoteKeepPathItem(); + 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": { + schema: { $ref: "#/components/schemas/microsoft.graph.onenotePage" }, + }, + }, + }, + responses: { "2XX": { description: "Success" } }, + }; + const corrected = keep(variant.contentPath, { + ...record(sourcePaths()[variant.contentPath]), + patch: { ...declared, operationId: "upstream.PatchContent" }, + }); + 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", () => { + 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, 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, + 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: "

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(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"); + expect(patch!.contentType).toMatch(/^application\/json/); + expect(decodeJsonArray(patch!.body)).toEqual(commands); + }), + ); +});