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

package/README.md

@@ -1255,6 +1255,33 @@ settings.listenForSettingsChanges((settingName, newValue) => {
 const allSettings = await settings.getSettingsConfig();
 ```
 
+##### Action settings (buttons)
+
+A setting of type `'action'` renders as a button for a one-off command (restart a device, start a self-test, …). Every tap writes the current time as an ISO 8601 string to the setting, so each tap arrives as a change event — react to the event, not to the stored value.
+
+Use an action only for something that *happens*. Anything that has a state the user turns on or off (e.g. "charging cable locked") is a `checkbox`, not an action.
+
+```typescript
+await settings.addSettingConfig({
+    name: `restart-${applianceId}`,
+    applianceId,
+    type: 'action',
+    required: false,
+    fieldName: [{ language: 'en', value: 'Restart wallbox' }, { language: 'de', value: 'Wallbox neu starten' }],
+    actionOptions: {
+        buttonCaption: [{ language: 'en', value: 'Restart now' }, { language: 'de', value: 'Jetzt neu starten' }],
+        // optional: ask before triggering
+        confirmationText: [{ language: 'en', value: 'Restart the wallbox?' }, { language: 'de', value: 'Wallbox neu starten?' }],
+    },
+});
+
+settings.listenForSettingsChanges((event) => {
+    if (event.settingName === `restart-${applianceId}`) {
+        void restartWallbox();
+    }
+});
+```
+
 #### `useConfigurationManager(): EnergyAppConfigurationManager`
 
 Register **internal**, non user-facing configurations for your package and react to value changes. Unlike `useSettings()`, configurations registered here are NOT rendered in the Energy App UI — they are intended for values the package itself reads and writes at runtime (e.g. internal feature toggles, tuning parameters, calibration values) and need to be persisted across restarts.
@@ -3180,7 +3207,9 @@ const packageDef = defineEnergyAppPackage({
 | `pricingModel` | `per-package` (default): one price for the package on the device. `per-unit`: the price is charged per unit — see [Per-unit plans](#per-unit-plans). |
 | `prices` | One net price per currency. `amountWithoutTax` is always the **total for one interval** — per month, per year, or the single one-time amount; per unit for `per-unit` plans — in the currency (not cent), at most two decimals; enyo adds VAT. |
 | `trialDays` | Optional free trial in days. Not allowed for `one-time` plans. |
-| `storeEntry` | Title, short description and optional benefits; `de` and `en` are required. |
+| `storeEntry` | Title, short description and optional benefits; `de` and `en` are required. Prefer `includedFeatures` over `benefits`. |
+| `includedFeatures` | Optional feature keys from `subscriptionFeatures`, or `{ featureKey, value }` with a translated value — see [Offer screen](#offer-screen). |
+| `highlight` | Optional badge: `recommended`, `best-value` or `most-popular`. At most one plan per package. |
 | `internalComment` | Optional note, never shown to users. |
 
 What a plan unlocks is decided by the app: check `isPlanActive(subscriptions, planKey)` at runtime (see
@@ -3209,6 +3238,97 @@ In tests, `InMemorySubscriptions` takes the mode as its third constructor argume
 throws when an `optional` package reports `SubscriptionRequired`. The same check is available as
 `assertEnergyAppStateMatchesSubscriptionMode(mode, state)`.
 
+### Offer screen
+
+Promote the plans on the screen where enyo sells them: declare a **feature catalog** once, say which features the
+**free tier** and each plan include, and build the screen from **blocks**. All three are optional. Without an offer
+screen, enyo shows only the plan cards.
+
+```typescript
+import {
+    defineSubscriptionFeature,
+    defineSubscriptionOfferScreen,
+    EnyoSubscriptionOfferHintKindEnum,
+    EnyoSubscriptionOfferIconEnum,
+    EnyoSubscriptionPlanHighlightEnum
+} from '@enyo-energy/energy-app-sdk';
+
+defineEnergyAppPackage({
+    // ...
+    subscriptionMode: EnyoSubscriptionModeEnum.Optional,
+    subscriptionFeatures: [
+        defineSubscriptionFeature({
+            featureKey: 'pv-charging',
+            icon: EnyoSubscriptionOfferIconEnum.Sun,
+            storeEntry: [
+                { language: 'en', title: 'PV surplus charging' },
+                { language: 'de', title: 'PV-Überschussladen' }
+            ]
+        }),
+        defineSubscriptionFeature({
+            featureKey: 'price-optimisation',
+            icon: EnyoSubscriptionOfferIconEnum.PiggyBank,
+            storeEntry: [
+                { language: 'en', title: 'Dynamic price optimisation', description: 'Charges when electricity is cheapest.' },
+                { language: 'de', title: 'Optimierung nach dynamischen Preisen', description: 'Lädt, wenn Strom am günstigsten ist.' }
+            ]
+        }),
+        defineSubscriptionFeature({
+            featureKey: 'vehicles',
+            icon: EnyoSubscriptionOfferIconEnum.Car,
+            storeEntry: [{ language: 'en', title: 'Connected vehicles' }, { language: 'de', title: 'Verbundene Fahrzeuge' }]
+        })
+    ],
+    subscriptionFreeTier: {
+        storeEntry: [{ language: 'en', title: 'Basic' }, { language: 'de', title: 'Basis' }],
+        includedFeatures: ['pv-charging']
+    },
+    subscriptionPlans: [
+        defineSubscriptionPlan({
+            planKey: 'premium',
+            highlight: EnyoSubscriptionPlanHighlightEnum.Recommended,
+            includedFeatures: [
+                'pv-charging',
+                'price-optimisation',
+                { featureKey: 'vehicles', value: [{ language: 'en', value: 'up to 5' }, { language: 'de', value: 'bis zu 5' }] }
+            ],
+            // paymentInterval, prices, storeEntry ...
+        })
+    ],
+    subscriptionOfferScreen: defineSubscriptionOfferScreen({
+        blocks: [
+            { type: 'hero', icon: 'piggy-bank', storeEntry: [
+                { language: 'en', title: 'Charge for less', text: 'Smart charging with dynamic prices.' },
+                { language: 'de', title: 'Günstiger laden', text: 'Intelligentes Laden mit dynamischen Preisen.' }
+            ] },
+            { type: 'comparison' },                     // Basic vs. Premium, one row per feature
+            { type: 'hint', kind: EnyoSubscriptionOfferHintKindEnum.PricingReason, icon: 'handshake', storeEntry: [
+                { language: 'en', title: 'Why does this cost money?', text: 'The car vendors charge us for every connected vehicle.' },
+                { language: 'de', title: 'Warum kostet das Geld?', text: 'Die Fahrzeughersteller berechnen uns jedes verbundene Fahrzeug.' }
+            ] },
+            { type: 'plans' }
+        ]
+    })
+});
+```
+
+| Block | Shows | Notes |
+|---|---|---|
+| `hero` | A large headline with optional text and icon | `title` is required. |
+| `features` | Features with icon and description | `featureKeys` picks and orders them; omit it to list all. |
+| `comparison` | A table: one row per feature, one column per tier | The free column is shown when a free tier is declared (`includeFreeTier` overrides this). `planKeys` and `featureKeys` pick the columns and rows. A cell shows a check mark, the feature's `value`, or nothing. Needs at least two columns. |
+| `hint` | A highlighted note | `kind`: `pricing-reason` (why it costs money), `requirement`, `info`, `legal`. `text` is required. |
+| `plans` | The plan cards and checkout | At most one. Without it, the plans follow the last block. |
+
+- **Icons** come from a fixed set, `EnyoSubscriptionOfferIconEnum` (`piggy-bank`, `sun`, `car`, `wallbox`, `heat-pump`,
+  `handshake`, …), so every app's offer screen looks the same.
+- **A plan's `includedFeatures` should list everything the customer gets with it**, including the free tier's
+  features. The comparison table takes each column straight from the tier's list.
+- **`subscriptionFreeTier` is only allowed with `subscriptionMode: 'optional'`**.
+- Every text needs `de` and `en`. `validatePackageSubscriptionPlans()` checks all of this as well (it calls
+  `validatePackageSubscriptionOffer()`). It also warns about features that no tier includes and comparison rows
+  that stay empty.
+
 ### Per-unit plans
 
 For a `per-unit` plan the price is charged once per unit — 3 units on a yearly plan for 10 € cost 30 € per year
@@ -3873,6 +3993,26 @@ await applianceManager.updateHeatpumpDomesticHotWater(applianceId, 0, { timeProg
 
 Validate before publishing with `validateHeatpumpHeatingCurve`, `validateHeatpumpTimeProgram` or `validateHeatpumpAdvancedMetadata` (or their `assertValid*` counterparts). Each returns `{ ok, errors, warnings }`.
 
+**SG Ready relays.** You can declare 0–n SG Ready inputs in `metadata.heatpump.sgReadyRelays`. Each one has a
+`function` that says what it acts on: `heating` (a heating circuit), `dhw-heatpump` (DHW heated by the compressor)
+or `dhw-heating-rod` (DHW heated by the heating rod). `zoneIndex` names the heating circuit or DHW zone; omit it for
+the first one. If only some of the four states (`blocked`, `normal`, `recommended`, `forced`) are wired, list them
+in `supportedStates`. `activeState` reports the current state. This works independently of `connectionType`.
+
+```typescript
+sgReadyRelays: [
+    { index: 0, function: EnyoHeatpumpSgReadyFunctionEnum.Heating, zoneIndex: 0, name: 'K1/K2' },
+    { index: 1, function: EnyoHeatpumpSgReadyFunctionEnum.DhwHeatpump, name: 'K3/K4' },
+    { index: 2, function: EnyoHeatpumpSgReadyFunctionEnum.DhwHeatingRod,
+      supportedStates: [EnyoHeatpumpSgReadyStateEnum.Normal, EnyoHeatpumpSgReadyStateEnum.Forced] },
+]
+```
+
+`validateHeatpumpAdvancedMetadata` checks the relays too. It rejects duplicate indexes, unknown functions or
+states, and an `activeState` that is not in `supportedStates`. It warns about unknown zones, two relays with the
+same function on one zone, a relay without `normal`, and a `dhw-heating-rod` relay when `additionalDevices` has
+no `HeatingRod`.
+
 ### WallboxIntegrationEnergyApp
 
 Drives an EV wallbox / charger. Has the richest command surface of all integrations.

package/dist/cjs/energy-app-package-definition.d.cts

@@ -4,6 +4,7 @@ import type { EnyoFileTranslation } from "./types/enyo-file.cjs";
 import type { EnyoOnboardingV2Guide } from "./types/enyo-onboarding-v2.cjs";
 import type { EnyoOnboardingTranslatedContent } from "./types/enyo-onboarding.cjs";
 import type { EnyoSubscriptionMode, EnyoSubscriptionPaymentInterval, EnyoSubscriptionPrice, EnyoSubscriptionPricingModel } from "./types/enyo-subscription.cjs";
+import type { EnyoSubscriptionFeature, EnyoSubscriptionFreeTier, EnyoSubscriptionIncludedFeature, EnyoSubscriptionOfferScreen, EnyoSubscriptionPlanHighlight } from "./types/enyo-subscription-offer.cjs";
 export type EnergyAppPackageLanguage = 'de' | 'en';
 export declare enum EnergyAppPackageCategory {
     Inverter = "inverter",
@@ -294,7 +295,13 @@ export interface EnergyAppPackageSubscriptionPlanStoreEntry {
     title: string;
     /** One sentence describing what the plan unlocks */
     shortDescription: string;
-    /** Optional list of benefits, shown as bullet points on the offer screen */
+    /**
+     * Optional list of benefits, shown as bullet points on the plan card.
+     *
+     * Prefer {@link EnergyAppPackageSubscriptionPlan.includedFeatures}: features
+     * carry icons and descriptions and feed the comparison table. The host
+     * shows `benefits` only for plans without `includedFeatures`.
+     */
     benefits?: string[];
 }
 /**
@@ -358,6 +365,21 @@ export interface EnergyAppPackageSubscriptionPlan {
     trialDays?: number;
     /** Localized store information. Entries for `de` and `en` are required. */
     storeEntry: EnergyAppPackageSubscriptionPlanStoreEntry[];
+    /**
+     * The features this plan includes, as keys of
+     * {@link EnergyAppPackageDefinition.subscriptionFeatures} — or with a
+     * translated value such as "up to 5 vehicles" — in display order. Shown on
+     * the plan card and in the comparison table.
+     *
+     * List every feature the customer gets with the plan, including those of
+     * the free tier, so the comparison table reads correctly.
+     */
+    includedFeatures?: EnyoSubscriptionIncludedFeature[];
+    /**
+     * Optional badge that makes this plan stand out on the offer screen, e.g.
+     * `recommended`. At most one plan of a package may be highlighted.
+     */
+    highlight?: EnyoSubscriptionPlanHighlight;
     /** Optional internal note explaining this plan; never shown to users. */
     internalComment?: string;
 }
@@ -1064,6 +1086,29 @@ export interface EnergyAppPackageDefinition {
      * Omit for packages that are free.
      */
     subscriptionPlans?: EnergyAppPackageSubscriptionPlan[];
+    /**
+     * The package's feature catalog: every feature that the plans and the free
+     * tier refer to, declared once with its icon and translations. enyo builds
+     * the feature lists and the comparison table of the offer screen from it.
+     *
+     * Only used together with {@link subscriptionPlans}. Validate it with
+     * `validatePackageSubscriptionPlans()`.
+     */
+    subscriptionFeatures?: EnyoSubscriptionFeature[];
+    /**
+     * What the app offers without a plan, shown as the free column of the
+     * comparison table. Only allowed with `subscriptionMode: 'optional'`.
+     */
+    subscriptionFreeTier?: EnyoSubscriptionFreeTier;
+    /**
+     * The blocks of the screen on which enyo offers the plans — a headline,
+     * feature lists, a comparison table, hints such as why the app costs
+     * money, and the plan cards — in display order.
+     *
+     * Omit to show only the plan cards. Validate it with
+     * `validatePackageSubscriptionPlans()`.
+     */
+    subscriptionOfferScreen?: EnyoSubscriptionOfferScreen;
     /**
      * Whether the app needs one of its plans to work at all.
      *

package/dist/cjs/implementations/heatpump/heatpump-metadata-validators.cjs

@@ -3,7 +3,8 @@
  * Client-side validation for the advanced heatpump metadata an integration
  * publishes: heating curves ({@link EnyoHeatpumpApplianceHeatingCurve}), time
  * programs ({@link EnyoHeatpumpTimeProgram}), the room-temperature wiring of
- * heating circuits and the program-switch modes of circuits and DHW zones.
+ * heating circuits, the program-switch modes of circuits and DHW zones, and
+ * the SG Ready relays ({@link EnyoHeatpumpApplianceSgReadyRelay}).
  *
  * None of these shapes can be checked at the type level — a curve with one
  * point, an unsorted curve, `'25:00'` as a switching time or a period on day
@@ -47,6 +48,8 @@ const TIME_OF_DAY = /^([01]\d|2[0-3]):([0-5]\d)$/;
 const LEVELS = new Set(Object.values(enyo_heatpump_appliance_js_1.EnyoHeatpumpTimeProgramLevelEnum));
 const PROGRAM_MODES = new Set(Object.values(enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum));
 const OVERRIDE_PROGRAM_MODES = new Set([enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum.Comfort, enyo_heatpump_appliance_js_1.EnyoHeatpumpProgramModeEnum.Eco]);
+const SG_READY_FUNCTIONS = new Set(Object.values(enyo_heatpump_appliance_js_1.EnyoHeatpumpSgReadyFunctionEnum));
+const SG_READY_STATES = new Set(Object.values(enyo_heatpump_appliance_js_1.EnyoHeatpumpSgReadyStateEnum));
 /**
  * Validates the program-switch fields of one heating circuit or DHW zone
  * (`supportedProgramModes`, `programModeTemperaturesC`, `activeProgramMode`)
@@ -121,6 +124,79 @@ function checkHeatingCurveOffset(circuit, prefix, errors) {
         }
     });
 }
+/**
+ * Validates the SG Ready relays of a heatpump and appends the problems to
+ * `errors` / `warnings`.
+ *
+ * Errors: duplicate relay `index`, an unknown `function`, an unknown or empty
+ * `supportedStates`, an unknown `activeState` or one outside
+ * `supportedStates`.
+ *
+ * Warnings: a `zoneIndex` naming no declared heating circuit / DHW zone, two
+ * relays with the same function on the same zone, `supportedStates` without
+ * `Normal` or with duplicates, a `dhw-heating-rod` relay while the
+ * installation does not list a heating rod in `additionalDevices`.
+ *
+ * @param relays - The declared SG Ready relays.
+ * @param metadata - The heatpump metadata, for zones and additional devices.
+ * @param errors - Receives blocking problems.
+ * @param warnings - Receives advisory problems.
+ */
+function checkSgReadyRelays(relays, metadata, errors, warnings) {
+    const indexes = relays.map(relay => relay.index);
+    const duplicates = indexes.filter((index, i) => indexes.indexOf(index) !== i);
+    if (duplicates.length > 0) {
+        errors.push(`sgReadyRelays contains duplicate index ${[...new Set(duplicates)].join(', ')}`);
+    }
+    const targets = new Set();
+    for (const relay of relays) {
+        const prefix = `sgReadyRelays[index=${relay.index}]`;
+        if (!SG_READY_FUNCTIONS.has(relay.function)) {
+            errors.push(`${prefix}: function "${relay.function}" is not a valid value`);
+            continue;
+        }
+        const isHeating = relay.function === enyo_heatpump_appliance_js_1.EnyoHeatpumpSgReadyFunctionEnum.Heating;
+        const zones = isHeating ? metadata.heatingCircuits : metadata.domesticHotWater;
+        const zoneField = isHeating ? 'heatingCircuits' : 'domesticHotWater';
+        const zoneIndex = relay.zoneIndex ?? zones?.[0]?.index ?? 0;
+        if (relay.zoneIndex !== undefined && zones?.length && !zones.some(zone => zone.index === relay.zoneIndex)) {
+            warnings.push(`${prefix}: zoneIndex ${relay.zoneIndex} is not an index of ${zoneField}`);
+        }
+        const target = `${relay.function}@${zoneIndex}`;
+        if (targets.has(target)) {
+            warnings.push(`${prefix}: another relay already has function ${relay.function} on zone ${zoneIndex}`);
+        }
+        targets.add(target);
+        if (relay.function === enyo_heatpump_appliance_js_1.EnyoHeatpumpSgReadyFunctionEnum.DhwHeatingRod
+            && !(metadata.additionalDevices ?? []).includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpApplianceAdditionalDeviceEnum.HeatingRod)) {
+            warnings.push(`${prefix}: function dhw-heating-rod is declared but additionalDevices does not list a HeatingRod`);
+        }
+        const supported = relay.supportedStates;
+        if (supported !== undefined) {
+            if (supported.length === 0) {
+                errors.push(`${prefix}: supportedStates must not be empty — omit it when all four states are wired`);
+            }
+            for (const state of supported) {
+                if (!SG_READY_STATES.has(state))
+                    errors.push(`${prefix}: supportedStates contains unknown state "${state}"`);
+            }
+            if (new Set(supported).size !== supported.length) {
+                warnings.push(`${prefix}: supportedStates contains duplicate states`);
+            }
+            if (supported.length > 0 && !supported.includes(enyo_heatpump_appliance_js_1.EnyoHeatpumpSgReadyStateEnum.Normal)) {
+                warnings.push(`${prefix}: supportedStates does not include normal — the relay could never release the heatpump`);
+            }
+        }
+        if (relay.activeState !== undefined) {
+            if (!SG_READY_STATES.has(relay.activeState)) {
+                errors.push(`${prefix}: activeState "${relay.activeState}" is not a valid value`);
+            }
+            else if (supported !== undefined && !supported.includes(relay.activeState)) {
+                errors.push(`${prefix}: activeState ${relay.activeState} is not one of supportedStates`);
+            }
+        }
+    }
+}
 /**
  * Parses an `HH:mm` time of day into minutes since midnight.
  *
@@ -374,6 +450,7 @@ function assertValidHeatpumpTimeProgram(program) {
  *  - Heating curve offset: errors from {@link checkHeatingCurveOffset}.
  *    Warning: `HeatingCurveOffset` is declared but no circuit has a
  *    `heatingCurveOffsetRangeK` — no offset other than `0` could be accepted.
+ *  - SG Ready relays: errors and warnings from {@link checkSgReadyRelays}.
  *
  * @param metadata - The heatpump metadata to validate.
  * @returns The validation result.
@@ -476,5 +553,6 @@ function validateHeatpumpAdvancedMetadata(metadata) {
             merge(`domesticHotWater[index=${zone.index}].timeProgram`, validateHeatpumpTimeProgram(zone.timeProgram));
         }
     }
+    checkSgReadyRelays(metadata.sgReadyRelays ?? [], metadata, errors, warnings);
     return { ok: errors.length === 0, errors, warnings };
 }

package/dist/cjs/implementations/heatpump/heatpump-metadata-validators.d.cts

@@ -2,7 +2,8 @@
  * Client-side validation for the advanced heatpump metadata an integration
  * publishes: heating curves ({@link EnyoHeatpumpApplianceHeatingCurve}), time
  * programs ({@link EnyoHeatpumpTimeProgram}), the room-temperature wiring of
- * heating circuits and the program-switch modes of circuits and DHW zones.
+ * heating circuits, the program-switch modes of circuits and DHW zones, and
+ * the SG Ready relays ({@link EnyoHeatpumpApplianceSgReadyRelay}).
  *
  * None of these shapes can be checked at the type level — a curve with one
  * point, an unsorted curve, `'25:00'` as a switching time or a period on day
@@ -116,8 +117,9 @@ export declare function assertValidHeatpumpTimeProgram(program: EnyoHeatpumpTime
  *  - Heating curve offset: errors from {@link checkHeatingCurveOffset}.
  *    Warning: `HeatingCurveOffset` is declared but no circuit has a
  *    `heatingCurveOffsetRangeK` — no offset other than `0` could be accepted.
+ *  - SG Ready relays: errors and warnings from {@link checkSgReadyRelays}.
  *
  * @param metadata - The heatpump metadata to validate.
  * @returns The validation result.
  */
-export declare function validateHeatpumpAdvancedMetadata(metadata: Pick<EnyoHeatpumpApplianceMetadata, 'availableFeatures' | 'heatingCircuits' | 'domesticHotWater' | 'building'>): HeatpumpMetadataValidationResult;
+export declare function validateHeatpumpAdvancedMetadata(metadata: Pick<EnyoHeatpumpApplianceMetadata, 'availableFeatures' | 'heatingCircuits' | 'domesticHotWater' | 'building'> & Partial<Pick<EnyoHeatpumpApplianceMetadata, 'sgReadyRelays' | 'additionalDevices'>>): HeatpumpMetadataValidationResult;

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

@@ -20,6 +20,9 @@ exports.isSubscriptionActive = isSubscriptionActive;
 exports.isPlanActive = isPlanActive;
 exports.isSameSubscriptionUnit = isSameSubscriptionUnit;
 exports.isUnitActive = isUnitActive;
+exports.defineSubscriptionFeature = defineSubscriptionFeature;
+exports.defineSubscriptionOfferScreen = defineSubscriptionOfferScreen;
+exports.getIncludedFeatureKey = getIncludedFeatureKey;
 const enyo_subscription_js_1 = require("../../types/enyo-subscription.cjs");
 /**
  * Subscription statuses in which the customer may use what a plan unlocks.
@@ -122,3 +125,48 @@ function isUnitActive(subscriptions, planKey, unit) {
         && isSubscriptionActive(subscription)
         && (subscription.units ?? []).some(paid => isSameSubscriptionUnit(paid, unit)));
 }
+/**
+ * Identity helper that type-checks a feature of the package's feature catalog
+ * ({@link EnergyAppPackageDefinition.subscriptionFeatures}) where it is
+ * written.
+ *
+ * @param feature - The feature declaration.
+ * @returns The same feature, unchanged.
+ *
+ * @example
+ * ```typescript
+ * defineSubscriptionFeature({
+ *     featureKey: 'price-optimisation',
+ *     icon: EnyoSubscriptionOfferIconEnum.PiggyBank,
+ *     storeEntry: [
+ *         {language: 'en', title: 'Dynamic price optimisation'},
+ *         {language: 'de', title: 'Optimierung nach dynamischen Preisen'}
+ *     ]
+ * })
+ * ```
+ */
+function defineSubscriptionFeature(feature) {
+    return feature;
+}
+/**
+ * Identity helper that type-checks the package's offer screen
+ * ({@link EnergyAppPackageDefinition.subscriptionOfferScreen}) where it is
+ * written.
+ *
+ * @param screen - The offer screen declaration.
+ * @returns The same offer screen, unchanged.
+ */
+function defineSubscriptionOfferScreen(screen) {
+    return screen;
+}
+/**
+ * Returns the feature key of an included feature, whether it was declared as
+ * a plain key or with a value.
+ *
+ * @param feature - An entry of {@link EnergyAppPackageSubscriptionPlan.includedFeatures}
+ *   or {@link EnyoSubscriptionFreeTier.includedFeatures}.
+ * @returns Its {@link EnyoSubscriptionFeature.featureKey}.
+ */
+function getIncludedFeatureKey(feature) {
+    return typeof feature === 'string' ? feature : feature.featureKey;
+}

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

@@ -14,6 +14,7 @@
  */
 import type { EnergyAppPackageSubscriptionPlan } from '../../energy-app-package-definition.cjs';
 import { EnyoSubscription, EnyoSubscriptionStatus, EnyoSubscriptionUnit } from '../../types/enyo-subscription.cjs';
+import type { EnyoSubscriptionFeature, EnyoSubscriptionIncludedFeature, EnyoSubscriptionOfferScreen } from '../../types/enyo-subscription-offer.cjs';
 /**
  * Subscription statuses in which the customer may use what a plan unlocks.
  *
@@ -98,3 +99,42 @@ export declare function isSameSubscriptionUnit(a: Pick<EnyoSubscriptionUnit, 'ty
  * ```
  */
 export declare function isUnitActive(subscriptions: EnyoSubscription[], planKey: string, unit: Pick<EnyoSubscriptionUnit, 'type' | 'referenceId'>): boolean;
+/**
+ * Identity helper that type-checks a feature of the package's feature catalog
+ * ({@link EnergyAppPackageDefinition.subscriptionFeatures}) where it is
+ * written.
+ *
+ * @param feature - The feature declaration.
+ * @returns The same feature, unchanged.
+ *
+ * @example
+ * ```typescript
+ * defineSubscriptionFeature({
+ *     featureKey: 'price-optimisation',
+ *     icon: EnyoSubscriptionOfferIconEnum.PiggyBank,
+ *     storeEntry: [
+ *         {language: 'en', title: 'Dynamic price optimisation'},
+ *         {language: 'de', title: 'Optimierung nach dynamischen Preisen'}
+ *     ]
+ * })
+ * ```
+ */
+export declare function defineSubscriptionFeature(feature: EnyoSubscriptionFeature): EnyoSubscriptionFeature;
+/**
+ * Identity helper that type-checks the package's offer screen
+ * ({@link EnergyAppPackageDefinition.subscriptionOfferScreen}) where it is
+ * written.
+ *
+ * @param screen - The offer screen declaration.
+ * @returns The same offer screen, unchanged.
+ */
+export declare function defineSubscriptionOfferScreen(screen: EnyoSubscriptionOfferScreen): EnyoSubscriptionOfferScreen;
+/**
+ * Returns the feature key of an included feature, whether it was declared as
+ * a plain key or with a value.
+ *
+ * @param feature - An entry of {@link EnergyAppPackageSubscriptionPlan.includedFeatures}
+ *   or {@link EnyoSubscriptionFreeTier.includedFeatures}.
+ * @returns Its {@link EnyoSubscriptionFeature.featureKey}.
+ */
+export declare function getIncludedFeatureKey(feature: EnyoSubscriptionIncludedFeature): string;