@promptly/service-utils

Shared utilities for Promptly services including authentication, logging, and common helpers.

Installation

npm install @promptly/service-utils

Features

• Authentication: Clerk-based JWT authentication middleware
• Logging: Structured logging with Winston
• Common Utilities: Retry logic, environment variable parsing, sanitization

Usage

Authentication

import { authMiddleware, optionalAuthMiddleware } from '@promptly/service-utils';
import express from 'express';

const app = express();

// Required authentication for all routes under /api
app.use('/api', authMiddleware);

// Optional authentication (doesn't fail if no token)
app.use('/public', optionalAuthMiddleware);

Logging

import { logger, logRequest, logResponse } from '@promptly/service-utils';

// Basic logging
logger.info('Service started');
logger.error('Something went wrong', { error: 'details' });

// Request/response logging
app.use((req, res, next) => {
  const start = Date.now();
  logRequest(req);

  res.on('finish', () => {
    const duration = Date.now() - start;
    logResponse(req, res, duration);
  });

  next();
});

Common Utilities

import {
  sleep,
  retryWithBackoff,
  validateEnvironmentVariables,
  parseBooleanEnv,
  parseNumberEnv,
} from '@promptly/service-utils';

// Environment validation
validateEnvironmentVariables(['DATABASE_URL', 'API_KEY']);

// Environment parsing
const isProduction = parseBooleanEnv('IS_PRODUCTION', false);
const port = parseNumberEnv('PORT', 3000);

// Retry with backoff
const result = await retryWithBackoff(
  async () => {
    return await someApiCall();
  },
  3,
  1000
);

Environment Variables

Required for Authentication

• CLERK_SECRET_KEY: Clerk secret key for JWT validation
• CLERK_PUBLISHABLE_KEY: Clerk publishable key

Optional

• LOG_LEVEL: Logging level (default: 'info')
• SERVICE_NAME: Service name for logging context
• NODE_ENV: Environment (affects logging format)

TypeScript Support

This package includes full TypeScript definitions. The main types exported are:

import type { UserContext, AuthenticatedRequest } from '@promptly/service-utils';

// UserContext is available on req.user after authentication
interface UserContext {
  userId: string;
  email: string;
  roles: string[];
}

Development

# Install dependencies
pnpm install

# Build the package
pnpm build

# Watch for changes during development
pnpm dev

Publishing

# Bump version and publish
pnpm deploy

License

MIT