
=== Keytomic ===
Contributors: salam09
Tags: content publishing, rest api, seo, content automation, editorial workflow
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 8.1
Stable tag: 0.1.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Keytomic companion plugin that receives blog drafts via API and saves them as WordPress posts (draft or published).

== Description ==

Keytomic is a lightweight companion plugin for the Keytomic platform. It allows Keytomic to send blog drafts to your WordPress site using a secure REST API endpoint.

The plugin does not generate content inside WordPress. It receives a request from Keytomic and creates or updates a post on your site based on the payload you provide.

= Key features =

1. Secure authentication using an API key (stored as a hash).
2. REST endpoint for creating or updating posts (slug-based upsert):
   - POST /wp-json/keytomic/v1/drafts
3. Supports multiple modes:
   - ping (connection test)
   - draft (creates or updates a draft post by slug)
   - publish (creates or updates a published post by slug)
4. Converts Keytomic payloads into WordPress post content:
   - contentHtml, contentMarkdown, or sections (heading/body)
5. Optional featured image sideloading from a provided URL (skips re-sideloading when the same URL is sent again for the same post).
6. Stores an SEO meta description and outputs it as a meta description tag on single posts.

= Authentication =

Requests must include the Authorization header:

Authorization: Keytomic YOUR_API_KEY

(As a fallback, apiKey may also be provided in the JSON payload.)

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/` or install via the WordPress admin.
2. Activate the plugin from the “Plugins” page.
3. Go to **Settings → Keytomic**.
4. Paste your Keytomic API key and save.
5. In Keytomic, connect your WordPress site using your site URL and the endpoint shown above.

== External services ==

This plugin is designed to be used with the Keytomic platform and requires an API key generated in your Keytomic account.

This plugin does not send your site’s content to Keytomic on its own. It only processes inbound requests made to your site’s endpoint.

Data handled:
- API key (entered by the site admin and stored as a hash in WordPress options)
- Post data received from Keytomic (title, slug, summary/excerpt, content, optional hero image URL and alt text, optional SEO description)

When data is processed:
- When Keytomic sends a request to your site’s REST endpoint
- When the plugin downloads a featured image from a URL provided in the request (if used)

External service links:
- Keytomic: https://keytomic.com
- Privacy Policy: https://keytomic.com/privacy
- Terms of Service: https://keytomic.com/terms

== Frequently Asked Questions ==

= Where is the endpoint? =
POST /wp-json/keytomic/v1/drafts

= How do I test the connection? =
Send a request with mode set to ping and your Authorization header. A successful response returns “Connection successful”.

= Does it publish automatically? =
It supports both draft and publish modes. Keytomic controls the mode per request.

= Does it create duplicates if I send the same draft again? =
No, the plugin updates the existing post when the incoming slug matches an existing WordPress post. If the slug changes, it creates a new post.

= Is the API key stored in plain text? =
No. The API key is stored as a hash and verified server-side.

= What payload formats are supported? =
The plugin accepts contentHtml, contentMarkdown, or sections (heading/body). It can also accept a heroImage URL to set a featured image.

== Screenshots ==

1. Keytomic settings screen
2. Example request result (connection successful)
3. Draft post created by Keytomic

== Changelog ==

= 0.1.3 =
* Add slug-based upsert for draft/publish requests (same slug updates the same post).
* Promote draft-to-publish on the same post when slug matches.
* Skip duplicate hero image sideloading when the source URL is unchanged.
* Add response metadata for create/update operations.

= 0.1.2 =
* Internal improvements and compatibility updates.

= 0.1.0 =
* Initial release.
* Settings screen for API key.
* REST endpoint for ping, draft, and publish modes.
* Optional featured image sideloading.
* Meta description support.

== Upgrade Notice ==

= 0.1.3 =
Adds slug-based upsert behavior for incoming Keytomic draft/publish requests and avoids duplicate featured image sideloads on retries.
