================================================================================
BD BOOKSHELF PLUGIN SPECIFICATION
================================================================================

Version: 2.2.0
Location: /wp-content/plugins/bd-bookshelf/

================================================================================
1. OVERVIEW
================================================================================

This plugin serves as a helper for BD Bookshelf. it is a plugin with the same name to show they go together. Make your website the destination to find the best place to buy your book. Enter your ISBN and the system will search book seller websites for your book.

The plugin will let the user enter a book by Title and ISBNs. There can be four ISBNs for each book, coorisponding to the form factor: eBook, Paperback, Hard Cover, audio. The system will allow entry and track this information.

With the ISBN the system will use known patters to get direct links to popular book selling sites. The user can see the links and edit them.
The sites are Amazon, Barnes and Noble, Apple, Google, Kobo. 
The plugin will allow the user to create a new link, entering the name and the link manually. The icon for these links will be a general page of a book and quill.

The user can enter affiliate codes related to each of the sites and the system will automatically incorporate them into links to that site.

The system will use the ISBN/ASIN information to get ratings for the book. It will get the information from Amazon and Goodreads (author information - author ID in theme). The system will scan and do updates every 12 hours with a cron job. The ratings will be shown when the book is displayed with a [rating] short tag - specific to that book.

The plugin will create a grid of selling site icons and links when a short code is used on a page. The short codes are specific to format and ISBN. codes: [sell_ebook], [sell_pb], [sell_hc], [sell_audio]

The plugin will provide the popup and checks for GDPR compliance

The plugin will allow creating and editing SEO metadata for book pages.

The plugin will allow creation and management of short codes. A code defined by website/shrtcode that can be redirected, expanded to another site. 






GDPR compliance - get approval for cookies.
7) SEO metadata
8) short codes

2) User enters book
	Title and ISBN - a book can have eBook, Paperback, Hardcover, Audio.
2.1) site identifier ASIN/ISBN
3) System confirms top sites name and link pattern - show site general link  search on sites - Need ISBN/ASIN/ident
3.1 list of sites with pattern to search.
Amazon
B&N
Apple
Google
Kobo
4) Adding affiliate codes for sites
5)get ratings from site (Amazon/goodreads) - limit updates to every x hours


6) Generate sell buttons/links from a shortcode - links with affiliate codes on page.
	codes: [sell_ebook], [sell_pb], [sell_hc], [sell_audio] When the code is entered the system will generate a grid of the site options to purchase the book.
6.2)





PlatformPrimary IdentifierBest URL Structure for Programmatic Linking
Bookshop.org	ISBN-13				https://bookshop.org/books/{ISBN13}	
Barnes & Noble (Print)EAN / ISBN-13	https://www.barnesandnoble.com/s/{ISBN13}

shortcodes?

"Theme Transition Helper" - it provides a bridge
between WordPress and the BD BookShelf theme by managing book data, generating
the Amazon-style book display layout, and providing shortcodes for theme use.

Purpose:
- Manage book data (titles, blurbs, covers, ratings) in custom database tables
- Generate HTML output with specific CSS classes (.bd-book-*) for theme styling
- Provide REST API endpoints for book data
- Handle multi-language support with localized content per language
- Manage retailer links and affiliate tracking

================================================================================
2. FILE STRUCTURE
================================================================================

bd-bookshelfhelper.php          Main plugin file - initialization, constants
inc/class-bookhelper.php       Core plugin class - CPTs, taxonomies, shortcodes
inc/class-admin.php            Admin functionality - data entry interface
inc/class-install.php          Database installation, table creation
assets/css/admin.css           Admin interface styling
assets/js/admin.js             Enhanced data entry with auto-save/validation
uninstall.php                  Cleanup on plugin deletion

================================================================================
3. CUSTOM POST TYPES
================================================================================

 CPT: "book"
 ---------------------------------------------------------------------------
 Public: Yes
 Has Archive: Yes (/book)
 Show in Menu: No
 Supports: title, editor, thumbnail, excerpt, custom-fields
 REST API: Yes (show_in_rest = true)
 Menu Icon: dashicons-book-alt

 Capabilities: Uses native post capability type (edit_posts, etc.)

 CPT: "bd_shortlink"
 ---------------------------------------------------------------------------
 Purpose: Internal short link management
 Public: No
 Show UI: No

================================================================================
4. CUSTOM TAXONOMIES
================================================================================

 Taxonomy: "series" (Hierarchical)
 ---------------------------------------------------------------------------
 Object Type: book
 Public: Yes
 Show Admin Column: Yes
 REST API: Yes
 Rewrite: /series

================================================================================
5. DATABASE TABLES
================================================================================

TABLE: {prefix}bd_books
---------------------------------------------------------------------------
id               BIGINT(20) AUTO_INCREMENT PRIMARY KEY
post_id          BIGINT(20) NOT NULL UNIQUE
pen_name_id      BIGINT(20)
series_id        BIGINT(20)
volume_number    INT(11)
asin             VARCHAR(20)
isbn             VARCHAR(20)
publish_date     DATE
sort_order       INT(11) DEFAULT 0
created_at       DATETIME

TABLE: {prefix}bd_book_meta
---------------------------------------------------------------------------
id               BIGINT(20) AUTO_INCREMENT PRIMARY KEY
book_id          BIGINT(20) NOT NULL
language_code    VARCHAR(5) NOT NULL
title            VARCHAR(255)
blurb            TEXT
preview_excerpt  TEXT
pull_quotes      JSON
UNIQUE KEY (book_id, language_code)

TABLE: {prefix}bd_pen_names
---------------------------------------------------------------------------
id               BIGINT(20) AUTO_INCREMENT PRIMARY KEY
pen_name         VARCHAR(255) NOT NULL
notes            TEXT
active           TINYINT(1) DEFAULT 1
created_at       DATETIME

TABLE: {prefix}bd_reviews
---------------------------------------------------------------------------
id               BIGINT(20) AUTO_INCREMENT PRIMARY KEY
book_id          BIGINT(20) NOT NULL
comment_text     TEXT
synopsis         TEXT
source_name      VARCHAR(255) NOT NULL
source_url       VARCHAR(500)
display_order   INT(11) DEFAULT 0

TABLE: {prefix}bd_ratings
---------------------------------------------------------------------------
id               BIGINT(20) AUTO_INCREMENT PRIMARY KEY
book_id          BIGINT(20) NOT NULL
source           VARCHAR(20) NOT NULL
rating           DECIMAL(3,2)
review_count     INT(11)
last_updated     DATETIME
UNIQUE KEY (book_id, source)

TABLE: {prefix}bd_series
---------------------------------------------------------------------------
id               BIGINT(20) AUTO_INCREMENT PRIMARY KEY
name             VARCHAR(255) NOT NULL
slug             VARCHAR(100) NOT NULL UNIQUE
cover_attachment_id  BIGINT(20)
header_attachment_id BIGINT(20)
blurb            TEXT
display_order   INT(11) DEFAULT 0
created_at       DATETIME

TABLE: {prefix}bd_review_shortlinks
---------------------------------------------------------------------------
id               BIGINT(20) AUTO_INCREMENT PRIMARY KEY
book_id          BIGINT(20) NOT NULL
site_code        VARCHAR(5) NOT NULL
slug             VARCHAR(20) NOT NULL UNIQUE
destination_url  VARCHAR(500)
status           VARCHAR(20) DEFAULT 'pending'
created_at       DATETIME
activated_at     DATETIME

================================================================================
6. POST META FIELDS FOR BOOKS
================================================================================

Identification:
  pen_name_id         int     FK to bd_pen_names table
  asin                string  Amazon Standard Identification Number (10 chars)
  isbn                string  ISBN-13 (13 digits)
  short_link_slug     string  Custom short URL slug (e.g., "ph")

Series & Order:
  volume_number       int     Book position in series
  publish_date        date    Publication date (YYYY-MM-DD)
  sort_order          int     Manual sort position

Ratings:
  amazon_rating       string  Amazon rating (e.g., "4.5")
  goodreads_rating    string  Goodreads rating (e.g., "4.2")

Localized Content (by language code: en, fr, de, es, it, pt, ru, ja, zh):
  title_{lang}         string  Book title in language
  blurb_{lang}        string  Back cover blurb
  preview_excerpt_{lang}  string  Preview text excerpt
  pull_quote_{lang}_{n}    string  Pull quote n (1-5)
  genre_tags_{lang}    string  Genre tags (comma-separated)
  amazon_search_terms_{lang}  string  Amazon search keywords
  cover_{lang}         int     Cover image ID for language

Retailer Links (format + retailer):
  {format}_url_{retailer}
  
  Formats: ebook, paperback, hardback, audiobook
  Retailers: amazon, apple, barnes, kobo, google, bookshop, amazon_uk, waterstones, audible, scribner
  
  Examples:
    ebook_url_amazon       eBook Amazon link
    paperback_url_barnes   B&N paperback link
    hardback_url_amazon    Amazon hardback link

SEO:
  seo_title           string  Custom meta title
  seo_description     string  Meta description

Legacy/Migration:
  genre               string  Primary genre
  pages               string  Page count
  language            string  Book language (default: "English")
  publisher           string  Publisher name

================================================================================
7. SHORTCODES
================================================================================

SHORTCODE: [bd-book]
---------------------------------------------------------------------------
Displays a single book by ID or title.

Attributes:
  book (string, required) - Book ID (integer) or title

Usage:
  [bd-book book="123"]
  [bd-book book="Pandemic Hacker"]

Output: Returns render_book_display() HTML or error message with bd-book-error class.

SHORTCODE: [bd-books]
---------------------------------------------------------------------------
Displays all books in a list.

Attributes:
  limit       int     default: -1 (all) - Number of books to display
  orderby     string  default: "date" - Sort field (date, title, menu_order, etc.)
  order       string  default: "DESC" - Sort direction (ASC or DESC)

Usage:
  [bd-books limit="10" orderby="date" order="DESC"]

Output: Wraps all render_book_display() outputs in <div class="bd-books-list">

================================================================================
8. RENDER_BOOK_DISPLAY() OUTPUT STRUCTURE
================================================================================

This is the CORE HTML OUTPUT that the plugin generates. The theme MUST provide
CSS styling for these classes to achieve the Amazon Detail layout.

```html
<div class="bd-book-listing">
    <div class="bd-book-entry">
        
        <!-- LEFT COLUMN (25%) -->
        <div class="bd-book-cover">
            <a href="[book-url]">
                <img src="[cover-url]" alt="[book-title] Cover">
            </a>
            <div class="bd-book-purchase">
                <div class="bd-book-format-selector">
                    <button class="bd-book-format-btn active" data-format="ebook">eBook</button>
                    <button class="bd-book-format-btn" data-format="paperback">Paperback</button>
                    <button class="bd-book-format-btn" data-format="hardback">Hardback</button>
                </div>
                <div class="bd-book-retailers" data-book-id="[book-id]">
                    <!-- Retailer links injected here by display_retailer_links() -->
                </div>
            </div>
        </div>

        <!-- RIGHT COLUMN (75%) -->
        <div class="bd-book-details">
            <h2 class="bd-book-title">
                <a href="[book-url]">[book-title]</a>
            </h2>
            <p class="bd-book-byline">by [pen-name]</p>

            <div class="bd-book-ratings">
                <span class="rating-amazon">Amazon: [rating]/5</span>
                <span class="rating-goodreads">Goodreads: [rating]/5</span>
            </div>

            <hr class="bd-book-separator">

            <div class="bd-book-blurb">
                [blurb content with wpautop()]
            </div>

            <div class="bd-book-metadata">
                <span class="metadata-genre">[genre]</span> |
                <span class="metadata-pages">[pages] pages</span> |
                <span class="metadata-language">[language]</span> |
                <span class="metadata-publisher">[publisher]</span>
            </div>

            <div class="bd-book-categories">
                [category-list]
            </div>
        </div>
    </div>
</div>
```

================================================================================
9. DISPLAY_RETAILER_LINKS() METHOD
================================================================================

Method: public static function display_retailer_links($book_id, $format = 'ebook')

Output HTML:
```html
<a href="[url]" class="retailer-box retailer-[key]" target="_blank" rel="noopener noreferrer">[name]</a>
```

Supported Retailers:
  Key     Name            Base URL
  ----    -------------   ----------------------------------------------
  amazon  Amazon          https://www.amazon.com/dp/
  apple   Apple Books     https://books.apple.com/
  barnes  Barnes & Noble  https://www.barnesandnoble.com/
  kobo    Kobo            https://www.kobo.com/
  google  Google Play     https://play.google.com/store/apps/details?id=

Amazon Auto-URL Generation:
If asin meta is set but no URL, constructs: https://www.amazon.com/dp/{asin}?tag={affiliate}

================================================================================
10. CSS CLASSES GENERATED BY PLUGIN
================================================================================

The following classes are output by the plugin and MUST be styled by the theme:

FRONTEND BOOK DISPLAY:
  bd-book-listing         Outer wrapper container
  bd-book-entry           Flex container with cover + details
  bd-book-cover           Left column (25% width)
  bd-book-purchase        Purchase section below cover
  bd-book-format-selector Container for format toggle buttons
  bd-book-format-btn       Individual format button
  bd-book-format-btn.active  Active format state
  bd-book-retailers       Container for retailer-box links
  bd-book-details         Right column (75% width)
  bd-book-title           Title heading (h2)
  bd-book-title a         Title link
  bd-book-byline          "by [pen-name]" text
  bd-book-ratings         Ratings container
  rating-amazon          Amazon rating span
  rating-goodreads        Goodreads rating span
  bd-book-separator       HR element (divider)
  bd-book-blurb           Book description/synopsis
  bd-book-metadata        Genre, pages, language, publisher row
  metadata-genre          Genre span
  metadata-pages          Pages span
  metadata-language       Language span
  metadata-publisher      Publisher span
  bd-book-categories      Book categories
  bd-book-error           Error message paragraph

BOOKS LIST WRAPPER:
  bd-books-list           Container wrapping multiple book listings

RETAILER LINKS:
  retailer-box             Base class for all retailer links
  retailer-amazon          Amazon links
  retailer-apple           Apple Books links
  retailer-barnes          Barnes & Noble links
  retailer-kobo            Kobo links
  retailer-google          Google Play links
  retailer-unavailable     Disabled/unavailable retailer

================================================================================
11. STATIC HELPER METHODS
================================================================================

The following static methods are available for theme use:

get_featured_books($limit = 5)          Get books ordered by publish_date
get_cover_url($book_id, $size = 'thumbnail', $lang = 'en')  Get cover image URL
get_book_url($book_id)                  Get book URL (short link or permalink)
get_ratings($book_id)                    Get amazon/goodreads ratings array
get_retailer_links($book_id, $format = 'ebook')  Get retailer purchase links array
get_localized_title($book_id, $lang = 'en')    Get title for language
get_localized_blurb($book_id, $lang = 'en')    Get blurb for language
get_preview_excerpt($book_id, $lang = 'en')    Get preview excerpt
get_pull_quotes($book_id, $lang = 'en')         Get up to 5 pull quotes
get_reviews($book_id)                    Get reviews from bd_reviews table
get_pen_name($book_id)                   Get author pen name
get_series_info($book_id)               Get series data + volume
series_count()                          Count of active series
get_supported_languages()               List supported language codes
get_awards()                            Get awards option
output_seo_tags($book_id)               Output meta/OG tags
generate_schema($book_id)              Generate schema.org data

================================================================================
12. MULTI-LANGUAGE SUPPORT
================================================================================

Supported Languages:
  en     English
  fr     Francais
  de     Deutsch
  es     Espanol
  it     Italiano
  pt     Portugues
  ru     Russkiy
  ja     Japanese
  zh     Chinese (Simplified)

Implementation:
- Each language gets its own meta fields (title_en, title_fr, blurb_en, etc.)
- get_localized_title/blurb methods default to English if requested language not found
- Data entry interface has language tabs with panels for each language

================================================================================
13. CRON JOBS
================================================================================

Hook: bd_bookshelf_goodreads_refresh
Schedule: Daily
Purpose: Refresh data from Goodreads API

Hook: bd_bookshelf_amazon_scrape
Schedule: Every 6 hours
Purpose: Scrape Amazon for ratings

================================================================================
14. THEME DEPENDENCIES
================================================================================

The plugin is designed to work with the BD BookShelf theme.

Integration points:
1. Nav Menu Filter: Hooks into bdm_nav_menu_items filter to inject Series menu
2. Book Display: render_book_display() outputs HTML with .bd-book-* classes
3. Cover Images: Uses theme's standard WordPress featured image system
4. Short Link Rewrite: Registers /[slug] pattern that works site-wide

================================================================================
15. ADMIN PAGES
================================================================================

Menu: BD BookHelper (main menu icon: dashicons-book-alt)

  Dashboard              bd-bookshelf-dashboard      Overview and quick links
  Books                  edit.php?post_type=book       Book list
  Book Data Entry        bd-bookshelf-data-entry      Enhanced book editor
  Series                 edit-tags.php?taxonomy=series Series taxonomy management
  Short Links            bd-bookshelf-bulk-actions     Short link management
  Reviews                bd-bookshelf-reviews          Review management
  Pen Names              bd-bookshelf-pen-names       Pen name CRUD
  Settings               bd-bookshelf-settings        Affiliate codes, Goodreads ID
  Migrate                bd-bookshelf-migrate         Migration from BD Books

================================================================================
16. REQUIRED THEME CSS (MINIMUM)
================================================================================

The theme MUST provide CSS for the following classes to render the Amazon Detail layout:

/* Book Listing Container */
.bd-book-listing { margin-bottom: 2rem; }

/* Entry Flex Container */
.bd-book-entry { display: flex; gap: 2rem; }

/* Cover Column (25%) */
.bd-book-cover { flex: 0 0 25%; max-width: 25%; }
.bd-book-cover img { width: 100%; height: auto; box-shadow: 0 4px 8px rgba(0,0,0,0.2); border-radius: 4px; }

/* Format Selector */
.bd-book-format-selector { display: flex; gap: 0.5rem; margin-bottom: 1rem; }
.bd-book-format-btn { padding: 0.5rem 1rem; border: 1px solid var(--bdm-navy); background: #fff; cursor: pointer; border-radius: 4px; }
.bd-book-format-btn.active { background: var(--bdm-navy); color: #fff; }

/* Retailer Links */
.bd-book-retailers { display: flex; flex-wrap: wrap; gap: 0.5rem; }
.retailer-box { display: inline-block; padding: 0.5rem 1rem; background: #FF9900; color: #000; text-decoration: none; border-radius: 4px; font-weight: bold; }

/* Details Column (75%) */
.bd-book-details { flex: 1; }
.bd-book-title { margin: 0 0 0.5rem 0; font-family: var(--bdm-heading-font); font-size: 1.5rem; }
.bd-book-byline { color: var(--bdm-mid-grey); margin: 0 0 1rem 0; }
.bd-book-ratings { margin-bottom: 1rem; }
.bd-book-separator { border: none; border-top: 1px solid #eee; margin: 1rem 0; }
.bd-book-blurb { margin-bottom: 1rem; line-height: 1.8; }
.bd-book-metadata { margin-bottom: 1rem; color: var(--bdm-mid-grey); }
.bd-book-categories { font-size: 0.85rem; color: var(--bdm-light-grey); }

/* Responsive */
@media (max-width: 768px) {
    .bd-book-entry { flex-direction: column; }
    .bd-book-cover { flex: 0 0 100%; max-width: 100%; }
}

================================================================================
17. ACTIVATION/DEACTIVATION
================================================================================

Activation creates:
- All database tables via dbDelta()
- 'book_manager' role with limited capabilities
- Default pen name "B.D. Murphy"
- Scheduled cron events
- Flushes rewrite rules

Deactivation removes:
- 'book_manager' role
- Scheduled cron events
- Flushes rewrite rules

================================================================================