@nextsparkjs/theme-default 0.1.0-beta.1

package/config/app.config.ts

@@ -0,0 +1,367 @@
+/**
+ * boilerplate Theme- Application Configuration Overrides
+ *
+ * This file allows the theme to override core application configuration values.
+ * Only include properties you want to override - missing properties will use core defaults.
+ */
+
+// Partial configuration type - all properties are optional
+export const APP_CONFIG_OVERRIDES = {
+  // =============================================================================
+  // APPLICATION METADATA OVERRIDES
+  // =============================================================================
+  app: {
+    name: 'Boilerplate',
+    version: '1.0.0',
+  },
+
+  // =============================================================================
+  // TEAMS CONFIGURATION - MULTI-TENANT MODE
+  // =============================================================================
+  /**
+   * Multi-tenant mode:
+   * - Multiple work teams (workspaces)
+   * - Team switching enabled
+   * - Invitations enabled
+   * - Can create new teams
+   */
+  teams: {
+    mode: 'multi-tenant' as const,
+    options: {
+      maxMembersPerTeam: 50,
+      allowLeaveTeam: true,
+      allowCreateTeams: true,
+    },
+  },
+
+  // =============================================================================
+  // INTERNATIONALIZATION OVERRIDES
+  // =============================================================================
+  i18n: {
+    /**
+     * Supported locales for your project
+     * Add/remove locales as needed
+     */
+    supportedLocales: ['en', 'es'],
+
+    /**
+     * Default locale for your project
+     * Override to change the primary language
+     */
+    defaultLocale: 'es' as const,
+
+    /**
+     * Additional namespaces specific to Boilerplate
+     */
+    namespaces: [
+      'common',
+      'dashboard',
+      'settings',
+      'auth',
+      'public',
+      'validation',
+
+      // Project specific
+      'tasks',
+      'clients',
+    ],
+  },
+
+  // =============================================================================
+  // API CONFIGURATION OVERRIDES
+  // =============================================================================
+  api: {
+    cors: {
+      allowedOrigins: {
+        development: [
+          'http://localhost:3000',
+          'http://localhost:5173',
+          'http://127.0.0.1:3000',
+          'http://127.0.0.1:5173',
+          // Project specific development origins
+        ],
+        production: [
+          // Add Project production domains
+          // 'https://boilerplate-themoneyteam.xyz',
+        ],
+      },
+    },
+  },
+
+  // =============================================================================
+  // DOCUMENTATION CONFIGURATION
+  // =============================================================================
+  docs: {
+    /**
+     * Enable/disable documentation system
+     */
+    enabled: true,
+
+    /**
+     * Public access to documentation
+     * - true: Documentation accessible without authentication
+     * - false: Requires user to be logged in
+     */
+    public: true,
+
+    /**
+     * Enable search functionality in documentation
+     */
+    searchEnabled: true,
+
+    /**
+     * Show breadcrumbs in documentation pages
+     */
+    breadcrumbs: true,
+
+    /**
+     * Theme Documentation Configuration
+     * Controls how theme-level documentation appears in the sidebar
+     */
+    theme: {
+      /** Show/hide theme documentation category */
+      enabled: true,
+      /** Expand theme category by default on page load */
+      open: true,
+      /** Custom label displayed in sidebar for theme category */
+      label: "Default Theme",
+    },
+
+    /**
+     * Plugins Documentation Configuration
+     * Controls how plugin documentation appears in the sidebar
+     */
+    plugins: {
+      /** Show/hide plugin documentation category */
+      enabled: true,
+      /** Expand plugins category by default on page load */
+      open: false,
+      /** Custom label displayed in sidebar for plugins category */
+      label: "Plugins",
+    },
+
+    /**
+     * Core Documentation Configuration
+     * Controls how core framework documentation appears in the sidebar
+     */
+    core: {
+      /** Show/hide core documentation category */
+      enabled: true,
+      /** Expand core category by default on page load */
+      open: true,
+      /** Custom label displayed in sidebar for core category */
+      label: "Core",
+    },
+
+    /**
+     * Additional environment-based check for plugin docs in production
+     * Plugin docs will only show if BOTH conditions are met:
+     * 1. plugins.enabled is true
+     * 2. Either in development OR showPluginsDocsInProd is true
+     *
+     * @deprecated Prefer using plugins.enabled for simpler control
+     * By default plugins documentation is not available in prod environments
+     */
+    showPluginsDocsInProd: false,
+  },
+
+  // =============================================================================
+  // TEAM ROLES - NOW IN permissions.config.ts
+  // =============================================================================
+  // Team roles (additionalRoles, hierarchy, displayNames, descriptions) are now
+  // defined in permissions.config.ts under the `roles` section.
+  // This is the SINGLE SOURCE OF TRUTH for all permissions and roles.
+  //
+  // See: contents/themes/default/config/permissions.config.ts
+  //
+  // To add custom roles, edit permissions.config.ts:
+  // ```
+  // roles: {
+  //   additionalRoles: ['editor'],
+  //   hierarchy: { editor: 5 },
+  //   displayNames: { editor: 'common.teamRoles.editor' },
+  //   descriptions: { editor: 'Can view team content...' },
+  // },
+  // ```
+
+  // =============================================================================
+  // USER ROLES EXTENSION
+  // =============================================================================
+  // User roles (member, superadmin, developer) are system-level roles.
+  // For team roles configuration, see permissions.config.ts
+  //
+  // Uncomment to extend user roles:
+  // userRoles: {
+  //   additionalRoles: ['moderator'] as const,
+  //   hierarchy: { moderator: 50 },
+  //   displayNames: { moderator: 'common.userRoles.moderator' },
+  //   descriptions: { moderator: 'Can moderate content' },
+  // },
+
+  // =============================================================================
+  // MOBILE NAVIGATION OVERRIDES
+  // =============================================================================
+  // Uncomment and modify to customize mobile navigation items
+  // You can add/remove/reorder items, change icons, or disable items
+  //
+  mobileNav: {
+    /**
+     * Mobile bottom navigation items
+     * Configure which items appear in the mobile navigation bar
+     *
+     * Icon names use lucide-react icons (https://lucide.dev)
+     * Set isCentral: true for the highlighted center button (only one should have this)
+     */
+    items: [
+      {
+        id: 'home',
+        labelKey: 'common.mobileNav.home',
+        href: '/dashboard',
+        icon: 'Home',
+        enabled: true,
+      },
+      {
+        id: 'tasks',
+        labelKey: 'common.mobileNav.tasks',
+        href: '/dashboard/tasks',
+        icon: 'CheckSquare',
+        enabled: true,
+      },
+      {
+        id: 'create',
+        labelKey: 'common.mobileNav.create',
+        icon: 'Plus',
+        isCentral: true,
+        action: 'quickCreate',
+        enabled: true,
+      },
+      {
+        id: 'settings',
+        labelKey: 'common.mobileNav.settings',
+        href: '/dashboard/settings',
+        icon: 'Settings',
+        enabled: true,
+      },
+      {
+        id: 'more',
+        labelKey: 'common.mobileNav.more',
+        icon: 'Menu',
+        action: 'moreSheet',
+        enabled: true,
+      },
+    ],
+
+    /**
+     * More Sheet items
+     * Configure which items appear in the "More" sheet
+     *
+     * These are secondary navigation items that appear when the user taps "More"
+     * Typical use: Settings subpages, help, support, profile, etc.
+     */
+    moreSheetItems: [
+      {
+        id: 'profile',
+        labelKey: 'common.navigation.profile',
+        href: '/dashboard/settings/profile',
+        icon: 'User',
+        enabled: true,
+      },
+      {
+        id: 'billing',
+        labelKey: 'common.navigation.billing',
+        href: '/dashboard/settings/billing',
+        icon: 'CreditCard',
+        enabled: true,
+      },
+      {
+        id: 'api-keys',
+        labelKey: 'common.navigation.apiKeys',
+        href: '/dashboard/settings/api-keys',
+        icon: 'Key',
+        enabled: true,
+      },
+      {
+        id: 'help',
+        labelKey: 'common.navigation.help',
+        href: '/support',
+        icon: 'HelpCircle',
+        enabled: false,
+        external: true,
+      },
+    ],
+  },
+
+  // =============================================================================
+  // SCHEDULED ACTIONS CONFIGURATION
+  // =============================================================================
+  /**
+   * Scheduled Actions System
+   * Background task processing via external cron
+   */
+  scheduledActions: {
+    /** Enable/disable scheduled actions system */
+    enabled: true,
+
+    /** Retention period for completed/failed actions (days) */
+    retentionDays: 7,
+
+    /** Maximum number of actions to process per cron run */
+    batchSize: 10,
+
+    /** Default timeout per action (milliseconds) */
+    defaultTimeout: 30000,
+
+    /**
+     * Multi-endpoint Webhook Configuration
+     *
+     * Each webhook endpoint is identified by a key and reads its URL from an env variable.
+     * Webhooks can auto-match by event pattern or be explicitly called by key.
+     */
+    webhooks: {
+      endpoints: {
+        // Default catch-all webhook (disabled by default)
+        default: {
+          envVar: 'WEBHOOK_URL_DEFAULT',
+          description: 'Default webhook for general notifications',
+          patterns: ['*:*'],
+          enabled: false,
+        },
+        // Task lifecycle webhook
+        tasks: {
+          envVar: 'WEBHOOK_URL_TASKS',
+          description: 'Task create/update/delete notifications',
+          patterns: ['task:created', 'task:updated', 'task:deleted'],
+          enabled: true,
+        },
+        // Subscription lifecycle webhook
+        subscriptions: {
+          envVar: 'WEBHOOK_URL_SUBSCRIPTIONS',
+          description: 'Subscription lifecycle notifications (create, update, cancel, renewal, expiring)',
+          patterns: ['subscription:created', 'subscription:updated', 'subscription:renewed', 'subscription:cancelled', 'subscription:expiring_soon'],
+          enabled: true,
+        },
+      },
+      defaultEndpoint: 'default',
+    },
+
+    /**
+     * Deduplication Settings
+     *
+     * Prevents duplicate scheduled actions within a time window.
+     * Behavior:
+     * - windowSeconds > 0: Updates existing action's payload (always keeps latest)
+     * - windowSeconds = 0: Disables deduplication (track all changes)
+     */
+    deduplication: {
+      /** Time window in seconds (same entityId within window = duplicate). Set to 0 to disable. */
+      windowSeconds: 30,
+    },
+  },
+
+  // =============================================================================
+  // DEV KEYRING - MOVED TO dev.config.ts
+  // =============================================================================
+  // DevKeyring configuration has been moved to dev.config.ts
+  // This separates development-only settings from production configuration.
+  // See: contents/themes/default/config/dev.config.ts
+}

package/config/billing.config.ts

@@ -0,0 +1,349 @@
+/**
+ * Billing Configuration - Default Theme
+ *
+ * Defines plans, features, limits, and action mappings for the default theme.
+ * This configuration is used by BILLING_REGISTRY with pre-computed matrices
+ * for O(1) runtime lookups.
+ *
+ * The three-layer model:
+ * RESULT = Permission (RBAC) AND Feature (Plan) AND Quota (Limits)
+ */
+
+import type { BillingConfig } from '@nextsparkjs/core/lib/billing/config-types'
+
+export const billingConfig: BillingConfig = {
+  provider: 'stripe',
+  currency: 'usd',
+  defaultPlan: 'free',
+
+  // ===========================================
+  // FEATURE DEFINITIONS
+  // ===========================================
+  features: {
+    // Analytics features
+    basic_analytics: {
+      name: 'billing.features.basic_analytics',
+      description: 'billing.features.basic_analytics_description',
+    },
+    advanced_analytics: {
+      name: 'billing.features.advanced_analytics',
+      description: 'billing.features.advanced_analytics_description',
+    },
+    realtime_analytics: {
+      name: 'billing.features.realtime_analytics',
+      description: 'billing.features.realtime_analytics_description',
+    },
+
+    // API features
+    api_access: {
+      name: 'billing.features.api_access',
+      description: 'billing.features.api_access_description',
+    },
+    webhooks: {
+      name: 'billing.features.webhooks',
+      description: 'billing.features.webhooks_description',
+    },
+
+    // Customization features
+    custom_branding: {
+      name: 'billing.features.custom_branding',
+      description: 'billing.features.custom_branding_description',
+    },
+    white_label: {
+      name: 'billing.features.white_label',
+      description: 'billing.features.white_label_description',
+    },
+
+    // Security features
+    sso: {
+      name: 'billing.features.sso',
+      description: 'billing.features.sso_description',
+    },
+    audit_logs: {
+      name: 'billing.features.audit_logs',
+      description: 'billing.features.audit_logs_description',
+    },
+
+    // Support features
+    priority_support: {
+      name: 'billing.features.priority_support',
+      description: 'billing.features.priority_support_description',
+    },
+    dedicated_support: {
+      name: 'billing.features.dedicated_support',
+      description: 'billing.features.dedicated_support_description',
+    },
+
+    // Collaboration features
+    guest_access: {
+      name: 'billing.features.guest_access',
+      description: 'billing.features.guest_access_description',
+    },
+
+    // Domain-specific features (tasks & customers)
+    task_automation: {
+      name: 'billing.features.task_automation',
+      description: 'billing.features.task_automation_description',
+    },
+    customer_import: {
+      name: 'billing.features.customer_import',
+      description: 'billing.features.customer_import_description',
+    },
+    recurring_tasks: {
+      name: 'billing.features.recurring_tasks',
+      description: 'billing.features.recurring_tasks_description',
+    },
+  },
+
+  // ===========================================
+  // LIMIT DEFINITIONS
+  // ===========================================
+  // Note: Limits correspond to actual entities in the theme (tasks, customers)
+  // and system resources (team_members, storage, api_calls)
+  limits: {
+    team_members: {
+      name: 'billing.limits.team_members',
+      unit: 'count',
+      resetPeriod: 'never',
+    },
+    tasks: {
+      name: 'billing.limits.tasks',
+      unit: 'count',
+      resetPeriod: 'never',
+    },
+    customers: {
+      name: 'billing.limits.customers',
+      unit: 'count',
+      resetPeriod: 'never',
+    },
+    api_calls: {
+      name: 'billing.limits.api_calls',
+      unit: 'calls',
+      resetPeriod: 'monthly',
+    },
+    storage_gb: {
+      name: 'billing.limits.storage',
+      unit: 'bytes',
+      resetPeriod: 'never',
+    },
+    file_uploads: {
+      name: 'billing.limits.file_uploads',
+      unit: 'count',
+      resetPeriod: 'monthly',
+    },
+    webhooks_count: {
+      name: 'billing.limits.webhooks_count',
+      unit: 'count',
+      resetPeriod: 'never',
+    },
+  },
+
+  // ===========================================
+  // PLAN DEFINITIONS
+  // ===========================================
+  plans: [
+    // Free Plan - Basic access for small teams
+    {
+      slug: 'free',
+      name: 'billing.plans.free.name',
+      description: 'billing.plans.free.description',
+      type: 'free',
+      visibility: 'public',
+      price: { monthly: 0, yearly: 0 },
+      trialDays: 0,
+      features: [
+        'basic_analytics',
+      ],
+      limits: {
+        team_members: 3,
+        tasks: 50,
+        customers: 25,
+        api_calls: 1000,
+        storage_gb: 1,
+        file_uploads: 100,
+        webhooks_count: 0,
+      },
+      stripePriceIdMonthly: null,
+      stripePriceIdYearly: null,
+    },
+
+    // Starter Plan - For growing teams
+    {
+      slug: 'starter',
+      name: 'billing.plans.starter.name',
+      description: 'billing.plans.starter.description',
+      type: 'paid',
+      visibility: 'public',
+      price: {
+        monthly: 1500,  // $15.00
+        yearly: 14400,  // $144.00 (20% savings)
+      },
+      trialDays: 7,
+      features: [
+        'basic_analytics',
+        'advanced_analytics',
+        'api_access',
+        'guest_access',
+      ],
+      limits: {
+        team_members: 5,
+        tasks: 200,
+        customers: 100,
+        api_calls: 10000,
+        storage_gb: 10,
+        file_uploads: 500,
+        webhooks_count: 3,
+      },
+      stripePriceIdMonthly: 'price_starter_monthly',
+      stripePriceIdYearly: 'price_starter_yearly',
+    },
+
+    // Pro Plan - For professional teams
+    {
+      slug: 'pro',
+      name: 'billing.plans.pro.name',
+      description: 'billing.plans.pro.description',
+      type: 'paid',
+      visibility: 'public',
+      price: {
+        monthly: 2900,  // $29.00
+        yearly: 29000,  // $290.00 (16% savings)
+      },
+      trialDays: 14,
+      features: [
+        'basic_analytics',
+        'advanced_analytics',
+        'realtime_analytics',
+        'api_access',
+        'webhooks',
+        'custom_branding',
+        'guest_access',
+        'priority_support',
+        'task_automation',
+      ],
+      limits: {
+        team_members: 15,
+        tasks: 1000,
+        customers: 500,
+        api_calls: 100000,
+        storage_gb: 50,
+        file_uploads: 2000,
+        webhooks_count: 10,
+      },
+      stripePriceIdMonthly: 'price_pro_monthly',
+      stripePriceIdYearly: 'price_pro_yearly',
+    },
+
+    // Business Plan - For larger organizations
+    {
+      slug: 'business',
+      name: 'billing.plans.business.name',
+      description: 'billing.plans.business.description',
+      type: 'paid',
+      visibility: 'public',
+      price: {
+        monthly: 7900,  // $79.00
+        yearly: 79000,  // $790.00 (16% savings)
+      },
+      trialDays: 14,
+      features: [
+        'basic_analytics',
+        'advanced_analytics',
+        'realtime_analytics',
+        'api_access',
+        'webhooks',
+        'custom_branding',
+        'sso',
+        'audit_logs',
+        'guest_access',
+        'priority_support',
+        'task_automation',
+        'customer_import',
+        'recurring_tasks',
+      ],
+      limits: {
+        team_members: 50,
+        tasks: 5000,
+        customers: 2000,
+        api_calls: 500000,
+        storage_gb: 200,
+        file_uploads: 10000,
+        webhooks_count: 50,
+      },
+      stripePriceIdMonthly: 'price_business_monthly',
+      stripePriceIdYearly: 'price_business_yearly',
+    },
+
+    // Enterprise Plan - Custom unlimited plan
+    {
+      slug: 'enterprise',
+      name: 'billing.plans.enterprise.name',
+      description: 'billing.plans.enterprise.description',
+      type: 'enterprise',
+      visibility: 'hidden',
+      trialDays: 30,
+      features: ['*'],  // All features
+      limits: {
+        team_members: -1,  // Unlimited
+        tasks: -1,
+        customers: -1,
+        api_calls: -1,
+        storage_gb: -1,
+        file_uploads: -1,
+        webhooks_count: -1,
+      },
+      stripePriceIdMonthly: null,
+      stripePriceIdYearly: null,
+    },
+  ],
+
+  // ===========================================
+  // ACTION MAPPINGS
+  // ===========================================
+  // Maps user actions to RBAC permissions, plan features, and limits.
+  // This is the "three-layer model": RESULT = Permission AND Feature AND Quota
+  actionMappings: {
+    // RBAC permissions (optional - integrates with existing permission system)
+    permissions: {
+      'team.members.invite': 'team.members.invite',
+      'team.settings.edit': 'team.settings.edit',
+      'team.billing.manage': 'team.billing.manage',
+    },
+
+    // Feature requirements per action
+    features: {
+      // Analytics features
+      'analytics.view_advanced': 'advanced_analytics',
+      'analytics.view_realtime': 'realtime_analytics',
+      // API features
+      'api.generate_key': 'api_access',
+      'webhooks.create': 'webhooks',
+      // Branding features
+      'branding.customize': 'custom_branding',
+      'branding.white_label': 'white_label',
+      // Security features
+      'auth.configure_sso': 'sso',
+      'security.view_audit_logs': 'audit_logs',
+      // Support features
+      'support.priority_access': 'priority_support',
+      'support.dedicated_channel': 'dedicated_support',
+      // Collaboration features
+      'team.invite_guest': 'guest_access',
+      // Domain-specific features (tasks & customers)
+      'tasks.automate': 'task_automation',
+      'tasks.create_recurring': 'recurring_tasks',
+      'customers.bulk_import': 'customer_import',
+    },
+
+    // Limit consumption per action (maps to actual entities)
+    limits: {
+      'team.members.invite': 'team_members',
+      'tasks.create': 'tasks',
+      'customers.create': 'customers',
+      'api.call': 'api_calls',
+      'files.upload': 'storage_gb',
+      'files.upload_count': 'file_uploads',
+      'webhooks.create': 'webhooks_count',
+    },
+  },
+}