@oshun/* Shared Libraries Reference

import { createLogger } from '@oshun/logging';
import { OshunError, NotFoundError } from '@oshun/errors';
import { sql, createPostgresClient } from '@oshun/database';

                        +--------------+
                        | @oshun/types  |  (zero dependencies, foundation)
                        +------+-------+
                               |
              +----------------+----------------+
              |                |                |
       +------v------+  +-----v------+  +------v------+
       | @oshun/errors|  |@oshun/config|  |@oshun/health|
       +------+------+  +-----+------+  +------+------+
              |                |
              |    +-----------+
              |    |
       +------v----v--+
       |@oshun/logging |
       +------+-------+
              |
     +--------+--------+
     |                  |
+----v------+    +------v-----+
|@oshun/    |    |@oshun/     |
|metrics    |    |tracing     |
+----+------+    +------+-----+
     |                  |
     |    +-------------+
     |    |
+----v----v---+     +-------------+     +------------------+
|@oshun/      |     |@oshun/      |     |@oshun/           |
|database     |     |cache        |     |http-client       |
+----+--------+     +------+------+     +--------+---------+
     |                     |                     |
     |    +----------------+                     |
     |    |                                      |
+----v----v---+   +------------+   +-------------v-----------+
|@oshun/      |   |@oshun/     |   |@oshun/runpod-client     |
|security     |   |queue       |   +-----------+-------------+
+-------------+   +------+-----+               |
                         |          +-----------v-----------+
                  +------v------+   |@oshun/gpu-dispatcher  |
                  |@oshun/      |   +-----------------------+
                  |event-bus    |
                  +------+------+
                         |
              +----------+----------+
              |                     |
   +----------v-------+   +--------v-----------+
   |@oshun/            |   |@oshun/             |
   |service-discovery  |   |websocket           |
   +-------------------+   +--------------------+

+-------------------+     +-------------------+
|@oshun/            |     |@oshun/            |
|auth-primitives    +---->+auth               |
+-------------------+     +-------------------+

+-------------------+     +-------------------+
|@oshun/ai          +---->+@oshun/ai-advanced |
+-------------------+     +-------------------+

Standalone / minimal dependencies:
  @oshun/identity
  @oshun/traefik-config
  @oshun/migration
  @oshun/infrastructure
  @oshun/rate-limit
  @oshun/testing

import { type UserID, type ProjectID, type AssetID } from '@oshun/types';

const userId = 'user-abc' as UserID;
const projectId = 'proj-123' as ProjectID;
// TypeScript error: Type 'UserID' is not assignable to type 'ProjectID'

import { type Result, type AsyncResult } from '@oshun/types';

function divide(a: number, b: number): Result<number, string> {
  if (b === 0) return { success: false, error: 'Division by zero' };
  return { success: true, data: a / b };
}

import {
  type BaseEntity,
  type SoftDeletable,
  type Versioned,
} from '@oshun/types';

// Compose entity shapes
type MyEntity = BaseEntity & SoftDeletable & Versioned;

OshunError (base)
├── BadRequestError (400)
├── UnauthorizedError (401)
├── PaymentRequiredError (402)
├── ForbiddenError (403)
├── NotFoundError (404)
├── MethodNotAllowedError (405)
├── ConflictError (409)
├── GoneError (410)
├── UnprocessableEntityError (422)
├── TooManyRequestsError (429)
├── InternalServerError (500)
├── NotImplementedError (501)
├── BadGatewayError (502)
├── ServiceUnavailableError (503)
├── GatewayTimeoutError (504)
├── ValidationError
├── AuthenticationError / TokenExpiredError / SessionError
├── AuthorizationError
├── ResourceNotFoundError / DuplicateError / VersionConflictError
├── RateLimitError
├── ExternalServiceError / DatabaseError / CacheError / QueueError
├── AIServiceError / GenerationError
├── InvalidStateError / PreconditionError / LimitExceededError
└── AggregateError (wraps multiple errors)

import { ERROR_CODES, GENERAL_ERRORS, AUTH_ERRORS } from '@oshun/errors';

// ERROR_CODES.NOT_FOUND, ERROR_CODES.UNAUTHORIZED, etc.
// AUTH_ERRORS.TOKEN_EXPIRED, AUTH_ERRORS.INVALID_CREDENTIALS, etc.

import { NotFoundError, ValidationError, ConflictError } from '@oshun/errors';

throw new NotFoundError('User not found');
throw new ValidationError('Invalid input', {
  fields: { email: ['Must be a valid email'] },
});
throw new ConflictError('Username already taken');

import {
  isOshunError,
  isClientError,
  isServerError,
  wrapError,
  ensureError,
  catchAsync,
  tryCatch,
  getErrorChain,
  createErrorResponse,
  createSafeErrorResponse,
  formatErrorForLogging,
} from '@oshun/errors';

// Wrap unknown caught values into OshunError
try {
  await riskyOperation();
} catch (err) {
  throw wrapError(err, 'Failed during operation');
}

// Async route handler wrapper (catches thrown errors)
app.get(
  '/users/:id',
  catchAsync(async (req, res) => {
    const user = await getUser(req.params.id);
    res.json(user);
  })
);

// Result-style error handling
const [error, result] = await tryCatch(fetchUser(id));
if (error) {
  return createSafeErrorResponse(error); // strips internal details
}

import {
  getEnv,
  getEnvRequired,
  getEnvNumber,
  getEnvBool,
  getEnvArray,
  getEnvJson,
  getEnvUrl,
  getEnvironment,
  isProduction,
  isDevelopment,
  isTest,
  getLogLevel,
  getPort,
} from '@oshun/config';

const apiKey = getEnv('API_KEY'); // string | undefined
const dbUrl = getEnvRequired('DATABASE_URL'); // string (throws if missing)
const port = getEnvNumber('PORT', 3000); // number with default
const debug = getEnvBool('DEBUG', false); // boolean with default
const origins = getEnvArray('CORS_ORIGINS', ','); // string[]
const config = getEnvJson<MyConfig>('APP_CONFIG'); // parsed JSON

import {
  databaseConfigSchema,
  serverConfigSchema,
  redisConfigSchema,
  aiConfigSchema,
  validateConfig,
} from '@oshun/config';

// Validate environment against schema
const dbConfig = validateConfig(databaseConfigSchema, {
  url: process.env.DATABASE_URL,
  pool: { min: 2, max: 10 },
});

import {
  loadServiceConfig,
  loadDatabaseConfig,
  loadRedisConfig,
  loadStorageConfig,
  loadAuthConfig,
  loadAIConfig,
  createConfigLoader,
} from '@oshun/config';

const service = loadServiceConfig('my-service');
// Returns: { name, version, port, host, env, logging, database, redis, ... }

// Custom loader for domain-specific config
const loadMyConfig = createConfigLoader(myConfigSchema, (env) => ({
  apiKey: env.MY_API_KEY,
  maxRetries: parseInt(env.MAX_RETRIES || '3'),
}));

import {
  isFeatureEnabled,
  getFeatureValue,
  shouldUseRunPod,
  getRunPodConfig,
  FeatureFlags,
} from '@oshun/config';

if (isFeatureEnabled('USE_RUNPOD_GPU')) {
  const rpConfig = getRunPodConfig();
  // rpConfig.apiKey, rpConfig.endpointId, etc.
}

import { createLogger, log, OshunLogger } from '@oshun/logging';

// Create a service-specific logger
const logger = createLogger({
  service: 'api-gateway',
  version: '1.2.0',
  level: 'info', // 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
});

logger.info('Server started', { port: 3000 });
logger.error(new Error('Connection failed'), 'Database error');
logger.warn('Deprecation', { endpoint: '/v1/old' });

// Child logger with persistent context
const reqLogger = logger.child({ requestId: 'req-abc-123' });
reqLogger.info('Processing request'); // includes requestId in every line

// Global logger (initialized once, used everywhere)
import { initializeLogger, log } from '@oshun/logging';
initializeLogger({ service: 'worker', level: 'debug' });
log.info('Worker started');

import {
  createFileTransport,
  createElasticsearchTransport,
  createHttpTransport,
  createTcpTransport,
  createConsoleTransport,
} from '@oshun/logging/transports';

const logger = createLogger({
  service: 'api',
  transports: [
    createFileTransport({ path: './logs/app.log', rotate: true }),
    createElasticsearchTransport({
      url: 'https://es.example.com',
      index: 'app-logs',
      apiKey: '...',
    }),
  ],
});

import { expressRequestLogger } from '@oshun/logging/middleware';

app.use(
  expressRequestLogger(logger, {
    ignorePaths: ['/health', '/metrics'],
    logBody: true,
  })
);

import {
  createFixedRateSampler,
  createSamplingTransport,
} from '@oshun/logging/sampling';

const sampler = createFixedRateSampler({
  rate: 0.1, // 10% of log entries
  alwaysLogLevels: ['error', 'fatal'],
});

import {
  createRegistry,
  counter,
  gauge,
  histogram,
  summary,
  initializeRegistry,
} from '@oshun/metrics';

// Initialize a global registry
initializeRegistry({ prefix: 'myservice_' });

// Create metrics (auto-registered in global registry)
const requestsTotal = counter({
  name: 'http_requests_total',
  help: 'Total HTTP requests',
  labelNames: ['method', 'path', 'status'],
});

const requestDuration = histogram({
  name: 'http_request_duration_seconds',
  help: 'HTTP request duration',
  labelNames: ['method', 'path'],
  buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
});

const activeConnections = gauge({
  name: 'active_connections',
  help: 'Current active connections',
});

import {
  createHttpMetrics,
  recordHttpRequest,
  createDbMetrics,
  recordDbQuery,
  createCacheMetrics,
  recordCacheOperation,
  createAiMetrics,
  recordAiRequest,
  createQueueMetrics,
  recordJobCompletion,
  createTimer,
  measureDuration,
} from '@oshun/metrics';

// HTTP metrics (auto-creates counter + histogram)
const httpMetrics = createHttpMetrics({ prefix: 'api_' });
recordHttpRequest(httpMetrics, {
  method: 'GET',
  path: '/users',
  status: 200,
  durationMs: 45,
});

// Timer utility
const timer = createTimer();
await doWork();
const elapsed = timer(); // returns milliseconds

import { createMetricsServer, startMetricsServer } from '@oshun/metrics';

// Expose /metrics endpoint on port 9090
const server = createMetricsServer({ port: 9090, path: '/metrics' });
await startMetricsServer();

import { createTracer, initializeTracer } from '@oshun/tracing';

// Initialize global tracer
initializeTracer({
  serviceName: 'api-gateway',
  serviceVersion: '1.0.0',
  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
  sampler: { type: 'ratio', ratio: 0.1 }, // Sample 10%
});

import {
  withSpan,
  traceServiceCall,
  traceDatabaseCall,
  traceExternalApiCall,
  traceAiCall,
  traceJob,
  traceBatch,
} from '@oshun/tracing';

// Wrap any async function with a span
const user = await withSpan('get-user', async (span) => {
  span.setAttribute('user.id', userId);
  return await db.getUser(userId);
});

// Trace a database call
const rows = await traceDatabaseCall(
  {
    system: 'postgresql',
    operation: 'SELECT',
    table: 'users',
  },
  () => db.query('SELECT * FROM users')
);

// Trace an AI request
const response = await traceAiCall(
  {
    model: 'claude-3-opus',
    provider: 'anthropic',
  },
  () => llm.complete(prompt)
);

import {
  createExpressTracingMiddleware,
  createFastifyTracingPlugin,
  createHonoTracingMiddleware,
  createKoaTracingMiddleware,
  createTracedFetch,
} from '@oshun/tracing';

// Express
app.use(createExpressTracingMiddleware({ serviceName: 'api' }));

// Hono
app.use('*', createHonoTracingMiddleware({ serviceName: 'api' }));

// Outbound: propagate trace context through fetch calls
const tracedFetch = createTracedFetch(fetch);
const response = await tracedFetch('https://internal-service/api');

import {
  extractTraceContext,
  injectTraceContext,
  generateTraceId,
  generateSpanId,
  generateCorrelationId,
} from '@oshun/tracing';

// Extract from incoming headers
const context = extractTraceContext(request.headers);

// Inject into outgoing headers
const headers = {};
injectTraceContext(headers);

import {
  createXRayTracerConfig,
  otelToXRayTraceId,
  fetchECSMetadata,
} from '@oshun/tracing/xray';

const config = createXRayTracerConfig({
  serviceName: 'api',
  region: 'us-east-1',
});

import {
  createHealthManager,
  healthy,
  degraded,
  unhealthy,
} from '@oshun/health';

const health = createHealthManager({ cacheDuration: 5000 });

// Register health checks
health.register('database', async () => {
  try {
    await db.query('SELECT 1');
    return healthy({ latencyMs: 5 });
  } catch (err) {
    return unhealthy({ error: err.message });
  }
});

health.register('redis', async () => {
  const latency = await redis.ping();
  return latency < 100
    ? healthy({ latencyMs: latency })
    : degraded({ latencyMs: latency });
});

// Run all checks
const report = await health.check();
// { status: 'healthy', checks: [...], uptime: 3600, ... }

import { createProbeHandlers } from '@oshun/health';

const probes = createProbeHandlers(healthManager);

// Attach to your HTTP server
app.get('/healthz', probes.liveness);
app.get('/readyz', probes.readiness);
app.get('/startupz', probes.startup);

import {
  createDependencyAggregator,
  createDatabaseCheck,
  createCacheCheck,
  createQueueCheck,
  createApiCheck,
} from '@oshun/health';

const aggregator = createDependencyAggregator();
aggregator.add(createDatabaseCheck('postgres', pgClient));
aggregator.add(createCacheCheck('redis', redisClient));
aggregator.add(
  createApiCheck('payment-service', 'https://payments.internal/health')
);

import {
  createPostgresClient,
  createPostgresClientFromUrl,
  createPostgresClientFromEnv,
} from '@oshun/database';

const db = createPostgresClient({
  host: 'localhost',
  port: 5432,
  database: 'oshun_dev',
  user: 'oshun',
  password: 'oshun_dev',
  pool: { min: 2, max: 10 },
});

const result = await db.query('SELECT * FROM users WHERE id = $1', [
  'user-123',
]);

import { sql, sqlRaw, sqlJoin, sqlEmpty } from '@oshun/database';

const userId = 'user-123';
const query = sql`SELECT * FROM users WHERE id = ${userId}`;
// { text: 'SELECT * FROM users WHERE id = $1', values: ['user-123'] }

// Raw SQL (no parameterization -- use for trusted identifiers only)
const table = sqlRaw('users');
const q = sql`SELECT * FROM ${table} WHERE active = ${true}`;

// Join multiple conditions
const conditions = [sql`status = ${status}`, sql`role = ${role}`];
const where = sqlJoin(conditions, ' AND ');
const fullQuery = sql`SELECT * FROM users WHERE ${where}`;

import {
  buildWhereClause,
  buildOrderByClause,
  buildPaginationClause,
  buildInsertStatement,
  buildUpdateStatement,
  buildDeleteStatement,
  sanitizeIdentifier,
  quoteIdentifier,
} from '@oshun/database';

import {
  createRedisClient,
  createRedisClientFromUrl,
  createRedisClusterClient,
} from '@oshun/database';

const redis = createRedisClient({ host: 'localhost', port: 6379 });
await redis.set('key', 'value');
const val = await redis.get('key');

import {
  withTransaction,
  withSerializableTransaction,
  withAdvisoryLock,
  withSavepoint,
} from '@oshun/database';

// Basic transaction
await withTransaction(db, async (tx) => {
  await tx.query(sql`INSERT INTO orders (...) VALUES (...)`);
  await tx.query(sql`UPDATE inventory SET quantity = quantity - 1 WHERE ...`);
});

// Serializable isolation (strongest consistency)
await withSerializableTransaction(db, async (tx) => {
  /* ... */
});

// Advisory locks for distributed mutual exclusion
await withAdvisoryLock(db, 12345, async () => {
  // Only one process can hold this lock at a time
});

import {
  createMigrationRunner,
  createSqlMigration,
  MigrationRunner,
} from '@oshun/database';

const runner = createMigrationRunner(db, { schema: 'public' });

runner.addMigration(
  createSqlMigration(
    '001_create_users',
    'CREATE TABLE users (id UUID PRIMARY KEY, email TEXT UNIQUE)',
    'DROP TABLE users'
  )
);

const summary = await runner.up(); // Apply all pending
await runner.down(1); // Rollback last

import {
  checkPostgresHealth,
  checkRedisHealth,
  createHealthMonitor,
  instrumentPostgresClient,
  PoolStatsMonitor,
} from '@oshun/database';

// One-shot health check
const pgHealth = await checkPostgresHealth(db);
const redisHealth = await checkRedisHealth(redis);

// Continuous monitoring
const monitor = createHealthMonitor({ postgres: db, redis });
monitor.start(5000); // Check every 5 seconds
monitor.on('unhealthy', (info) => console.error('Database unhealthy:', info));

// Instrument for Prometheus metrics
instrumentPostgresClient(db, metricsRegistry);

import {
  parsePostgresConnectionString,
  buildPostgresConnectionString,
  maskPostgresConnectionString,
  detectDatabaseType,
  validateConnectionString,
} from '@oshun/database';

const parsed = parsePostgresConnectionString(
  'postgresql://user:pass@host:5432/db'
);
// { host: 'host', port: 5432, database: 'db', user: 'user', password: 'pass' }

const masked = maskPostgresConnectionString(url);
// 'postgresql://user:****@host:5432/db'

import {
  createRedisClient,
  createRedisClusterClient,
  createCacheClientFromEnv,
  initializeCacheClient,
} from '@oshun/cache';

const cache = createRedisClient({
  host: 'localhost',
  port: 6379,
  keyPrefix: 'myapp:',
});

await cache.set('user:123', JSON.stringify(user), { ttl: 300 });
const data = await cache.get('user:123');
await cache.del('user:123');

import { withRedisCache, withMemoryCache, cachedMethod } from '@oshun/cache';

// Fetch-through cache: returns cached value or calls function and caches result
const user = await withRedisCache(cache, 'user:123', 300, async () => {
  return await db.getUser('123');
});

// In-memory cache (no Redis required)
const config = await withMemoryCache('app-config', 60, async () => {
  return await loadConfig();
});

// Decorator pattern for class methods
class UserService {
  @cachedMethod({ key: (id) => `user:${id}`, ttl: 300 })
  async getUser(id: string) {
    return await db.findUser(id);
  }
}

import {
  cacheKey,
  userKey,
  sessionKey,
  contentKey,
  rateLimitKey,
  lockKey,
  keyPattern,
  parseKey,
  tempKey,
} from '@oshun/cache';

userKey('123'); // 'user:123'
sessionKey('sess-1'); // 'session:sess-1'
contentKey('article', '456'); // 'content:article:456'
lockKey('process-order', 'ord-789'); // 'lock:process-order:ord-789'
keyPattern('user', '*'); // 'user:*'
tempKey('import'); // 'temp:import:a1b2c3'

import { createMemoryCache, OshunMemoryCache } from '@oshun/cache';

const memCache = createMemoryCache({ maxSize: 1000, ttl: 60 });
memCache.set('key', value);
const hit = memCache.get('key');
const stats = memCache.stats(); // { hits, misses, size, hitRate }

import { createLockManager } from '@oshun/cache';

const locks = createLockManager(redisClient);

const lock = await locks.acquire('order-processing:ord-123', {
  ttl: 30000, // 30 seconds
  retries: 5,
  retryDelay: 200,
});

try {
  await processOrder('ord-123');
} finally {
  await lock.release();
}

import { createCircuitBreaker, withCircuitBreaker } from '@oshun/cache';

const breaker = createCircuitBreaker({
  threshold: 5, // Open after 5 failures
  resetTimeout: 30000, // Try again after 30 seconds
  halfOpenMax: 3, // Allow 3 test requests in half-open
});

const result = await withCircuitBreaker(breaker, async () => {
  return await externalService.call();
});

import { createPubSubClient } from '@oshun/cache';

const pubsub = createPubSubClient(redisClient);
await pubsub.subscribe('user:updated', async (message) => {
  console.log('User updated:', message);
});
await pubsub.publish('user:updated', { userId: '123', changes: ['email'] });

import {
  createInvalidationManager,
  invalidateKey,
  invalidatePattern,
  invalidateByPrefix,
} from '@oshun/cache';

const invalidation = createInvalidationManager(cache, pubsub);
await invalidateKey(cache, 'user:123');
await invalidatePattern(cache, 'user:*'); // Wildcard invalidation
await invalidateByPrefix(cache, 'session:'); // All sessions

import { instrumentCacheClient, CacheStatsTracker } from '@oshun/cache';

const instrumented = instrumentCacheClient(cache, metricsRegistry);
// Automatically records hit/miss rates, latency, etc.

import { createS3Client, createMinioClient } from '@oshun/storage';

const storage = createS3Client({
  bucket: 'oshun-assets',
  region: 'us-east-1',
  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
});

// For local development with MinIO
const localStorage = createMinioClient({
  bucket: 'dev-assets',
  endpoint: 'http://localhost:9000',
  accessKeyId: 'minioadmin',
  secretAccessKey: 'minioadmin',
});

// Upload
const result = await storage.upload({
  key: 'uploads/avatar.png',
  body: fileBuffer,
  contentType: 'image/png',
  metadata: { userId: '123' },
});

// Download
const file = await storage.download('uploads/avatar.png');

// List files
const files = await storage.listObjects({
  prefix: 'uploads/',
  maxKeys: 100,
});

// Copy
await storage.copy({
  sourceKey: 'temp/file.pdf',
  destinationKey: 'permanent/file.pdf',
});

// Delete
await storage.delete('temp/file.pdf');

import {
  generateGpuUploadUrl,
  generateGpuDownloadUrl,
  generateBatchUploadUrls,
  createRunPodUploadInstructions,
} from '@oshun/storage';

// Presigned upload URL (for GPU results)
const { url, key } = await generateGpuUploadUrl(storage, {
  jobId: 'job-123',
  outputType: 'image/png',
  expiresIn: 3600,
});

// Presigned download URL
const downloadUrl = await generateGpuDownloadUrl(storage, {
  key: 'results/job-123/output.png',
  expiresIn: 7200,
});

import {
  generateFileKey,
  sanitizeFilename,
  getMimeType,
  isImageMimeType,
  formatBytes,
  parseBytes,
  computeSha256,
  createFileManifest,
} from '@oshun/storage';

const key = generateFileKey({ prefix: 'uploads', filename: 'photo.jpg' });
const mime = getMimeType('photo.jpg'); // 'image/jpeg'
const size = formatBytes(1048576); // '1.00 MB'
const hash = computeSha256(buffer);

import { createLocalStorageClient } from '@oshun/storage';

const localStorage = createLocalStorageClient({
  basePath: '/tmp/oshun-storage',
  baseUrl: 'http://localhost:3000/files',
});

import { createQueue, createWorker } from '@oshun/queue';

// Create a queue
const queue = createQueue('email-jobs', {
  redis: { host: 'localhost', port: 6379 },
});

// Add jobs with priority and retry
await queue.add(
  'send-welcome',
  {
    userId: '123',
    template: 'welcome',
  },
  {
    priority: 'high',
    retry: { maxRetries: 3, backoff: 'exponential', delay: 1000 },
  }
);

// Create a worker
const worker = createWorker(
  'email-jobs',
  async (job, ctx) => {
    await sendEmail(job.data.userId, job.data.template);
    ctx.reportProgress(100);
    return { sent: true };
  },
  {
    concurrency: 5,
    redis: { host: 'localhost', port: 6379 },
  }
);

import { createDeadLetterQueue } from '@oshun/queue';

const dlq = createDeadLetterQueue('email-jobs', {
  maxEntries: 10000,
  retentionDays: 30,
});

// List failed jobs
const failed = await dlq.list({ limit: 50 });

// Retry a failed job
await dlq.retry(failed[0].id);

// Get DLQ statistics
const stats = await dlq.stats();
// { total: 42, byReason: { timeout: 12, validation: 30 }, ... }

import {
  createMemoryQueue,
  createMemoryWorker,
  createMemoryDeadLetterQueue,
  clearAllMemoryStores,
} from '@oshun/queue';

const queue = createMemoryQueue('test-jobs');
const worker = createMemoryWorker('test-jobs', async (job) => {
  return { processed: true };
});

// In test teardown
clearAllMemoryStores();

import { QUEUE_NAMES, PRIORITY_VALUES } from '@oshun/queue';
// QUEUE_NAMES: standard queue names used across the platform
// PRIORITY_VALUES: { low: 10, normal: 5, high: 2, critical: 1 }

import {
  createHttpClient,
  createSimpleHttpClient,
  createResilientHttpClient,
} from '@oshun/http-client';

// Full-featured client
const client = createHttpClient({
  baseUrl: 'https://api.example.com',
  timeout: 30000,
  retry: { maxRetries: 3, backoff: 'exponential' },
  circuitBreaker: { threshold: 5, resetTimeout: 30000 },
});

// Simple client (no retry, no circuit breaker)
const simple = createSimpleHttpClient({ baseUrl: 'https://api.example.com' });

// Resilient client (aggressive retry + circuit breaker)
const resilient = createResilientHttpClient({
  baseUrl: 'https://flaky-service.internal',
});

const users = await client.get('/users', { params: { page: 1, limit: 20 } });
const created = await client.post('/users', {
  name: 'Jane',
  email: 'jane@example.com',
});
const updated = await client.put('/users/123', { name: 'Jane Doe' });
await client.delete('/users/123');

import {
  retry,
  createRetryPolicy,
  defaultRetryPolicy,
  aggressiveRetryPolicy,
  conservativeRetryPolicy,
} from '@oshun/http-client';

// Custom retry
const result = await retry(
  async () => {
    return await unstableService.call();
  },
  {
    maxRetries: 5,
    backoff: 'exponential',
    delay: 1000,
    maxDelay: 30000,
  }
);

import {
  createCircuitBreaker,
  createCircuitBreakerRegistry,
  withCircuitBreaker,
} from '@oshun/http-client';

// Per-service circuit breakers
const registry = createCircuitBreakerRegistry();
const breaker = registry.get('payment-service', {
  threshold: 3,
  resetTimeout: 60000,
});

const result = await withCircuitBreaker(breaker, async () => {
  return await paymentService.charge(amount);
});

import {
  createAuthInterceptor,
  createCorrelationIdInterceptor,
  createTimingInterceptor,
  createLoggingInterceptors,
  createStandardInterceptors,
} from '@oshun/http-client';

const client = createHttpClient({
  baseUrl: 'https://api.internal',
  interceptors: createStandardInterceptors(logger),
  // Includes: auth, correlation ID, timing, logging, error handling
});

import {
  withTimeout,
  createDeadline,
  getRemainingTime,
  combineSignals,
} from '@oshun/http-client';

const result = await withTimeout(5000, async (signal) => {
  return await fetch(url, { signal });
});

import { createEventBus, EventTypes } from '@oshun/event-bus';

const bus = createEventBus({
  redisUrl: process.env.REDIS_URL!,
  sourceDomain: 'isis',
});

// Publish a typed event
await bus.publish(EventTypes.ISIS_ASSET_GENERATED, {
  assetId: 'asset-123',
  projectId: 'proj-456',
  type: 'image',
  url: 'https://cdn.example.com/output.png',
});

// Subscribe with wildcard pattern
await bus.subscribe('isis.asset.*', async (event, ctx) => {
  console.log('Event type:', event.type);
  console.log('Payload:', event.payload);

  // Acknowledge the event
  await ctx.ack();
});

// Subscribe to specific event
await bus.subscribe('yemaya.project.created', async (event, ctx) => {
  await createProjectAssets(event.payload);
  await ctx.ack();
});

interface EventEnvelope {
  id: string; // Unique event ID (nanoid)
  type: string; // e.g., 'isis.asset.generated'
  source: string; // Originating domain
  timestamp: string; // ISO 8601
  correlationId: string;
  causationId?: string; // ID of the event that caused this one
  payload: unknown;
}

const bus = createEventBus({
  redisUrl: process.env.REDIS_URL!,
  sourceDomain: 'isis',
  retry: {
    maxRetries: 3,
    backoff: 'exponential',
    initialDelay: 1000,
  },
  deadLetter: {
    enabled: true,
    maxEntries: 10000,
  },
});

import { createWSServer } from '@oshun/websocket';
import { createServer } from 'http';
import Redis from 'ioredis';

const httpServer = createServer();
const redis = new Redis();

const wsServer = createWSServer(httpServer, redis, {
  requireAuth: true,
  path: '/ws',
  maxPayloadSize: 65536,
});

wsServer.setAuthHandler(async (token) => {
  const verified = await jwtService.verifyToken(token);
  return verified
    ? {
        userId: verified.payload.sub,
        email: verified.payload.email,
        role: verified.payload.role,
      }
    : null;
});

import { createRoomManager, COMMON_CHANNEL_CONFIGS } from '@oshun/websocket';

const rooms = createRoomManager(redis);

// Subscribe a user to a channel
await rooms.subscribe(clientId, 'project:proj-123');

// Broadcast to channel
await wsServer.broadcastToChannel('project:proj-123', {
  type: 'update',
  payload: { field: 'title', value: 'New Title' },
});

import {
  createConnectionLimiter,
  createMessageRateLimiter,
  MESSAGE_RATE_PRESETS,
} from '@oshun/websocket';

const connLimiter = createConnectionLimiter({
  maxConnectionsPerUser: 5,
  maxTotalConnections: 10000,
});

const msgLimiter = createMessageRateLimiter(MESSAGE_RATE_PRESETS.standard);

import { createRedisAdapter } from '@oshun/websocket';

const adapter = createRedisAdapter(redis, {
  serverId: 'ws-server-1',
  heartbeatInterval: 5000,
});

// Messages are broadcast across all WS servers via Redis pub/sub

import {
  createConnectionStateManager,
  createWSMetrics,
} from '@oshun/websocket';

const stateManager = createConnectionStateManager();
const metrics = createWSMetrics();
const snapshot = metrics.snapshot();
// { connections, messages, channels, errors, latency }

import { createServiceDiscovery, ServiceNames } from '@oshun/service-discovery';

const discovery = createServiceDiscovery({
  redisUrl: process.env.REDIS_URL!,
});

// Register a service instance
const instanceId = await discovery.register({
  name: ServiceNames.ISIS_WORKER,
  domain: 'isis',
  host: 'worker-1.isis.internal',
  port: 8080,
  protocol: 'http',
  version: '1.0.0',
  tags: ['gpu', 'a100'],
  healthCheck: { path: '/health', interval: 10000 },
});

// Discover a service (with load balancing)
const url = await discovery.getServiceUrl(ServiceNames.SOPHIA_RAG);
// 'http://rag-2.sophia.internal:8080'

// Watch for service changes
const unwatch = discovery.watch(ServiceNames.ISIS_WORKER, (event, instance) => {
  if (event === 'removed') {
    console.log('Worker went down:', instance.host);
  }
});

// Deregister on shutdown
await discovery.deregister(instanceId);

import { service, route, gateway } from '@oshun/traefik-config';

const myService = service('isis-api')
  .scope('isis')
  .url('http://isis-api:4000')
  .healthCheck('/health')
  .loadBalancing('round-robin')
  .build();

const myRoute = route('isis-assets')
  .path('/api/v1/assets/*')
  .methods(['GET', 'POST', 'PUT', 'DELETE'])
  .service('isis-api')
  .auth('required')
  .rateLimit('standard')
  .build();

const config = gateway().addService(myService).addRoute(myRoute).build();

import {
  YEMAYA_SERVICES,
  YEMAYA_ROUTES,
  ISIS_SERVICES,
  ISIS_ROUTES,
  SOPHIA_SERVICES,
  SOPHIA_ROUTES,
  HATHOR_SERVICES,
  HATHOR_ROUTES,
  BELLONA_SERVICES,
  BELLONA_ROUTES,
  LILITH_SERVICES,
  LILITH_ROUTES,
  SHARED_SERVICES,
  SHARED_ROUTES,
  getAllServices,
  getAllRoutes,
} from '@oshun/traefik-config';

import { generateTraefikConfigs } from '@oshun/traefik-config';

const { staticConfig, dynamicConfig } = generateTraefikConfigs(gatewayConfig);
// Write to traefik.yml and dynamic-config.yml

import {
  createHmacJwtService,
  createRsaJwtService,
  parseAuthorizationHeader,
  createAuthorizationHeader,
} from '@oshun/auth-primitives';

// HMAC-based JWT (shared secret)
const jwt = createHmacJwtService({
  secret: process.env.JWT_SECRET!,
  issuer: 'oshun',
  audience: ['api'],
  accessTokenTtl: 900, // 15 minutes
  refreshTokenTtl: 604800, // 7 days
});

const token = await jwt.sign({ sub: 'user-123', role: 'admin' });
const payload = await jwt.verify(token);

// RSA-based JWT (asymmetric keys)
const rsaJwt = createRsaJwtService({
  privateKey: process.env.JWT_PRIVATE_KEY!,
  publicKey: process.env.JWT_PUBLIC_KEY!,
  algorithm: 'RS256',
});

// Extract token from Authorization header
const token = parseAuthorizationHeader('Bearer eyJhbGciOi...');

import {
  createPasswordHasher,
  createPasswordValidator,
  generatePassword,
  DEFAULT_PASSWORD_POLICY,
} from '@oshun/auth-primitives';

const hasher = createPasswordHasher();
const hash = await hasher.hash('SecureP@ss123');
const valid = await hasher.verify('SecureP@ss123', hash);

const validator = createPasswordValidator(DEFAULT_PASSWORD_POLICY);
const result = validator.validate('weak'); // { valid: false, errors: [...] }

const generated = generatePassword({ length: 20, symbols: true });

import {
  createSessionManager,
  createInMemorySessionStore,
} from '@oshun/auth-primitives';

const sessions = createSessionManager(createInMemorySessionStore(), {
  ttl: 3600,
  maxSessions: 5,
});

const session = await sessions.create({
  userId: 'user-123',
  device: { userAgent: req.headers['user-agent'], ip: req.ip },
});

const active = await sessions.get(session.id);
await sessions.destroy(session.id);
await sessions.destroyAll('user-123'); // Logout everywhere

import {
  createApiKeyManager,
  createInMemoryApiKeyStore,
  extractApiKey,
  maskApiKey,
} from '@oshun/auth-primitives';

const apiKeys = createApiKeyManager(createInMemoryApiKeyStore());

const { key, hashedKey } = await apiKeys.create({
  name: 'Production API Key',
  scopes: ['read:users', 'write:content'],
  expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000),
});

const validated = await apiKeys.validate(key);
console.log(maskApiKey(key)); // 'sk_live_abc...xyz'

import { AuthService, createAuthService } from '@oshun/auth';

const authService = new AuthService(userRepo, tokenRepo, auditRepo, {
  jwt: {
    secret: process.env.JWT_SECRET!,
    algorithm: 'HS256',
    issuer: 'oshun',
    accessTokenTtl: 900,
    refreshTokenTtl: 604800,
  },
  lockout: {
    maxAttempts: 5,
    lockoutDuration: 900000, // 15 minutes
    resetAfter: 3600000, // 1 hour
  },
  emailVerificationRequired: true,
});

// Register
const result = await authService.register({
  email: 'user@example.com',
  username: 'johndoe',
  password: 'SecureP@ss123',
  acceptTerms: true,
});

// Login
const tokens = await authService.login({
  email: 'user@example.com',
  password: 'SecureP@ss123',
});

// Refresh tokens
const newTokens = await authService.refresh(tokens.refreshToken);

import {
  hasMinimumRole,
  hasPermission,
  hasAllPermissions,
  hasAnyPermission,
  ROLE_HIERARCHY,
  ROLE_PERMISSIONS,
} from '@oshun/auth';

// Role hierarchy: guest < user < creator < pro < team < enterprise < admin < super-admin
hasMinimumRole('admin', 'creator'); // true (admin >= creator)

// Permission checks
hasPermission('admin', 'write:users'); // true
hasAllPermissions('user', ['read:content', 'write:content']); // depends on role config

import {
  createAuthMiddleware,
  requireAuth,
  requireRole,
  requirePermissions,
  requireOwnership,
  denySelf,
} from '@oshun/auth';

// Authenticate all routes
app.use(createAuthMiddleware({ authService }));

// Route-specific guards
app.get('/admin', requireRole('admin'), adminHandler);
app.post('/articles', requirePermissions(['write:content']), createArticle);

// Ownership check (user can only edit their own resources)
app.put(
  '/users/:id',
  requireOwnership((req) => req.params.id),
  updateUser
);

// Prevent self-action (e.g., admin can't delete themselves)
app.delete('/users/:id', requireRole('admin'), denySelf(), deleteUser);

import {
  createAccountLockoutManager,
  createDistributedLockoutManager,
} from '@oshun/auth';

// In-memory (single instance)
const lockout = createAccountLockoutManager({
  maxAttempts: 5,
  lockoutDuration: 900000,
});

// Redis-backed (distributed)
const distributedLockout = createDistributedLockoutManager(redisClient, {
  maxAttempts: 5,
  lockoutDuration: 900000,
});

import {
  createJwtService,
  authenticate,
  hasRole,
  hasPermissions,
  extractBearerToken,
  getPermissionsForRole,
} from '@oshun/identity';

const jwtService = createJwtService({
  secret: process.env.JWT_SECRET!,
  issuer: 'oshun',
  audience: ['api'],
});

// Authenticate a request
const result = await authenticate(jwtService, request);
if (result.authenticated) {
  console.log('User:', result.user);
}

// Check role
if (hasRole(result.user, 'admin')) {
  /* ... */
}

// Check specific permissions
if (hasPermissions(result.user, ['write:content', 'publish:content'])) {
  /* ... */
}

import {
  createAuditLogger,
  createMemoryAuditStore,
  createDatabaseAuditStore,
  userActor,
  systemActor,
  auditTarget,
} from '@oshun/security';

const auditLogger = createAuditLogger({
  service: 'api-gateway',
  version: '1.0.0',
  environment: 'production',
  store: createDatabaseAuditStore(dbAdapter),
  batchingEnabled: true,
  batchSize: 100,
  batchFlushInterval: 5000,
});

// Log authentication event
await auditLogger.logAuth(
  'auth.login',
  userActor('user-123', { email: 'user@example.com' }),
  'success',
  'User logged in successfully'
);

// Log data access
await auditLogger.logDataAccess(
  'data.read',
  userActor('user-123'),
  auditTarget('user', 'user-456'),
  'success',
  'Viewed user profile'
);

// Query audit logs
const logs = await auditLogger.query({
  actorId: 'user-123',
  startDate: new Date('2025-01-01'),
  limit: 50,
});

import { createBuiltinScanner } from '@oshun/security';

const scanner = createBuiltinScanner();

// Scan file for threats
const fileResult = await scanner.scanFile('/path/to/upload.pdf');
if (!fileResult.clean) {
  console.log('Threats:', fileResult.threats);
}

// Scan text for sensitive data (API keys, passwords, PII)
const textResult = await scanner.scanText('api_key=sk_live_12345');
// Detects: exposed API keys, passwords, SSN, credit cards, etc.

import {
  createSecretManager,
  createMemorySecretStore,
  createDatabaseSecretStore,
} from '@oshun/security';

const secretManager = createSecretManager({
  store: createDatabaseSecretStore(dbAdapter),
  cacheEnabled: true,
  cacheTtl: 300,
  autoRotationEnabled: true,
  rotationCheckInterval: 3600,
});

// Create a secret
await secretManager.createSecret({
  name: 'database-password',
  value: 'super-secret-password',
  type: 'database_credential',
  autoRotate: true,
  rotationInterval: 30 * 24 * 60 * 60, // 30 days
});

// Retrieve
const password = await secretManager.getSecret('database-password');

// Rotate
const result = await secretManager.rotateSecret('database-password', {
  autoGenerate: true,
  generateOptions: { length: 32, charset: 'alphanumeric' },
});

import {
  createSlidingWindowRateLimiter,
  createFixedWindowRateLimiter,
  createTokenBucketRateLimiter,
  createAdaptiveRateLimiter,
  createInMemoryRateLimiter,
} from '@oshun/rate-limit';

// Sliding window (most accurate)
const limiter = createSlidingWindowRateLimiter(redis, {
  limit: 100,
  window: 60, // seconds
});

const result = await limiter.check('user:123');
// { allowed: true, remaining: 99, resetAt: Date, retryAfter?: number }

// Token bucket (allows bursts)
const bucket = createTokenBucketRateLimiter(redis, {
  capacity: 100,
  refillRate: 10, // 10 tokens per second
});

// Adaptive (adjusts limits based on server load)
const adaptive = createAdaptiveRateLimiter(redis, {
  baseLimit: 100,
  minLimit: 20,
  maxLimit: 500,
  loadProvider: createSimpleLoadProvider(),
});

import {
  createRateLimitMiddleware,
  createUserRateLimitMiddleware,
  createApiKeyRateLimitMiddleware,
  createEndpointRateLimitMiddleware,
} from '@oshun/rate-limit';

// General rate limit
app.use('/api/*', createRateLimitMiddleware({ limiter }));

// Per-user rate limit
app.use(
  '/api/*',
  createUserRateLimitMiddleware({
    limiter,
    keyGenerator: (c) => c.get('userId'),
  })
);

// Per-endpoint rate limit
app.use(
  '/api/generate',
  createEndpointRateLimitMiddleware({
    limiter: createSlidingWindowRateLimiter(redis, { limit: 10, window: 60 }),
  })
);

import {
  createExemptRateLimiter,
  createExemptionManager,
  COMMON_BYPASS_RULES,
} from '@oshun/rate-limit';

const exemptLimiter = createExemptRateLimiter(limiter, {
  exemptionManager: createExemptionManager({
    store: createRedisExemptionStore(redis),
  }),
});

// Exempt a specific IP
await exemptLimiter.addExemption({
  entityType: 'ip',
  entityId: '10.0.0.1',
  reason: 'internal_service',
  expiresAt: new Date(Date.now() + 86400000),
});

import {
  createMonitoredRateLimiter,
  createAlertManager,
  COMMON_ALERT_RULES,
} from '@oshun/rate-limit';

const monitored = createMonitoredRateLimiter(limiter, {
  metricsInterval: 60000,
});

const alerts = createAlertManager({
  rules: COMMON_ALERT_RULES,
  handlers: [(alert) => notifyOps(alert)],
});

import {
  createAnthropicProvider,
  createOpenAIProvider,
  createGoogleProvider,
  createXAIProvider,
  createOllamaProvider,
} from '@oshun/ai';

const anthropic = createAnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

const openai = createOpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY!,
});

const google = createGoogleProvider({
  apiKey: process.env.GOOGLE_AI_API_KEY!,
});

// Local models via Ollama
const ollama = createOllamaProvider({
  baseUrl: 'http://localhost:11434',
});

// Make a request
const response = await anthropic.chat({
  model: 'claude-3-opus',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  maxTokens: 1000,
});

import {
  createModelRouter,
  createQualityRouter,
  createMLRouter,
} from '@oshun/ai';

// Rule-based routing
const router = createModelRouter({
  providers: { anthropic, openai, google },
  rules: [
    {
      taskType: 'creative-writing',
      provider: 'anthropic',
      model: 'claude-3-opus',
    },
    { taskType: 'code', provider: 'openai', model: 'gpt-4' },
    { taskType: 'summarization', provider: 'google', model: 'gemini-pro' },
  ],
  fallback: { provider: 'anthropic', model: 'claude-3-haiku' },
});

// Quality-based routing (evaluates speed, cost, quality)
const qualityRouter = createQualityRouter({
  providers: { anthropic, openai },
  weights: { quality: 0.5, speed: 0.3, cost: 0.2 },
});

// ML-based routing (learns from historical performance)
const mlRouter = createMLRouter({
  providers: { anthropic, openai, google },
  config: createCostOptimizedConfig(), // or createQualityOptimizedConfig()
});

import {
  createPromptTemplate,
  createDefaultTemplateLibrary,
  CREATIVE_TEMPLATES,
  TECHNICAL_TEMPLATES,
} from '@oshun/ai';

const template = createPromptTemplate({
  name: 'character-description',
  template:
    'Create a detailed character description for {{name}} who is a {{role}} in {{setting}}.',
  variables: {
    name: { type: 'string', required: true },
    role: { type: 'string', required: true },
    setting: { type: 'string', required: true },
  },
});

const prompt = template.compile({
  name: 'Elena',
  role: 'detective',
  setting: 'cyberpunk Tokyo',
});

import { createCachedProvider, createResponseCache } from '@oshun/ai';

const cache = createResponseCache({ maxSize: 1000, ttl: 3600 });
const cached = createCachedProvider(anthropic, cache);

// Identical requests return cached responses
const response1 = await cached.chat({ model: 'claude-3-haiku', messages: [...] });
const response2 = await cached.chat({ model: 'claude-3-haiku', messages: [...] }); // from cache

import { createUsageTracker } from '@oshun/ai';

const tracker = createUsageTracker({
  budget: { monthly: 1000, daily: 50, currency: 'USD' },
});

tracker.on('budget:warning', ({ usage, limit }) => {
  console.warn(`AI budget at ${((usage / limit) * 100).toFixed(0)}%`);
});

const summary = tracker.getSummary();
// { totalTokens, totalCost, byProvider: { anthropic: {...}, openai: {...} } }

import {
  createBatchProcessor,
  createPromptCompressor,
  createPromptABTester,
  createPromptSanitizer,
  createPromptDebugger,
} from '@oshun/ai';

// Batch processing (parallel requests with rate limiting)
const batch = createBatchProcessor(anthropic, {
  concurrency: 5,
  rateLimit: 60,
});

// Prompt compression (reduce token usage)
const compressor = createPromptCompressor();

// A/B testing of prompt variants
const abTester = createPromptABTester();

// Prompt injection prevention
const sanitizer = createPromptSanitizer();
const result = sanitizer.scan(userInput);
if (result.hasInjection) {
  console.warn('Injection detected:', result.injectionType);
}

import {
  createModelManager,
  createInferenceEngine,
  createLocalLLMStack,
  estimateVRAMRequirements,
  getRecommendedQuantization,
} from '@oshun/ai';

// Estimate hardware requirements
const vram = estimateVRAMRequirements('llama-2-7b', 'q4_0');
const quant = getRecommendedQuantization({ vramGb: 8 });

// Full local LLM stack
const stack = createLocalLLMStack({
  modelsDir: '/models',
  maxLoadedModels: 2,
  defaultQuantization: 'q4_0',
});

await stack.modelManager.loadModel('llama-2-7b');
const result = await stack.inferenceEngine.infer({
  model: 'llama-2-7b',
  prompt: 'Tell me a story',
  maxTokens: 500,
});

import {
  AdapterManager,
  createBuiltInAdapters,
  InMemoryAdapterStorage,
} from '@oshun/ai-advanced';

const adapterManager = new AdapterManager(new InMemoryAdapterStorage());

// Register built-in adapters (Anthropic, OpenAI, Google, etc.)
const builtInAdapters = createBuiltInAdapters();
for (const adapter of builtInAdapters) {
  await adapterManager.register(adapter);
}

// List available adapters
const adapters = await adapterManager.list();
// Filter by capability
const visionAdapters = await adapterManager.findByCapability('vision');

import {
  BenchmarkManager,
  getStandardBenchmarkTasks,
  InMemoryBenchmarkStorage,
} from '@oshun/ai-advanced';

const benchmarks = new BenchmarkManager(new InMemoryBenchmarkStorage());

// Run benchmarks against standard tasks
const tasks = getStandardBenchmarkTasks();
const results = await benchmarks.run('claude-3-opus', tasks, adapter);
// { accuracy, latencyP50, latencyP99, tokensPerSecond, costPerToken }

import { ModelSelector, InMemoryModelProfileStorage } from '@oshun/ai-advanced';

const selector = new ModelSelector(new InMemoryModelProfileStorage());

// Find the best model for a task
const bestModel = await selector.select({
  taskType: 'creative-writing',
  maxLatencyMs: 5000,
  maxCostPerToken: 0.001,
  requiredCapabilities: ['text-generation'],
});

import { EdgeManager, InMemoryEdgeModelStorage } from '@oshun/ai-advanced';

const edgeManager = new EdgeManager(new InMemoryEdgeModelStorage());

// Deploy a model to edge devices
await edgeManager.deploy({
  modelId: 'text-classifier-v1',
  targetDevice: 'browser',
  quantization: 'int8',
  maxModelSize: 50 * 1024 * 1024, // 50 MB
});

// Run inference on device
const result = await edgeManager.infer('text-classifier-v1', {
  text: 'Classify this input',
});

import { ResearchManager, InMemoryResearchStorage } from '@oshun/ai-advanced';

const research = new ResearchManager(new InMemoryResearchStorage());

// Search arXiv papers
const papers = await research.searchPapers({
  query: 'transformer attention mechanisms',
  maxResults: 10,
});

// Search HuggingFace models and datasets
const models = await research.searchModels({ query: 'text-to-image' });
const datasets = await research.searchDatasets({ query: 'sentiment analysis' });

// Track experiments
const experiment = await research.createExperiment({
  name: 'prompt-optimization-v2',
  description: 'Testing new prompt templates',
});

import { createRunPodClient } from '@oshun/runpod-client';

const client = createRunPodClient({
  apiKey: process.env.RUNPOD_API_KEY!,
  retry: { maxRetries: 3, backoff: 'exponential' },
  polling: { initialDelay: 1000, maxDelay: 10000 },
});

// Async job (submit and poll)
const job = await client.run('endpoint-id', {
  input: { prompt: 'A photo of a sunset', width: 1024, height: 1024 },
});

// Wait for completion
const result = await client.runAndWait('endpoint-id', {
  input: { prompt: 'Generate image' },
  maxWaitTime: 120000, // 2 minutes
});
console.log(result.output);

// Synchronous execution (blocks until done, for quick jobs)
const syncResult = await client.runSync('endpoint-id', {
  input: { prompt: 'Hello' },
  timeout: 30,
});

const results = await client.runBatch('endpoint-id', [
  { input: { prompt: 'Image 1' } },
  { input: { prompt: 'Image 2' } },
  { input: { prompt: 'Image 3' } },
]);

const status = await client.status('endpoint-id', 'job-123');
await client.cancel('endpoint-id', 'job-123');
const health = await client.health('endpoint-id');
await client.purgeQueue('endpoint-id');

import { createGpuDispatcher, createRunPodClient } from '@oshun/gpu-dispatcher';

const runpod = createRunPodClient({ apiKey: process.env.RUNPOD_API_KEY! });

const dispatcher = createGpuDispatcher(
  {
    runpodApiKey: process.env.RUNPOD_API_KEY!,
    endpoints: [
      { id: 'comfyui-sd', name: 'ComfyUI SD', jobTypes: ['image-generation'] },
      {
        id: 'comfyui-flux',
        name: 'ComfyUI Flux',
        jobTypes: ['image-generation'],
      },
      { id: 'video-gen', name: 'Video Gen', jobTypes: ['video-generation'] },
    ],
  },
  runpod
);

// Create a job
const job = await dispatcher.createJob({
  type: 'image-generation',
  input: { prompt: 'A beautiful sunset', width: 1024, height: 1024 },
  priority: 'high',
});

// Wait for completion
const result = await dispatcher.waitForJob(job.id);

// Or event-driven approach
dispatcher.on('job:completed', ({ job, result }) => {
  console.log(`Job ${job.id} completed:`, result.output);
});

dispatcher.on('job:failed', ({ job, error }) => {
  console.error(`Job ${job.id} failed:`, error.message);
});

dispatcher.startProcessing();

import { createCostTracker, DEFAULT_GPU_PRICING } from '@oshun/gpu-dispatcher';

const costs = createCostTracker({
  pricing: DEFAULT_GPU_PRICING,
  budget: { daily: 100, monthly: 2000, currency: 'USD' },
});

costs.on('budget:exceeded', ({ period, spent, limit }) => {
  console.error(`GPU budget exceeded: $${spent}/$${limit} (${period})`);
});

const stats = costs.getStatistics();
// { totalCost, jobCount, avgCostPerJob, costByType, costByEndpoint }

import { createFallbackManager } from '@oshun/gpu-dispatcher';

const fallback = createFallbackManager({
  strategy: 'priority', // or 'round-robin', 'random', 'least-loaded'
  healthCheckInterval: 30000,
});
// Automatically routes to healthy endpoints when primary is down

import {
  createResultValidator,
  createImageValidationConfig,
  createVideoValidationConfig,
} from '@oshun/gpu-dispatcher';

const validator = createResultValidator(
  createImageValidationConfig({
    maxFileSize: 10 * 1024 * 1024, // 10 MB
    allowedFormats: ['png', 'jpg', 'webp'],
    minResolution: { width: 512, height: 512 },
  })
);

const validation = await validator.validate(result);
if (!validation.valid) {
  console.error('Invalid output:', validation.errors);
}

import {
  createGpuTimeoutManager,
  IMAGE_GENERATION_TIMEOUT,
  VIDEO_GENERATION_TIMEOUT,
} from '@oshun/gpu-dispatcher';

const timeouts = createGpuTimeoutManager({
  'image-generation': IMAGE_GENERATION_TIMEOUT,
  'video-generation': VIDEO_GENERATION_TIMEOUT,
});

import { createPerformanceManager } from '@oshun/infrastructure';

const perf = createPerformanceManager({
  assetLoader: myAssetLoader,
  assetStorage: new InMemoryAssetStorage(),
  lodProvider: myLODProvider,
  memoryMonitor: myMemoryMonitor,
  taskExecutor: myTaskExecutor,
  taskStorage: new InMemoryTaskStorage(),
  gpuCompute: myGPUCompute,
});

// Lazy asset loading with Level-of-Detail
await perf.loadAsset('asset-123', { priority: 'high', lod: 'medium' });

// Background task scheduling
await perf.scheduleTask({
  type: 'preprocess',
  priority: 'low',
  payload: { assetId: 'asset-123' },
});

// Memory management
const usage = perf.getMemoryUsage();
if (usage.pressure === 'critical') {
  await perf.cleanup({ maxAge: 3600 });
}

import { createSecurityManager } from '@oshun/infrastructure';

const security = createSecurityManager({
  encryption: myEncryptionProvider,
  secretStorage: new InMemorySecretStorage(),
  apiKeyProvider: myAPIKeyProvider,
  apiKeyStorage: new InMemoryAPIKeyStorage(),
  vulnerabilityScanner: myScanner,
  scanResultStorage: new InMemoryScanResultStorage(),
  securityAudit: new InMemorySecurityAudit(),
});

// Encrypt/decrypt data
const encrypted = await security.encrypt(sensitiveData);
const decrypted = await security.decrypt(encrypted);

// Manage API keys
const key = await security.createApiKey({
  name: 'Production',
  scopes: ['read'],
});
const valid = await security.validateApiKey(key.value);

// Run vulnerability scan
const scanResult = await security.scan({
  type: 'dependency',
  target: 'package.json',
});

import { createMonitoringManager } from '@oshun/infrastructure';

const monitoring = createMonitoringManager({
  tracing: new InMemoryTracingProvider(),
  traceStorage: new InMemoryTraceStorage(),
  metrics: new InMemoryMetricsProvider(),
  metricsStorage: new InMemoryMetricsStorage(),
  alerting: myAlertingProvider,
  alertStorage: new InMemoryAlertStorage(),
  alertRuleStorage: new InMemoryAlertRuleStorage(),
  dashboardStorage: new InMemoryDashboardStorage(),
  analytics: new InMemoryAnalyticsProvider(),
});

// Create traces and spans
const trace = await monitoring.createTrace({ name: 'request', service: 'api' });

// Record metrics
await monitoring.recordMetric({
  name: 'request_duration',
  type: 'histogram',
  value: 45.2,
  labels: { method: 'GET', path: '/users' },
});

// Manage alert rules
await monitoring.createAlertRule({
  name: 'High Error Rate',
  condition: { metric: 'error_rate', operator: '>', threshold: 0.05 },
  severity: 'critical',
  channels: ['pagerduty', 'slack'],
});

// Dashboard management
await monitoring.createDashboard({ name: 'API Overview', panels: [...] });

import {
  MigrationRunner,
  MigrationRegistry,
  createMigrationRunner,
} from '@oshun/migration';

const registry = new MigrationRegistry();

// Register migrations
registry.add({
  id: '001',
  name: 'migrate-users-to-new-schema',
  description: 'Moves user data from lilith to yemaya schema',
  sourceDomain: 'lilith',
  targetDomain: 'yemaya',
  version: '1.0.0',
  reversible: true,
  up: async (ctx) => {
    const users = await ctx.source.query('SELECT * FROM users');
    for (const batch of ctx.progress.batches(users, 100)) {
      await ctx.target.query(sql`INSERT INTO users ...`);
      ctx.progress.report(batch.processed, batch.total);
    }
  },
  down: async (ctx) => {
    await ctx.target.query('DELETE FROM users WHERE migrated = true');
  },
});

const runner = createMigrationRunner(registry, { batchSize: 100 });

// Dry run first
const dryResult = await runner.run('001', { dryRun: true, verbose: true });

// Execute
const result = await runner.run('001');
console.log(result.status, result.duration);

// Rollback if needed
await runner.rollback('001');

import {
  createMockLogger,
  createMockHttpClient,
  createMockRedisClient,
  createMockDatabaseClient,
  createMockEventEmitter,
  createMockTimers,
} from '@oshun/testing';

const logger = createMockLogger();
const http = createMockHttpClient();
const redis = createMockRedisClient();
const db = createMockDatabaseClient();

// Mock HTTP responses
http.onGet('/users/123').respond({ id: '123', name: 'Test' });
http.onPost('/users').respond({ id: '456' }, { status: 201 });

import {
  createUser,
  createUsers,
  createContent,
  userFactory,
  contentFactory,
  randomEmail,
  randomUUID,
  randomString,
  createFixtureFactory,
} from '@oshun/testing';

// Quick fixtures
const user = createUser({ role: 'admin' });
const users = createUsers(10); // 10 random users

// Factory pattern
const myFactory = createFixtureFactory({
  id: () => randomUUID(),
  email: () => randomEmail(),
  name: () => randomString(10),
  role: 'user',
  active: true,
});

const record = myFactory.create({ role: 'admin' }); // Override specific fields
const records = myFactory.createMany(5);

import {
  assertDefined,
  assertRejects,
  assertAppError,
  assertApiSuccess,
  assertApiError,
  assertResultOk,
  assertResultErr,
  waitFor,
  retryUntil,
  measureTime,
  assertExecutesWithin,
} from '@oshun/testing';

// Wait for async condition
await waitFor(() => queue.length === 0, { timeout: 5000, interval: 100 });

// Assert execution time
await assertExecutesWithin(500, async () => {
  await fastOperation();
});

// Assert error types
await assertAppError(() => service.getUser('nonexistent'), 'NotFoundError');

import {
  createPostgresContainer,
  createRedisContainer,
  createContainerManager,
} from '@oshun/testing';

// Requires testcontainers peer dependency
const pg = await createPostgresContainer({
  image: 'postgres:16',
  database: 'test',
});

const redis = await createRedisContainer();

// Manage multiple containers
const manager = createContainerManager();
manager.add('postgres', pg);
manager.add('redis', redis);

await manager.startAll();
// ... run tests ...
await manager.stopAll();

import {
  createVitestConfig,
  createServiceVitestConfig,
  createIntegrationVitestConfig,
  createWorkspaceAliases,
} from '@oshun/testing';

// For a library
export default createVitestConfig({
  name: '@oshun/my-lib',
  aliases: createWorkspaceAliases({
    '@oshun/logging': '../logging/src/index.ts',
    '@oshun/errors': '../errors/src/index.ts',
  }),
  coverage: { threshold: 80 },
});

// For a service with integration tests
export default createServiceVitestConfig({
  name: 'my-service',
  setupFiles: ['./test/setup.ts'],
});

# Build everything tagged scope:shared
pnpm nx run-many --target=build --projects=tag:scope:shared

# Build a single library
pnpm nx build @oshun/logging

# Run all shared library tests
pnpm nx run-many --target=test --projects=tag:scope:shared

# Lint
pnpm nx run-many --target=lint --projects=tag:scope:shared

# Start infrastructure
docker compose -f docker/docker-compose.dev.yml up -d

# Verify
docker compose -f docker/docker-compose.dev.yml ps