@vasperacapital/vaspera-shared 0.1.0

package/src/types/index.ts

@@ -0,0 +1,164 @@
+// Subscription Types
+export type SubscriptionTier = 'free' | 'starter' | 'pro' | 'enterprise';
+export type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'trialing' | 'incomplete';
+
+// User Profile
+export interface UserProfile {
+  id: string;
+  email: string;
+  fullName: string | null;
+  avatarUrl: string | null;
+  subscriptionTier: SubscriptionTier;
+  subscriptionStatus: SubscriptionStatus;
+  stripeCustomerId: string | null;
+  stripeSubscriptionId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// API Key
+export interface ApiKey {
+  id: string;
+  userId: string;
+  name: string;
+  keyPrefix: string;
+  lastUsedAt: string | null;
+  expiresAt: string | null;
+  revokedAt: string | null;
+  createdAt: string;
+}
+
+export interface ApiKeyWithSecret extends Omit<ApiKey, 'revokedAt'> {
+  key: string; // Full key (only shown once)
+}
+
+// Usage
+export interface UsageEvent {
+  id: string;
+  userId: string;
+  apiKeyId: string | null;
+  toolName: string;
+  tokensUsed: number;
+  latencyMs: number | null;
+  success: boolean;
+  errorCode: string | null;
+  requestId: string | null;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+}
+
+export interface UsageSummary {
+  period: {
+    start: string;
+    end: string;
+  };
+  summary: {
+    totalToolCalls: number;
+    totalTokensUsed: number;
+    quotaUsed: number;
+    quotaLimit: number;
+    quotaPercentage: number;
+  };
+  byTool: Array<{
+    tool: string;
+    calls: number;
+    tokensUsed: number;
+    avgLatencyMs: number;
+  }>;
+}
+
+// Quota Limits by Tier
+export const QUOTA_LIMITS: Record<SubscriptionTier, number> = {
+  free: 5,
+  starter: 100,
+  pro: 500,
+  enterprise: 999999, // Effectively unlimited
+};
+
+export const RATE_LIMITS: Record<SubscriptionTier, { perMinute: number; perDay: number }> = {
+  free: { perMinute: 10, perDay: 100 },
+  starter: { perMinute: 30, perDay: 1000 },
+  pro: { perMinute: 60, perDay: 5000 },
+  enterprise: { perMinute: 120, perDay: 999999 },
+};
+
+// Integration Types
+export type IntegrationProvider = 'jira' | 'linear' | 'github' | 'gitlab' | 'asana';
+
+export interface IntegrationToken {
+  id: string;
+  userId: string;
+  provider: IntegrationProvider;
+  tokenType: string;
+  expiresAt: string | null;
+  scopes: string[] | null;
+  providerUserId: string | null;
+  providerEmail: string | null;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface IntegrationStatus {
+  provider: IntegrationProvider;
+  connected: boolean;
+  connectedAt?: string;
+  providerEmail?: string;
+  scopes?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+// MCP Tool Types
+export type McpToolName =
+  | 'synthesize_requirements'
+  | 'review_prd'
+  | 'explode_backlog'
+  | 'generate_architecture'
+  | 'sync_to_tracker'
+  | 'infer_prd_from_code'
+  | 'reverse_engineer_user_flows'
+  | 'generate_test_specs'
+  | 'explain_codebase'
+  | 'validate_implementation'
+  | 'suggest_refactors'
+  | 'generate_api_docs'
+  | 'dependency_audit'
+  | 'estimate_migration';
+
+export interface McpToolResult<T = unknown> {
+  content: Array<{
+    type: 'text' | 'image' | 'resource';
+    text?: string;
+    data?: string;
+    mimeType?: string;
+  }>;
+  data?: T;
+  tokensUsed?: number;
+  isError?: boolean;
+}
+
+// API Response Types
+export interface ApiSuccessResponse<T> {
+  success: true;
+  data: T;
+  meta?: {
+    requestId: string;
+    timestamp: string;
+  };
+}
+
+export interface ApiErrorResponse {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+    docUrl?: string;
+  };
+  meta?: {
+    requestId: string;
+    timestamp: string;
+  };
+}
+
+export type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;

package/src/utils/api-key.ts

@@ -0,0 +1,72 @@
+import { randomBytes, createHash } from 'crypto';
+
+const API_KEY_PREFIX_LIVE = 'vpm_live_';
+const API_KEY_PREFIX_TEST = 'vpm_test_';
+const API_KEY_RANDOM_BYTES = 24; // 32 chars in base64url
+
+export interface GeneratedApiKey {
+  key: string;        // Full key to show user once
+  keyPrefix: string;  // First 16 chars for identification
+  keyHash: string;    // Hash for storage and validation
+}
+
+/**
+ * Generate a new API key
+ * @param environment - 'live' or 'test'
+ * @returns Generated key with prefix and hash
+ */
+export function generateApiKey(environment: 'live' | 'test' = 'live'): GeneratedApiKey {
+  const prefix = environment === 'live' ? API_KEY_PREFIX_LIVE : API_KEY_PREFIX_TEST;
+  const randomPart = randomBytes(API_KEY_RANDOM_BYTES)
+    .toString('base64url')
+    .slice(0, 32);
+
+  const key = `${prefix}${randomPart}`;
+  const keyPrefix = key.slice(0, 16);
+  const keyHash = hashApiKey(key);
+
+  return {
+    key,
+    keyPrefix,
+    keyHash,
+  };
+}
+
+/**
+ * Hash an API key for storage
+ * Using SHA-256 since we need to look up by hash
+ */
+export function hashApiKey(key: string): string {
+  return createHash('sha256').update(key).digest('hex');
+}
+
+/**
+ * Validate API key format
+ */
+export function isValidApiKeyFormat(key: string): boolean {
+  const livePattern = /^vpm_live_[a-zA-Z0-9_-]{32}$/;
+  const testPattern = /^vpm_test_[a-zA-Z0-9_-]{32}$/;
+  return livePattern.test(key) || testPattern.test(key);
+}
+
+/**
+ * Extract prefix from API key
+ */
+export function extractKeyPrefix(key: string): string {
+  return key.slice(0, 16);
+}
+
+/**
+ * Check if key is a test key
+ */
+export function isTestKey(key: string): boolean {
+  return key.startsWith(API_KEY_PREFIX_TEST);
+}
+
+/**
+ * Mask an API key for display (show first 16 and last 4 chars)
+ */
+export function maskApiKey(key: string): string {
+  if (key.length < 24) return key;
+  return `${key.slice(0, 16)}...${key.slice(-4)}`;
+}

package/src/utils/encryption.ts

@@ -0,0 +1,79 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+  scrypt,
+} from 'crypto';
+import { promisify } from 'util';
+
+const scryptAsync = promisify(scrypt);
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 16;
+const SALT_LENGTH = 32;
+const TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+
+/**
+ * Encrypt text using AES-256-GCM
+ * @param text - Plain text to encrypt
+ * @param secret - Encryption secret
+ * @returns Encrypted string in format: salt:iv:tag:ciphertext (all base64)
+ */
+export async function encrypt(text: string, secret: string): Promise<string> {
+  const salt = randomBytes(SALT_LENGTH);
+  const iv = randomBytes(IV_LENGTH);
+  const key = (await scryptAsync(secret, salt, KEY_LENGTH)) as Buffer;
+
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(text, 'utf8'),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+
+  // Format: salt:iv:tag:encrypted (all base64)
+  return [
+    salt.toString('base64'),
+    iv.toString('base64'),
+    tag.toString('base64'),
+    encrypted.toString('base64'),
+  ].join(':');
+}
+
+/**
+ * Decrypt text that was encrypted with encrypt()
+ * @param encryptedText - Encrypted string in format: salt:iv:tag:ciphertext
+ * @param secret - Encryption secret (must match encryption)
+ * @returns Decrypted plain text
+ */
+export async function decrypt(
+  encryptedText: string,
+  secret: string
+): Promise<string> {
+  const parts = encryptedText.split(':');
+  if (parts.length !== 4) {
+    throw new Error('Invalid encrypted text format');
+  }
+
+  const [saltB64, ivB64, tagB64, encryptedB64] = parts;
+
+  const salt = Buffer.from(saltB64!, 'base64');
+  const iv = Buffer.from(ivB64!, 'base64');
+  const tag = Buffer.from(tagB64!, 'base64');
+  const encrypted = Buffer.from(encryptedB64!, 'base64');
+
+  const key = (await scryptAsync(secret, salt, KEY_LENGTH)) as Buffer;
+
+  const decipher = createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(tag);
+
+  return decipher.update(encrypted) + decipher.final('utf8');
+}
+
+/**
+ * Generate a random encryption secret
+ * @returns 32-byte hex string suitable for use as encryption secret
+ */
+export function generateEncryptionSecret(): string {
+  return randomBytes(32).toString('hex');
+}

package/src/utils/index.ts

@@ -0,0 +1,15 @@
+export {
+  generateApiKey,
+  hashApiKey,
+  isValidApiKeyFormat,
+  extractKeyPrefix,
+  isTestKey,
+  maskApiKey,
+} from './api-key.js';
+export type { GeneratedApiKey } from './api-key.js';
+
+export {
+  encrypt,
+  decrypt,
+  generateEncryptionSecret,
+} from './encryption.js';

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@vaspera/tsconfig/node.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/errors/index.ts', 'src/types/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+});