@tsdevstack/nest-common 0.1.4

package/dist/secrets/providers/cloud-provider-adapter.d.ts

@@ -0,0 +1,50 @@
+import { SecretsProvider } from '../secrets.interface';
+import { CloudSecretsProvider } from './cloud-provider.interface';
+/**
+ * Adapter to make CloudSecretsProvider compatible with SecretsProvider interface
+ *
+ * The CloudSecretsProvider interface is designed for cloud-native operations
+ * (get, set, remove, list, exists) while SecretsProvider is the legacy interface
+ * used throughout the application.
+ *
+ * This adapter bridges the two interfaces, allowing cloud providers to work
+ * with the existing SecretsService implementation.
+ */
+export declare class CloudProviderAdapter implements SecretsProvider {
+    private cloudProvider;
+    private serviceName;
+    constructor(cloudProvider: CloudSecretsProvider, serviceName: string);
+    /**
+     * Get a single secret by key
+     * Delegates to cloud provider's get() which handles service-scoped → shared fallback
+     */
+    get(key: string): Promise<string>;
+    /**
+     * Get all secrets for a service
+     * Lists all secrets and filters by service name
+     *
+     * Note: This is less efficient than the local provider's getAll()
+     * since cloud providers need to fetch each secret individually.
+     * Consider caching at the application level if this becomes a bottleneck.
+     */
+    getAll(): Promise<Record<string, string>>;
+    /**
+     * Set a secret value
+     * Adds metadata to indicate it's a user-managed secret
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Delete a secret
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Get provider name
+     */
+    getName(): string;
+    /**
+     * Clear cache
+     * Cloud providers don't expose cache clearing, so this is a no-op
+     * The cache will expire naturally based on TTL
+     */
+    clearCache(): void;
+}

package/dist/secrets/providers/cloud-provider-adapter.test.d.ts

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

package/dist/secrets/providers/cloud-provider.interface.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Cloud Secrets Provider Interface
+ *
+ * Common interface for all cloud secret providers (GCP, AWS, Azure).
+ * Providers handle cloud-specific API calls and caching.
+ */
+export interface CloudSecretsProvider {
+    /**
+     * Get secret value by key
+     *
+     * Provider handles:
+     * - Service-scoped lookup: {project}-{service}-{key}
+     * - Shared fallback: {project}-shared-{key}
+     * - Caching (5-minute TTL)
+     *
+     * @param key Secret key (e.g., 'DATABASE_URL')
+     * @returns Secret value or null if not found
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set secret value
+     *
+     * Provider determines scope (service vs shared) and creates/updates secret.
+     *
+     * @param key Secret key
+     * @param value Secret value
+     * @param metadata Optional metadata tags/labels
+     */
+    set(key: string, value: string, metadata?: Record<string, string>): Promise<void>;
+    /**
+     * Remove secret from cloud
+     *
+     * @param key Secret key
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * List all secret keys managed by tsdevstack
+     *
+     * Filters by: managed-by=tsdevstack
+     *
+     * @returns Array of secret keys (without project/scope prefix)
+     */
+    list(): Promise<string[]>;
+    /**
+     * Check if secret exists in cloud
+     *
+     * @param key Secret key
+     * @returns True if exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Get provider name
+     *
+     * @returns 'gcp' | 'aws' | 'azure' | 'local'
+     */
+    getProviderName(): string;
+}
+/**
+ * Configuration for cloud providers
+ */
+export interface CloudProviderConfig {
+    /**
+     * Project name from .tsdevstack/config.json
+     * Used as prefix for all secrets
+     */
+    projectName: string;
+    /**
+     * Service name (e.g., 'auth-service', 'bff-service')
+     * Used for service-scoped secrets
+     */
+    serviceName: string;
+    /**
+     * Provider-specific configuration
+     * - GCP: { projectId, credentialsPath }
+     * - AWS: { region, credentialsPath }
+     * - Azure: { vaultUrl, credentialsPath }
+     */
+    providerConfig?: Record<string, unknown>;
+}
+/**
+ * Cache entry for secret values
+ */
+export interface CacheEntry {
+    value: string;
+    expiresAt: number;
+}

package/dist/secrets/providers/gcp.provider.d.ts

@@ -0,0 +1,64 @@
+import { CloudSecretsProvider, CloudProviderConfig } from './cloud-provider.interface';
+export declare class GCPSecretsProvider implements CloudSecretsProvider {
+    private readonly logger;
+    private client;
+    private projectName;
+    private serviceName;
+    private gcpProjectId;
+    private cache;
+    private readonly CACHE_TTL_MS;
+    constructor(config: CloudProviderConfig);
+    /**
+     * Get secret with service-scoped → shared fallback and caching
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a secret with optional metadata labels
+     */
+    set(key: string, value: string, metadata?: Record<string, string>): Promise<void>;
+    /**
+     * Remove a secret
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * List all secrets for this service (both service-scoped and shared)
+     */
+    list(): Promise<string[]>;
+    /**
+     * Check if a secret exists (checks both service-scoped and shared)
+     */
+    exists(key: string): Promise<boolean>;
+    getProviderName(): string;
+    /**
+     * Build secret name following convention: {projectName}-{scope}-{KEY}
+     */
+    private buildSecretName;
+    /**
+     * Extract secret ID from full secret name
+     * Input: "tsdevstack-auth-service-DATABASE_URL"
+     * Output: "tsdevstack-auth-service-DATABASE_URL"
+     */
+    private extractSecretId;
+    /**
+     * Extract key from secret ID
+     * Input: "tsdevstack-auth-service-DATABASE_URL"
+     * Output: "DATABASE_URL"
+     */
+    private extractKeyFromSecretId;
+    /**
+     * Fetch secret value from GCP
+     */
+    private fetchSecretFromGCP;
+    /**
+     * Build GCP labels from metadata
+     * GCP supports up to 64 labels per secret
+     */
+    private buildLabels;
+    /**
+     * Cache management methods
+     */
+    private getFromCache;
+    private setCache;
+    private isUrlValue;
+    private invalidateCache;
+}

package/dist/secrets/providers/gcp.provider.test.d.ts

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

package/dist/secrets/providers/local.provider.d.ts

@@ -0,0 +1,82 @@
+import { SecretsProvider } from "../secrets.interface";
+/**
+ * Local Secrets Provider
+ *
+ * Reads secrets from .secrets.local.json file in the project root.
+ * Implements caching with 1-minute TTL for performance.
+ *
+ * File format:
+ * {
+ *   "auth-service": {
+ *     "DATABASE_URL": "postgresql://...",
+ *     "AUTH_SECRET": "..."
+ *   },
+ *   "shared": {
+ *     "API_KEY": "...",
+ *     "REDIS_PASSWORD": "..."
+ *   }
+ * }
+ */
+export declare class LocalSecretsProvider implements SecretsProvider {
+    private secrets;
+    private secretsFilePath;
+    private cache;
+    private serviceCache;
+    private readonly cacheTtl;
+    private serviceName?;
+    constructor(secretsFilePath?: string, cacheTtl?: number);
+    /**
+     * Set the service name for scoped secret access
+     * Used when getting secrets without specifying service name
+     *
+     * Also injects DATABASE_URL into process.env for Prisma
+     * (Prisma schema uses env("DATABASE_URL") before SecretsService is available)
+     */
+    setServiceName(serviceName: string): void;
+    /**
+     * Find the project root by looking for .secrets.local.json
+     * Walks up the directory tree from current working directory
+     */
+    private findProjectRoot;
+    /**
+     * Load and parse the secrets file
+     */
+    private loadSecretsFile;
+    /**
+     * Get all secrets for a service
+     *
+     * All references are pre-resolved in .secrets.local.json, so we just load the values directly.
+     * No need to resolve "secrets" array - it doesn't exist in the final merged file.
+     *
+     * Note: All secrets are now flat (no nested objects like REDIS)
+     */
+    getAll(serviceName: string): Promise<Record<string, string>>;
+    /**
+     * Get provider name
+     */
+    getName(): string;
+    /**
+     * Get the path to the secrets file (for debugging)
+     */
+    getSecretsFilePath(): string;
+    /**
+     * Get a single secret by key with caching
+     * Searches in current service's secrets or top-level secrets
+     */
+    get(key: string): Promise<string>;
+    /**
+     * Set a secret value
+     * Updates .secrets.user.json and triggers regeneration
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Delete a secret
+     * Removes from .secrets.user.json and triggers regeneration
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all cached secrets
+     * Forces next get() to reload from file
+     */
+    clearCache(): void;
+}

package/dist/secrets/providers/local.provider.test.d.ts

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

package/dist/secrets/providers/provider-factory.d.ts

@@ -0,0 +1,39 @@
+import { CloudSecretsProvider } from './cloud-provider.interface';
+export type SecretsProviderType = 'local' | 'gcp' | 'aws' | 'azure';
+/**
+ * Factory for creating cloud secrets providers
+ *
+ * IMPORTANT: This runtime factory ONLY reads environment variables.
+ * It does NOT read files or configs. All configuration must be set via env vars.
+ *
+ * Required environment variables:
+ * - SECRETS_PROVIDER: 'local' | 'gcp' | 'aws' | 'azure'
+ * - PROJECT_NAME: Your project name (required for cloud providers)
+ * - SERVICE_NAME: Set by bootstrap
+ *
+ * Provider-specific env vars:
+ * - GCP: GCP_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS (or K_SERVICE on Cloud Run)
+ * - AWS: AWS_REGION (credentials from task role on ECS, or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY)
+ * - Azure: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID, AZURE_KEYVAULT_NAME
+ *
+ * The CLI (cloud:init, cloud-secrets:*) handles all file operations.
+ * Runtime just reads env vars and fails fast if missing.
+ */
+export declare class SecretsProviderFactory {
+    /**
+     * Create a secrets provider based on environment variables ONLY
+     */
+    static createProvider(serviceName: string): CloudSecretsProvider | null;
+    /**
+     * Get provider type from environment variable ONLY
+     */
+    private static getProviderType;
+    /**
+     * Get project name from environment variable ONLY
+     */
+    private static getProjectName;
+    /**
+     * Validate provider-specific environment variables
+     */
+    private static validateProviderEnvVars;
+}

package/dist/secrets/providers/provider-factory.test.d.ts

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

package/dist/secrets/secrets.interface.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Secrets Provider Interface
+ *
+ * All secret providers (local, AWS, GCP, Azure) must implement this interface.
+ */
+export interface SecretsProvider {
+    /**
+     * Get all secrets for a specific service
+     * @param serviceName - The name of the service (e.g., 'auth-service', 'shared')
+     * @returns Object containing all secrets for the service
+     */
+    getAll(serviceName: string): Promise<Record<string, string>>;
+    /**
+     * Get a single secret by key
+     * Supports caching with TTL for performance
+     * @param key - The secret key to retrieve
+     * @returns The secret value
+     * @throws Error if secret not found
+     */
+    get(key: string): Promise<string>;
+    /**
+     * Set a secret value
+     * For local provider: Updates .secrets.user.json and triggers regeneration
+     * For cloud providers: Updates the secret in the cloud provider
+     * @param key - The secret key
+     * @param value - The secret value
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Delete a secret
+     * For local provider: Removes from .secrets.user.json and triggers regeneration
+     * For cloud providers: Deletes from the cloud provider
+     * @param key - The secret key to delete
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Get the provider name (for logging/debugging)
+     */
+    getName(): string;
+    /**
+     * Clear any cached secrets
+     * Forces next get() to reload from source
+     */
+    clearCache(): void;
+}
+/**
+ * Cloud provider types supported by the framework
+ */
+export type CloudProvider = 'local' | 'aws' | 'gcp' | 'azure';
+/**
+ * Secrets strategy types
+ */
+export type SecretsStrategy = 'local' | 'aws-secrets-manager' | 'gcp-secret-manager' | 'azure-key-vault';
+/**
+ * Configuration for secrets service
+ */
+export interface SecretsConfig {
+    /**
+     * The service name (e.g., 'auth-service')
+     */
+    serviceName: string;
+    /**
+     * Path to framework config file (for detecting cloud provider)
+     * @default '.tsdevstack/config.json'
+     */
+    configPath?: string;
+    /**
+     * Force a specific provider (useful for testing)
+     * If not specified, provider is auto-detected
+     */
+    forceProvider?: SecretsProvider;
+}
+/**
+ * Result of loading secrets
+ */
+export interface SecretsLoadResult {
+    /**
+     * Whether secrets were loaded successfully
+     */
+    success: boolean;
+    /**
+     * The provider that was used
+     */
+    provider: string;
+    /**
+     * Number of secrets loaded
+     */
+    count: number;
+    /**
+     * Error message if loading failed
+     */
+    error?: string;
+}

package/dist/secrets/secrets.module.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Secrets Module
+ *
+ * Global module that provides SecretsService for runtime secret access.
+ * Automatically available in all modules without importing.
+ *
+ * Usage in any service:
+ * ```typescript
+ * @Injectable()
+ * export class MyService {
+ *   constructor(private secrets: SecretsService) {}
+ *
+ *   async doSomething() {
+ *     const apiKey = await this.secrets.get('API_KEY');
+ *     // Cached for 1 minute, refreshes automatically
+ *   }
+ * }
+ * ```
+ *
+ * Note: This module must be imported in AppModule for dependency injection to work.
+ * The SecretsService is then available globally in all services.
+ */
+export declare class SecretsModule {
+}

package/dist/secrets/secrets.service.d.ts

@@ -0,0 +1,70 @@
+import type { SecretsProvider } from './secrets.interface';
+import type { SecretsConfig } from './secrets.interface';
+/**
+ * Secrets Service
+ *
+ * Service for runtime secret access through provider abstraction.
+ * Detects provider based on SECRETS_PROVIDER environment variable.
+ *
+ * Usage pattern:
+ * ```typescript
+ * @Injectable()
+ * class MyService {
+ *   constructor(private secrets: SecretsService) {}
+ *
+ *   async doSomething() {
+ *     const apiKey = await this.secrets.get('API_KEY');
+ *     // Cached for 1 minute (local), 5 minutes (cloud)
+ *   }
+ * }
+ * ```
+ *
+ * IMPORTANT: Apps should NEVER use process.env to access secrets.
+ * Always inject SecretsService and use await this.secrets.get('KEY').
+ *
+ * Requires SECRETS_PROVIDER env var to be set to: local, aws, gcp, or azure
+ */
+export declare class SecretsService {
+    private provider;
+    private config;
+    constructor(config: SecretsConfig);
+    /**
+     * Get the current provider
+     */
+    getProvider(): SecretsProvider;
+    /**
+     * Get a single secret by key with caching
+     * Supports runtime secret refresh (cached for 1 minute in local provider)
+     *
+     * @param key - The secret key to retrieve
+     * @returns The secret value
+     * @throws Error if secret not found
+     */
+    get(key: string): Promise<string>;
+    /**
+     * Set a secret value
+     * For local provider: Updates .secrets.user.json and triggers regeneration
+     * For cloud providers: Updates the secret in the cloud provider
+     *
+     * @param key - The secret key
+     * @param value - The secret value
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Delete a secret
+     * For local provider: Removes from .secrets.user.json and triggers regeneration
+     * For cloud providers: Deletes from the cloud provider
+     *
+     * @param key - The secret key to delete
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear any cached secrets
+     * Forces next get() to reload from source
+     */
+    clearCache(): void;
+    /**
+     * Auto-detect which secrets provider to use based on SECRETS_PROVIDER env var
+     */
+    private detectProvider;
+}

package/dist/secrets/secrets.service.test.d.ts

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

package/dist/service-client/base-service-client.d.ts

@@ -0,0 +1,113 @@
+import { Logger } from '@nestjs/common';
+/**
+ * Configuration for initializing a service client.
+ *
+ * @template TApi - The generated API client type (e.g., Api from swagger-typescript-api)
+ */
+export interface ServiceClientConfig<TApi> {
+    /**
+     * The service base URL
+     */
+    baseURL: string;
+    /**
+     * The service API key for authentication
+     */
+    apiKey: string;
+    /**
+     * Factory function to create the API client instance
+     * @param baseURL - The service base URL
+     * @param apiKey - The service API key
+     * @returns Instance of the generated API client
+     */
+    createClient: (baseURL: string, apiKey: string) => TApi;
+}
+/**
+ * Base class for service-to-service HTTP client wrappers.
+ *
+ * This class standardizes the pattern for initializing generated TypeScript API clients
+ * with proper authentication for service-to-service communication.
+ *
+ * ## Features
+ * - Automatic initialization during module init
+ * - API key injection for service-to-service authentication
+ * - Support for JWT forwarding via securityWorker (user context)
+ * - Standardized error handling and logging
+ * - Type-safe client access
+ *
+ * ## Usage
+ *
+ * @example Basic service client
+ * ```typescript
+ * import { Injectable, OnModuleInit } from '@nestjs/common';
+ * import { BaseServiceClient } from '@tsdevstack/nest-common';
+ * import { Api } from '@shared/auth-service-client';
+ * import { SecretsService } from '@tsdevstack/nest-common';
+ *
+ * @Injectable()
+ * export class AuthClientService extends BaseServiceClient<Api<{ token: string }>> implements OnModuleInit {
+ *   constructor(private secrets: SecretsService) {
+ *     super();
+ *   }
+ *
+ *   async onModuleInit(): Promise<void> {
+ *     const baseURL = await this.secrets.get('AUTH_SERVICE_URL');
+ *     const apiKey = await this.secrets.get('AUTH_SERVICE_API_KEY');
+ *
+ *     this.initialize({
+ *       baseURL,
+ *       apiKey,
+ *       createClient: (baseURL, apiKey) =>
+ *         new Api({
+ *           baseURL,
+ *           headers: { 'x-api-key': apiKey },
+ *           securityWorker: (securityData) =>
+ *             securityData?.token
+ *               ? { headers: { Authorization: `Bearer ${securityData.token}` } }
+ *               : {},
+ *         }),
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Using the client in a controller
+ * ```typescript
+ * @Controller('users')
+ * export class UsersController {
+ *   constructor(private authClient: AuthClientService) {}
+ *
+ *   @Get('account')
+ *   async getAccount(@Request() req: AuthenticatedRequest) {
+ *     // Forward user JWT for user-specific requests
+ *     const user = await this.authClient.client.v1.getUserAccount();
+ *     return user.data;
+ *   }
+ *
+ *   @Get('internal')
+ *   async internalOperation() {
+ *     // Service-to-service call (uses API key automatically)
+ *     const result = await this.authClient.client.v1.someInternalEndpoint();
+ *     return result.data;
+ *   }
+ * }
+ * ```
+ *
+ * @template TApi - The generated API client type
+ */
+export declare abstract class BaseServiceClient<TApi> {
+    /**
+     * The initialized API client instance.
+     * Available after initialization.
+     */
+    client: TApi;
+    protected readonly logger: Logger;
+    constructor();
+    /**
+     * Initializes the service client with the provided configuration.
+     * Should be called in the subclass's onModuleInit() method.
+     *
+     * @param config - Configuration containing baseURL, apiKey, and client factory
+     * @throws Error if configuration is invalid
+     */
+    protected initialize(config: ServiceClientConfig<TApi>): void;
+}

package/dist/service-client/base-service-client.test.d.ts

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

package/dist/service-client/filter-forward-headers.d.ts

@@ -0,0 +1,11 @@
+import type { IncomingHttpHeaders } from 'node:http';
+/**
+ * Filters request headers for forwarding in service-to-service calls.
+ *
+ * Use this when making internal service calls to forward authentication
+ * and context headers while excluding headers that would break routing.
+ *
+ * @param headers - The incoming request headers (from Express/NestJS request object)
+ * @returns Filtered headers safe to forward to internal services
+ */
+export declare function filterForwardHeaders(headers: IncomingHttpHeaders): Record<string, string>;

package/dist/service-client/filter-forward-headers.test.d.ts

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

package/dist/telemetry/index.d.ts

@@ -0,0 +1,4 @@
+export { TelemetryModule } from './telemetry.module';
+export { TelemetryService } from './telemetry.service';
+export { TracingInterceptor } from './tracing.interceptor';
+export type { TelemetryModuleOptions } from './telemetry.interface';