@ciq-dev/neoiq-foundation-node 1.0.1-beta.1 → 1.0.1-beta.3

package/README.md

@@ -24,6 +24,7 @@ Node.js observability foundation for CommerceIQ services. Integrates with **Grou
 - **Type-Safe Configuration**: Zod validation with helpful error messages
 - **Fastify Plugin**: One-line integration for request lifecycle
 - **HTTP Client**: Axios wrapper with retry, circuit breaker, and trace propagation
+- **Object Store Adapter**: Provider-agnostic wrapper for cloud object storage (e.g. S3) to avoid direct SDK coupling
 
 ---
 
@@ -39,6 +40,9 @@ npm install zod @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-me
   @opentelemetry/exporter-trace-otlp-grpc @opentelemetry/exporter-metrics-otlp-grpc \
   @opentelemetry/auto-instrumentations-node @opentelemetry/resources @opentelemetry/semantic-conventions \
   pino pino-pretty axios axios-retry opossum fastify-plugin
+
+# Optional (only if you want AWS S3 implementation of ObjectStore)
+npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
 ```
 
 ### 2. Initialize (First Line of the App)
@@ -318,6 +322,40 @@ process.on('SIGTERM', async () => {
 
 ---
 
+## Object Store Adapter (S3 / Cloud Abstraction)
+
+Use this when you want to **decouple application code** from `aws-sdk` / cloud vendor SDKs.
+
+### AWS S3 (optional peer deps)
+
+```typescript
+import { AwsS3ObjectStore } from '@ciq-dev/neoiq-foundation-node';
+
+const store = new AwsS3ObjectStore({
+  clientOptions: { region: process.env.AWS_REGION || 'us-east-1' },
+});
+
+const ref = { bucket: 'my-bucket', key: 'path/to/file.json' };
+
+// Upload
+await store.putObject(ref, JSON.stringify({ ok: true }), { contentType: 'application/json' });
+
+// Presigned PUT URL (browser upload)
+const uploadUrl = await store.presignPutObject(ref, { expiresInSeconds: 60, contentType: 'application/json' });
+```
+
+### In-memory (local/tests)
+
+```typescript
+import { InMemoryObjectStore } from '@ciq-dev/neoiq-foundation-node';
+
+const store = new InMemoryObjectStore();
+await store.putObject({ bucket: 'b', key: 'k' }, 'hello');
+const obj = await store.getObject({ bucket: 'b', key: 'k' });
+```
+
+---
+
 ## Complete Example
 
 ```typescript
@@ -422,7 +460,8 @@ src/
 │   └── metrics.ts              # OTEL meter provider
 └── integrations/
     ├── fastify-plugin.ts       # Fastify observability plugin
-    └── http-client.ts          # Axios wrapper with observability
+    ├── http-client.ts          # Axios wrapper with observability
+    └── object-store/           # Cloud object store abstraction (S3, etc.)
 ```
 
 ---

package/dist/bootstrap.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/bootstrap.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/bootstrap.js

@@ -0,0 +1,31 @@
+"use strict";
+const require_tracing = require('./tracing-DM5OFo7l.js');
+
+//#region src/bootstrap.ts
+const VALID_ENVIRONMENTS = [
+	"development",
+	"staging",
+	"qa",
+	"production"
+];
+function resolveEnvironment() {
+	const env = process.env.NODE_ENV;
+	if (env && VALID_ENVIRONMENTS.includes(env)) return env;
+	return "development";
+}
+const serviceName = process.env.FOUNDATION_SERVICE_NAME || process.env.SERVICE_NAME;
+if (!serviceName) console.warn("[neoiq-foundation/bootstrap] FOUNDATION_SERVICE_NAME or SERVICE_NAME env var not set. Skipping tracing bootstrap. Set the env var or use createFoundation() directly.");
+else try {
+	require_tracing.setupTracing({
+		serviceName,
+		serviceVersion: process.env.SERVICE_VERSION || "1.0.0",
+		environment: resolveEnvironment(),
+		endpoint: require_tracing.getDefaultOtelEndpoint()
+	});
+	console.log(`[neoiq-foundation/bootstrap] Tracing initialized for "${serviceName}"`);
+} catch (err) {
+	console.error("[neoiq-foundation/bootstrap] Failed to initialize tracing:", err);
+}
+
+//#endregion
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","names":[],"sources":["../src/bootstrap.ts"],"sourcesContent":["/**\n * Bootstrap entry point for OTEL auto-instrumentation.\n *\n * Usage: node -r @ciq-dev/neoiq-foundation-node/bootstrap app.js\n *\n * Ensures tracing is initialized BEFORE any target libraries (pg, http,\n * ioredis, etc.) are imported, which is required for monkey-patching\n * to work. Reads config from environment variables.\n */\n\nimport { setupTracing } from './features/tracing';\nimport { getDefaultOtelEndpoint } from './config';\n\nconst VALID_ENVIRONMENTS = ['development', 'staging', 'qa', 'production'] as const;\n\nfunction resolveEnvironment(): string {\n  const env = process.env.NODE_ENV;\n  if (env && (VALID_ENVIRONMENTS as readonly string[]).includes(env)) return env;\n  return 'development';\n}\n\nconst serviceName = process.env.FOUNDATION_SERVICE_NAME || process.env.SERVICE_NAME;\n\nif (!serviceName) {\n  console.warn(\n    '[neoiq-foundation/bootstrap] FOUNDATION_SERVICE_NAME or SERVICE_NAME env var not set. ' +\n      'Skipping tracing bootstrap. Set the env var or use createFoundation() directly.',\n  );\n} else {\n  try {\n    setupTracing({\n      serviceName,\n      serviceVersion: process.env.SERVICE_VERSION || '1.0.0',\n      environment: resolveEnvironment(),\n      endpoint: getDefaultOtelEndpoint(),\n    });\n    console.log(`[neoiq-foundation/bootstrap] Tracing initialized for \"${serviceName}\"`);\n  } catch (err) {\n    console.error('[neoiq-foundation/bootstrap] Failed to initialize tracing:', err);\n  }\n}\n"],"mappings":";;;;AAaA,MAAM,qBAAqB;CAAC;CAAe;CAAW;CAAM;AAAa;AAEzE,SAAS,qBAA6B;CACpC,MAAM,MAAM,QAAQ,IAAI;AACxB,KAAI,OAAO,mBAA0C,SAAS,IAAI,CAAE,QAAO;AAC3E,QAAO;AACR;AAED,MAAM,cAAc,QAAQ,IAAI,2BAA2B,QAAQ,IAAI;AAEvE,KAAK,YACH,SAAQ,KACN,wKAED;IAED,KAAI;AACF,8BAAa;EACX;EACA,gBAAgB,QAAQ,IAAI,mBAAmB;EAC/C,aAAa,oBAAoB;EACjC,UAAU,wCAAwB;CACnC,EAAC;AACF,SAAQ,KAAK,wDAAwD,YAAY,GAAG;AACrF,SAAQ,KAAK;AACZ,SAAQ,MAAM,8DAA8D,IAAI;AACjF"}

package/dist/bootstrap.mjs

@@ -0,0 +1,30 @@
+import { getDefaultOtelEndpoint, setupTracing } from "./tracing-Cv-Y3fZx.mjs";
+
+//#region src/bootstrap.ts
+const VALID_ENVIRONMENTS = [
+	"development",
+	"staging",
+	"qa",
+	"production"
+];
+function resolveEnvironment() {
+	const env = process.env.NODE_ENV;
+	if (env && VALID_ENVIRONMENTS.includes(env)) return env;
+	return "development";
+}
+const serviceName = process.env.FOUNDATION_SERVICE_NAME || process.env.SERVICE_NAME;
+if (!serviceName) console.warn("[neoiq-foundation/bootstrap] FOUNDATION_SERVICE_NAME or SERVICE_NAME env var not set. Skipping tracing bootstrap. Set the env var or use createFoundation() directly.");
+else try {
+	setupTracing({
+		serviceName,
+		serviceVersion: process.env.SERVICE_VERSION || "1.0.0",
+		environment: resolveEnvironment(),
+		endpoint: getDefaultOtelEndpoint()
+	});
+	console.log(`[neoiq-foundation/bootstrap] Tracing initialized for "${serviceName}"`);
+} catch (err) {
+	console.error("[neoiq-foundation/bootstrap] Failed to initialize tracing:", err);
+}
+
+//#endregion
+//# sourceMappingURL=bootstrap.mjs.map

package/dist/bootstrap.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.mjs","names":[],"sources":["../src/bootstrap.ts"],"sourcesContent":["/**\n * Bootstrap entry point for OTEL auto-instrumentation.\n *\n * Usage: node -r @ciq-dev/neoiq-foundation-node/bootstrap app.js\n *\n * Ensures tracing is initialized BEFORE any target libraries (pg, http,\n * ioredis, etc.) are imported, which is required for monkey-patching\n * to work. Reads config from environment variables.\n */\n\nimport { setupTracing } from './features/tracing';\nimport { getDefaultOtelEndpoint } from './config';\n\nconst VALID_ENVIRONMENTS = ['development', 'staging', 'qa', 'production'] as const;\n\nfunction resolveEnvironment(): string {\n  const env = process.env.NODE_ENV;\n  if (env && (VALID_ENVIRONMENTS as readonly string[]).includes(env)) return env;\n  return 'development';\n}\n\nconst serviceName = process.env.FOUNDATION_SERVICE_NAME || process.env.SERVICE_NAME;\n\nif (!serviceName) {\n  console.warn(\n    '[neoiq-foundation/bootstrap] FOUNDATION_SERVICE_NAME or SERVICE_NAME env var not set. ' +\n      'Skipping tracing bootstrap. Set the env var or use createFoundation() directly.',\n  );\n} else {\n  try {\n    setupTracing({\n      serviceName,\n      serviceVersion: process.env.SERVICE_VERSION || '1.0.0',\n      environment: resolveEnvironment(),\n      endpoint: getDefaultOtelEndpoint(),\n    });\n    console.log(`[neoiq-foundation/bootstrap] Tracing initialized for \"${serviceName}\"`);\n  } catch (err) {\n    console.error('[neoiq-foundation/bootstrap] Failed to initialize tracing:', err);\n  }\n}\n"],"mappings":";;;AAaA,MAAM,qBAAqB;CAAC;CAAe;CAAW;CAAM;AAAa;AAEzE,SAAS,qBAA6B;CACpC,MAAM,MAAM,QAAQ,IAAI;AACxB,KAAI,OAAO,mBAA0C,SAAS,IAAI,CAAE,QAAO;AAC3E,QAAO;AACR;AAED,MAAM,cAAc,QAAQ,IAAI,2BAA2B,QAAQ,IAAI;AAEvE,KAAK,YACH,SAAQ,KACN,wKAED;IAED,KAAI;AACF,cAAa;EACX;EACA,gBAAgB,QAAQ,IAAI,mBAAmB;EAC/C,aAAa,oBAAoB;EACjC,UAAU,wBAAwB;CACnC,EAAC;AACF,SAAQ,KAAK,wDAAwD,YAAY,GAAG;AACrF,SAAQ,KAAK;AACZ,SAAQ,MAAM,8DAA8D,IAAI;AACjF"}

package/dist/index.d.mts

@@ -1,8 +1,8 @@
+import { Meter, Meter as Meter$1, Span, SpanStatusCode, Tracer, Tracer as Tracer$1, context, metrics, propagation, trace } from "@opentelemetry/api";
 import { z } from "zod";
 import { Logger as Logger$1 } from "pino";
-import * as _opentelemetry_api0 from "@opentelemetry/api";
-import { Meter, Span, SpanStatusCode, Tracer, context, metrics, propagation, trace } from "@opentelemetry/api";
-import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
+import { AxiosInstance, AxiosInstance as AxiosInstance$1, AxiosRequestConfig, AxiosResponse } from "axios";
+import { Readable } from "node:stream";
 import { FastifyPluginAsync } from "fastify";
 
 //#region src/config.d.ts
@@ -122,13 +122,13 @@ declare const FeaturesConfigSchema: z.ZodObject<{
 }>;
 type FeaturesConfig = z.infer<typeof FeaturesConfigSchema>;
 declare const OtelConfigSchema: z.ZodObject<{
-  endpoint: z.ZodOptional<z.ZodDefault<z.ZodString>>;
-  metricsIntervalMs: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
-  traceSampleRate: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+  endpoint: z.ZodDefault<z.ZodString>;
+  metricsIntervalMs: z.ZodDefault<z.ZodNumber>;
+  traceSampleRate: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-  endpoint?: string | undefined;
-  metricsIntervalMs?: number | undefined;
-  traceSampleRate?: number | undefined;
+  endpoint: string;
+  metricsIntervalMs: number;
+  traceSampleRate: number;
 }, {
   endpoint?: string | undefined;
   metricsIntervalMs?: number | undefined;
@@ -166,6 +166,25 @@ declare const RequestLoggingConfigSchema: z.ZodObject<{
   redactHeaders?: string[] | undefined;
 }>;
 type RequestLoggingConfig = z.infer<typeof RequestLoggingConfigSchema>;
+declare const RedactionConfigSchema: z.ZodObject<{
+  additionalPaths: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
+}, "strip", z.ZodTypeAny, {
+  additionalPaths?: string[] | undefined;
+}, {
+  additionalPaths?: string[] | undefined;
+}>;
+type RedactionConfig = z.infer<typeof RedactionConfigSchema>;
+declare const ShutdownConfigSchema: z.ZodObject<{
+  flushOnCrash: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+  flushTimeoutMs: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+  flushOnCrash?: boolean | undefined;
+  flushTimeoutMs?: number | undefined;
+}, {
+  flushOnCrash?: boolean | undefined;
+  flushTimeoutMs?: number | undefined;
+}>;
+type ShutdownConfig = z.infer<typeof ShutdownConfigSchema>;
 declare const FoundationConfigSchema: z.ZodObject<{
   serviceName: z.ZodString;
   serviceVersion: z.ZodDefault<z.ZodString>;
@@ -247,13 +266,13 @@ declare const FoundationConfigSchema: z.ZodObject<{
     } | undefined;
   }>>;
   otel: z.ZodDefault<z.ZodObject<{
-    endpoint: z.ZodOptional<z.ZodDefault<z.ZodString>>;
-    metricsIntervalMs: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
-    traceSampleRate: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    endpoint: z.ZodDefault<z.ZodString>;
+    metricsIntervalMs: z.ZodDefault<z.ZodNumber>;
+    traceSampleRate: z.ZodDefault<z.ZodNumber>;
   }, "strip", z.ZodTypeAny, {
-    endpoint?: string | undefined;
-    metricsIntervalMs?: number | undefined;
-    traceSampleRate?: number | undefined;
+    endpoint: string;
+    metricsIntervalMs: number;
+    traceSampleRate: number;
   }, {
     endpoint?: string | undefined;
     metricsIntervalMs?: number | undefined;
@@ -288,6 +307,23 @@ declare const FoundationConfigSchema: z.ZodObject<{
     maxBodySize?: number | undefined;
     redactHeaders?: string[] | undefined;
   }>>;
+  redaction: z.ZodDefault<z.ZodObject<{
+    additionalPaths: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString, "many">>>;
+  }, "strip", z.ZodTypeAny, {
+    additionalPaths?: string[] | undefined;
+  }, {
+    additionalPaths?: string[] | undefined;
+  }>>;
+  shutdown: z.ZodDefault<z.ZodObject<{
+    flushOnCrash: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    flushTimeoutMs: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+  }, "strip", z.ZodTypeAny, {
+    flushOnCrash?: boolean | undefined;
+    flushTimeoutMs?: number | undefined;
+  }, {
+    flushOnCrash?: boolean | undefined;
+    flushTimeoutMs?: number | undefined;
+  }>>;
 }, "strip", z.ZodTypeAny, {
   logging: {
     level?: "debug" | "info" | "warn" | "error" | undefined;
@@ -315,9 +351,9 @@ declare const FoundationConfigSchema: z.ZodObject<{
     } | undefined;
   };
   otel: {
-    endpoint?: string | undefined;
-    metricsIntervalMs?: number | undefined;
-    traceSampleRate?: number | undefined;
+    endpoint: string;
+    metricsIntervalMs: number;
+    traceSampleRate: number;
   };
   requestLogging: {
     logHeaders?: boolean | undefined;
@@ -326,6 +362,13 @@ declare const FoundationConfigSchema: z.ZodObject<{
     maxBodySize?: number | undefined;
     redactHeaders?: string[] | undefined;
   };
+  redaction: {
+    additionalPaths?: string[] | undefined;
+  };
+  shutdown: {
+    flushOnCrash?: boolean | undefined;
+    flushTimeoutMs?: number | undefined;
+  };
 }, {
   serviceName: string;
   logging?: {
@@ -364,9 +407,16 @@ declare const FoundationConfigSchema: z.ZodObject<{
     maxBodySize?: number | undefined;
     redactHeaders?: string[] | undefined;
   } | undefined;
+  redaction?: {
+    additionalPaths?: string[] | undefined;
+  } | undefined;
+  shutdown?: {
+    flushOnCrash?: boolean | undefined;
+    flushTimeoutMs?: number | undefined;
+  } | undefined;
 }>;
 type FoundationConfig = z.infer<typeof FoundationConfigSchema>;
-type FoundationConfigInput = Partial<FoundationConfig> & {
+type FoundationConfigInput = z.input<typeof FoundationConfigSchema> & {
   serviceName: string;
 };
 /** Parse and validate configuration */
@@ -377,13 +427,18 @@ declare function getDefaultOtelEndpoint(): string; //#endregion
 
 //# sourceMappingURL=config.d.ts.map
 /**
- * Context Manager - AsyncLocalStorage for request context propagation
+ * Context Manager
+ *
+ * Uses OTEL Baggage as the primary store for correlationId when tracing
+ * is active. Falls back to AsyncLocalStorage when tracing is disabled,
+ * ensuring correlation IDs work regardless of OTEL state.
  */
 interface RequestContext {
   correlationId?: string;
   traceId?: string;
   spanId?: string;
   startTime?: number;
+  contextData?: Record<string, unknown>;
   [key: string]: unknown;
 }
 interface ContextManager {
@@ -391,6 +446,16 @@ interface ContextManager {
   run<T>(context: RequestContext, fn: () => T): T;
   get<K extends keyof RequestContext>(key: K): RequestContext[K] | undefined;
   update(updates: Partial<RequestContext>): RequestContext | undefined;
+  /** Set an arbitrary context value (e.g. tenant_id, user_id) — auto-injected into every log line */
+  setContextValue(key: string, value: unknown): void;
+  /** Get a single context value by key */
+  getContextValue(key: string): unknown;
+  /** Get all arbitrary context data */
+  getContextData(): Record<string, unknown>;
+  /** Bulk-set multiple context values */
+  setContextData(data: Record<string, unknown>): void;
+  /** Clear all arbitrary context data */
+  clearContextData(): void;
 }
 /** Create a new context manager instance */
 declare function createContextManager(): ContextManager;
@@ -405,6 +470,7 @@ interface LoggerOptions {
   level: 'debug' | 'info' | 'warn' | 'error';
   prettyPrint: boolean;
   contextManager?: ContextManager;
+  additionalRedactPaths?: string[];
 }
 interface Logger {
   debug: (obj: object, msg?: string) => void;
@@ -417,7 +483,7 @@ interface Logger {
 /** Create a structured logger with automatic trace context injection */
 declare function createLogger(options: LoggerOptions): Logger;
 /** Fallback logger when Pino is not available */
-declare function createFallbackLogger(serviceName?: string): Logger;
+declare function createFallbackLogger(serviceName?: string, baseBindings?: object): Logger;
 declare function setGlobalLogger(logger: Logger): void;
 declare function getGlobalLogger(): Logger;
 
@@ -437,7 +503,7 @@ declare function setupTracing(options: TracingOptions): void;
 /** Shutdown tracing gracefully */
 declare function shutdownTracing(): Promise<void>;
 declare function getTracer(name: string): Tracer;
-declare function getActiveSpan(): _opentelemetry_api0.Span | undefined;
+declare function getActiveSpan(): ReturnType<typeof trace.getActiveSpan>;
 declare function getTraceContext(): {
   traceId?: string;
   spanId?: string;
@@ -488,7 +554,6 @@ interface FastifyPluginOptions {
 }
 declare module 'fastify' {
   interface FastifyRequest {
-    __span?: Span;
     __requestContext?: PluginRequestContext;
   }
 }
@@ -496,12 +561,44 @@ declare module 'fastify' {
 declare function createObservabilityPlugin(options: FastifyPluginOptions): FastifyPluginAsync<Partial<FastifyPluginOptions>>;
 
 //#endregion
-//#region src/integrations/http-client.d.ts
+//#region src/types.d.ts
+interface HealthStatus {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  timestamp: string;
+  service: string;
+  version: string;
+  uptime: number;
+  components: {
+    tracing: ComponentHealth;
+    metrics: ComponentHealth;
+    logging: ComponentHealth;
+  };
+}
+interface ComponentHealth {
+  enabled: boolean;
+  status: 'up' | 'down' | 'disabled';
+  message?: string;
+}
+interface ObservabilityModule {
+  readonly logger: Logger;
+  readonly tracer: Tracer$1 | null;
+  readonly meter: Meter$1 | null;
+  getTracer(name?: string): Tracer$1;
+  getMeter(name: string, version?: string): Meter$1;
+  getTraceContext(): {
+    traceId?: string;
+    spanId?: string;
+  };
+  getActiveSpan(): Span | undefined;
+  trace<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+}
+type HttpClient = AxiosInstance$1;
 interface HttpClientOptions {
   baseURL: string;
   serviceName: string;
   timeout?: number;
   retry?: {
+    enabled?: boolean;
     retries?: number;
     retryDelay?: number;
     retryStatusCodes?: number[];
@@ -514,60 +611,241 @@ interface HttpClientOptions {
   headers?: Record<string, string>;
   foundation?: FoundationInstance;
 }
-type HttpClient = AxiosInstance;
-/** Create a configured HTTP client with full observability */
-declare function createHttpClient(options: HttpClientOptions): HttpClient;
-
-//#endregion
-//#region src/foundation.d.ts
-interface HealthStatus {
-  status: 'healthy' | 'degraded' | 'unhealthy';
-  timestamp: string;
-  service: string;
-  version: string;
-  uptime: number;
-  components: {
-    tracing: ComponentHealth;
-    metrics: ComponentHealth;
-    logging: ComponentHealth;
-  };
+interface HttpModule {
+  createClient(options: Omit<HttpClientOptions, 'foundation'>): HttpClient;
 }
-interface ComponentHealth {
-  enabled: boolean;
-  status: 'up' | 'down' | 'disabled';
-  message?: string;
+interface LifecycleModule {
+  health(): HealthStatus;
+  isReady(): boolean;
+  shutdown(): Promise<void>;
+  safeRun<T>(fn: () => T | Promise<T>, fallback?: T): Promise<T | undefined>;
 }
 interface FoundationInstance {
   readonly config: FoundationConfig;
-  readonly logger: Logger;
-  readonly context: ContextManager;
-  readonly tracer: Tracer | null;
-  readonly meter: Meter | null;
-  readonly fastifyPlugin: ReturnType<typeof createObservabilityPlugin>;
   readonly features: {
     tracing: boolean;
     metrics: boolean;
     logging: boolean;
   };
-  getTracer: (name?: string) => Tracer;
-  getMeter: (name: string, version?: string) => Meter;
+  readonly observability: ObservabilityModule;
+  readonly http: HttpModule;
+  readonly lifecycle: LifecycleModule;
+  readonly logger: Logger;
+  readonly context: ContextManager;
+  readonly fastifyPlugin: FastifyPluginAsync;
+  /** @deprecated Use `foundation.observability.tracer` */
+  readonly tracer: Tracer$1 | null;
+  /** @deprecated Use `foundation.observability.meter` */
+  readonly meter: Meter$1 | null;
+  /** @deprecated Use `foundation.observability.getTracer()` */
+  getTracer: (name?: string) => Tracer$1;
+  /** @deprecated Use `foundation.observability.getMeter()` */
+  getMeter: (name: string, version?: string) => Meter$1;
+  /** @deprecated Use `foundation.observability.getTraceContext()` */
   getTraceContext: () => {
     traceId?: string;
     spanId?: string;
   };
-  getActiveSpan: () => ReturnType<typeof getActiveSpan>;
+  /** @deprecated Use `foundation.observability.getActiveSpan()` */
+  getActiveSpan: () => Span | undefined;
+  /** @deprecated Use `foundation.http.createClient()` */
   createHttpClient: (options: Omit<HttpClientOptions, 'foundation'>) => HttpClient;
+  /** @deprecated Use `foundation.lifecycle.shutdown()` */
   shutdown: () => Promise<void>;
+  /** @deprecated Use `foundation.lifecycle.isReady()` */
   isReady: () => boolean;
+  /** @deprecated Use `foundation.lifecycle.health()` */
   health: () => HealthStatus;
+  /** @deprecated Use `foundation.observability.trace()` */
   trace: <T>(name: string, fn: () => T | Promise<T>) => Promise<T>;
+  /** @deprecated Use `foundation.lifecycle.safeRun()` */
   safeRun: <T>(fn: () => T | Promise<T>, fallback?: T) => Promise<T | undefined>;
 }
+
+//#endregion
+//#region src/foundation.d.ts
+//# sourceMappingURL=types.d.ts.map
 /** Create a fully configured observability foundation */
 declare function createFoundation(input: FoundationConfigInput): FoundationInstance;
 /** Alias for createFoundation */
 declare const setupObservability: typeof createFoundation;
 
 //#endregion
-export { AutoInstrumentationConfig, AutoInstrumentationConfigSchema, AxiosInstance, AxiosRequestConfig, AxiosResponse, ComponentHealth, ContextManager, FastifyPluginOptions, FeaturesConfig, FeaturesConfigSchema, FoundationConfig, FoundationConfigInput, FoundationConfigSchema, FoundationInstance, HealthStatus, HttpClient, HttpClientOptions, Logger, LoggerOptions, LoggingConfig, LoggingConfigSchema, Meter, MetricsOptions, OtelConfig, OtelConfigSchema, RequestContext, RequestLoggingConfig, RequestLoggingConfigSchema, SpanStatusCode, Tracer, TracingOptions, context, createContextManager, createFallbackLogger, createFoundation, createHttpClient, createLogger, createObservabilityPlugin, getActiveSpan, getDefaultOtelEndpoint, getGlobalLogger, getMeter, getTraceContext, getTracer, isMetricsEnabled, isTracingEnabled, metrics, parseConfig, propagation, setGlobalLogger, setupMetrics, setupObservability, setupTracing, shutdownMetrics, shutdownTracing, trace };
+//#region src/features/redaction.d.ts
+/**
+ * Log Redaction & PII Sanitization
+ *
+ * Two-layer approach:
+ * - Layer A: Pino native `redact` (fast-redact) for key-based redaction on every log call.
+ *   Compiled at init, near-zero runtime cost.
+ * - Layer B: Deep-traverse sanitizer for value-pattern detection (JWTs, AWS keys, etc.).
+ *   Only used for request/response body logging — NOT on every log call.
+ */
+/**
+ * Key names that Pino's fast-redact will censor automatically.
+ * Supports wildcards: '*.password' matches nested keys one level deep.
+ */
+declare const REDACT_PATHS: ReadonlyArray<string>;
+/**
+ * Deep-traverse sanitizer for request/response bodies.
+ * Checks both key names (deny-list) and value patterns (JWT, AWS keys, etc.).
+ * NOT intended for every log call — use Pino native `redact` for that.
+ */
+declare function sanitizeBody<T>(body: T): T;
+/** Build the Pino `redact` config object for fast-redact integration */
+declare function buildPinoRedactConfig(additionalPaths?: string[]): {
+  paths: string[];
+  censor: string;
+};
+
+//#endregion
+//#region src/integrations/http-client.d.ts
+//# sourceMappingURL=redaction.d.ts.map
+/** Create a configured HTTP client with full observability */
+declare function createHttpClient(options: HttpClientOptions): HttpClient;
+
+//#endregion
+//#region src/integrations/object-store/types.d.ts
+type ObjectStoreProvider = 'aws-s3' | 'gcp-gcs' | 'azure-blob' | 'in-memory';
+interface ObjectRef {
+  bucket: string;
+  key: string;
+}
+type ObjectBody = string | Uint8Array | Buffer | Readable;
+interface PutObjectOptions {
+  contentType?: string;
+  cacheControl?: string;
+  metadata?: Record<string, string>;
+}
+interface PutObjectResult {
+  etag?: string;
+  versionId?: string;
+}
+interface HeadObjectResult {
+  exists: boolean;
+  contentType?: string;
+  contentLength?: number;
+  etag?: string;
+  versionId?: string;
+  metadata?: Record<string, string>;
+  lastModified?: Date;
+}
+interface GetObjectResult {
+  body: Readable;
+  contentType?: string;
+  contentLength?: number;
+  etag?: string;
+  versionId?: string;
+  metadata?: Record<string, string>;
+  lastModified?: Date;
+}
+interface ListObjectsOptions {
+  bucket: string;
+  prefix?: string;
+  continuationToken?: string;
+  maxKeys?: number;
+}
+interface ListObjectsResult {
+  objects: Array<{
+    key: string;
+    size?: number;
+    etag?: string;
+    lastModified?: Date;
+  }>;
+  nextContinuationToken?: string;
+}
+interface PresignGetObjectOptions {
+  expiresInSeconds: number;
+  responseContentType?: string;
+}
+interface PresignPutObjectOptions {
+  expiresInSeconds: number;
+  contentType?: string;
+}
+
+//#endregion
+//#region src/integrations/object-store/object-store.d.ts
+//# sourceMappingURL=types.d.ts.map
+/**
+ * ObjectStore - provider-agnostic interface to wrap AWS S3 / GCS / etc.
+ *
+ * Downstream services should depend on this interface, not on cloud SDKs directly.
+ */
+interface ObjectStore {
+  readonly provider: string;
+  putObject(ref: ObjectRef, body: ObjectBody, options?: PutObjectOptions): Promise<PutObjectResult>;
+  getObject(ref: ObjectRef): Promise<GetObjectResult>;
+  headObject(ref: ObjectRef): Promise<HeadObjectResult>;
+  deleteObject(ref: ObjectRef): Promise<void>;
+  listObjects(options: ListObjectsOptions): Promise<ListObjectsResult>;
+  presignGetObject(ref: ObjectRef, options: PresignGetObjectOptions): Promise<string>;
+  presignPutObject(ref: ObjectRef, options: PresignPutObjectOptions): Promise<string>;
+}
+
+//#endregion
+//#region src/integrations/object-store/aws-s3.d.ts
+//# sourceMappingURL=object-store.d.ts.map
+/**
+ * Minimal interface for the subset of AWS S3Client we use.
+ * Keeps the module free of `any` while the SDK is dynamically imported.
+ */
+interface S3ClientLike {
+  send(command: unknown): Promise<Record<string, unknown>>;
+}
+interface AwsS3ObjectStoreOptions {
+  /** Provide an existing S3 client instance (advanced use). */
+  client?: S3ClientLike;
+  /** Options forwarded to `new S3Client(...)` when `client` isn't provided. */
+  clientOptions?: Record<string, unknown>;
+}
+/**
+ * AwsS3ObjectStore - wraps AWS S3 behind the provider-agnostic `ObjectStore` interface.
+ *
+ * This implementation uses dynamic imports so `neoiq-foundation-node` can be used without AWS SDK.
+ */
+declare class AwsS3ObjectStore implements ObjectStore {
+  readonly provider = "aws-s3";
+  private readonly clientPromise;
+  private readonly awsPromise;
+  constructor(options?: AwsS3ObjectStoreOptions);
+  private client;
+  putObject(ref: ObjectRef, body: ObjectBody, options?: PutObjectOptions): Promise<PutObjectResult>;
+  getObject(ref: ObjectRef): Promise<GetObjectResult>;
+  headObject(ref: ObjectRef): Promise<HeadObjectResult>;
+  deleteObject(ref: ObjectRef): Promise<void>;
+  listObjects(options: ListObjectsOptions): Promise<ListObjectsResult>;
+  presignGetObject(ref: ObjectRef, options: PresignGetObjectOptions): Promise<string>;
+  presignPutObject(ref: ObjectRef, options: PresignPutObjectOptions): Promise<string>;
+}
+
+//#endregion
+//#region src/integrations/object-store/in-memory.d.ts
+interface InMemoryObjectStoreOptions {
+  /** Maximum number of objects across all buckets. Throws when exceeded. */
+  maxObjects?: number;
+}
+/**
+ * InMemoryObjectStore - useful for local dev, unit tests, and as a safe default.
+ * NOTE: presign* methods are not meaningful here and will throw.
+ */
+declare class InMemoryObjectStore implements ObjectStore {
+  readonly provider = "in-memory";
+  private readonly buckets;
+  private readonly maxObjects;
+  private objectCount;
+  constructor(options?: InMemoryObjectStoreOptions);
+  private bucketMap;
+  putObject(ref: ObjectRef, body: ObjectBody, options?: PutObjectOptions): Promise<PutObjectResult>;
+  getObject(ref: ObjectRef): Promise<GetObjectResult>;
+  headObject(ref: ObjectRef): Promise<HeadObjectResult>;
+  deleteObject(ref: ObjectRef): Promise<void>;
+  listObjects(options: ListObjectsOptions): Promise<ListObjectsResult>;
+  presignGetObject(_ref: ObjectRef, _options: PresignGetObjectOptions): Promise<string>;
+  presignPutObject(_ref: ObjectRef, _options: PresignPutObjectOptions): Promise<string>;
+}
+
+//#endregion
+//# sourceMappingURL=in-memory.d.ts.map
+
+export { AutoInstrumentationConfig, AutoInstrumentationConfigSchema, AwsS3ObjectStore, AwsS3ObjectStoreOptions, AxiosInstance, AxiosRequestConfig, AxiosResponse, ComponentHealth, ContextManager, FastifyPluginOptions, FeaturesConfig, FeaturesConfigSchema, FoundationConfig, FoundationConfigInput, FoundationConfigSchema, FoundationInstance, GetObjectResult, HeadObjectResult, HealthStatus, HttpClient, HttpClientOptions, HttpModule, InMemoryObjectStore, LifecycleModule, ListObjectsOptions, ListObjectsResult, Logger, LoggerOptions, LoggingConfig, LoggingConfigSchema, Meter, MetricsOptions, ObjectBody, ObjectRef, ObjectStore, ObjectStoreProvider, ObservabilityModule, OtelConfig, OtelConfigSchema, PresignGetObjectOptions, PresignPutObjectOptions, PutObjectOptions, PutObjectResult, REDACT_PATHS, RedactionConfig, RedactionConfigSchema, RequestContext, RequestLoggingConfig, RequestLoggingConfigSchema, RequestLoggingOptions, ShutdownConfig, ShutdownConfigSchema, SpanStatusCode, Tracer, TracingOptions, buildPinoRedactConfig, context, createContextManager, createFallbackLogger, createFoundation, createHttpClient, createLogger, createObservabilityPlugin, getActiveSpan, getDefaultOtelEndpoint, getGlobalLogger, getMeter, getTraceContext, getTracer, isMetricsEnabled, isTracingEnabled, metrics, parseConfig, propagation, sanitizeBody, setGlobalLogger, setupMetrics, setupObservability, setupTracing, shutdownMetrics, shutdownTracing, trace };
 //# sourceMappingURL=index.d.mts.map