=== CloseHub Connector ===
Contributors: closetechnology, davidperez
Tags: api, integration, closehub, woocommerce, gravity-forms
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.2.0
Version: 1.2.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect your WordPress site to CloseHub with a single API key in order to send statistics.

== Description ==

CloseHub Connector replaces the multiple credentials previously required to link a WordPress site with [CloseHub](https://close.marketing/closehub/) — a marketing project management platform.

Once the plugin is activated, it generates a secure API key and exposes a dedicated REST API namespace (`/wp-json/closehub/v1/`) that CloseHub uses to interact with your site.

It also exposes content abilities through the WordPress MCP Adapter. MCP clients can discover, list, read, create, update, upload an image, update a post slug, replace one exact Gutenberg block, and send posts to the trash using the server at `/wp-json/mcp/mcp-adapter-default-server`. `closehub/upload-media` accepts an image as `data_base64`, returns its Media Library URL, and requires the user's `upload_files` capability; pass that URL as `featured_image_url` to create or update content without uploading a duplicate. `closehub/update-post-slug` accepts a post ID and slug, then returns the normalized unique slug and resulting URL. `closehub/get-post` returns a `content_hash`; use it with `closehub/replace-gutenberg-block`, a zero-based `block_path`, the current block name, and one replacement serialized block so a stale read cannot overwrite newer content. These abilities default to the `post` type but accept a `post_type` input for any other post type registered with an admin UI — pages, WooCommerce products (including product types WooCommerce's own MCP abilities don't support, such as subscriptions), or custom post types. Authenticate with a WordPress user account that has the required post capabilities; the CloseHub API key is not used for MCP authentication.

When WPML is active, create-post and `POST /closehub/v1/posts` also accept `language` and an optional `translation_of` source post ID. The connector assigns the new post to the requested language and joins it to the source post's translation group. List/get/create responses include the language and translation-group details. Existing posts retain their language on update.

For WooCommerce, MCP clients with the `manage_woocommerce` capability can retrieve an order summary for a date range, including order count, total sales, average order value, and matching orders.

It also exposes a set of "site" abilities for the CLOSE web go-live checklist — configuration steps that used to be manual or wp-cli only. Each requires the WordPress capability noted below.

**Available MCP site abilities:**

* `closehub/search-replace-domain` (`manage_options`) — Replace `old_domain` with `new_domain` across post content, options, comments, and meta tables, re-serializing serialized values safely. Skips `wp_posts.guid`. Pass `dry_run: true` to preview the number of rows that would change per table without writing anything. Example: `{ "old_domain": "staging.example.com", "new_domain": "example.com" }`.
* `closehub/set-robots-txt` (`manage_options`) — Write `content` to `robots.txt`, physically if the site root is writable, otherwise served virtually through the `robots_txt` filter. Example: `{ "content": "User-agent: *\nDisallow:\nSitemap: https://example.com/sitemap.xml" }`.
* `closehub/set-post-noindex` (`edit_post` on the target `post_id`) — Set or clear the noindex robots meta for one post/page using whichever SEO plugin (Rank Math or Yoast) is active. Example: `{ "post_id": 42, "noindex": true }`.
* `closehub/flush-permalinks` (`manage_options`) — Regenerate rewrite rules, equivalent to `wp rewrite flush`. Takes no parameters.
* `closehub/get-htaccess` (`manage_options`, read-only) — Return whether `.htaccess` exists and its current content. Takes no parameters.
* `closehub/set-site-settings` (`manage_options`) — Update the site timezone and/or admin email; at least one is required. Example: `{ "timezone": "Europe/Madrid", "admin_email": "client@example.com" }`.
* `closehub/reassign-posts-author` (`edit_others_posts`) — Reassign every post of `post_type` (default `post`) from `from_author_id` to `to_author_id`, with a per-post success result. Example: `{ "from_author_id": 3, "to_author_id": 1 }`.
* `closehub/install-wp-org-plugin` (`install_plugins`) — Install (without activating) a plugin from the WordPress.org plugin directory by `slug`. Example: `{ "slug": "two-factor" }`.
* `closehub/list-unused-plugins` (`activate_plugins`, read-only) — List installed plugins that are not currently active, as removal candidates. Takes no parameters.
* `closehub/update-plugins-and-core` (`update_plugins` and `update_core`) — Update every plugin with an available update and WordPress core to the latest version, with a per-plugin success result. Takes no parameters.
* `closehub/create-site-user` (`create_users`, plus `promote_users` when `role` is `administrator`) — Create a WordPress user for the site's client. `role` defaults to `editor`; `username` defaults to the local part of `email` when omitted. Example: `{ "email": "client@example.com", "role": "editor" }`.
* `closehub/clear-cache` (`rocket_purge_cache` or `manage_options`) — Purge the page cache of the active caching plugin (currently WP Rocket). `scope` is `all` (default, whole site) or `posts` (only the given `post_ids`; IDs that don't match a post are reported back in `invalid_post_ids`). Pass `minify: true` to also clear minified CSS/JS files. Returns `503` when no supported cache plugin is active. On multisite it purges only the site the MCP request is made against; on a subdirectory network, purging the main site with WP Rocket also clears the subsites' cached pages, since they live inside the main site's cache folder. Example: `{ "scope": "posts", "post_ids": [ 42, 57 ] }`.

**What it replaces:**

* WordPress Application Password (username + password)
* WooCommerce REST API consumer key and consumer secret
* Gravity Forms API key

**You only need to share two things with CloseHub:**

1. Your site URL
2. The generated API key (found at Settings → CloseHub)

**Available endpoints:**

* `GET /closehub/v1/ping` — verify the connection
* `POST /closehub/v1/posts` — publish or draft a post (or another post type via `post_type`), including optional SEO metadata (Rank Math or Yoast), featured image, categories, and WPML `language`/`translation_of` when WPML is active
* `PUT /closehub/v1/posts/{id}` — update a post's (or other post type's) title, content, excerpt, status, SEO metadata, featured image, or categories
* `GET /closehub/v1/woocommerce/orders` — fetch order data (requires WooCommerce)
* `GET /closehub/v1/gravity-forms/forms` — list forms (requires Gravity Forms)
* `GET /closehub/v1/gravity-forms/forms/{id}` — get form details
* `GET /closehub/v1/gravity-forms/forms/{id}/entries` — count form entries by date range
* `POST /closehub/v1/elm-releases` — create an Easy License Manager release for a product (by `product_id` or `product_sku`) and update its WooCommerce download file to the given `zip_url` in one call; optional `tested`, `requires`, `requires_php`, `upgrade_notice`
* `PUT /closehub/v1/elm-releases/{id}` — update fields on an existing release (all optional) and, if `zip_url` is given, its product's download file

WooCommerce, Gravity Forms, and Easy License Manager endpoints return a clear error if those plugins are not active — they are not required.

**Multisite networks:**

On a WordPress Multisite network, the same endpoints listed above are shared by every site in the network — there is no separate namespace or key to manage. Activate the plugin network-wide and go to **Network Admin → Settings → CloseHub** to find one API key shared by the whole network. Every request to those endpoints automatically returns a `sites` array with one entry per site in the network (`site_id`, `url`, and that site's data or an `error` message), instead of a single site's result — handy when a network is used to run the same company in multiple languages.

== Installation ==

1. Upload the `closehub-connector` folder to `/wp-content/plugins/`.
2. Activate the plugin through the **Plugins** screen in WordPress admin.
3. Go to **Settings → CloseHub**.
4. Copy the **Site URL** and **API Key** shown on that page.
5. Paste both values into CloseHub under your project's WordPress connection settings.

== Frequently Asked Questions ==

= Where do I find my API key? =

Go to **Settings → CloseHub** in your WordPress admin. The key is displayed there along with a copy button.

= Can I regenerate the API key? =

Yes. Click **Regenerate Key** on the Settings → CloseHub page. The old key stops working immediately — update CloseHub with the new key right away.

= Do I need WooCommerce or Gravity Forms installed? =

No. Both are optional. If they are not active, those endpoints return a `503` response with a clear message instead of crashing.

= How is the API key secured? =

The key is stored in `wp_options` (or network-wide in `wp_sitemeta` on multisite), never exposed on the frontend, transmitted only via HTTPS, and verified using constant-time comparison (`hash_equals`) to prevent timing attacks. It is never logged or included in REST responses.

= Can I use this plugin on a multisite network? =

Yes. When network-activated, the plugin generates one API key shared by every site in the network (managed from **Network Admin → Settings → CloseHub** instead of a per-site Settings page), and the same REST endpoints automatically query every site and return combined, per-site results. On a regular, non-multisite install, everything works exactly as a single site as described above.

= Is this plugin affiliated with WooCommerce or Gravity Forms? =

No. It integrates with those plugins using their public PHP APIs but is not developed, endorsed, or supported by WooCommerce or Gravity Forms.

== Screenshots ==

1. Settings page showing the Site URL, API key, and available endpoints.
2. Regenerate Key button with confirmation notice.

== Changelog ==

= 1.2.0 =
* Added WordPress Multilingual Plugin (WPML) support to MCP and REST content creation, including optional language assignment and translation-group linking. (#30)
* Added MCP image uploads from base64 to the Media Library, with validation, quota checks, attachment metadata safeguards, and reuse as a post's featured image. (#40)
* Added a branded OAuth consent screen that clearly discloses the public CloseHub MCP abilities being authorized. (#41)
* Added the `closehub/clear-cache` MCP ability for supported caching plugins, starting with WP Rocket. (#35)
* Fixed CloseHub content and site abilities not being exposed as direct tools by the default MCP server.
* Fixed Claude and other hosted MCP clients that identify themselves with a Client ID Metadata Document: OAuth authorization now validates that document directly when no prior dynamic registration exists, and advertises that capability in the authorization-server metadata. Re-registering the same verified client is idempotent and refreshes its stored metadata instead of failing on a duplicate client ID. (#34)
* Added `POST /closehub/v1/elm-releases` to create an Easy License Manager release and update the product's WooCommerce download file in one call, unblocking automated premium-plugin releases. Accepts optional `tested`, `requires`, `requires_php`, and `upgrade_notice`. Preserves any other downloadable files already on the product instead of replacing them. Returns `503` if Easy License Manager is not active. (#19)
* Added `PUT /closehub/v1/elm-releases/{id}` to update fields on an existing release (and its product's download file) without creating a duplicate release for the same version.
* Fixed a crash on PHP 8+ when a route's numeric `id`/`product_id` argument was validated: `is_numeric` was registered directly as `validate_callback`, but WordPress calls it with 3 arguments and the internal function only accepts 1. Affected `/posts/{id}`, `/gravity-forms/forms/{id}`, and both new `elm-releases` routes.

= Unreleased =

= 1.1.2 =
* Fixed MCP OAuth discovery on Apache-managed sites, including reliable handling of the protected-resource and authorization-server metadata routes after activation, URL changes, or regeneration. (#27)
* Added precise Gutenberg block replacement through MCP, with content-hash concurrency protection and block-path/type validation, plus an MCP ability to update a post slug and return its normalized URL. (#29)

= 1.1.1 =
* Added 11 MCP "site" abilities covering the CLOSE web go-live checklist: domain search-replace, robots.txt content, per-page noindex, permalink flush, `.htaccess` read, timezone/admin email, bulk post-author reassignment, WordPress.org plugin install, unused-plugin listing, plugin/core updates, and client user creation. See the Description section for the full list and required capabilities.
* Added `post_type` support to all `closehub/*-post` MCP abilities (list-posts, get-post, create-post, update-post, trash-post) and to the `/closehub/v1/posts` REST endpoints. They still default to `post`, but can now read and write pages and WooCommerce products (including product types WooCommerce's own MCP abilities don't support, such as subscriptions) instead of only plain blog posts. Allowed post types are limited to ones registered as public and admin-manageable, so internal WooCommerce records such as orders and coupons, and Media Library attachments, are not exposed as generic content.
* Fixed: creating a post now checks that post type's own `create_posts` capability, and publishing through `create-post`/`update-post` checks its `publish_*` capability (e.g. `publish_products`), instead of always assuming `post`'s `edit_posts`/`publish_posts`.
* Fixed: MCP post creation and updates now recheck those capabilities independently on every site in a multisite network before writing, so a denied site reports a per-site error without changing its content.
* Fixed: setting `categories` on a post type that doesn't support that taxonomy is now rejected before any other change is saved, instead of possibly after the title, content, or other fields were already updated.

= 1.1.0 =
* Added an MCP server (OAuth 2.1 + PKCE) so AI clients such as Claude can list, read, create, update, and trash posts and read WooCommerce order summaries with the permissions of a real WordPress user.
* Added a `PUT /closehub/v1/posts/{id}` endpoint to update a post's title, content, excerpt, status, SEO metadata, featured image, or categories.
* Fixed: MCP post creation/update no longer lets a user without the `manage_categories` capability create new categories by naming one that doesn't exist yet.
* Fixed: MCP get-post/list-posts now include the same featured image and SEO metadata create-post and update-post accept.
* Fixed: a dynamic OAuth client registration using a real client_id metadata URL could no longer have its verified name and redirect URI overridden by the request body — closing an impersonation path where a code could be redirected to an attacker-controlled URI while the consent screen showed a trusted name.
* Fixed: the OAuth consent page now sends `X-Frame-Options`/CSP headers to prevent it from being framed (clickjacking the Authorize button).
* Fixed: an MCP access token could previously authenticate as its user for any WordPress REST route whose query string happened to contain the MCP endpoint path, not just the MCP endpoint itself.
* Fixed: OAuth token responses now send `Cache-Control: no-store`; the dynamic client registration endpoint is now rate-limited per IP.

= 1.0.5 =
* Fixed: featured images from URLs without a filename extension, including Google Drive download URLs, can now be attached when CloseHub creates a WordPress draft.

= 1.0.4 =
* Added support for optional SEO titles, meta descriptions, focus keywords, categories, and featured images when creating posts from CloseHub.
* Added support for saving SEO metadata in Rank Math and Yoast SEO when either plugin is active.
* Improved post creation reliability by completing metadata before publishing and removing incomplete posts when metadata processing fails.

= 1.0.3 =
* Fixed: sites that already had an API key configured on a subsite before multisite support was added (<=1.0.1) now keep working after upgrading — the existing key is migrated to the network-wide setting instead of a new one being generated, which previously caused CloseHub requests to fail with 401.

= 1.0.2 =
* Added WordPress Multisite network support: one API key shared across the whole network, managed from Network Admin → Settings → CloseHub.
* On multisite, existing endpoints (ping, posts, woocommerce/orders, gravity-forms/*) now return combined results for every site in the network instead of a single site.

= 1.0.1 =
* Updated assets.

= 1.0.0 =
* Initial release.
* Single API key replaces WordPress Application Password, WooCommerce REST credentials, and Gravity Forms API key.
* Endpoints: ping, posts, woocommerce/orders, gravity-forms/forms.
* Admin settings page at Settings → CloseHub with copy buttons and regenerate key action.

== Upgrade Notice ==

= 1.0.0 =
Initial release — no upgrade steps required.
