byte8/module-activation

Shared activation-gate primitive for Byte8 Magento 2 modules. Lightweight runtime client for byte8.io product_activations — used by the free lead-magnet modules (VAT Validator, PingBell, Stock Radar) to verify their activation key against api.byte8.io once per 24h with a 7-day grace window.

dev-main 2026-05-21 12:39 UTC

Requires

• php: ^8.1|^8.2|^8.3|^8.4|^8.5
• magento/framework: ^103.0

MIT

• Byte8 Ltd

• magento
• activation
• magento2
• magento-2
• license-key
• byte8

README

Shared activation-gate primitive for Byte8 Magento 2 modules. Not directly merchant-facing — pulled in transitively by the lead-magnet modules (byte8/module-vat-validator, byte8/module-pingbell, byte8/module-stock-radar, future free modules).

What it does

A consuming module wires this once via DI, then calls Activation::isActive() on its hot path (observer, validator, plugin). The gate:

1. Reads an activation key from the consumer's encrypted admin config (<product>/activation/key).
2. Verifies it against https://api.byte8.io/graphql once per 24h (cached in Magento's default cache).
3. Falls back to the cached envelope for up to 7 days during a Byte8 Core outage (grace window).
4. Returns false cleanly when the key is missing, denied, or grace has expired — the consumer's code is expected to silently no-op so Magento native behaviour takes over.

A soft-gate window runs until 2026-06-18: any non-empty key is treated as active, no server roundtrip. This lets modules ship to Packagist before the activate endpoint is live and lets admins test against placeholder keys.

Consumer wiring (one per module)

1. composer.json — add the dep:

   "require": {
       "byte8/module-activation": "^1"
   }

2. etc/module.xml — declare the load-order dep:

   <module name="Byte8_YourModule">
       <sequence>
           <module name="Byte8_Activation"/>
       </sequence>
   </module>

3. Model/Activation.php — empty subclass anchors the type-hint in your namespace:

   namespace Byte8\YourModule\Model;
   class Activation extends \Byte8\Activation\Model\Activation {}

4. etc/di.xml — bind your product:

   <type name="Byte8\YourModule\Model\Activation">
       <arguments>
           <argument name="productId" xsi:type="string">your_product</argument>
           <argument name="configPathPrefix" xsi:type="string">byte8_your_module/activation/</argument>
       </arguments>
   </type>

5. etc/adminhtml/system.xml — add the activation group with key, endpoint, timeout, connect_timeout fields. (Key uses Magento\Config\Model\Config\Backend\Encrypted.)

6. etc/config.xml — defaults for endpoint, timeout, connect_timeout.

7. Consumer hot path — inject the subclass, gate behaviour:

   public function __construct(
       private readonly \Byte8\YourModule\Model\Activation $activation,
   ) {}
   
   public function execute() {
       if (!$this->activation->isActive()) {
           return;  // Module silently no-ops; native Magento behaviour takes over.
       }
       // ...
   }

See module-vat-validator/ or module-pingbell/ for a worked example.

What lives where

Class	Purpose
Byte8\Activation\Model\Activation	Orchestrator. Holds soft-gate / fresh / grace windows. isActive() and getStatus() are the public surface.
Byte8\Activation\Model\Client	GraphQL verifyProductActivation HTTP client. Stateless. Never throws.
Byte8\Activation\Model\Cache	Wraps Magento's default cache. Keyed by SHA-1 of the plain key, prefixed by product id.
Byte8\Activation\Model\Status	Value object — state (active / grace / inactive / unknown) + last-checked timestamp + reason.
Byte8\Activation\Logger\Logger	Dedicated logger writing to var/log/activation.log.

Distribution

Published on public Packagist as byte8/module-activation. MIT licensed. Has no proprietary deps — only magento/framework.

Activation server

Server-side lives in infra/core/src/domains/activation/ on the byte8.io monorepo. The wire-format spec is docs/products/VELAFRONT_LICENSE_SERVER.md §3.