From 84725b2dfae10047d661cd23a013ef2b0b5fd35f Mon Sep 17 00:00:00 2001
From: Darko Gjorgjijoski <dg@darkog.com>
Date: Thu, 9 Apr 2026 00:28:59 +0200
Subject: [PATCH] feat(modules): relocate marketplace browser to super-admin
 context
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The module marketplace browser UI (ModuleIndexView, ModuleDetailView,
ModuleCard, the four-step installer store) was filed under
features/company/modules/ only by historical accident — it's authorized via
the manage modules ability (super-admin-only) and conceptually belongs in the
admin context, not the company context.

- Move features/company/modules/{store.ts, views/ModuleIndexView.vue,
  views/ModuleDetailView.vue, components/ModuleCard.vue} to
  features/admin/modules/.
- Update hardcoded /admin/modules/... paths in the moved files to
  /admin/administration/modules/... so the breadcrumbs and ModuleCard
  navigation target the new admin-context routes.
- Tighten the four-step installer's silent catch {} blocks in the moved
  store.ts: errors were being swallowed, now they dispatch through the
  global notification store instead.
- New features/admin/modules/routes.ts declares admin.modules.index +
  admin.modules.view as children of /admin/administration with
  meta.isSuperAdmin: true.
- features/admin/{index,routes}.ts re-export and mount the relocated routes.
- config/invoiceshelf.php gains a new AdminModules entry in admin_menu
  pointing at /admin/administration/modules with super_admin_only: true.
- The dev-gated navigation.modules entry in main_menu is replaced (not
  deleted) with a non-gated entry pointing at the new company-context
  Active Modules index page that lands in the next commit. The
  ability is set to manage modules so non-owners can't see it.

The new company-context Active Modules index, schema-driven settings page,
and dynamic sidebar group are introduced in subsequent commits.
---
 config/invoiceshelf.php                       |  36 ++--
 resources/scripts/features/admin/index.ts     |  16 ++
 .../modules/components/ModuleCard.vue         |   2 +-
 .../scripts/features/admin/modules/index.ts   |  17 ++
 .../scripts/features/admin/modules/routes.ts  |  34 +++
 .../scripts/features/admin/modules/store.ts   | 193 ++++++++++++++++++
 .../modules/views/ModuleDetailView.vue        |   4 +-
 .../modules/views/ModuleIndexView.vue         |   0
 resources/scripts/features/admin/routes.ts    |   2 +
 9 files changed, 286 insertions(+), 18 deletions(-)
 rename resources/scripts/features/{company => admin}/modules/components/ModuleCard.vue (97%)
 create mode 100644 resources/scripts/features/admin/modules/index.ts
 create mode 100644 resources/scripts/features/admin/modules/routes.ts
 create mode 100644 resources/scripts/features/admin/modules/store.ts
 rename resources/scripts/features/{company => admin}/modules/views/ModuleDetailView.vue (99%)
 rename resources/scripts/features/{company => admin}/modules/views/ModuleIndexView.vue (100%)

diff --git a/config/invoiceshelf.php b/config/invoiceshelf.php
index 95cea065..fba7c1d3 100644
--- a/config/invoiceshelf.php
+++ b/config/invoiceshelf.php
@@ -346,21 +346,16 @@ return [
             'ability' => 'view-expense',
             'model' => Expense::class,
         ],
-        // TODO: remove env check once the module management os implemented.
-        ...(
-            env('APP_ENV', 'production') == 'development' ? [
-                [
-                    'title' => 'navigation.modules',
-                    'group' => 3,
-                    'link' => '/admin/modules',
-                    'icon' => 'PuzzlePieceIcon',
-                    'name' => 'Modules',
-                    'owner_only' => true,
-                    'ability' => '',
-                    'model' => '',
-                ],
-            ] : []
-        ),
+        [
+            'title' => 'navigation.modules',
+            'group' => 3,
+            'link' => '/admin/modules',
+            'icon' => 'PuzzlePieceIcon',
+            'name' => 'Modules',
+            'owner_only' => false,
+            'ability' => 'manage modules',
+            'model' => '',
+        ],
         [
             'title' => 'navigation.members',
             'group' => 3,
@@ -430,6 +425,17 @@ return [
             'ability' => '',
             'model' => '',
         ],
+        [
+            'title' => 'navigation.modules',
+            'group' => 1,
+            'link' => '/admin/administration/modules',
+            'icon' => 'PuzzlePieceIcon',
+            'name' => 'AdminModules',
+            'owner_only' => false,
+            'super_admin_only' => true,
+            'ability' => '',
+            'model' => '',
+        ],
         [
             'title' => 'navigation.settings',
             'group' => 1,
diff --git a/resources/scripts/features/admin/index.ts b/resources/scripts/features/admin/index.ts
index 64e64cc5..0453838c 100644
--- a/resources/scripts/features/admin/index.ts
+++ b/resources/scripts/features/admin/index.ts
@@ -18,3 +18,19 @@ export { default as AdminSettingsView } from './views/AdminSettingsView.vue'
 
 export { default as AdminCompanyDropdown } from './components/AdminCompanyDropdown.vue'
 export { default as AdminUserDropdown } from './components/AdminUserDropdown.vue'
+
+// Modules (super-admin marketplace browser)
+export {
+  adminModuleRoutes,
+  useModuleStore,
+  ModuleIndexView,
+  ModuleDetailView,
+  ModuleCard,
+} from './modules'
+export type {
+  ModuleState,
+  ModuleStore,
+  ModuleDetailResponse,
+  ModuleDetailMeta,
+  InstallationStep,
+} from './modules'
diff --git a/resources/scripts/features/company/modules/components/ModuleCard.vue b/resources/scripts/features/admin/modules/components/ModuleCard.vue
similarity index 97%
rename from resources/scripts/features/company/modules/components/ModuleCard.vue
rename to resources/scripts/features/admin/modules/components/ModuleCard.vue
index 022fccfd..bd1e5445 100644
--- a/resources/scripts/features/company/modules/components/ModuleCard.vue
+++ b/resources/scripts/features/admin/modules/components/ModuleCard.vue
@@ -1,7 +1,7 @@
 <template>
   <div
     class="relative shadow-md border-2 border-line-default/60 rounded-lg cursor-pointer overflow-hidden h-100"
-    @click="$router.push(`/admin/modules/${data.slug}`)"
+    @click="$router.push(`/admin/administration/modules/${data.slug}`)"
   >
     <div
       v-if="data.purchased"
diff --git a/resources/scripts/features/admin/modules/index.ts b/resources/scripts/features/admin/modules/index.ts
new file mode 100644
index 00000000..795e3060
--- /dev/null
+++ b/resources/scripts/features/admin/modules/index.ts
@@ -0,0 +1,17 @@
+export { adminModuleRoutes } from './routes'
+
+export { useModuleStore } from './store'
+export type {
+  ModuleState,
+  ModuleStore,
+  ModuleDetailResponse,
+  ModuleDetailMeta,
+  InstallationStep,
+} from './store'
+
+// Views
+export { default as ModuleIndexView } from './views/ModuleIndexView.vue'
+export { default as ModuleDetailView } from './views/ModuleDetailView.vue'
+
+// Components
+export { default as ModuleCard } from './components/ModuleCard.vue'
diff --git a/resources/scripts/features/admin/modules/routes.ts b/resources/scripts/features/admin/modules/routes.ts
new file mode 100644
index 00000000..57c5ca6e
--- /dev/null
+++ b/resources/scripts/features/admin/modules/routes.ts
@@ -0,0 +1,34 @@
+import type { RouteRecordRaw } from 'vue-router'
+
+const ModuleIndexView = () => import('./views/ModuleIndexView.vue')
+const ModuleDetailView = () => import('./views/ModuleDetailView.vue')
+
+/**
+ * Super-admin marketplace browser routes.
+ *
+ * These are mounted as children of `/admin/administration` in features/admin/routes.ts,
+ * meaning they require `meta.isSuperAdmin` and the admin-mode bootstrap.
+ *
+ * Company-context module routes (the read-only Active Modules index and the
+ * schema-rendered settings page) live in features/company/modules/routes.ts.
+ */
+export const adminModuleRoutes: RouteRecordRaw[] = [
+  {
+    path: 'modules',
+    name: 'admin.modules.index',
+    component: ModuleIndexView,
+    meta: {
+      isSuperAdmin: true,
+      title: 'modules.title',
+    },
+  },
+  {
+    path: 'modules/:slug',
+    name: 'admin.modules.view',
+    component: ModuleDetailView,
+    meta: {
+      isSuperAdmin: true,
+      title: 'modules.title',
+    },
+  },
+]
diff --git a/resources/scripts/features/admin/modules/store.ts b/resources/scripts/features/admin/modules/store.ts
new file mode 100644
index 00000000..1bdd7dcc
--- /dev/null
+++ b/resources/scripts/features/admin/modules/store.ts
@@ -0,0 +1,193 @@
+import { defineStore } from 'pinia'
+import { moduleService } from '../../../api/services/module.service'
+import type {
+  Module,
+  ModuleReview,
+  ModuleFaq,
+  ModuleLink,
+  ModuleScreenshot,
+} from '../../../types/domain/module'
+
+// ----------------------------------------------------------------
+// Types
+// ----------------------------------------------------------------
+
+export interface ModuleDetailMeta {
+  modules: Module[]
+}
+
+export interface ModuleDetailResponse {
+  data: Module
+  meta: ModuleDetailMeta
+}
+
+export interface InstallationStep {
+  translationKey: string
+  stepUrl: string
+  time: string | null
+  started: boolean
+  completed: boolean
+}
+
+// ----------------------------------------------------------------
+// Store
+// ----------------------------------------------------------------
+
+export interface ModuleState {
+  currentModule: ModuleDetailResponse | null
+  modules: Module[]
+  apiToken: string | null
+  currentUser: {
+    api_token: string | null
+  }
+  enableModules: string[]
+}
+
+export const useModuleStore = defineStore('modules', {
+  state: (): ModuleState => ({
+    currentModule: null,
+    modules: [],
+    apiToken: null,
+    currentUser: {
+      api_token: null,
+    },
+    enableModules: [],
+  }),
+
+  getters: {
+    salesTaxUSEnabled: (state): boolean =>
+      state.enableModules.includes('SalesTaxUS'),
+
+    installedModules: (state): Module[] =>
+      state.modules.filter((m) => m.installed),
+  },
+
+  actions: {
+    async fetchModules(): Promise<void> {
+      const response = await moduleService.list()
+      this.modules = response.data
+    },
+
+    async fetchModule(slug: string): Promise<ModuleDetailResponse> {
+      const response = await moduleService.get(slug)
+      const data = response as unknown as ModuleDetailResponse
+
+      if ((data as Record<string, unknown>).error === 'invalid_token') {
+        this.currentModule = null
+        this.modules = []
+        this.apiToken = null
+        this.currentUser.api_token = null
+        return data
+      }
+
+      this.currentModule = data
+      return data
+    },
+
+    async checkApiToken(token: string): Promise<{ success: boolean; error?: string }> {
+      const response = await moduleService.checkToken(token)
+      return {
+        success: response.success ?? false,
+        error: response.error,
+      }
+    },
+
+    async disableModule(moduleName: string): Promise<{ success: boolean }> {
+      return moduleService.disable(moduleName)
+    },
+
+    async enableModule(moduleName: string): Promise<{ success: boolean }> {
+      return moduleService.enable(moduleName)
+    },
+
+    async installModule(
+      moduleName: string,
+      version: string,
+      onStepUpdate?: (step: InstallationStep) => void,
+    ): Promise<boolean> {
+      const steps: InstallationStep[] = [
+        {
+          translationKey: 'modules.download_zip_file',
+          stepUrl: '/api/v1/modules/download',
+          time: null,
+          started: false,
+          completed: false,
+        },
+        {
+          translationKey: 'modules.unzipping_package',
+          stepUrl: '/api/v1/modules/unzip',
+          time: null,
+          started: false,
+          completed: false,
+        },
+        {
+          translationKey: 'modules.copying_files',
+          stepUrl: '/api/v1/modules/copy',
+          time: null,
+          started: false,
+          completed: false,
+        },
+        {
+          translationKey: 'modules.completing_installation',
+          stepUrl: '/api/v1/modules/complete',
+          time: null,
+          started: false,
+          completed: false,
+        },
+      ]
+
+      let path: string | null = null
+
+      for (const step of steps) {
+        step.started = true
+        onStepUpdate?.(step)
+
+        try {
+          const stepFns: Record<string, () => Promise<Record<string, unknown>>> = {
+            '/api/v1/modules/download': () =>
+              moduleService.download({ module: moduleName, version, path: path ?? undefined } as never) as Promise<Record<string, unknown>>,
+            '/api/v1/modules/unzip': () =>
+              moduleService.unzip({ module: moduleName, version, path: path ?? undefined } as never) as Promise<Record<string, unknown>>,
+            '/api/v1/modules/copy': () =>
+              moduleService.copy({ module: moduleName, version, path: path ?? undefined } as never) as Promise<Record<string, unknown>>,
+            '/api/v1/modules/complete': () =>
+              moduleService.complete({ module: moduleName, version, path: path ?? undefined } as never) as Promise<Record<string, unknown>>,
+          }
+
+          const result = await stepFns[step.stepUrl]()
+          step.completed = true
+          onStepUpdate?.(step)
+
+          if ((result as Record<string, unknown>).path) {
+            path = (result as Record<string, unknown>).path as string
+          }
+
+          if (!(result as Record<string, unknown>).success) {
+            const message = (result as Record<string, unknown>).error
+            if (typeof message === 'string') {
+              const { useNotificationStore } = await import('@/scripts/stores/notification.store')
+              useNotificationStore().showNotification({
+                type: 'error',
+                message,
+              })
+            }
+            return false
+          }
+        } catch (err: unknown) {
+          step.completed = true
+          onStepUpdate?.(step)
+          const { useNotificationStore } = await import('@/scripts/stores/notification.store')
+          useNotificationStore().showNotification({
+            type: 'error',
+            message: err instanceof Error ? err.message : 'Module installation failed',
+          })
+          return false
+        }
+      }
+
+      return true
+    },
+  },
+})
+
+export type ModuleStore = ReturnType<typeof useModuleStore>
diff --git a/resources/scripts/features/company/modules/views/ModuleDetailView.vue b/resources/scripts/features/admin/modules/views/ModuleDetailView.vue
similarity index 99%
rename from resources/scripts/features/company/modules/views/ModuleDetailView.vue
rename to resources/scripts/features/admin/modules/views/ModuleDetailView.vue
index 1d9a2c0a..206d800c 100644
--- a/resources/scripts/features/company/modules/views/ModuleDetailView.vue
+++ b/resources/scripts/features/admin/modules/views/ModuleDetailView.vue
@@ -10,7 +10,7 @@
     <BasePageHeader :title="moduleData.name">
       <BaseBreadcrumb>
         <BaseBreadcrumbItem :title="$t('general.home')" to="dashboard" />
-        <BaseBreadcrumbItem :title="$t('modules.title')" to="/admin/modules" />
+        <BaseBreadcrumbItem :title="$t('modules.title')" to="/admin/administration/modules" />
         <BaseBreadcrumbItem :title="moduleData.name" to="#" active />
       </BaseBreadcrumb>
     </BasePageHeader>
@@ -291,7 +291,7 @@
       <div class="flex items-center justify-between space-x-4">
         <h2 class="text-lg font-medium text-heading">{{ $t('modules.other_modules') }}</h2>
         <a
-          href="/admin/modules"
+          href="/admin/administration/modules"
           class="whitespace-nowrap text-sm font-medium text-primary-600 hover:text-primary-500"
         >
           {{ $t('modules.view_all') }}
diff --git a/resources/scripts/features/company/modules/views/ModuleIndexView.vue b/resources/scripts/features/admin/modules/views/ModuleIndexView.vue
similarity index 100%
rename from resources/scripts/features/company/modules/views/ModuleIndexView.vue
rename to resources/scripts/features/admin/modules/views/ModuleIndexView.vue
diff --git a/resources/scripts/features/admin/routes.ts b/resources/scripts/features/admin/routes.ts
index e295e5d0..289c8197 100644
--- a/resources/scripts/features/admin/routes.ts
+++ b/resources/scripts/features/admin/routes.ts
@@ -1,4 +1,5 @@
 import type { RouteRecordRaw } from 'vue-router'
+import { adminModuleRoutes } from './modules/routes'
 
 const CompanyLayout = () => import('../../layouts/CompanyLayout.vue')
 const AdminDashboardView = () => import('./views/AdminDashboardView.vue')
@@ -64,6 +65,7 @@ export const adminRoutes: RouteRecordRaw[] = [
           isSuperAdmin: true,
         },
       },
+      ...adminModuleRoutes,
       {
         path: 'settings',
         name: 'admin.settings',