[Copilot]

This PR implements a comprehensive Webflow strategy for the crosspost project, enabling users to post content to Webflow CMS collections via the Webflow API v2.

Features

Core Functionality

• CMS Integration: Posts content to Webflow CMS collections using the official API v2
• OAuth Authentication: Supports OAuth access tokens with proper scope validation
• Image Support: Uploads images as Webflow assets and references them in collection items
• Error Handling: Comprehensive error handling with descriptive messages for API failures
• AbortSignal Support: Proper cancellation support following crosspost patterns

API Integration Details

• Uses Webflow CMS API v2 endpoints (/collections/{id}/items and /sites/{id}/assets)
• Implements proper authentication headers and request formatting
• Handles rate limiting scenarios and provides guidance for production use
• Supports custom API base URLs for testing and future API versions

Strategy Implementation

import { WebflowStrategy } from "@humanwhocodes/crosspost";

const strategy = new WebflowStrategy({
    accessToken: "your-oauth-token",
    siteId: "your-site-id", 
    collectionId: "your-collection-id"
});

// Post with images
await strategy.post("Hello Webflow!", {
    images: [{ data: imageData, alt: "Description" }]
});

Documentation

The implementation includes comprehensive documentation covering:

• API References: Links to official Webflow documentation for collection items, OAuth, and app registration
• Authentication Requirements: OAuth scopes, application registration process
• Rate Limits: Best practices for production usage and retry strategies
• Configuration: Required parameters and collection structure requirements
• Limitations: Current constraints and future enhancement opportunities

Testing

Added 24 comprehensive test cases covering:

• Constructor validation and error handling
• Message posting with various scenarios
• Image upload functionality and error cases
• API error responses and network failures
• AbortSignal cancellation support
• Request body validation and slug generation
• Response URL generation

All existing tests continue to pass (314 total tests passing).

Implementation Notes

• Follows established crosspost strategy patterns for consistency
• Uses proper TypeScript/JSDoc type definitions
• Implements automatic slug generation from message content
• Handles long messages by truncating names while preserving full content
• Maps images to common Webflow field patterns (main-image and images arrays)

The strategy is production-ready and integrates seamlessly with the existing crosspost ecosystem.

Fixes #117.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[nzakas]

Thanks for starting this. Webflow CMS is a useful target. I checked the implementation against the current Webflow Data API v2 docs, and the core API calls don't match the real API, so this won't work end to end yet, even though the mocked tests pass (24/24 locally). Details are in the inline comments. Summary, most severe first:

API correctness (blocking)

1. name/slug are sent top-level instead of inside fieldData, so create requests will fail validation.
2. Items are created as drafts on the staged endpoint and never published. Use /items/live or isDraft: false + /items/publish.
3. Image upload uses a multipart POST to /sites/{id}/assets, but v2 requires { fileName, fileHash } JSON followed by an S3 upload. Image field values also need to be { url, alt } objects, not asset IDs.
4. getUrlFromResponse reads a top-level slug that the API doesn't return. Because Client calls it synchronously, the throw rejects the whole client.post() for all strategies. The constructed https://{siteId}.webflow.io/{slug} URL is also wrong (short name, not ID, and missing the collection path).

Design
5. Field slugs (content, main-image, images) are hard-coded. Collections are user-defined, so this mapping needs to be configurable.
6. Slug generation collides on repeated or similar messages and strips non-ASCII letters.
7. abortSignal isn't passed to image uploads. MAX_MESSAGE_LENGTH = 10000 appears arbitrary.

Missing wiring. The PR only adds the strategy and its tests. Nothing else references it:

• src/index.ts doesn't export WebflowStrategy or its types, so it isn't reachable from the package.
• src/bin.js has no --webflow flag, usage line, or env vars (e.g. WEBFLOW_ACCESS_TOKEN, WEBFLOW_COLLECTION_ID, plus WEBFLOW_SITE_ID if still needed), so it's also unavailable to the MCP server, which gets its strategies from the CLI flags.
• README: the strategy list, API example, CLI flags, env var list, and a setup section (how to get a site token with cms:write/assets:write scopes and find the collection ID) are all missing. A site API token is also much simpler for users than a registered OAuth app, so the docs shouldn't imply OAuth is required.
• src/strategies/webflow.js isn't in release-please-config.json extra-files, so the // x-release-please-version User-Agent strings will never update (they already say v0.15.1; the current version is 1.0.4).

Mergeability. GitHub reports the PR as mergeable/clean. main is 34 commits ahead, but the strategy interface (src/types.js Strategy/PostOptions) and Client haven't changed since the base, so the shape (id, name, post(message, postOptions), getUrlFromResponse, MAX_MESSAGE_LENGTH, calculateMessageLength, validatePostOptions) is still consistent with the other strategies.

Tests. Beyond the specific comments, the mocks mirror the implementation's assumptions rather than the API's (201 instead of 202, top-level slug, multipart asset upload), and most tests don't inspect request bodies. Fixing the fixtures to match the documented request/response shapes should come first, so the tests can catch these issues.

[nzakas]

Request body shape doesn't match the v2 API. For POST /v2/collections/{collection_id}/items, name and slug are required fields inside fieldData, not top-level properties (see Create Collection Item). As written, every real request will fail validation because fieldData has no name/slug. Suggested shape:

const payload = {
	isDraft: false,
	fieldData: {
		name,
		slug,
		[this.#contentField]: message,
	},
};

The WebflowCollectionItem typedef needs the same fix.

[nzakas]

Items are created as drafts and never published. isDraft defaults to true on this endpoint, and the staged endpoint only writes to the staged collection, so the post never appears on the live site. That defeats the purpose of crossposting. Options:

• Use POST /v2/collections/{collection_id}/items/live (docs), which creates and publishes in one call, or
• Create with isDraft: false, then call POST /v2/collections/{collection_id}/items/publish with { itemIds: [id] }.

The first is simpler. Also note that both endpoints return 202, not 201 (the mocks use 201).

[nzakas]

Asset upload doesn't follow the Webflow v2 flow. Create Asset is not a multipart upload of the file. It's a two-step process:

1. POST /v2/sites/{site_id}/assets with a JSON body { fileName, fileHash } (fileHash = MD5 of the bytes). The response includes uploadUrl, uploadDetails, id, and hostedUrl.
2. POST a multipart form to uploadUrl (S3) with every uploadDetails field plus the file.

The current code will fail against the real API. Also in this function:

• The filename is hard-coded as image.jpg regardless of type. getImageMimeType() from ../util/images.js can pick the right extension.
• postOptions.signal isn't passed to this fetch, so aborting during an image upload has no effect. #uploadImage should accept the signal.

[nzakas]

Wrong value format for image fields, and hard-coded field slugs. Per field types and item values, Image fields take an object like { url, alt }, and MultiImage fields take an array of those objects, not bare asset ID strings. Since Image fields accept a url directly, you may be able to skip the Assets API (and siteId) entirely by using the hostedUrl from the upload. Worth checking, because that would simplify this a lot.

Separately, main-image and images are field slugs that only exist if the user's collection happens to define them. Collections without them will likely reject the request or silently drop the images. Also alt is lost here, even though it's available on each ImageEmbed.

[nzakas]

Field mapping should be configurable. Webflow collection schemas are user-defined, so a hard-coded content field (plus main-image/images below) only works if the user's collection happens to use those exact slugs. I suggest constructor options such as contentField (required, or defaulting to something documented), imageField, and maybe nameFrom or a name-building strategy. Also consider whether contentField is RichText: a RichText field expects HTML, so plain text with newlines will render as one paragraph unless it's converted.

Related: using the first 256 characters of the whole message as name puts newlines and URLs in the item title. Using the first line, like DevtoStrategy does, would be more consistent. message.slice(0, 256) can also split a surrogate pair (emoji) in half.

[nzakas]

10000 looks arbitrary. The JSDoc says it's the name limit, but the name is truncated to 256, and Webflow doesn't document a PlainText/RichText length limit. The MCP server uses this value to tell the model how much to rewrite, so an invented limit has visible effects. DevtoStrategy uses Infinity for its long-form target. Consider doing the same, or documenting where 10000 comes from.

[nzakas]

This assertion encodes the payload bug. It checks top-level body.slug, but the API requires body.fieldData.slug (and fieldData.name). Once the payload is fixed, please assert the full request body here, including isDraft.

[nzakas]

This fixture doesn't match the real v2 response. slug lives under fieldData (along with name), and the real response also includes isDraft, isArchived, lastPublished, etc. Because of this, the getUrlFromResponse tests pass even though the method will throw on real responses. The mocks should also use status 202.

[nzakas]

These two tests (default and custom apiBaseUrl) only assert strategy.id, so they test nothing about the base URL. The custom-URL case could register a MockServer on the custom host and assert the request goes there.

[nzakas]

The image test only checks the returned value, so it would pass no matter what's sent. It should assert the asset-creation request body (fileName, fileHash), the S3 upload, and the image value written into fieldData (for example, { url, alt }). That's what would have caught the upload-format and field-format issues. An abort-during-upload test would also cover the missing signal.