@geenius/tools 0.1.0

package/packages/convex/shared/src/audit/schema.ts

@@ -0,0 +1,85 @@
+// @geenius-tools/convex-wrappers — src/audit/schema.ts
+
+/**
+ * Audit log table schema definition for Convex.
+ *
+ * Usage: Import and spread into your Convex schema definition.
+ *
+ * @example
+ * ```ts
+ * // convex/schema.ts
+ * import { defineSchema, defineTable } from 'convex/server'
+ * import { auditLogFields, auditLogIndexes } from '@geenius-tools/convex-wrappers/audit'
+ *
+ * export default defineSchema({
+ *   auditLogs: defineTable(auditLogFields)
+ *     .index('by_entity', auditLogIndexes.by_entity)
+ *     .index('by_entityTable', auditLogIndexes.by_entityTable)
+ *     .index('by_action', auditLogIndexes.by_action)
+ *     .index('by_createdAt', auditLogIndexes.by_createdAt)
+ *     .searchIndex('search_auditLogs', auditLogIndexes.search),
+ * })
+ * ```
+ */
+
+import { v } from 'convex/values'
+
+/**
+ * Field validators for the auditLogs table.
+ */
+export const auditLogFields = {
+    /** The user who performed the action */
+    actorId: v.optional(v.id('users')),
+    /** Role of the actor (e.g., 'admin', 'user', 'system') */
+    role: v.string(),
+    /** Array of roles the actor had at time of action */
+    actorRoles: v.optional(v.array(v.string())),
+
+    /** Action that was performed (e.g., 'create', 'update', 'delete') */
+    action: v.string(),
+
+    /** Table the entity belongs to */
+    entityTable: v.string(),
+    /** ID of the affected entity */
+    entityId: v.optional(v.string()),
+    /** Type classification of the entity */
+    entityType: v.optional(v.string()),
+    /** Human-readable title of the entity */
+    entityTitle: v.optional(v.string()),
+
+    /** JSON snapshot of the entity before the action */
+    beforeJson: v.optional(v.string()),
+    /** JSON snapshot of the entity after the action */
+    afterJson: v.optional(v.string()),
+    /** JSON diff of changes */
+    diffJson: v.optional(v.string()),
+
+    /** Reason for the action (e.g., admin note) */
+    reason: v.optional(v.string()),
+    /** Human-readable description */
+    description: v.optional(v.string()),
+    /** Request tracing ID */
+    requestId: v.optional(v.string()),
+
+    /** Additional context-specific metadata */
+    metadata: v.optional(v.any()),
+
+    /** ISO timestamp of when the action occurred */
+    createdAt: v.string(),
+    /** Concatenated searchable text for full-text search */
+    searchableText: v.optional(v.string()),
+}
+
+/**
+ * Recommended indexes for the auditLogs table.
+ */
+export const auditLogIndexes = {
+    by_entity: ['entityTable', 'entityId'] as const,
+    by_entityTable: ['entityTable'] as const,
+    by_action: ['action'] as const,
+    by_createdAt: ['createdAt'] as const,
+    search: {
+        searchField: 'searchableText' as const,
+        filterFields: ['entityTable', 'action'] as const,
+    },
+}

package/packages/convex/shared/src/audit/write.ts

@@ -0,0 +1,102 @@
+// @geenius-tools/convex-wrappers — src/audit/write.ts
+
+import type { AuditLogEntry } from '../types'
+
+/**
+ * Generate searchable text from an audit log entry.
+ * Concatenates key fields for full-text search indexing.
+ */
+export function generateSearchableText(params: {
+    action?: string
+    table?: string
+    id?: string
+    title?: string
+    description?: string
+    reason?: string
+    actorName?: string
+    [key: string]: unknown
+}): string {
+    return [
+        params.action,
+        params.table,
+        params.id,
+        params.title,
+        params.description,
+        params.reason,
+        params.actorName,
+    ]
+        .filter(Boolean)
+        .join(' ')
+}
+
+/**
+ * Write an audit log entry to the database.
+ *
+ * This is a generic helper — you pass in your Convex MutationCtx.
+ * It auto-generates `createdAt` and `searchableText` if not provided.
+ *
+ * @example
+ * ```ts
+ * import { writeAudit } from '@geenius-tools/convex-wrappers'
+ *
+ * // Inside a Convex mutation:
+ * await writeAudit(ctx, {
+ *   actorId: user._id,
+ *   role: 'admin',
+ *   action: 'update',
+ *   entityTable: 'orders',
+ *   entityId: orderId,
+ *   entityTitle: 'Order #123',
+ *   beforeJson: JSON.stringify(before),
+ *   afterJson: JSON.stringify(after),
+ * })
+ * ```
+ */
+export async function writeAudit(
+    ctx: { db: { insert: (table: string, doc: Record<string, unknown>) => Promise<unknown> } },
+    entry: Omit<AuditLogEntry, 'createdAt'> & { createdAt?: string; searchableText?: string },
+): Promise<void> {
+    const createdAt = entry.createdAt ?? new Date().toISOString()
+
+    const searchableText =
+        entry.searchableText ??
+        generateSearchableText({
+            action: entry.action,
+            table: entry.entityTable,
+            id: entry.entityId,
+            title: entry.entityTitle,
+            description: entry.description,
+            reason: entry.reason,
+        })
+
+    await ctx.db.insert('auditLogs', {
+        ...entry,
+        createdAt,
+        searchableText,
+    })
+}
+
+/**
+ * Compute a JSON diff between before and after objects.
+ * Returns an object with only the changed fields.
+ */
+export function computeDiff(
+    before: Record<string, unknown> | null | undefined,
+    after: Record<string, unknown> | null | undefined,
+): Record<string, { from: unknown; to: unknown }> {
+    const diff: Record<string, { from: unknown; to: unknown }> = {}
+    const allKeys = new Set([
+        ...Object.keys(before ?? {}),
+        ...Object.keys(after ?? {}),
+    ])
+
+    for (const key of allKeys) {
+        const fromVal = (before as Record<string, unknown>)?.[key]
+        const toVal = (after as Record<string, unknown>)?.[key]
+        if (JSON.stringify(fromVal) !== JSON.stringify(toVal)) {
+            diff[key] = { from: fromVal, to: toVal }
+        }
+    }
+
+    return diff
+}

package/packages/convex/shared/src/extract.ts

@@ -0,0 +1,75 @@
+// @geenius-tools/convex-errors — src/extract.ts
+
+import { ConvexError } from 'convex/values'
+import type { AppErrorCode, AppErrorPayload, ValidationError } from './types'
+import { HTTP_STATUS_MAP } from './types'
+
+/**
+ * Check if an error is a ConvexError with AppErrorPayload.
+ */
+export function isAppError(error: unknown): error is ConvexError<AppErrorPayload> {
+    return error instanceof ConvexError && typeof (error.data as AppErrorPayload)?.code === 'string'
+}
+
+/**
+ * Extract AppErrorPayload from a ConvexError, or return null.
+ */
+export function extractAppError(error: unknown): AppErrorPayload | null {
+    if (isAppError(error)) {
+        return error.data
+    }
+    return null
+}
+
+/**
+ * Get the error code from a ConvexError, or 'INTERNAL' as fallback.
+ */
+export function getErrorCode(error: unknown): AppErrorCode {
+    const payload = extractAppError(error)
+    return payload?.code ?? 'INTERNAL'
+}
+
+/**
+ * Get the error message from a ConvexError, or a fallback string.
+ */
+export function getErrorMsg(error: unknown, fallback = 'An unexpected error occurred'): string {
+    const payload = extractAppError(error)
+    return payload?.message ?? (error instanceof Error ? error.message : fallback)
+}
+
+/**
+ * Get validation errors from a ConvexError, or empty array.
+ */
+export function getValidationErrors(error: unknown): ValidationError[] {
+    const payload = extractAppError(error)
+    return payload?.validationErrors ?? []
+}
+
+/**
+ * Get HTTP status code for a ConvexError.
+ */
+export function getHttpStatus(error: unknown): number {
+    const code = getErrorCode(error)
+    return HTTP_STATUS_MAP[code] ?? 500
+}
+
+/**
+ * Convert an error to a JSON-serializable response object.
+ * Useful for HTTP error responses.
+ */
+export function toErrorResponse(error: unknown): {
+    status: number
+    body: { error: AppErrorPayload }
+} {
+    const payload = extractAppError(error)
+    const code = payload?.code ?? 'INTERNAL'
+    return {
+        status: HTTP_STATUS_MAP[code] ?? 500,
+        body: {
+            error: payload ?? {
+                code: 'INTERNAL',
+                message: error instanceof Error ? error.message : 'Unknown error',
+            },
+        },
+    }
+}

package/packages/convex/shared/src/index.ts

@@ -0,0 +1,41 @@
+// @geenius-tools/convex-errors — src/index.ts
+
+// Types
+export type {
+    AppErrorCode,
+    AppErrorPayload,
+    ValidationError,
+} from './types'
+export { HTTP_STATUS_MAP } from './types'
+
+// Error throwers
+export {
+    unauthenticated,
+    forbidden,
+    notFound,
+    badRequest,
+    conflict,
+    internal,
+    featureDisabled,
+    rateLimited,
+    validationError,
+    withErrorMeta,
+} from './throw'
+
+// Error messages
+export {
+    DEFAULT_ERROR_MESSAGES,
+    configureErrorMessages,
+    getErrorMessage,
+} from './messages'
+
+// Error extraction (for frontend)
+export {
+    isAppError,
+    extractAppError,
+    getErrorCode,
+    getErrorMsg,
+    getValidationErrors,
+    getHttpStatus,
+    toErrorResponse,
+} from './extract'

package/packages/convex/shared/src/messages.ts

@@ -0,0 +1,45 @@
+// @geenius-tools/convex-errors — src/messages.ts
+
+import type { AppErrorCode } from './types'
+
+/**
+ * Default English error messages.
+ * Override these by passing your own messages to `configureErrorMessages()`.
+ */
+export const DEFAULT_ERROR_MESSAGES: Record<AppErrorCode, string> = {
+    UNAUTHENTICATED: 'Please sign in to continue.',
+    FORBIDDEN: 'You do not have permission for this action.',
+    NOT_FOUND: 'The requested resource was not found.',
+    BAD_REQUEST: 'Invalid request. Please check your input.',
+    CONFLICT: 'Action not possible (conflict with existing data).',
+    INTERNAL: 'An internal error occurred. Please try again later.',
+    VALIDATION_ERROR: 'Please check your input and try again.',
+    RATE_LIMITED: 'Too many requests. Please try again later.',
+    FEATURE_DISABLED: 'This feature is currently disabled.',
+}
+
+let currentMessages: Record<AppErrorCode, string> = { ...DEFAULT_ERROR_MESSAGES }
+
+/**
+ * Override default error messages (e.g., for i18n / localization).
+ *
+ * @example
+ * ```ts
+ * configureErrorMessages({
+ *   UNAUTHENTICATED: 'Bitte melde dich an, um fortzufahren.',
+ *   FORBIDDEN: 'Du hast keine Berechtigung für diese Aktion.',
+ * })
+ * ```
+ */
+export function configureErrorMessages(
+    messages: Partial<Record<AppErrorCode, string>>,
+): void {
+    currentMessages = { ...currentMessages, ...messages }
+}
+
+/**
+ * Get the current error message for a given code.
+ */
+export function getErrorMessage(code: AppErrorCode): string {
+    return currentMessages[code]
+}

package/packages/convex/shared/src/security.ts

@@ -0,0 +1,112 @@
+// @geenius-tools/convex-wrappers — src/security.ts
+
+import type { RateLimitConfig, PrivacyConfig } from './types'
+
+/**
+ * Simple in-memory rate limiter for development/prototyping.
+ * In production, you'd want to use Convex's built-in rate limiting
+ * or a persistent store.
+ *
+ * This provides the core rate limit checking logic.
+ * The actual Convex integration is left to the consumer to wire up.
+ *
+ * @example
+ * ```ts
+ * import { checkRateLimit } from '@geenius-tools/convex-wrappers'
+ *
+ * // In your mutation wrapper:
+ * const isAllowed = checkRateLimit({
+ *   key: userId,
+ *   maxRequests: 10,
+ *   windowMs: 60_000,
+ * })
+ * if (!isAllowed) {
+ *   rateLimited('Too many requests')
+ * }
+ * ```
+ */
+const rateLimitStore = new Map<string, { count: number; resetAt: number }>()
+
+export function checkRateLimit(params: {
+    key: string
+    maxRequests: number
+    windowMs: number
+}): boolean {
+    const { key, maxRequests, windowMs } = params
+    const now = Date.now()
+    const entry = rateLimitStore.get(key)
+
+    if (!entry || now > entry.resetAt) {
+        rateLimitStore.set(key, { count: 1, resetAt: now + windowMs })
+        return true
+    }
+
+    if (entry.count >= maxRequests) {
+        return false
+    }
+
+    entry.count++
+    return true
+}
+
+/**
+ * Clear rate limit for a specific key (e.g., after successful auth).
+ */
+export function clearRateLimit(key: string): void {
+    rateLimitStore.delete(key)
+}
+
+/**
+ * Validate that a user has one of the required roles.
+ */
+export function requireRoles(
+    user: { role?: string; roleType?: string; roles?: string[] },
+    requiredRoles: readonly string[],
+): void {
+    const userRoles = [
+        user.role,
+        user.roleType,
+        ...(user.roles ?? []),
+    ].filter(Boolean) as string[]
+
+    const hasRole = requiredRoles.some((r) => userRoles.includes(r))
+    if (!hasRole) {
+        throw new Error(
+            `Forbidden: user has roles [${userRoles.join(', ')}] but needs one of [${requiredRoles.join(', ')}]`,
+        )
+    }
+}
+
+/**
+ * Redact args based on privacy config.
+ */
+export function redactArgs(
+    args: Record<string, unknown>,
+    privacy: PrivacyConfig,
+): Record<string, unknown> {
+    if (privacy.mode === 'none') return args
+
+    const sensitive = new Set(
+        privacy.sensitiveFields ?? ['password', 'token', 'secret', 'apiKey'],
+    )
+
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(args)) {
+        if (sensitive.has(key)) {
+            result[key] = privacy.mode === 'hash' ? `[HASHED:${hashSimple(String(value))}]` : '[REDACTED]'
+        } else {
+            result[key] = value
+        }
+    }
+    return result
+}
+
+function hashSimple(input: string): string {
+    let hash = 0
+    for (let i = 0; i < input.length; i++) {
+        const char = input.charCodeAt(i)
+        hash = (hash << 5) - hash + char
+        hash |= 0
+    }
+    return Math.abs(hash).toString(36)
+}

package/packages/convex/shared/src/throw.ts

@@ -0,0 +1,184 @@
+// @geenius-tools/convex-errors — src/throw.ts
+
+import { ConvexError, type Value } from 'convex/values'
+import type { AppErrorCode, AppErrorPayload, ValidationError } from './types'
+import { getErrorMessage } from './messages'
+
+/**
+ * Internal function to throw a ConvexError with AppErrorPayload.
+ */
+function throwAppError(
+    code: AppErrorCode,
+    message?: string,
+    details?: Record<string, Value>,
+    validationErrors?: ValidationError[],
+    metadata?: AppErrorPayload['_metadata'],
+): never {
+    const payload: AppErrorPayload = {
+        code,
+        message: message || getErrorMessage(code),
+        details,
+        validationErrors,
+        _metadata: {
+            timestamp: new Date().toISOString(),
+            ...metadata,
+        },
+    }
+    throw new ConvexError<AppErrorPayload>(payload)
+}
+
+/**
+ * Throw UNAUTHENTICATED error (401).
+ * Use when user is not authenticated.
+ */
+export function unauthenticated(
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('UNAUTHENTICATED', message, details)
+}
+
+/**
+ * Throw FORBIDDEN error (403).
+ * Use when user lacks permission for the action.
+ */
+export function forbidden(
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('FORBIDDEN', message, details)
+}
+
+/**
+ * Throw NOT_FOUND error (404).
+ * Use when a requested resource doesn't exist.
+ */
+export function notFound(
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('NOT_FOUND', message, details)
+}
+
+/**
+ * Throw BAD_REQUEST error (400).
+ * Use for invalid input or business rule violations.
+ */
+export function badRequest(
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('BAD_REQUEST', message, details)
+}
+
+/**
+ * Throw CONFLICT error (409).
+ * Use for state conflicts (e.g., optimistic concurrency control failures).
+ */
+export function conflict(
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('CONFLICT', message, details)
+}
+
+/**
+ * Throw INTERNAL error (500).
+ * Use for internal server errors and unexpected conditions.
+ */
+export function internal(
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('INTERNAL', message, details)
+}
+
+/**
+ * Throw FEATURE_DISABLED error.
+ * Use when a feature flag is off.
+ */
+export function featureDisabled(
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('FEATURE_DISABLED', message, details)
+}
+
+/**
+ * Throw RATE_LIMITED error (429).
+ * Use when rate limits are exceeded.
+ */
+export function rateLimited(
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('RATE_LIMITED', message, details)
+}
+
+/**
+ * Throw VALIDATION_ERROR (422).
+ * Use for form validation errors with field-level details.
+ *
+ * @example
+ * ```ts
+ * const errors: ValidationError[] = []
+ * if (!email.includes('@')) {
+ *   errors.push({ field: 'email', message: 'Invalid email address' })
+ * }
+ * if (errors.length > 0) {
+ *   validationError(errors, 'Please check your input')
+ * }
+ * ```
+ */
+export function validationError(
+    validationErrors: ValidationError[],
+    message?: string,
+    details?: Record<string, Value>,
+): never {
+    throwAppError('VALIDATION_ERROR', message, details, validationErrors)
+}
+
+/**
+ * Create error helpers pre-enriched with metadata.
+ *
+ * @example
+ * ```ts
+ * const err = withErrorMeta({
+ *   functionName: 'users.update',
+ *   requestId: 'abc123',
+ * })
+ * err.notFound('User not found')
+ * ```
+ */
+export function withErrorMeta(meta: {
+    functionName?: string
+    requestId?: string
+    userId?: string
+}) {
+    const mergeDetails = (d?: Record<string, Value>): Record<string, Value> => ({
+        ...(d ?? {}),
+        ...meta,
+    })
+
+    return {
+        unauthenticated: (m?: string, d?: Record<string, Value>) =>
+            unauthenticated(m, mergeDetails(d)),
+        forbidden: (m?: string, d?: Record<string, Value>) =>
+            forbidden(m, mergeDetails(d)),
+        notFound: (m?: string, d?: Record<string, Value>) =>
+            notFound(m, mergeDetails(d)),
+        badRequest: (m?: string, d?: Record<string, Value>) =>
+            badRequest(m, mergeDetails(d)),
+        conflict: (m?: string, d?: Record<string, Value>) =>
+            conflict(m, mergeDetails(d)),
+        internal: (m?: string, d?: Record<string, Value>) =>
+            internal(m, mergeDetails(d)),
+        validationError: (
+            ve: ValidationError[],
+            m?: string,
+            d?: Record<string, Value>,
+        ) => validationError(ve, m, mergeDetails(d)),
+        rateLimited: (m?: string, d?: Record<string, Value>) =>
+            rateLimited(m, mergeDetails(d)),
+    }
+}

package/packages/convex/shared/src/types.ts

@@ -0,0 +1,57 @@
+// @geenius-tools/convex-errors — src/types.ts
+
+import type { Value } from 'convex/values'
+
+/**
+ * Standard error codes for Convex applications.
+ */
+export type AppErrorCode =
+    | 'UNAUTHENTICATED'
+    | 'FORBIDDEN'
+    | 'NOT_FOUND'
+    | 'BAD_REQUEST'
+    | 'CONFLICT'
+    | 'INTERNAL'
+    | 'VALIDATION_ERROR'
+    | 'RATE_LIMITED'
+    | 'FEATURE_DISABLED'
+
+/**
+ * A field-level validation error.
+ */
+export type ValidationError = {
+    field: string
+    message: string
+    code?: string
+}
+
+/**
+ * Structured payload thrown via `ConvexError<AppErrorPayload>`.
+ */
+export type AppErrorPayload = {
+    code: AppErrorCode
+    message?: string
+    details?: Record<string, Value>
+    validationErrors?: ValidationError[]
+    _metadata?: {
+        timestamp: string
+        functionName?: string
+        userId?: string
+        requestId?: string
+    }
+}
+
+/**
+ * HTTP status code mapping for error codes.
+ */
+export const HTTP_STATUS_MAP: Record<AppErrorCode, number> = {
+    UNAUTHENTICATED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    BAD_REQUEST: 400,
+    CONFLICT: 409,
+    INTERNAL: 500,
+    VALIDATION_ERROR: 422,
+    RATE_LIMITED: 429,
+    FEATURE_DISABLED: 403,
+}