@autumnsgrove/groveengine 0.4.12 → 0.6.1

package/dist/groveauth/index.js

@@ -0,0 +1,35 @@
+/**
+ * GroveAuth Client Module
+ *
+ * Client library for integrating with GroveAuth authentication service.
+ *
+ * @example
+ * ```typescript
+ * import { createGroveAuthClient } from '@autumnsgrove/groveengine/groveauth';
+ *
+ * const auth = createGroveAuthClient({
+ *   clientId: 'your-client-id',
+ *   clientSecret: env.GROVEAUTH_CLIENT_SECRET,
+ *   redirectUri: 'https://yoursite.com/auth/callback',
+ * });
+ *
+ * // Generate login URL
+ * const { url, state, codeVerifier } = await auth.getLoginUrl();
+ *
+ * // Exchange code for tokens
+ * const tokens = await auth.exchangeCode(code, codeVerifier);
+ *
+ * // Check post limits
+ * const { allowed, status } = await auth.canUserCreatePost(tokens.access_token, userId);
+ * ```
+ */
+// Client
+export { GroveAuthClient, createGroveAuthClient } from './client.js';
+export { generateCodeVerifier, generateCodeChallenge, generateState } from './client.js';
+export { GroveAuthError, TIER_POST_LIMITS, TIER_NAMES } from './types.js';
+// Post limit helpers
+export { getQuotaDescription, getQuotaUrgency, getSuggestedActions, getUpgradeRecommendation, getQuotaWidgetData, getPreSubmitCheck, } from './limits.js';
+// Color utilities
+export { STATUS_COLORS, ALERT_VARIANTS, getStatusColorFromPercentage, getAlertVariantFromColor, } from './colors.js';
+// Rate limiting
+export { RateLimiter, RateLimitError, withRateLimit, DEFAULT_RATE_LIMITS, } from './rate-limit.js';

package/dist/groveauth/limits.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Post Limit Enforcement
+ *
+ * High-level utilities for enforcing post limits in GroveEngine.
+ * Uses GroveAuth subscription API to check and update limits.
+ */
+import type { SubscriptionStatus, CanPostResponse } from './types.js';
+/**
+ * Get a human-readable description of the quota status
+ */
+export declare function getQuotaDescription(status: SubscriptionStatus): string;
+/**
+ * Get the urgency level for the current quota status
+ */
+export declare function getQuotaUrgency(status: SubscriptionStatus): 'healthy' | 'warning' | 'critical' | 'blocked';
+/**
+ * Get suggested actions based on quota status
+ */
+export declare function getSuggestedActions(status: SubscriptionStatus): string[];
+/**
+ * Get upgrade recommendation based on current usage
+ */
+export declare function getUpgradeRecommendation(status: SubscriptionStatus): {
+    recommended: boolean;
+    fromTier: string;
+    toTier: string | null;
+    reason: string;
+};
+export interface QuotaWidgetData {
+    /** Current post count */
+    count: number;
+    /** Post limit (null if unlimited) */
+    limit: number | null;
+    /** Percentage used (null if unlimited) */
+    percentage: number | null;
+    /** Posts remaining (null if unlimited) */
+    remaining: number | null;
+    /** Status color */
+    color: 'green' | 'yellow' | 'red' | 'gray';
+    /** Status text */
+    statusText: string;
+    /** Human-readable description */
+    description: string;
+    /** Whether to show upgrade prompt */
+    showUpgrade: boolean;
+    /** Tier name */
+    tierName: string;
+    /** Whether user can create posts */
+    canPost: boolean;
+}
+/**
+ * Get data for rendering a quota widget
+ */
+export declare function getQuotaWidgetData(status: SubscriptionStatus): QuotaWidgetData;
+export interface PreSubmitCheckResult {
+    /** Whether the post can be created */
+    allowed: boolean;
+    /** Whether to show a warning dialog */
+    showWarning: boolean;
+    /** Warning message if applicable */
+    warningMessage: string | null;
+    /** Whether upgrade is required */
+    upgradeRequired: boolean;
+    /** Full status for additional UI */
+    status: SubscriptionStatus;
+}
+/**
+ * Check if a post can be created and whether to show warnings
+ */
+export declare function getPreSubmitCheck(response: CanPostResponse): PreSubmitCheckResult;

package/dist/groveauth/limits.js

@@ -0,0 +1,202 @@
+/**
+ * Post Limit Enforcement
+ *
+ * High-level utilities for enforcing post limits in GroveEngine.
+ * Uses GroveAuth subscription API to check and update limits.
+ */
+import { TIER_POST_LIMITS, TIER_NAMES } from './types.js';
+// =============================================================================
+// LIMIT STATUS HELPERS
+// =============================================================================
+/**
+ * Get a human-readable description of the quota status
+ */
+export function getQuotaDescription(status) {
+    if (status.post_limit === null) {
+        return 'Unlimited posts';
+    }
+    const remaining = status.posts_remaining ?? 0;
+    const limit = status.post_limit;
+    const used = status.post_count;
+    if (status.upgrade_required) {
+        return `Limit reached (${used}/${limit}). Upgrade required.`;
+    }
+    if (status.is_in_grace_period && status.grace_period_days_remaining !== null) {
+        return `Limit reached. ${status.grace_period_days_remaining} days remaining in grace period.`;
+    }
+    if (status.is_at_limit) {
+        return `At limit (${used}/${limit}). Delete posts or upgrade.`;
+    }
+    if (status.percentage_used !== null && status.percentage_used >= 90) {
+        return `${remaining} posts remaining (${status.percentage_used.toFixed(0)}% used)`;
+    }
+    return `${used}/${limit} posts used`;
+}
+/**
+ * Get the urgency level for the current quota status
+ */
+export function getQuotaUrgency(status) {
+    if (status.upgrade_required) {
+        return 'blocked';
+    }
+    if (status.is_at_limit || (status.percentage_used !== null && status.percentage_used >= 100)) {
+        return 'critical';
+    }
+    if (status.percentage_used !== null && status.percentage_used >= 90) {
+        return 'warning';
+    }
+    return 'healthy';
+}
+/**
+ * Get suggested actions based on quota status
+ */
+export function getSuggestedActions(status) {
+    const actions = [];
+    if (status.upgrade_required) {
+        actions.push('Upgrade your plan to continue posting');
+        actions.push('Delete older posts to free up space');
+        return actions;
+    }
+    if (status.is_in_grace_period) {
+        actions.push(`Upgrade within ${status.grace_period_days_remaining} days to avoid read-only mode`);
+        actions.push('Delete older posts to get under the limit');
+    }
+    if (status.is_at_limit) {
+        actions.push('Upgrade your plan for more posts');
+        actions.push('Delete older posts to create new ones');
+    }
+    if (status.percentage_used !== null && status.percentage_used >= 75 && status.percentage_used < 90) {
+        actions.push('Consider upgrading soon - you\'re using most of your quota');
+    }
+    return actions;
+}
+/**
+ * Get upgrade recommendation based on current usage
+ */
+export function getUpgradeRecommendation(status) {
+    const tierName = TIER_NAMES[status.tier];
+    if (status.tier === 'evergreen') {
+        return {
+            recommended: false,
+            fromTier: tierName,
+            toTier: null,
+            reason: 'You have the highest tier with unlimited posts',
+        };
+    }
+    if (status.tier === 'oak') {
+        return {
+            recommended: false,
+            fromTier: tierName,
+            toTier: 'Evergreen',
+            reason: 'You already have unlimited posts. Evergreen adds domain search and support hours.',
+        };
+    }
+    if (status.upgrade_required || status.is_at_limit) {
+        const toTier = status.tier === 'seedling' ? 'Sapling' : 'Oak';
+        return {
+            recommended: true,
+            fromTier: tierName,
+            toTier,
+            reason: 'You\'ve reached your post limit',
+        };
+    }
+    if (status.percentage_used !== null && status.percentage_used >= 80) {
+        const toTier = status.tier === 'seedling' ? 'Sapling' : 'Oak';
+        return {
+            recommended: true,
+            fromTier: tierName,
+            toTier,
+            reason: `You're using ${status.percentage_used.toFixed(0)}% of your quota`,
+        };
+    }
+    return {
+        recommended: false,
+        fromTier: tierName,
+        toTier: null,
+        reason: 'Your current plan is sufficient for your usage',
+    };
+}
+/**
+ * Get data for rendering a quota widget
+ */
+export function getQuotaWidgetData(status) {
+    const urgency = getQuotaUrgency(status);
+    const colorMap = {
+        healthy: 'green',
+        warning: 'yellow',
+        critical: 'red',
+        blocked: 'red',
+    };
+    const statusTextMap = {
+        healthy: 'Healthy',
+        warning: 'Warning',
+        critical: 'Critical',
+        blocked: 'Blocked',
+    };
+    return {
+        count: status.post_count,
+        limit: status.post_limit,
+        percentage: status.percentage_used,
+        remaining: status.posts_remaining,
+        color: status.post_limit === null ? 'gray' : colorMap[urgency],
+        statusText: status.post_limit === null ? 'Unlimited' : statusTextMap[urgency],
+        description: getQuotaDescription(status),
+        showUpgrade: urgency === 'warning' || urgency === 'critical' || urgency === 'blocked',
+        tierName: TIER_NAMES[status.tier],
+        canPost: status.can_create_post,
+    };
+}
+/**
+ * Check if a post can be created and whether to show warnings
+ */
+export function getPreSubmitCheck(response) {
+    const { allowed, status } = response;
+    // Upgrade required - can't post at all
+    if (status.upgrade_required) {
+        return {
+            allowed: false,
+            showWarning: true,
+            warningMessage: 'Your grace period has expired. Please upgrade your plan or delete posts to continue.',
+            upgradeRequired: true,
+            status,
+        };
+    }
+    // In grace period - show warning but allow
+    if (status.is_in_grace_period) {
+        return {
+            allowed: true,
+            showWarning: true,
+            warningMessage: `You're over your post limit. ${status.grace_period_days_remaining} days remaining before your account becomes read-only.`,
+            upgradeRequired: false,
+            status,
+        };
+    }
+    // At or near limit - show warning
+    if (status.is_at_limit) {
+        return {
+            allowed,
+            showWarning: true,
+            warningMessage: 'You\'ve reached your post limit. Creating a new post will start your grace period.',
+            upgradeRequired: false,
+            status,
+        };
+    }
+    // Near limit (90%+) - gentle warning
+    if (status.percentage_used !== null && status.percentage_used >= 90) {
+        return {
+            allowed: true,
+            showWarning: true,
+            warningMessage: `You're at ${status.percentage_used.toFixed(0)}% of your post limit. Consider upgrading soon.`,
+            upgradeRequired: false,
+            status,
+        };
+    }
+    // All good
+    return {
+        allowed: true,
+        showWarning: false,
+        warningMessage: null,
+        upgradeRequired: false,
+        status,
+    };
+}

package/dist/groveauth/rate-limit.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Rate Limiting Utilities for GroveAuth API
+ *
+ * Provides CLIENT-SIDE rate limiting and request throttling as a first line
+ * of defense to prevent accidental API abuse and improve user experience.
+ *
+ * IMPORTANT: This is NOT a security measure. Client-side rate limiting can
+ * be bypassed. Server-side rate limiting should be the PRIMARY enforcement
+ * mechanism. This client-side limiter helps:
+ *
+ * 1. Reduce unnecessary API calls (fail fast before hitting server limits)
+ * 2. Improve UX by showing rate limit errors immediately
+ * 3. Prevent accidental DoS from buggy client code
+ *
+ * Server-side implementation should use Cloudflare Workers rate limiting:
+ * @see https://developers.cloudflare.com/workers/runtime-apis/rate-limit/
+ */
+interface RateLimitConfig {
+    /** Maximum requests allowed in the window */
+    maxRequests: number;
+    /** Time window in milliseconds */
+    windowMs: number;
+}
+/**
+ * Default rate limits for different endpoint types.
+ * These should match server-side limits.
+ */
+export declare const DEFAULT_RATE_LIMITS: Record<string, RateLimitConfig>;
+/**
+ * Simple in-memory rate limiter for client-side request throttling.
+ *
+ * Usage:
+ * ```typescript
+ * const limiter = new RateLimiter();
+ *
+ * // Before making an API call
+ * if (!limiter.checkLimit('subscription', userId)) {
+ *   throw new Error('Rate limit exceeded');
+ * }
+ * ```
+ */
+export declare class RateLimiter {
+    private limits;
+    private config;
+    constructor(config?: Record<string, RateLimitConfig>);
+    /**
+     * Check if a request is allowed and increment the counter.
+     *
+     * @param type - The endpoint type (token, subscription, postCount, canPost)
+     * @param key - Unique key for the rate limit (e.g., userId, IP)
+     * @returns true if request is allowed, false if rate limited
+     */
+    checkLimit(type: string, key: string): boolean;
+    /**
+     * Get remaining requests for a given type and key.
+     *
+     * @returns Object with remaining count and reset time, or null if no limit tracked
+     */
+    getRemaining(type: string, key: string): {
+        remaining: number;
+        resetAt: number;
+    } | null;
+    /**
+     * Clear rate limit entries (useful for testing or manual reset)
+     */
+    clear(type?: string, key?: string): void;
+    /**
+     * Clean up expired entries to prevent memory leaks.
+     * Call periodically in long-running processes.
+     */
+    cleanup(): number;
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export declare class RateLimitError extends Error {
+    readonly retryAfterMs: number;
+    constructor(type: string, retryAfterMs: number);
+}
+/**
+ * Create a rate-limited wrapper for async functions.
+ *
+ * Usage:
+ * ```typescript
+ * const limiter = new RateLimiter();
+ * const rateLimitedFetch = withRateLimit(
+ *   limiter,
+ *   'subscription',
+ *   () => userId,
+ *   fetchSubscription
+ * );
+ * ```
+ */
+export declare function withRateLimit<T extends (...args: unknown[]) => Promise<unknown>>(limiter: RateLimiter, type: string, getKey: (...args: Parameters<T>) => string, fn: T): T;
+export {};

package/dist/groveauth/rate-limit.js

@@ -0,0 +1,172 @@
+/**
+ * Rate Limiting Utilities for GroveAuth API
+ *
+ * Provides CLIENT-SIDE rate limiting and request throttling as a first line
+ * of defense to prevent accidental API abuse and improve user experience.
+ *
+ * IMPORTANT: This is NOT a security measure. Client-side rate limiting can
+ * be bypassed. Server-side rate limiting should be the PRIMARY enforcement
+ * mechanism. This client-side limiter helps:
+ *
+ * 1. Reduce unnecessary API calls (fail fast before hitting server limits)
+ * 2. Improve UX by showing rate limit errors immediately
+ * 3. Prevent accidental DoS from buggy client code
+ *
+ * Server-side implementation should use Cloudflare Workers rate limiting:
+ * @see https://developers.cloudflare.com/workers/runtime-apis/rate-limit/
+ */
+/**
+ * Default rate limits for different endpoint types.
+ * These should match server-side limits.
+ */
+export const DEFAULT_RATE_LIMITS = {
+    token: { maxRequests: 10, windowMs: 60000 }, // 10/min
+    subscription: { maxRequests: 60, windowMs: 60000 }, // 60/min
+    postCount: { maxRequests: 30, windowMs: 60000 }, // 30/min
+    canPost: { maxRequests: 120, windowMs: 60000 }, // 120/min
+};
+/**
+ * Simple in-memory rate limiter for client-side request throttling.
+ *
+ * Usage:
+ * ```typescript
+ * const limiter = new RateLimiter();
+ *
+ * // Before making an API call
+ * if (!limiter.checkLimit('subscription', userId)) {
+ *   throw new Error('Rate limit exceeded');
+ * }
+ * ```
+ */
+export class RateLimiter {
+    limits = new Map();
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_RATE_LIMITS, ...config };
+    }
+    /**
+     * Check if a request is allowed and increment the counter.
+     *
+     * @param type - The endpoint type (token, subscription, postCount, canPost)
+     * @param key - Unique key for the rate limit (e.g., userId, IP)
+     * @returns true if request is allowed, false if rate limited
+     */
+    checkLimit(type, key) {
+        const limitConfig = this.config[type];
+        if (!limitConfig) {
+            // Unknown type, allow by default
+            return true;
+        }
+        const limitKey = `${type}:${key}`;
+        const now = Date.now();
+        const entry = this.limits.get(limitKey);
+        // Check if we need to reset the window
+        if (!entry || now >= entry.resetAt) {
+            this.limits.set(limitKey, {
+                count: 1,
+                resetAt: now + limitConfig.windowMs,
+            });
+            return true;
+        }
+        // Check if we're within limits
+        if (entry.count < limitConfig.maxRequests) {
+            entry.count++;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get remaining requests for a given type and key.
+     *
+     * @returns Object with remaining count and reset time, or null if no limit tracked
+     */
+    getRemaining(type, key) {
+        const limitConfig = this.config[type];
+        if (!limitConfig)
+            return null;
+        const limitKey = `${type}:${key}`;
+        const now = Date.now();
+        const entry = this.limits.get(limitKey);
+        if (!entry || now >= entry.resetAt) {
+            return {
+                remaining: limitConfig.maxRequests,
+                resetAt: now + limitConfig.windowMs,
+            };
+        }
+        return {
+            remaining: Math.max(0, limitConfig.maxRequests - entry.count),
+            resetAt: entry.resetAt,
+        };
+    }
+    /**
+     * Clear rate limit entries (useful for testing or manual reset)
+     */
+    clear(type, key) {
+        if (type && key) {
+            this.limits.delete(`${type}:${key}`);
+        }
+        else if (type) {
+            for (const limitKey of this.limits.keys()) {
+                if (limitKey.startsWith(`${type}:`)) {
+                    this.limits.delete(limitKey);
+                }
+            }
+        }
+        else {
+            this.limits.clear();
+        }
+    }
+    /**
+     * Clean up expired entries to prevent memory leaks.
+     * Call periodically in long-running processes.
+     */
+    cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [key, entry] of this.limits.entries()) {
+            if (now >= entry.resetAt) {
+                this.limits.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+export class RateLimitError extends Error {
+    retryAfterMs;
+    constructor(type, retryAfterMs) {
+        super(`Rate limit exceeded for ${type}. Retry after ${Math.ceil(retryAfterMs / 1000)} seconds.`);
+        this.name = "RateLimitError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+/**
+ * Create a rate-limited wrapper for async functions.
+ *
+ * Usage:
+ * ```typescript
+ * const limiter = new RateLimiter();
+ * const rateLimitedFetch = withRateLimit(
+ *   limiter,
+ *   'subscription',
+ *   () => userId,
+ *   fetchSubscription
+ * );
+ * ```
+ */
+export function withRateLimit(limiter, type, getKey, fn) {
+    return (async (...args) => {
+        const key = getKey(...args);
+        const remaining = limiter.getRemaining(type, key);
+        if (!limiter.checkLimit(type, key)) {
+            const retryAfterMs = remaining?.resetAt
+                ? remaining.resetAt - Date.now()
+                : 60000;
+            throw new RateLimitError(type, retryAfterMs);
+        }
+        return fn(...args);
+    });
+}