Imported from WordPressBugBounty/plugins-templates-patterns-collection (templates-patterns-collection/vendor/codeinwp/themeisle-sdk/AGENTS.md). Install upstream with npx skills add WordPressBugBounty/plugins-templates-patterns-collection --skill themeisle-sdk. Copyright stays with the author.

ThemeIsle SDK — Agent Reference

Quick-reference guide for AI agents working on this codebase.

What This Is

A shared WordPress library bundled into Themeisle plugins and themes. It provides common features (licensing, analytics, notifications, promotions, etc.) so each product doesn't reimplement them. Multiple products may bundle different versions; only the highest version ever loads.

Directory Map

themeisle-sdk-main/
├── load.php            Entry point bundled by each product. Handles version arbitration.
├── start.php           Bootstrap: requires all class files, calls Loader::init().
├── src/
│   ├── Loader.php      Singleton. Owns $products, $available_modules, $labels.
│   ├── Product.php     Model for a registered plugin/theme. Reads file headers.
│   ├── Common/
│   │   ├── Abstract_module.php   Base class every module extends.
│   │   └── Module_factory.php    Instantiates + attaches modules to products.
│   └── Modules/        One file per feature module (18 total).
├── tests/              PHPUnit tests. One file per module.
├── docs/               Integration guides. One file per feature.
└── assets/             Compiled JS/CSS for SDK UI components.

Key Concepts

How Products Register

Products add their base file to the themeisle_sdk_products filter — that is the only required step:

add_filter( 'themeisle_sdk_products', function( $products ) {
    $products[] = __FILE__;
    return $products;
} );

Product File Headers

The SDK reads WordPress file headers to configure itself per product:

WordPress Available: yes   # yes = on WP.org (free). no = premium only.
Requires License:    yes   # yes = activates the Licenser module.
Pro Slug:            neve-pro  # Slug of the companion pro plugin.

Module Loading Contract

Each module in src/Modules/ extends Abstract_Module and implements:

• can_load( $product ) : bool — Should this module run for this product?
• load( $product ) : self — Register WordPress hooks.

Module_Factory::attach() calls both methods for every registered module/product pair.

Labels (UI Strings)

All UI strings are in Loader::$labels (see src/Loader.php lines 73–328). Products and plugins override them via:

add_filter( 'themeisle_sdk_labels', function( $labels ) {
    $labels['review']['notice'] = __( 'Custom message', 'text-domain' );
    return $labels;
} );

The merge logic ensures the first real translation wins; later callbacks cannot overwrite already-translated values.

All 20 Modules

Common Filter Reference

Common Action Reference

Global Helper Functions

Defined in load.php, available everywhere after init:

tsdk_utmify( $url, $area, $location )   // Append UTM params
tsdk_lstatus( $file )                   // License status string
tsdk_lis_valid( $file )                 // bool — is license valid?
tsdk_lplan( $file )                     // int — license price_id
tsdk_lkey( $file )                      // string — license key
tsdk_translate_link( $url, $type, $langs ) // Localize a URL
tsdk_support_link( $file )              // Pre-filled support URL or false

Options Written by the SDK

All options use {product_key} where key = slug with hyphens replaced by underscores.

API Endpoints

https://api.themeisle.com/license/check/{product}/{key}/{url}/{token}
https://api.themeisle.com/license/activate/{product}/{key}
https://api.themeisle.com/license/deactivate/{product}/{key}
https://api.themeisle.com/license/version/{product}/{key}/{version}/{url}
https://api.themeisle.com/license/versions/{product}/{key}/{url}/{version}
https://api.themeisle.com/tracking/log
https://api.themeisle.com/tracking/events
https://api.themeisle.com/tracking/uninstall
https://api.themeisle.com/tracking/crashes

Tests

composer install
./vendor/bin/phpunit

Test files mirror module names: tests/licenser-test.php, tests/loader-test.php, etc. Sample products used in tests live in tests/sample_products/.

Adding a New Module

1. Create src/Modules/My_Feature.php extending Abstract_Module
2. Implement can_load() and load()
3. Add 'my_feature' to $available_modules in Loader.php
4. Add the file path to the $files_to_load array in start.php
5. Add a test in tests/my-feature-test.php
6. Add a doc in docs/MY-FEATURE.md