agent foundation

lib/Support/helpers/app.php

@@ -42,7 +42,7 @@ function setAppContainer(\MintyPHP\App\AppContainer $container): void
 
     \MintyPHP\Http\ApiBootstrap::configure(
         static fn (): \MintyPHP\Service\Audit\ApiAuditService => $container->get(\MintyPHP\Service\Audit\ApiAuditService::class),
-        static fn (): \MintyPHP\Service\Settings\SettingGateway => $container->get(\MintyPHP\Service\Settings\SettingGateway::class),
+        static fn (): \MintyPHP\Service\Settings\SettingsApiPolicyGateway => $container->get(\MintyPHP\Service\Settings\SettingsApiPolicyGateway::class),
         static fn (): \MintyPHP\Service\Security\RateLimiterService => $container->get(\MintyPHP\Service\Security\RateLimiterService::class),
         static fn (): \MintyPHP\Http\ApiSystemAuditReporter => $container->get(\MintyPHP\Http\ApiSystemAuditReporter::class)
     );
@@ -290,6 +290,66 @@ function allowRegistration(): bool
     return in_array(strtolower($value), ['1', 'true', 'yes', 'on'], true);
 }
 
+/**
+ * Feature flag: allow frontend telemetry events.
+ */
+function frontendTelemetryEnabled(): bool
+{
+    $value = appSetting('frontend_telemetry_enabled');
+    if ($value === null || $value === '') {
+        return false;
+    }
+    return in_array(strtolower(trim($value)), ['1', 'true', 'yes', 'on'], true);
+}
+
+/**
+ * Frontend telemetry sample rate normalized to 0..1.
+ */
+function frontendTelemetrySampleRate(): float
+{
+    $value = appSetting('frontend_telemetry_sample_rate');
+    if ($value === null || trim($value) === '') {
+        return 0.2;
+    }
+
+    $rate = is_numeric($value) ? (float) $value : NAN;
+    if (!is_finite($rate) || $rate < 0 || $rate > 1) {
+        return 0.2;
+    }
+
+    return $rate;
+}
+
+/**
+ * Allowed frontend telemetry events as canonical short keys.
+ *
+ * @return list<string>
+ */
+function frontendTelemetryAllowedEvents(): array
+{
+    $allowed = ['warn_once', 'ajax_error'];
+    $value = appSetting('frontend_telemetry_allowed_events');
+    if ($value === null || trim($value) === '') {
+        return $allowed;
+    }
+
+    $items = preg_split('/[\s,]+/', strtolower(trim($value))) ?: [];
+    $normalized = array_values(array_unique(array_filter(
+        array_map(
+            static fn ($entry): string => trim((string) $entry),
+            $items
+        ),
+        static fn ($entry): bool => in_array($entry, $allowed, true)
+    )));
+
+    if ($normalized === []) {
+        return $allowed;
+    }
+
+    sort($normalized, SORT_STRING);
+    return $normalized;
+}
+
 /**
  * Resolve active primary color (tenant override -> app setting).
  */