@stacksjs/env 0.75.15 → 0.75.16

package/README.md

@@ -293,6 +293,40 @@ console.log(provider) // 'github' | 'gitlab' | 'vercel' | etc.
 console.log(providerInfo) // { name: 'GitHub Actions', detected: true }
 ```
 
+## Remote Integration Environments
+
+Use `initializeIntegration()` before creating a remote telemetry client. The
+initializer is not called when the current `APP_ENV` is excluded, so no client,
+capture hook, upload timer, or network transport is created. Included adapters
+receive the normalized environment for event metadata.
+
+```typescript
+import { initializeIntegration } from '@stacksjs/env'
+import { loghqTransport } from '@loghq/stacks'
+
+const loghq = {
+  key: process.env.LOGHQ_KEY,
+  environments: ['production', 'staging'],
+}
+
+const result = initializeIntegration(loghq, ({ environment }) =>
+  loghqTransport({ key: loghq.key, environment }))
+
+export const transports = result.initialized ? [result.value] : []
+```
+
+The same helper is suitable for BugHQ, workers, web and API servers, dashboard
+processes, and Buddy commands. Browser integrations should receive only the
+resolved public enablement or metadata they need, never a server credential.
+
+- `enabled: false` always disables initialization.
+- `enabled: true` does not bypass the environment allowlist.
+- An empty allowlist disables every environment.
+- Unknown or malformed environment names fail closed.
+- `local`, `development`, and `test` are distinct labels.
+- `APP_ENV` is configuration, not deployment proof. A local process launched
+  with `APP_ENV=production` qualifies for a production allowlist.
+
 ### Supported CI/CD Providers
 
 - GitHub Actions

package/dist/integrations.d.ts

@@ -33,6 +33,21 @@ export declare function integrationEnvironment(): string | undefined;
  * @param defaultEnvironments the allowlist to use when the app did not set one
  */
 export declare function integrationGate(options: EnvironmentGatedIntegration | undefined | null, defaultEnvironments?: readonly string[]): IntegrationGate;
+/**
+ * Initialize an integration only when its environment gate is open.
+ *
+ * The callback is never evaluated for an excluded environment, so constructing
+ * an SDK client, registering hooks, or starting a flush timer inside it is
+ * safe. Included adapters receive the normalized environment without exposing
+ * a second `environment` option to application configuration.
+ *
+ * @example
+ * ```ts
+ * const result = initializeIntegration(config.bughq, ({ environment }) =>
+ *   installBugHq({ key: config.bughq.key, environment }))
+ * ```
+ */
+export declare function initializeIntegration<T>(options: EnvironmentGatedIntegration | undefined | null, initialize: (context: IntegrationContext) => T, defaultEnvironments?: readonly string[]): IntegrationInitialization<T>;
 /**
  * One environment gate, shared by every integration that talks to a remote
  * service (stacksjs/stacks#2792).
@@ -87,9 +102,16 @@ export declare interface IntegrationGate {
   environment: string | undefined
   reason: IntegrationGateReason
 }
+/** Context Stacks resolves before an integration is allowed to initialize. */
+export declare interface IntegrationContext {
+  environment: string
+}
 /** Why the gate answered as it did. Worth logging; worth asserting in tests. */
 export type IntegrationGateReason = | 'disabled-explicitly'
   | 'empty-allowlist'
   | 'environment-unknown'
   | 'environment-excluded'
   | 'environment-allowed';
+/** The observable result of an environment-gated initialization attempt. */
+export type IntegrationInitialization<T> = | { initialized: false, gate: IntegrationGate }
+  | { initialized: true, gate: IntegrationGate, value: T }

package/dist/integrations.js

@@ -1 +1 @@
-export const REMOTE_TELEMETRY_ENVIRONMENTS=["production","staging"];export function normalizeEnvironmentName(value){if(typeof value!=="string")return;const normalized=value.trim().toLowerCase();if(!/^[a-z0-9_-]+$/.test(normalized))return;if(normalized==="prod")return"production";if(normalized==="stage")return"staging";if(normalized==="dev")return"development";return normalized}export function integrationEnvironment(){return normalizeEnvironmentName(process.env.APP_ENV)??normalizeEnvironmentName("development")}export function integrationGate(options,defaultEnvironments=REMOTE_TELEMETRY_ENVIRONMENTS){const environment=integrationEnvironment();if(options?.enabled===!1)return{enabled:!1,environment,reason:"disabled-explicitly"};const allowlist=options?.environments??defaultEnvironments;if(allowlist.length===0)return{enabled:!1,environment,reason:"empty-allowlist"};if(environment===void 0)return{enabled:!1,environment,reason:"environment-unknown"};const permitted=new Set;for(const entry of allowlist){const name=normalizeEnvironmentName(entry);if(name!==void 0)permitted.add(name)}return permitted.has(environment)?{enabled:!0,environment,reason:"environment-allowed"}:{enabled:!1,environment,reason:"environment-excluded"}}
+export const REMOTE_TELEMETRY_ENVIRONMENTS=["production","staging"];export function normalizeEnvironmentName(value){if(typeof value!=="string")return;const normalized=value.trim().toLowerCase();if(!/^[a-z0-9_-]+$/.test(normalized))return;if(normalized==="prod")return"production";if(normalized==="stage")return"staging";if(normalized==="dev")return"development";return normalized}export function integrationEnvironment(){return normalizeEnvironmentName(process.env.APP_ENV)??normalizeEnvironmentName("development")}export function integrationGate(options,defaultEnvironments=REMOTE_TELEMETRY_ENVIRONMENTS){const environment=integrationEnvironment();if(options?.enabled===!1)return{enabled:!1,environment,reason:"disabled-explicitly"};const allowlist=options?.environments??defaultEnvironments;if(allowlist.length===0)return{enabled:!1,environment,reason:"empty-allowlist"};if(environment===void 0)return{enabled:!1,environment,reason:"environment-unknown"};const permitted=new Set;for(const entry of allowlist){const name=normalizeEnvironmentName(entry);if(name!==void 0)permitted.add(name)}return permitted.has(environment)?{enabled:!0,environment,reason:"environment-allowed"}:{enabled:!1,environment,reason:"environment-excluded"}}export function initializeIntegration(options,initialize,defaultEnvironments=REMOTE_TELEMETRY_ENVIRONMENTS){const gate=integrationGate(options,defaultEnvironments);if(!gate.enabled||gate.environment===void 0)return{initialized:!1,gate};return{initialized:!0,gate,value:initialize({environment:gate.environment})}}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/env",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.15",
+  "version": "0.75.16",
   "description": "Stacks env helper methods.",
   "author": "Chris Breuer",
   "contributors": [
@@ -56,10 +56,10 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/path": "0.75.15"
+    "@stacksjs/path": "0.75.16"
   },
   "devDependencies": {
     "better-dx": "^0.2.24",
-    "@stacksjs/validation": "0.75.15"
+    "@stacksjs/validation": "0.75.16"
   }
 }