Hedomi Tarot

1. Overview

Hedomi Tarot is an independent WordPress plugin for creating tarot decks, registering cards and meanings, designing interactive spreads, generating traditional or AI-personalized interpretations, and selling access to individual spreads through WooCommerce reading credits.

1.1 Included features

• Optional visitor question.
• Optional reversed cards with configurable probability.
• Card-style or tab-style results.
• Configurable card-back image, card width, colors, instructions, and button labels.
• AI response language, tone, length, practical guidance, synthesis, and additional instructions.
• AI consent notice, privacy text, disclaimer, diagnostics, and hourly visitor limit.
• Free or paid access configured separately for each spread.
• Multiple reading credits per purchased product quantity.
• Automatic customer return to the tarot page after checkout.
• Administrator payment bypass for previews and configuration tests.
• AJAX nonce validation and server-side verification that selected cards belong to the configured deck.

1.2 Not yet included

• Ready-made commercial deck artwork or copyrighted card texts.
• CSV or JSON deck import and export.
• Shared credit wallets across different spreads.
• Recurring subscription products and automatic monthly credit renewal.
• Customer reading history.
• PDF generation and email delivery.
• Built-in presets such as Celtic Cross or Horseshoe.
• Frontend credit purchase quantity selector inside the spread panel.

2. Requirements and installation

2.1 Requirements

2.2 Installation

1. In WordPress, open Plugins → Add New Plugin → Upload Plugin.
2. Select the Hedomi Tarot 0.3.0 ZIP file.
3. Click Install Now, then Activate.
4. Open Hedomi Tarot → Decks and create a deck.
5. Create cards and assign them to the deck.
6. Create a spread and insert its shortcode on a WordPress page.
7. Configure AI and WooCommerce only after the traditional reading works correctly.

2.3 Updating

• Back up the database and plugin files before replacing a version.
• Use WordPress's replace-current-version option when uploading the new ZIP.
• Do not delete decks, cards, or spreads before updating; they are stored in the WordPress database.
• After updating, clear page cache, object cache, and browser cache.
• Retest one free spread, one AI spread, and one paid customer checkout.

3. Quick start

1. Create one deck.
2. Create at least three published cards and assign all of them to that deck.
3. Add a Featured Image, upright meaning, and reversed meaning to each card.
4. Create a spread with three positions.
5. Select the deck and choose manual, automatic, or both selection modes.
6. Publish the spread.
7. Copy the generated shortcode, for example [hedomi_tarot id="123"].
8. Paste the shortcode into a page and test the traditional reading.
9. Configure OpenAI under Hedomi Tarot → AI Settings, if required.
10. Create and connect a WooCommerce product if the spread will be paid.

4. Decks and cards

4.1 Creating a deck

1. Open Hedomi Tarot → Decks.
2. Enter a deck name and optional description.
3. Save the deck.

Decks are stored as the hedomi_tarot_deck taxonomy. A spread uses one selected deck, and the server verifies that every selected card belongs to it.

4.2 Creating cards

1. Open Hedomi Tarot → Cards → Add New.
2. Use the post title as the card name.
3. Set the card artwork as the Featured Image.
4. Assign the card to a deck.
5. Write the upright meaning.
6. Write the reversed meaning.
7. Add optional keywords.
8. Select Yes, No, or Maybe when this metadata is useful.
9. Publish the card.

If a reversed meaning is empty, the plugin falls back to the upright meaning when the card is selected in reversed orientation.

4.3 Image guidelines

• Use one consistent aspect ratio across the complete deck.
• Keep card artwork large enough for high-density screens, but compress it for web delivery.
• Use WebP or optimized JPEG where transparency is not required.
• Add meaningful Media Library alternative text.
• Use only artwork that you own or are licensed to distribute.
• The separate card-back image is configured in the spread settings.

5. Creating spreads

A spread controls the deck, the number and location of cards, selection behavior, result format, appearance, AI use, and payment access.

5.1 Spread settings

5.2 Positions

Add one row for each card required by the reading.

5.3 Visual editor

The visual layout preview allows the administrator to drag the position cards. The plugin updates the X and Y percentages automatically. Use the table fields for precise adjustments and rotation.

Example: three-card spread

6. AI personalized readings

AI personalization is optional. Traditional card meanings remain part of the plugin and can be used without an API key.

6.1 Saving the API key

1. Create an API key in the OpenAI API platform.
2. Open Hedomi Tarot → AI Settings.
3. Paste the key into OpenAI API key.
4. Click Save API key.
5. Confirm that the page reports a saved key and its storage source.
6. Click Save and run real API test.

The key is stored separately in the non-autoloaded WordPress option:

For stronger separation from the database, define a non-empty constant in wp-config.php:

A non-empty constant overrides the database key. An empty constant does not prevent the plugin from using the saved database value.

6.2 AI settings

6.3 Reading behavior

The plugin sends one request for the complete spread. The request includes:

• visitor question;
• spread title;
• card names;
• upright or reversed orientation;
• position names and contexts;
• keywords and Yes/No/Maybe metadata;
• the traditional meanings written by the site administrator.

The AI is instructed to treat the administrator's card meanings as authoritative, relate every card to the exact question and position, avoid guaranteed predictions, and return structured content for each position plus an optional overall synthesis.

6.4 Diagnostics

The real connection test makes a small generation request. It verifies the key, model, billing/quota, Responses API access, and outbound connection from the WordPress host.

The diagnostic panel stores sanitized information such as time, context, HTTP status, OpenAI error code, and request ID. It does not display the secret key.

7. WooCommerce payments and reading credits

Version 0.3.0 supports the model one WooCommerce product purchase grants one or more credits for one spread. Every completed reading uses one credit.

7.1 Creating the WooCommerce product

1. Install and activate WooCommerce.
2. Open Products → Add New.
3. Create a Simple product.
4. Enable Virtual.
5. Set the price.
6. Publish the product.

A simple, virtual, in-stock product can be added directly to checkout from the spread purchase button. Other product types send the visitor to the product page.

7.2 Connecting a spread to the product

1. Edit the tarot spread.
2. Find Payment and reading credits.
3. Set Access type to Paid with WooCommerce credit.
4. Select the WooCommerce product.
5. Set Credits per purchased quantity.
6. Edit the purchase button and locked message when needed.
7. Update the spread.

Example:

7.3 Customer flow

The order return URL is restricted to the same website host. After checkout, the plugin appends hedomi_tarot_purchase=success to the tarot page URL.

7.4 Reading-credit rules

• Credits belong to a specific customer and a specific spread.
• Credits are granted only once per WooCommerce order.
• Product quantity multiplies the configured credits per purchase.
• One successful reading consumes one credit.
• A temporary two-minute user/spread lock prevents simultaneous requests from consuming the same balance.
• Administrators with manage_options bypass payment and do not consume credits.
• If AI was attempted and failed, the plugin releases the lock and keeps the credit.
• If AI is not required or succeeds, the generated reading consumes the credit.
• Order notes record every credit grant and the resulting balance.

Credit storage

The balance is stored in WordPress user metadata:

For example, the balance for spread ID 123 is stored under _hedomi_tarot_credits_123.

7.5 Testing payments

1. Do not test the paid customer flow while logged in as an administrator; administrators bypass payment.
2. Use a non-administrator test account or a private browser window.
3. Enable a WooCommerce test payment method or gateway sandbox.
4. Buy the linked product.
5. Confirm the customer returns to the tarot page.
6. Open the WooCommerce order and verify the Hedomi Tarot credit note.
7. Generate one reading and confirm that the visible balance decreases by one.
8. Attempt a second reading when no credit remains and confirm the purchase panel returns.

Manual credit inspection

Developers can inspect the user metadata in the database or with WP-CLI. Direct database changes should be made only with a backup and an understanding of the spread-specific metadata key.

8. Publishing and frontend experience

8.1 Shortcode

Replace 123 with the published spread ID. The shortcode can be used in the block editor, classic editor, shortcode widgets, Elementor shortcode widgets, and most page builders that execute WordPress shortcodes.

8.2 Card selection

• Manual: the visitor selects the required number of unique cards.
• Automatic: the server shuffles the valid deck card IDs and selects the required amount.
• Both: the interface provides the supported manual and automatic paths.

The server rejects duplicate selections, the wrong number of cards, unpublished spreads, cards from another deck, and decks that contain fewer cards than the spread requires.

8.3 Results

Every reading can include:

• spread title and visitor question;
• card image, name, orientation, position, and position context;
• traditional meaning and keywords;
• AI-personalized interpretation and practical guidance;
• overall synthesis, closing reflection, and disclaimer;
• AI availability notice;
• payment notice and remaining credits;
• purchase button when another credit is required.

9. Customization

Most common visual options are configured separately for each spread:

• card-back image;
• card width;
• accent and background colors;
• instructions;
• reveal and shuffle button labels;
• purchase button label and locked message;
• position names, descriptions, coordinates, and rotation;
• result layout.

9.1 CSS customization

Add custom CSS in a child theme or a dedicated CSS plugin rather than editing Hedomi Tarot files directly. Inspect the frontend output to target the hedomi-tarot class namespace.

9.2 Translation

The plugin uses the hedomi-tarot text domain. Interface strings can be translated with WordPress translation tools. Text fields saved in the spread and AI settings are controlled directly by the site administrator.

10. Security, privacy, and copyright

10.1 Security measures in this build

• Reading AJAX uses a WordPress nonce.
• Spread IDs, card IDs, product IDs, and numeric settings are sanitized.
• Selected cards are validated against the configured deck.
• Paid AJAX requests verify login and available credit on the server.
• Credit granting is marked on the order to prevent duplicate grants.
• A temporary user/spread lock reduces simultaneous-credit consumption.
• Return URLs are limited to the same website host.
• The API key is not sent to the frontend.

10.2 Personal data

Depending on the enabled features, the website can process:

• visitor questions;
• selected cards and generated interpretations;
• anonymous visitor identifiers used for hourly limits;
• WordPress account information;
• WooCommerce order and billing data;
• spread-specific user credit balances.

When AI is enabled, the question and reading context are sent to OpenAI. Update the site's privacy notice and collect consent where required.

10.3 Copyright

Do not distribute copyrighted deck artwork or interpretations without permission. The fact that a deck is widely available online does not automatically make it public domain.

11. Troubleshooting

11.1 Support checklist

• WordPress, PHP, WooCommerce, and Hedomi Tarot versions.
• Spread ID and linked product ID.
• Whether the tester is administrator or customer.
• Order number and order status.
• Order notes related to Hedomi Tarot.
• Visible customer credit balance.
• Last API diagnostic status and code.
• Browser console errors and WordPress debug-log entries.

12. Technical reference

12.1 Plugin structure

12.2 Data storage

Main card metadata

Main payment metadata on a spread

12.3 Hooks

Access-control example

13. Suggested roadmap

14. Release notes

Version 0.3.0

• Free or paid access for each spread.
• WooCommerce product connection.
• Credits per purchased product quantity.
• Required checkout account registration for tarot products.
• Idempotent credit grant on payment complete, Processing, or Completed status.
• Spread-specific customer credit balances.
• One-credit consumption after a successful reading.
• Temporary credit lock against simultaneous requests.
• Credit retention when required AI personalization fails.
• Return to the tarot page after checkout.
• Administrator preview bypass.

Version 0.2.3

• Dedicated OpenAI API key storage.
• Migration from previous settings-array storage.
• Real API generation test and sanitized diagnostics.
• AI personalization per card, practical guidance, synthesis, privacy consent, fallback, and hourly limit.

Version 0.1.0

• Decks, cards, spreads, visual position builder, manual and automatic selection, reversed cards, result layouts, shortcode, and secure reading AJAX.