@enyo-energy/energy-app-sdk 1.44.0 → 1.45.0

package/dist/cjs/implementations/subscriptions/subscription-offer-validators.cjs

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Client-side validator for how a package promotes its subscription plans:
+ * the feature catalog ({@link EnergyAppPackageDefinition.subscriptionFeatures}),
+ * the free tier ({@link EnergyAppPackageDefinition.subscriptionFreeTier}), the
+ * offer screen blocks ({@link EnergyAppPackageDefinition.subscriptionOfferScreen})
+ * and the plans' `includedFeatures` and `highlight`.
+ *
+ * `validatePackageSubscriptionPlans()` runs these checks as part of the plan
+ * validation, so most callers never call {@link validatePackageSubscriptionOffer}
+ * directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePackageSubscriptionOffer = validatePackageSubscriptionOffer;
+const enyo_subscription_js_1 = require("../../types/enyo-subscription.cjs");
+const enyo_subscription_offer_js_1 = require("../../types/enyo-subscription-offer.cjs");
+const define_subscription_plan_js_1 = require("./define-subscription-plan.cjs");
+/** A feature key — the same kebab-case slug shape as a plan key. */
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Languages every text on the offer screen must be translated into. */
+const REQUIRED_LANGUAGES = ['de', 'en'];
+/**
+ * Checks that a list of localized entries has no duplicate language, covers
+ * every required language, and fills the required fields in every entry.
+ *
+ * @param entries - The localized entries, e.g. a feature's `storeEntry`.
+ * @param at - Location prefix for messages.
+ * @param requiredFields - Fields that must be non-empty in every entry.
+ * @param errors - Collector for blocking errors.
+ */
+function validateTranslations(entries, at, requiredFields, errors) {
+    const languages = new Set();
+    for (const [index, entry] of (entries ?? []).entries()) {
+        const entryAt = `${at}[${index}] (${entry.language || '?'})`;
+        if (languages.has(entry.language)) {
+            errors.push(`${entryAt}: duplicate language "${entry.language}".`);
+        }
+        languages.add(entry.language);
+        for (const field of requiredFields) {
+            const value = entry[field];
+            if (typeof value !== 'string' || !value.trim()) {
+                errors.push(`${entryAt}: ${field} is required.`);
+            }
+        }
+    }
+    for (const language of REQUIRED_LANGUAGES) {
+        if (!languages.has(language)) {
+            errors.push(`${at}: entry for language "${language}" is required.`);
+        }
+    }
+}
+/**
+ * Checks the included features of a plan or of the free tier: every entry
+ * names a declared feature, no feature is listed twice, and every value is
+ * translated.
+ *
+ * @param included - The included features, or `undefined` when none are declared.
+ * @param featureKeys - The keys of the feature catalog.
+ * @param at - Location prefix for messages.
+ * @param errors - Collector for blocking errors.
+ */
+function validateIncludedFeatures(included, featureKeys, at, errors) {
+    const seen = new Set();
+    for (const [index, feature] of (included ?? []).entries()) {
+        const key = (0, define_subscription_plan_js_1.getIncludedFeatureKey)(feature);
+        const featureAt = `${at}.includedFeatures[${index}] (${key || '?'})`;
+        if (!featureKeys.has(key)) {
+            errors.push(`${featureAt}: "${key}" is not a feature of subscriptionFeatures.`);
+        }
+        else if (seen.has(key)) {
+            errors.push(`${featureAt}: feature "${key}" is listed twice.`);
+        }
+        seen.add(key);
+        if (typeof feature !== 'string') {
+            validateTranslations(feature.value, `${featureAt}.value`, ['value'], errors);
+        }
+    }
+}
+/**
+ * Checks that every key of a block's key list is declared.
+ *
+ * @param keys - The keys the block refers to, or `undefined` for "all".
+ * @param known - The declared keys.
+ * @param kind - `'feature'` or `'plan'`, used in messages.
+ * @param at - Location prefix for messages.
+ * @param errors - Collector for blocking errors.
+ */
+function validateBlockKeys(keys, known, kind, at, errors) {
+    if (keys === undefined)
+        return;
+    if (keys.length === 0) {
+        errors.push(`${at}: ${kind}Keys must not be empty — omit it to use every ${kind}.`);
+    }
+    const seen = new Set();
+    for (const key of keys) {
+        if (!known.has(key))
+            errors.push(`${at}: "${key}" is not a declared ${kind}.`);
+        else if (seen.has(key))
+            errors.push(`${at}: ${kind} "${key}" is listed twice.`);
+        seen.add(key);
+    }
+}
+/**
+ * Checks a block's optional heading and text: when set, they must be
+ * translated into every required language.
+ *
+ * @param storeEntry - The block's localized texts.
+ * @param at - Location prefix for messages.
+ * @param requiredFields - Fields that must be non-empty in every entry.
+ * @param errors - Collector for blocking errors.
+ */
+function validateBlockTexts(storeEntry, at, requiredFields, errors) {
+    validateTranslations(storeEntry, `${at}.storeEntry`, requiredFields, errors);
+    for (const [index, entry] of (storeEntry ?? []).entries()) {
+        if (!entry.title?.trim() && !entry.text?.trim()) {
+            errors.push(`${at}.storeEntry[${index}] (${entry.language || '?'}): title or text is required.`);
+        }
+    }
+}
+/**
+ * Checks an optional icon against {@link EnyoSubscriptionOfferIconEnum}.
+ *
+ * @param icon - The icon, or `undefined`.
+ * @param at - Location prefix for messages.
+ * @param errors - Collector for blocking errors.
+ */
+function validateIcon(icon, at, errors) {
+    if (icon !== undefined && !Object.values(enyo_subscription_offer_js_1.EnyoSubscriptionOfferIconEnum).includes(icon)) {
+        errors.push(`${at}: icon "${icon}" is not supported — use one of EnyoSubscriptionOfferIconEnum.`);
+    }
+}
+/**
+ * Validates how a package promotes its plans:
+ *
+ * - **Features**: keys are unique kebab-case slugs, icons are known, and every
+ *   feature has a German and English title.
+ * - **Plans**: `includedFeatures` name declared features, at most once each,
+ *   with translated values; `highlight` is known and set on at most one plan.
+ * - **Free tier**: only with `subscriptionMode: 'optional'`, translated, and
+ *   its `includedFeatures` follow the plan rules.
+ * - **Offer screen**: at least one block, every block type is known, texts are
+ *   translated (a `hero` needs a title, a `hint` a known kind and a text),
+ *   referenced features and plans exist, a comparison has at least two
+ *   columns and a free column only with a free tier, and there is at most one
+ *   `plans` block.
+ *
+ * Warnings flag features no tier includes, comparison rows no column
+ * includes, and offer declarations without plans.
+ *
+ * @param definition - The package definition, or just the fields listed in
+ *   {@link PackageSubscriptionOfferSource}.
+ * @returns The {@link PackageSubscriptionOfferValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors} = validatePackageSubscriptionOffer(packageDef);
+ * if (!ok) throw new Error(errors.join('\n'));
+ * ```
+ */
+function validatePackageSubscriptionOffer(definition) {
+    const errors = [];
+    const warnings = [];
+    const plans = definition.subscriptionPlans ?? [];
+    const features = definition.subscriptionFeatures ?? [];
+    const freeTier = definition.subscriptionFreeTier;
+    const screen = definition.subscriptionOfferScreen;
+    if (!plans.length) {
+        if (definition.subscriptionFeatures || freeTier || screen) {
+            warnings.push('subscriptionFeatures, subscriptionFreeTier or subscriptionOfferScreen is set but no subscriptionPlans are declared — it has no effect.');
+        }
+        return { ok: true, errors, warnings };
+    }
+    const featureKeys = new Set();
+    for (const [index, feature] of features.entries()) {
+        const at = `subscriptionFeatures[${index}] (${feature.featureKey || '?'})`;
+        if (!feature.featureKey?.trim()) {
+            errors.push(`${at}: featureKey is required.`);
+        }
+        else if (!SLUG_RE.test(feature.featureKey)) {
+            errors.push(`${at}: featureKey must be a kebab-case slug, e.g. "price-optimisation".`);
+        }
+        else if (featureKeys.has(feature.featureKey)) {
+            errors.push(`${at}: duplicate featureKey "${feature.featureKey}" — feature keys must be unique within the package.`);
+        }
+        featureKeys.add(feature.featureKey);
+        validateIcon(feature.icon, at, errors);
+        validateTranslations(feature.storeEntry, `${at}.storeEntry`, ['title'], errors);
+    }
+    const includedSomewhere = new Set();
+    const highlighted = [];
+    for (const [index, plan] of plans.entries()) {
+        const at = `subscriptionPlans[${index}] (${plan.planKey || '?'})`;
+        validateIncludedFeatures(plan.includedFeatures, featureKeys, at, errors);
+        plan.includedFeatures?.forEach(feature => includedSomewhere.add((0, define_subscription_plan_js_1.getIncludedFeatureKey)(feature)));
+        if (plan.highlight !== undefined) {
+            if (!Object.values(enyo_subscription_offer_js_1.EnyoSubscriptionPlanHighlightEnum).includes(plan.highlight)) {
+                errors.push(`${at}: highlight "${plan.highlight}" is not supported.`);
+            }
+            highlighted.push(plan.planKey);
+        }
+    }
+    if (highlighted.length > 1) {
+        errors.push(`Only one plan may be highlighted, but ${highlighted.map(key => `"${key}"`).join(', ')} are.`);
+    }
+    if (freeTier) {
+        if (definition.subscriptionMode === enyo_subscription_js_1.EnyoSubscriptionModeEnum.Required) {
+            errors.push('subscriptionFreeTier is not allowed with subscriptionMode "required" — the app has no free base.');
+        }
+        validateTranslations(freeTier.storeEntry, 'subscriptionFreeTier.storeEntry', ['title'], errors);
+        validateIncludedFeatures(freeTier.includedFeatures, featureKeys, 'subscriptionFreeTier', errors);
+        freeTier.includedFeatures?.forEach(feature => includedSomewhere.add((0, define_subscription_plan_js_1.getIncludedFeatureKey)(feature)));
+    }
+    for (const feature of features) {
+        if (feature.featureKey && !includedSomewhere.has(feature.featureKey)) {
+            warnings.push(`Feature "${feature.featureKey}" is not included in any plan or the free tier.`);
+        }
+    }
+    if (screen) {
+        validateOfferScreenBlocks(screen.blocks, definition, featureKeys, errors, warnings);
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+/**
+ * Checks the blocks of the offer screen.
+ *
+ * @param blocks - The declared blocks.
+ * @param definition - The package definition, for plans and the free tier.
+ * @param featureKeys - The keys of the feature catalog.
+ * @param errors - Collector for blocking errors.
+ * @param warnings - Collector for advisory problems.
+ */
+function validateOfferScreenBlocks(blocks, definition, featureKeys, errors, warnings) {
+    if (!Array.isArray(blocks) || blocks.length === 0) {
+        errors.push('subscriptionOfferScreen.blocks must contain at least one block — omit subscriptionOfferScreen to show only the plans.');
+        return;
+    }
+    const plans = definition.subscriptionPlans ?? [];
+    const planKeys = new Set(plans.map(plan => plan.planKey));
+    let plansBlocks = 0;
+    for (const [index, block] of blocks.entries()) {
+        const at = `subscriptionOfferScreen.blocks[${index}] (${block?.type || '?'})`;
+        switch (block?.type) {
+            case enyo_subscription_offer_js_1.EnyoSubscriptionOfferBlockTypeEnum.Hero:
+                validateIcon(block.icon, at, errors);
+                validateBlockTexts(block.storeEntry, at, ['title'], errors);
+                break;
+            case enyo_subscription_offer_js_1.EnyoSubscriptionOfferBlockTypeEnum.Features:
+                if (featureKeys.size === 0) {
+                    errors.push(`${at}: a features block needs subscriptionFeatures to list.`);
+                }
+                validateBlockKeys(block.featureKeys, featureKeys, 'feature', at, errors);
+                if (block.storeEntry)
+                    validateBlockTexts(block.storeEntry, at, [], errors);
+                break;
+            case enyo_subscription_offer_js_1.EnyoSubscriptionOfferBlockTypeEnum.Comparison: {
+                if (featureKeys.size === 0) {
+                    errors.push(`${at}: a comparison block needs subscriptionFeatures as its rows.`);
+                }
+                validateBlockKeys(block.featureKeys, featureKeys, 'feature', at, errors);
+                validateBlockKeys(block.planKeys, planKeys, 'plan', at, errors);
+                const freeColumn = block.includeFreeTier ?? definition.subscriptionFreeTier !== undefined;
+                if (freeColumn && !definition.subscriptionFreeTier) {
+                    errors.push(`${at}: includeFreeTier needs subscriptionFreeTier to fill the free column.`);
+                }
+                const columnPlans = plans.filter(plan => block.planKeys?.includes(plan.planKey) ?? true);
+                if (columnPlans.length + (freeColumn ? 1 : 0) < 2) {
+                    errors.push(`${at}: a comparison needs at least two columns — add the free tier or another plan.`);
+                }
+                const included = new Set([
+                    ...(freeColumn ? definition.subscriptionFreeTier?.includedFeatures ?? [] : []),
+                    ...columnPlans.flatMap(plan => plan.includedFeatures ?? []),
+                ].map(define_subscription_plan_js_1.getIncludedFeatureKey));
+                for (const key of block.featureKeys ?? featureKeys) {
+                    if (featureKeys.has(key) && !included.has(key)) {
+                        warnings.push(`${at}: feature "${key}" is not included in any compared column — its row stays empty.`);
+                    }
+                }
+                if (block.storeEntry)
+                    validateBlockTexts(block.storeEntry, at, [], errors);
+                break;
+            }
+            case enyo_subscription_offer_js_1.EnyoSubscriptionOfferBlockTypeEnum.Hint:
+                if (!Object.values(enyo_subscription_offer_js_1.EnyoSubscriptionOfferHintKindEnum).includes(block.kind)) {
+                    errors.push(`${at}: kind "${block.kind}" is not supported.`);
+                }
+                validateIcon(block.icon, at, errors);
+                validateBlockTexts(block.storeEntry, at, ['text'], errors);
+                break;
+            case enyo_subscription_offer_js_1.EnyoSubscriptionOfferBlockTypeEnum.Plans:
+                plansBlocks++;
+                if (block.storeEntry)
+                    validateBlockTexts(block.storeEntry, at, [], errors);
+                break;
+            default:
+                errors.push(`${at}: block type "${block?.type}" is not supported.`);
+        }
+    }
+    if (plansBlocks > 1) {
+        errors.push('subscriptionOfferScreen.blocks may contain at most one "plans" block.');
+    }
+}

package/dist/cjs/implementations/subscriptions/subscription-offer-validators.d.cts

@@ -0,0 +1,54 @@
+/**
+ * Client-side validator for how a package promotes its subscription plans:
+ * the feature catalog ({@link EnergyAppPackageDefinition.subscriptionFeatures}),
+ * the free tier ({@link EnergyAppPackageDefinition.subscriptionFreeTier}), the
+ * offer screen blocks ({@link EnergyAppPackageDefinition.subscriptionOfferScreen})
+ * and the plans' `includedFeatures` and `highlight`.
+ *
+ * `validatePackageSubscriptionPlans()` runs these checks as part of the plan
+ * validation, so most callers never call {@link validatePackageSubscriptionOffer}
+ * directly.
+ */
+import type { EnergyAppPackageDefinition } from '../../energy-app-package-definition.cjs';
+/** The outcome of validating how a package promotes its plans. */
+export interface PackageSubscriptionOfferValidationResult {
+    /** True when there are no blocking `errors` (warnings are still allowed). */
+    ok: boolean;
+    /** Blocking problems — these must be fixed before releasing. */
+    errors: string[];
+    /** Advisory problems — allowed, but usually worth reviewing. */
+    warnings: string[];
+}
+/**
+ * The parts of a package definition the offer validator reads.
+ */
+export type PackageSubscriptionOfferSource = Pick<EnergyAppPackageDefinition, 'subscriptionPlans' | 'subscriptionMode' | 'subscriptionFeatures' | 'subscriptionFreeTier' | 'subscriptionOfferScreen'>;
+/**
+ * Validates how a package promotes its plans:
+ *
+ * - **Features**: keys are unique kebab-case slugs, icons are known, and every
+ *   feature has a German and English title.
+ * - **Plans**: `includedFeatures` name declared features, at most once each,
+ *   with translated values; `highlight` is known and set on at most one plan.
+ * - **Free tier**: only with `subscriptionMode: 'optional'`, translated, and
+ *   its `includedFeatures` follow the plan rules.
+ * - **Offer screen**: at least one block, every block type is known, texts are
+ *   translated (a `hero` needs a title, a `hint` a known kind and a text),
+ *   referenced features and plans exist, a comparison has at least two
+ *   columns and a free column only with a free tier, and there is at most one
+ *   `plans` block.
+ *
+ * Warnings flag features no tier includes, comparison rows no column
+ * includes, and offer declarations without plans.
+ *
+ * @param definition - The package definition, or just the fields listed in
+ *   {@link PackageSubscriptionOfferSource}.
+ * @returns The {@link PackageSubscriptionOfferValidationResult}.
+ *
+ * @example
+ * ```typescript
+ * const {ok, errors} = validatePackageSubscriptionOffer(packageDef);
+ * if (!ok) throw new Error(errors.join('\n'));
+ * ```
+ */
+export declare function validatePackageSubscriptionOffer(definition: PackageSubscriptionOfferSource): PackageSubscriptionOfferValidationResult;

package/dist/cjs/implementations/subscriptions/subscription-plan-validators.cjs

@@ -22,6 +22,7 @@ const energy_app_permission_type_js_1 = require("../../energy-app-permission.typ
 const enyo_energy_app_sdk_js_1 = require("../../enyo-energy-app-sdk.cjs");
 const enyo_currency_js_1 = require("../../types/enyo-currency.cjs");
 const enyo_subscription_js_1 = require("../../types/enyo-subscription.cjs");
+const subscription_offer_validators_js_1 = require("./subscription-offer-validators.cjs");
 /**
  * Thrown by {@link assertValidPackageSubscriptionPlans} when a package's
  * subscription plans fail validation. The message lists every blocking error
@@ -128,6 +129,10 @@ function validateStoreEntries(plan, at, errors) {
  *
  * A `subscriptionMode` without plans is a warning: it has no effect.
  *
+ * Also runs `validatePackageSubscriptionOffer()` on the feature catalog, the
+ * free tier, the offer screen and the plans' `includedFeatures` and
+ * `highlight`, and merges its errors and warnings into the result.
+ *
  * @param definition - The package definition, or just its `subscriptionPlans`,
  *   `subscriptionMode` and `permissions`. A package without plans is valid.
  * @returns The {@link PackageSubscriptionPlansValidationResult}.
@@ -143,6 +148,8 @@ function validatePackageSubscriptionPlans(definition) {
     const warnings = [];
     const plans = definition.subscriptionPlans;
     const mode = definition.subscriptionMode;
+    const offer = (0, subscription_offer_validators_js_1.validatePackageSubscriptionOffer)(definition);
+    warnings.push(...offer.warnings);
     if (!plans?.length) {
         if (mode !== undefined) {
             warnings.push('subscriptionMode is set but no subscriptionPlans are declared — it has no effect.');
@@ -192,6 +199,7 @@ function validatePackageSubscriptionPlans(definition) {
         }
         validateStoreEntries(plan, at, errors);
     }
+    errors.push(...offer.errors);
     return { ok: errors.length === 0, errors, warnings };
 }
 /**

package/dist/cjs/implementations/subscriptions/subscription-plan-validators.d.cts

@@ -37,10 +37,11 @@ export interface PackageSubscriptionPlansValidationResult {
 }
 /**
  * The parts of a package definition the validator reads: the plans, the
- * subscription mode, and the permissions to check that the app can read its
- * subscriptions.
+ * subscription mode, the permissions to check that the app can read its
+ * subscriptions, and optionally how the plans are promoted (features, free
+ * tier and offer screen).
  */
-export type PackageSubscriptionPlansSource = Pick<EnergyAppPackageDefinition, 'subscriptionPlans' | 'permissions' | 'subscriptionMode'>;
+export type PackageSubscriptionPlansSource = Pick<EnergyAppPackageDefinition, 'subscriptionPlans' | 'permissions' | 'subscriptionMode'> & Partial<Pick<EnergyAppPackageDefinition, 'subscriptionFeatures' | 'subscriptionFreeTier' | 'subscriptionOfferScreen'>>;
 /**
  * Structural validation of a package's subscription plans: plan keys are
  * unique kebab-case slugs, the payment interval is known, every plan has at
@@ -52,6 +53,10 @@ export type PackageSubscriptionPlansSource = Pick<EnergyAppPackageDefinition, 's
  *
  * A `subscriptionMode` without plans is a warning: it has no effect.
  *
+ * Also runs `validatePackageSubscriptionOffer()` on the feature catalog, the
+ * free tier, the offer screen and the plans' `includedFeatures` and
+ * `highlight`, and merges its errors and warnings into the result.
+ *
  * @param definition - The package definition, or just its `subscriptionPlans`,
  *   `subscriptionMode` and `permissions`. A package without plans is valid.
  * @returns The {@link PackageSubscriptionPlansValidationResult}.

package/dist/cjs/index.cjs

@@ -193,6 +193,7 @@ __exportStar(require("./packages/energy-app-cascade.cjs"), exports);
 __exportStar(require("./types/enyo-webhook.cjs"), exports);
 __exportStar(require("./packages/energy-app-webhook.cjs"), exports);
 __exportStar(require("./types/enyo-subscription.cjs"), exports);
+__exportStar(require("./types/enyo-subscription-offer.cjs"), exports);
 __exportStar(require("./packages/energy-app-subscriptions.cjs"), exports);
 __exportStar(require("./types/enyo-room.cjs"), exports);
 __exportStar(require("./packages/energy-app-room.cjs"), exports);
@@ -200,6 +201,7 @@ __exportStar(require("./types/enyo-room-temperature.cjs"), exports);
 __exportStar(require("./packages/energy-app-room-temperatures.cjs"), exports);
 __exportStar(require("./implementations/subscriptions/define-subscription-plan.cjs"), exports);
 __exportStar(require("./implementations/subscriptions/subscription-plan-validators.cjs"), exports);
+__exportStar(require("./implementations/subscriptions/subscription-offer-validators.cjs"), exports);
 __exportStar(require("./implementations/subscriptions/in-memory-subscriptions.cjs"), exports);
 __exportStar(require("./implementations/pricing/price-schedule-resolver.cjs"), exports);
 __exportStar(require("./implementations/pricing/price-component-validators.cjs"), exports);

package/dist/cjs/index.d.cts

@@ -177,6 +177,7 @@ export * from './packages/energy-app-cascade.cjs';
 export * from './types/enyo-webhook.cjs';
 export * from './packages/energy-app-webhook.cjs';
 export * from './types/enyo-subscription.cjs';
+export * from './types/enyo-subscription-offer.cjs';
 export * from './packages/energy-app-subscriptions.cjs';
 export * from './types/enyo-room.cjs';
 export * from './packages/energy-app-room.cjs';
@@ -184,6 +185,7 @@ export * from './types/enyo-room-temperature.cjs';
 export * from './packages/energy-app-room-temperatures.cjs';
 export * from './implementations/subscriptions/define-subscription-plan.cjs';
 export * from './implementations/subscriptions/subscription-plan-validators.cjs';
+export * from './implementations/subscriptions/subscription-offer-validators.cjs';
 export * from './implementations/subscriptions/in-memory-subscriptions.cjs';
 export * from './implementations/pricing/price-schedule-resolver.cjs';
 export * from './implementations/pricing/price-component-validators.cjs';

package/dist/cjs/types/enyo-authentication.d.cts

@@ -174,6 +174,17 @@ export interface EnyoAuthentication {
      * presented before or after the onboarding guide. When omitted, the host decides the default.
      */
     onboardingOrder?: EnyoAuthenticationOnboardingOrder;
+    /**
+     * Forces the host to show this authentication step even when the package is already in
+     * {@link EnyoAuthenticationStateEnum.Authenticated} state.
+     *
+     * By default the host skips the authentication step if the package reports it is already
+     * authenticated. Set this to `true` when the user must authenticate again regardless of the
+     * current state — for example to re-link an account, grant additional scopes, or authenticate
+     * a newly added appliance against the same vendor account. When omitted or `false`, the
+     * host keeps its default behaviour and may skip the step.
+     */
+    authenticationRequired?: boolean;
 }
 export interface EnyoApiKeyAuthenticationResponse {
     apiKey: string;

package/dist/cjs/types/enyo-heatpump-appliance.cjs

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C = exports.HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K = exports.EnyoHeatpumpHeatingControlReferenceEnum = exports.EnyoHeatpumpRoomTemperatureSourceEnum = exports.EnyoHeatpumpProgramModeEnum = exports.EnyoHeatpumpTimeProgramLevelEnum = exports.EnyoHeatpumpApplianceHeatingCircuitTypeEnum = exports.EnyoHeatpumpApplianceStorageTypeEnum = exports.EnyoHeatpumpApplianceHeatingRodUsageEnum = exports.EnyoHeatpumpApplianceAdditionalDeviceEnum = exports.EnyoHeatpumpApplianceConnectionTypeEnum = exports.EnyoHeatpumpApplianceModeEnum = exports.EnyoHeatpumpApplianceAvailableFeaturesEnum = void 0;
+exports.HEATPUMP_CURVE_OPTIMIZATION_DEFAULT_TARGET_C = exports.HEATPUMP_CURVE_OPTIMIZATION_MAX_LOWERING_K = exports.EnyoHeatpumpHeatingControlReferenceEnum = exports.EnyoHeatpumpRoomTemperatureSourceEnum = exports.EnyoHeatpumpProgramModeEnum = exports.EnyoHeatpumpTimeProgramLevelEnum = exports.EnyoHeatpumpApplianceHeatingCircuitTypeEnum = exports.EnyoHeatpumpApplianceStorageTypeEnum = exports.EnyoHeatpumpApplianceHeatingRodUsageEnum = exports.EnyoHeatpumpApplianceAdditionalDeviceEnum = exports.EnyoHeatpumpSgReadyStateEnum = exports.EnyoHeatpumpSgReadyFunctionEnum = exports.EnyoHeatpumpApplianceConnectionTypeEnum = exports.EnyoHeatpumpApplianceModeEnum = exports.EnyoHeatpumpApplianceAvailableFeaturesEnum = void 0;
 var EnyoHeatpumpApplianceAvailableFeaturesEnum;
 (function (EnyoHeatpumpApplianceAvailableFeaturesEnum) {
     /** If the heatpump is capable of domestic hot water*/
@@ -156,6 +156,38 @@ var EnyoHeatpumpApplianceConnectionTypeEnum;
     /** Connected via a vendor or local API (e.g. REST, Modbus, EEBus) */
     EnyoHeatpumpApplianceConnectionTypeEnum["Api"] = "api";
 })(EnyoHeatpumpApplianceConnectionTypeEnum || (exports.EnyoHeatpumpApplianceConnectionTypeEnum = EnyoHeatpumpApplianceConnectionTypeEnum = {}));
+/**
+ * What an SG Ready relay of a heatpump installation acts on
+ * ({@link EnyoHeatpumpApplianceSgReadyRelay.function}).
+ *
+ * Installations often wire more than one SG Ready input — e.g. one for space
+ * heating and one for domestic hot water — so the energy manager can raise one
+ * without the other.
+ */
+var EnyoHeatpumpSgReadyFunctionEnum;
+(function (EnyoHeatpumpSgReadyFunctionEnum) {
+    /** Heats domestic hot water with the electric heating rod of the DHW tank. */
+    EnyoHeatpumpSgReadyFunctionEnum["DhwHeatingRod"] = "dhw-heating-rod";
+    /** Heats domestic hot water with the heatpump's compressor. */
+    EnyoHeatpumpSgReadyFunctionEnum["DhwHeatpump"] = "dhw-heatpump";
+    /** Space heating of a heating circuit. */
+    EnyoHeatpumpSgReadyFunctionEnum["Heating"] = "heating";
+})(EnyoHeatpumpSgReadyFunctionEnum || (exports.EnyoHeatpumpSgReadyFunctionEnum = EnyoHeatpumpSgReadyFunctionEnum = {}));
+/**
+ * The four operating states of an SG Ready input, numbered 1–4 by the SG Ready
+ * label of the Bundesverband Wärmepumpe.
+ */
+var EnyoHeatpumpSgReadyStateEnum;
+(function (EnyoHeatpumpSgReadyStateEnum) {
+    /** State 1 (contacts 1:0): operation blocked, e.g. by the grid operator. */
+    EnyoHeatpumpSgReadyStateEnum["Blocked"] = "blocked";
+    /** State 2 (contacts 0:0): normal operation; the heatpump follows its own control. */
+    EnyoHeatpumpSgReadyStateEnum["Normal"] = "normal";
+    /** State 3 (contacts 0:1): switch-on recommended; the heatpump raises its setpoints. */
+    EnyoHeatpumpSgReadyStateEnum["Recommended"] = "recommended";
+    /** State 4 (contacts 1:1): switch-on forced; the heatpump runs at its maximum setpoints. */
+    EnyoHeatpumpSgReadyStateEnum["Forced"] = "forced";
+})(EnyoHeatpumpSgReadyStateEnum || (exports.EnyoHeatpumpSgReadyStateEnum = EnyoHeatpumpSgReadyStateEnum = {}));
 /**
  * Additional heating devices that can be attached to / combined with a
  * heatpump installation.

package/dist/cjs/types/enyo-heatpump-appliance.d.cts

@@ -150,6 +150,82 @@ export declare enum EnyoHeatpumpApplianceConnectionTypeEnum {
     /** Connected via a vendor or local API (e.g. REST, Modbus, EEBus) */
     Api = "api"
 }
+/**
+ * What an SG Ready relay of a heatpump installation acts on
+ * ({@link EnyoHeatpumpApplianceSgReadyRelay.function}).
+ *
+ * Installations often wire more than one SG Ready input — e.g. one for space
+ * heating and one for domestic hot water — so the energy manager can raise one
+ * without the other.
+ */
+export declare enum EnyoHeatpumpSgReadyFunctionEnum {
+    /** Heats domestic hot water with the electric heating rod of the DHW tank. */
+    DhwHeatingRod = "dhw-heating-rod",
+    /** Heats domestic hot water with the heatpump's compressor. */
+    DhwHeatpump = "dhw-heatpump",
+    /** Space heating of a heating circuit. */
+    Heating = "heating"
+}
+/**
+ * The four operating states of an SG Ready input, numbered 1–4 by the SG Ready
+ * label of the Bundesverband Wärmepumpe.
+ */
+export declare enum EnyoHeatpumpSgReadyStateEnum {
+    /** State 1 (contacts 1:0): operation blocked, e.g. by the grid operator. */
+    Blocked = "blocked",
+    /** State 2 (contacts 0:0): normal operation; the heatpump follows its own control. */
+    Normal = "normal",
+    /** State 3 (contacts 0:1): switch-on recommended; the heatpump raises its setpoints. */
+    Recommended = "recommended",
+    /** State 4 (contacts 1:1): switch-on forced; the heatpump runs at its maximum setpoints. */
+    Forced = "forced"
+}
+/**
+ * One SG Ready input of a heatpump installation — the two relay contacts that
+ * switch the four {@link EnyoHeatpumpSgReadyStateEnum | SG Ready states} — and
+ * what it acts on. Declared in {@link EnyoHeatpumpApplianceMetadata.sgReadyRelays}.
+ *
+ * An input wired with only one contact can switch only two states; declare
+ * them in {@link supportedStates}, e.g. `[Normal, Recommended]`.
+ *
+ * @example
+ * ```typescript
+ * sgReadyRelays: [
+ *     {index: 0, function: EnyoHeatpumpSgReadyFunctionEnum.Heating, zoneIndex: 0, name: 'K1/K2'},
+ *     {index: 1, function: EnyoHeatpumpSgReadyFunctionEnum.DhwHeatpump, zoneIndex: 0, name: 'K3/K4'},
+ *     {
+ *         index: 2,
+ *         function: EnyoHeatpumpSgReadyFunctionEnum.DhwHeatingRod,
+ *         supportedStates: [EnyoHeatpumpSgReadyStateEnum.Normal, EnyoHeatpumpSgReadyStateEnum.Forced]
+ *     }
+ * ]
+ * ```
+ */
+export interface EnyoHeatpumpApplianceSgReadyRelay {
+    /**
+     * Zero-based index of this relay, unique within the heatpump. Stable for as
+     * long as the wiring stays the same, so commands and readings can refer to
+     * the relay by it.
+     */
+    index: number;
+    /** What the relay acts on. */
+    function: EnyoHeatpumpSgReadyFunctionEnum;
+    /**
+     * The zone the relay acts on: the {@link EnyoHeatpumpApplianceHeatingCircuit.index}
+     * for {@link EnyoHeatpumpSgReadyFunctionEnum.Heating}, the
+     * {@link EnyoHeatpumpApplianceDomesticHotWater.index} for the DHW
+     * functions. Omit for the first (or only) zone.
+     */
+    zoneIndex?: number;
+    /** Optional label for installers and the UI, e.g. the terminal names `'K1/K2'`. */
+    name?: string;
+    /**
+     * The SG Ready states this relay can switch. Omit when all four are wired.
+     */
+    supportedStates?: EnyoHeatpumpSgReadyStateEnum[];
+    /** The state the relay is currently in, when known. Must be one of {@link supportedStates}. */
+    activeState?: EnyoHeatpumpSgReadyStateEnum;
+}
 /**
  * Additional heating devices that can be attached to / combined with a
  * heatpump installation.
@@ -810,6 +886,16 @@ export interface EnyoHeatpumpApplianceMetadata {
      * states, while an API connection typically allows direct read/write.
      */
     connectionType?: EnyoHeatpumpApplianceConnectionTypeEnum;
+    /**
+     * The SG Ready relays of the installation, 0 to n, each with the function
+     * it acts on (space heating, DHW by heatpump, DHW by heating rod). Omit or
+     * leave empty when no SG Ready input is wired.
+     *
+     * Independent of {@link connectionType}: an installation read through an
+     * API can still have SG Ready relays wired for control. Validate with
+     * `validateHeatpumpAdvancedMetadata()`.
+     */
+    sgReadyRelays?: EnyoHeatpumpApplianceSgReadyRelay[];
     /**
      * Whether the energy manager is allowed to actively control (steer) this
      * heatpump. When `false`, the heatpump is treated as read-only/monitor-only

package/dist/cjs/types/enyo-settings.d.cts

@@ -83,6 +83,25 @@ export interface EnyoPackageConfigurationSettingIntegerOptions {
 export interface EnyoPackageConfigurationSettingTextOptions {
     maxLength?: number;
 }
+/**
+ * Configuration options for action-type settings.
+ *
+ * An action setting renders as a button instead of an input, for a one-off command (restart a
+ * device, start a self-test). Anything with an on/off state belongs in a `checkbox` instead.
+ * It holds no meaningful value of its own: every tap writes the current time as an ISO 8601
+ * string (e.g. `"2026-10-29T10:15:00.000Z"`) to the setting, so each tap reaches
+ * {@link EnyoSettingsChangeListener} as a change event with a new value — even a second tap
+ * of the same button. Packages react to the event, not to the stored value.
+ */
+export interface EnyoPackageConfigurationSettingActionOptions {
+    /** Translated caption of the button (e.g. "Restart now") */
+    buttonCaption: EnyoPackageConfigurationTranslatedValue[];
+    /**
+     * Optional translated question the user has to confirm before the action is triggered.
+     * Omit it to trigger the action on the first tap.
+     */
+    confirmationText?: EnyoPackageConfigurationTranslatedValue[];
+}
 /**
  * Represents a single configuration setting for an Energy App package.
  */
@@ -90,7 +109,7 @@ export interface EnyoPackageConfigurationSetting {
     /** internal name of the setting - must be unique */
     name: string;
     /** the type of the setting */
-    type: 'text' | 'select' | 'float' | 'integer' | 'checkbox' | 'time' | 'priority';
+    type: 'text' | 'select' | 'float' | 'integer' | 'checkbox' | 'time' | 'priority' | 'action';
     /** if the setting is required */
     required: boolean;
     /** The displayed name of the field */
@@ -111,6 +130,8 @@ export interface EnyoPackageConfigurationSetting {
     timeOptions?: EnyoPackageConfigurationSettingTimeOptions;
     /** Optional configuration for priority-type settings, defining the available priority options with order indices */
     priorityOptions?: EnyoPackageConfigurationSettingPriorityOption[];
+    /** Configuration for action-type settings (a button). Required when `type` is `'action'`. */
+    actionOptions?: EnyoPackageConfigurationSettingActionOptions;
 }
 /**
  * Represents a change event when a setting value is modified.