@nextclaw/ui 0.15.26 → 0.15.27

package/src/features/apps/hooks/use-app-marketplace.test.ts

@@ -0,0 +1,144 @@
+import type { AppMarketplaceItemView } from './use-app-marketplace';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const app: AppMarketplaceItemView = {
+  id: 'app-personal-organizer',
+  slug: 'personal-organizer',
+  appId: 'nextclaw.personal-organizer',
+  name: '个人空间',
+  summary: 'A calm personal space.',
+  summaryI18n: { en: 'A calm personal space.' },
+  tags: ['personal'],
+  latestVersion: '0.1.1',
+  featured: true,
+  publisher: { id: 'nextclaw', name: 'NextClaw' },
+  install: {
+    kind: 'registry' as const,
+    spec: 'nextclaw.personal-organizer',
+    registry: 'https://apps-registry.nextclaw.io/api/v1/apps/registry/',
+  },
+  webUrl: 'https://apps.nextclaw.io/apps/personal-organizer',
+};
+
+afterEach(() => {
+  vi.resetModules();
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+});
+
+describe('withDevPreviewCover', () => {
+  it('uses an explicitly configured preview cover for a known official app', async () => {
+    vi.stubEnv('VITE_APP_MARKETPLACE_PREVIEW_COVER_BASE_URL', 'http://127.0.0.1:4178/covers/');
+    const { withDevPreviewCover } = await import('./use-app-marketplace');
+
+    expect(withDevPreviewCover(app).coverUrl).toBe(
+      'http://127.0.0.1:4178/covers/personal-organizer.webp',
+    );
+    expect(withDevPreviewCover(app).coverPreview).toBe(true);
+  });
+
+  it('keeps a Registry cover as the canonical source', async () => {
+    vi.stubEnv('VITE_APP_MARKETPLACE_PREVIEW_COVER_BASE_URL', 'http://127.0.0.1:4178/covers');
+    const { withDevPreviewCover } = await import('./use-app-marketplace');
+    const registryCover = 'https://apps-registry.nextclaw.io/cover.webp';
+
+    expect(withDevPreviewCover({ ...app, coverUrl: registryCover }).coverUrl).toBe(registryCover);
+    expect(withDevPreviewCover({ ...app, coverUrl: registryCover }).coverPreview).toBeUndefined();
+  });
+
+  it('does not guess preview assets for third-party apps', async () => {
+    vi.stubEnv('VITE_APP_MARKETPLACE_PREVIEW_COVER_BASE_URL', 'http://127.0.0.1:4178/covers');
+    const { withDevPreviewCover } = await import('./use-app-marketplace');
+
+    expect(withDevPreviewCover({
+      ...app,
+      publisher: { id: 'third-party', name: 'Third Party' },
+    }).coverUrl).toBeUndefined();
+  });
+});
+
+describe('fetchAppMarketplace', () => {
+  it('uses the cursor catalog endpoint and preserves pagination metadata', async () => {
+    const fetchMock = vi.fn(async (_input: string | URL | Request, _init?: RequestInit) => new Response(JSON.stringify({
+      ok: true,
+      data: {
+        items: [app],
+        hasMore: true,
+        nextCursor: 'cursor-2',
+        query: 'notes',
+        tag: 'personal',
+        sort: 'relevance',
+      },
+    }), { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+    const { fetchAppMarketplace } = await import('./use-app-marketplace');
+
+    await expect(fetchAppMarketplace({
+      q: 'notes',
+      tag: 'personal',
+      cursor: 'cursor-1',
+      limit: 24,
+    })).resolves.toMatchObject({
+      hasMore: true,
+      nextCursor: 'cursor-2',
+      items: [app],
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.stringContaining('/api/v2/apps/items?'),
+      expect.any(Object),
+    );
+    const requestUrl = fetchMock.mock.calls[0]?.[0];
+    expect(requestUrl).toBeTypeOf('string');
+    const url = new URL(String(requestUrl));
+    expect(Object.fromEntries(url.searchParams)).toMatchObject({
+      q: 'notes',
+      tag: 'personal',
+      cursor: 'cursor-1',
+      limit: '24',
+    });
+  });
+
+  it('uses the legacy catalog only when the server explicitly does not support v2', async () => {
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(new Response(null, { status: 404 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify({
+        ok: true,
+        data: { items: [app], page: 1, pageSize: 100, total: 1, totalPages: 1 },
+      }), { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+    const { fetchAppMarketplace } = await import('./use-app-marketplace');
+
+    await expect(fetchAppMarketplace({ tags: ['personal'], limit: 24 })).resolves.toMatchObject({
+      hasMore: false,
+      items: [app],
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[1]?.[0]).toContain('/api/v1/apps/items?');
+  });
+
+  it('does not hide a v2 server failure behind the compatibility path', async () => {
+    const fetchMock = vi.fn(async () => new Response(null, { status: 500 }));
+    vi.stubGlobal('fetch', fetchMock);
+    const { fetchAppMarketplace } = await import('./use-app-marketplace');
+
+    await expect(fetchAppMarketplace()).rejects.toThrow('Marketplace request failed (500)');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('forwards cancellation through both v2 and its explicit compatibility request', async () => {
+    const controller = new AbortController();
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(new Response(null, { status: 404 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify({
+        ok: true,
+        data: { items: [app], page: 1, pageSize: 100, total: 1, totalPages: 1 },
+      }), { status: 200 }));
+    vi.stubGlobal('fetch', fetchMock);
+    const { fetchAppMarketplace } = await import('./use-app-marketplace');
+
+    await fetchAppMarketplace({}, controller.signal);
+
+    expect(fetchMock.mock.calls[0]?.[1]).toMatchObject({ signal: controller.signal });
+    expect(fetchMock.mock.calls[1]?.[1]).toMatchObject({ signal: controller.signal });
+  });
+});

package/src/features/apps/hooks/use-app-marketplace.ts

@@ -1,95 +1,65 @@
-import { useQuery } from '@tanstack/react-query';
+import { useInfiniteQuery, useQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
+import {
+  fetchAppMarketplace,
+  fetchAppMarketplaceDetail,
+  withDevPreviewCover,
+} from '@/features/apps/services/app-marketplace.service';
+import type {
+  AppMarketplaceCatalogParams,
+  AppMarketplaceItemView,
+  AppMarketplaceListView,
+} from '@/features/apps/types/app-marketplace.types';
 
-const APP_MARKETPLACE_QUERY_KEY = ['app-marketplace'] as const;
-const APP_MARKETPLACE_BASE_URL = 'https://apps-registry.nextclaw.io';
+export { fetchAppMarketplace, withDevPreviewCover };
+export type {
+  AppMarketplaceCatalogParams,
+  AppMarketplaceCatalogView,
+  AppMarketplaceDetailView,
+  AppMarketplaceItemView,
+  AppMarketplaceListView,
+} from '@/features/apps/types/app-marketplace.types';
 
-export type AppMarketplaceItemView = {
-  id: string;
-  slug: string;
-  appId: string;
-  name: string;
-  summary: string;
-  summaryI18n: Record<string, string>;
-  tags: string[];
-  latestVersion: string;
-  featured: boolean;
-  publisher: {
-    id: string;
-    name: string;
-    url?: string;
-  };
-  install: {
-    kind: 'registry';
-    spec: string;
-    registry: string;
-  };
-  webUrl: string;
-};
+const APP_MARKETPLACE_QUERY_KEY = ['app-marketplace', 'v3'] as const;
 
-export type AppMarketplaceListView = {
-  total: number;
-  items: AppMarketplaceItemView[];
-};
-
-export function useAppMarketplace(enabled: boolean) {
-  return useQuery({
-    queryKey: APP_MARKETPLACE_QUERY_KEY,
-    queryFn: fetchAppMarketplace,
+export function useAppMarketplace(params: AppMarketplaceCatalogParams, enabled: boolean) {
+  const query = useInfiniteQuery({
+    queryKey: [...APP_MARKETPLACE_QUERY_KEY, params],
+    initialPageParam: undefined as string | undefined,
+    queryFn: async ({ pageParam, signal }) => await fetchAppMarketplace({
+      ...params,
+      cursor: pageParam,
+      limit: 24,
+    }, signal),
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
     enabled,
     retry: 1,
     staleTime: 5 * 60 * 1000,
   });
+  const data = useMemo<AppMarketplaceListView | undefined>(() => {
+    if (!query.data) {
+      return undefined;
+    }
+    const byId = new Map<string, AppMarketplaceItemView>();
+    for (const page of query.data.pages) {
+      for (const item of page.items) {
+        byId.set(item.id, item);
+      }
+    }
+    return {
+      items: [...byId.values()],
+      hasMore: query.data.pages.at(-1)?.hasMore ?? false,
+    };
+  }, [query.data]);
+  return { ...query, data };
 }
 
-async function fetchAppMarketplace(): Promise<AppMarketplaceListView> {
-  const response = await fetch(
-    `${APP_MARKETPLACE_BASE_URL}/api/v1/apps/items?page=1&pageSize=100`,
-    { headers: { accept: 'application/json' } },
-  );
-  if (!response.ok) {
-    throw new Error(`Marketplace request failed (${response.status})`);
-  }
-
-  const payload: unknown = await response.json();
-  if (!isRecord(payload) || payload.ok !== true || !isRecord(payload.data)) {
-    throw new Error('Marketplace returned an invalid response');
-  }
-
-  const items = Array.isArray(payload.data.items)
-    ? payload.data.items.filter(isAppMarketplaceItem)
-    : [];
-  return {
-    total: typeof payload.data.total === 'number' ? payload.data.total : items.length,
-    items,
-  };
-}
-
-function isAppMarketplaceItem(value: unknown): value is AppMarketplaceItemView {
-  if (!isRecord(value) || !isRecord(value.install) || !isRecord(value.publisher)) {
-    return false;
-  }
-  return typeof value.id === 'string'
-    && typeof value.slug === 'string'
-    && typeof value.appId === 'string'
-    && typeof value.name === 'string'
-    && typeof value.summary === 'string'
-    && isStringRecord(value.summaryI18n)
-    && Array.isArray(value.tags)
-    && value.tags.every((tag) => typeof tag === 'string')
-    && typeof value.latestVersion === 'string'
-    && typeof value.featured === 'boolean'
-    && typeof value.publisher.id === 'string'
-    && typeof value.publisher.name === 'string'
-    && value.install.kind === 'registry'
-    && typeof value.install.spec === 'string'
-    && typeof value.install.registry === 'string'
-    && typeof value.webUrl === 'string';
-}
-
-function isStringRecord(value: unknown): value is Record<string, string> {
-  return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'string');
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+export function useAppMarketplaceDetail(slug: string | null, enabled: boolean) {
+  return useQuery({
+    queryKey: ['app-marketplace-detail', 'v2', slug],
+    queryFn: async ({ signal }) => await fetchAppMarketplaceDetail(slug ?? '', signal),
+    enabled: enabled && Boolean(slug),
+    retry: 1,
+    staleTime: 5 * 60 * 1000,
+  });
 }

package/src/features/apps/hooks/use-app-packages.ts

@@ -1,10 +1,23 @@
+import { useEffect } from 'react';
 import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import type { AppPackageOperationStatus, AppPackageOperationView } from '@nextclaw/client-sdk';
 import { nextclawClient } from '@/shared/lib/api';
+import type { AppPackageOperationSettlementManager } from '@/features/apps/managers/app-package-operation-settlement.manager';
 
 const APP_PACKAGES_QUERY_KEY = ['app-packages'] as const;
 const PANEL_APPS_QUERY_KEY = ['panel-apps'] as const;
 const SERVICE_APPS_QUERY_KEY = ['service-apps'] as const;
 const SERVICE_ACTIONS_QUERY_KEY = ['service-actions'] as const;
+const APP_PACKAGE_OPERATIONS_QUERY_KEY = ['app-package-operations'] as const;
+
+const ACTIVE_OPERATION_STATUSES = new Set<AppPackageOperationStatus>([
+  'queued',
+  'resolving',
+  'downloading',
+  'verifying',
+  'installing',
+  'finalizing',
+]);
 
 export type AppPackageMutationInput =
   | { action: 'enable'; appId: string }
@@ -22,6 +35,47 @@ export function useAppPackages() {
   });
 }
 
+export function useAppPackageOperations() {
+  return useQuery({
+    queryKey: APP_PACKAGE_OPERATIONS_QUERY_KEY,
+    queryFn: () => nextclawClient.appPackages.listOperations(),
+    refetchInterval: (query) => {
+      const entries = query.state.data?.entries ?? [];
+      return entries.some((entry) => isAppPackageOperationActive(entry.status)) ? 500 : false;
+    },
+    staleTime: 0,
+  });
+}
+
+export function isAppPackageOperationActive(status: AppPackageOperationStatus): boolean {
+  return ACTIVE_OPERATION_STATUSES.has(status);
+}
+
+export function useAppPackageOperationSettlement({
+  isLoaded,
+  operations,
+  refetchPackages,
+  refetchPanels,
+  settlementManager,
+}: {
+  isLoaded: boolean;
+  operations: AppPackageOperationView[];
+  refetchPackages: () => Promise<unknown>;
+  refetchPanels: () => Promise<{
+    data?: { entries: Array<{ id: string; packageId?: string }> };
+  }>;
+  settlementManager: AppPackageOperationSettlementManager;
+}) {
+  useEffect(() => {
+    settlementManager.settle({
+      isLoaded,
+      operations,
+      refetchPackages,
+      refetchPanels,
+    });
+  }, [isLoaded, operations, refetchPackages, refetchPanels, settlementManager]);
+}
+
 export function useAppPackageMutation() {
   const queryClient = useQueryClient();
   return useMutation({
@@ -32,16 +86,16 @@ export function useAppPackageMutation() {
         case 'disable':
           return await nextclawClient.appPackages.disable(input.appId);
         case 'install':
-          return await nextclawClient.appPackages.install({
+          return await nextclawClient.appPackages.startInstall({
             source: input.source,
             registryUrl: input.registryUrl,
           });
         case 'update':
-          return await nextclawClient.appPackages.update(input.appId);
+          return await nextclawClient.appPackages.startUpdate(input.appId);
         case 'rollback':
-          return await nextclawClient.appPackages.rollback(input.appId, input.version);
+          return await nextclawClient.appPackages.startRollback(input.appId, input.version);
         case 'uninstall':
-          return await nextclawClient.appPackages.uninstall(
+          return await nextclawClient.appPackages.startUninstall(
             input.appId,
             input.purgeData ?? false,
           );
@@ -53,6 +107,7 @@ export function useAppPackageMutation() {
         queryClient.invalidateQueries({ queryKey: PANEL_APPS_QUERY_KEY }),
         queryClient.invalidateQueries({ queryKey: SERVICE_APPS_QUERY_KEY }),
         queryClient.invalidateQueries({ queryKey: SERVICE_ACTIONS_QUERY_KEY }),
+        queryClient.invalidateQueries({ queryKey: APP_PACKAGE_OPERATIONS_QUERY_KEY }),
       ]);
     },
   });

package/src/features/apps/index.ts

@@ -1 +1,2 @@
 export { AppsPanel, type AppsPanelTab } from './components/apps-panel';
+export { AppPackageOperationSettlementManager } from './managers/app-package-operation-settlement.manager';

package/src/features/apps/managers/__tests__/app-package-operation-settlement.manager.test.ts

@@ -0,0 +1,81 @@
+import type { AppPackageOperationView } from '@nextclaw/client-sdk';
+import { describe, expect, it, vi } from 'vitest';
+import { AppPackageOperationSettlementManager } from '@/features/apps/managers/app-package-operation-settlement.manager';
+
+const mocks = vi.hoisted(() => ({
+  error: vi.fn(),
+  success: vi.fn(),
+}));
+
+vi.mock('sonner', () => ({ toast: mocks }));
+
+function operation(
+  id: string,
+  overrides: Partial<AppPackageOperationView> = {},
+): AppPackageOperationView {
+  return {
+    id,
+    action: 'update',
+    appId: 'nextclaw.personal-organizer',
+    status: 'succeeded',
+    completedSteps: 5,
+    totalSteps: 5,
+    createdAt: '2026-08-12T00:00:00.000Z',
+    updatedAt: '2026-08-12T00:00:01.000Z',
+    completedAt: '2026-08-12T00:00:01.000Z',
+    result: {
+      appId: 'nextclaw.personal-organizer',
+      activeVersion: '0.1.1',
+      changed: true,
+    },
+    ...overrides,
+  };
+}
+
+describe('AppPackageOperationSettlementManager', () => {
+  it('ignores historical terminal operations and settles each new operation once', async () => {
+    const reloadByDedupeKeys = vi.fn();
+    const refetchPackages = vi.fn(async () => undefined);
+    const refetchPanels = vi.fn(async () => ({
+      data: {
+        entries: [
+          { id: 'todos', packageId: 'nextclaw.personal-organizer' },
+          { id: 'other', packageId: 'nextclaw.other' },
+        ],
+      },
+    }));
+    const manager = new AppPackageOperationSettlementManager({
+      reloadByDedupeKeys,
+    } as never);
+    const historical = operation('historical');
+
+    manager.settle({
+      isLoaded: true,
+      operations: [historical],
+      refetchPackages,
+      refetchPanels,
+    });
+    expect(mocks.success).not.toHaveBeenCalled();
+
+    const completed = operation('completed');
+    manager.settle({
+      isLoaded: true,
+      operations: [completed, historical],
+      refetchPackages,
+      refetchPanels,
+    });
+    manager.settle({
+      isLoaded: true,
+      operations: [completed, historical],
+      refetchPackages,
+      refetchPanels,
+    });
+
+    await vi.waitFor(() => {
+      expect(refetchPackages).toHaveBeenCalledTimes(1);
+      expect(refetchPanels).toHaveBeenCalledTimes(1);
+      expect(reloadByDedupeKeys).toHaveBeenCalledWith(['panel-app:todos']);
+    });
+    expect(mocks.success).toHaveBeenCalledTimes(1);
+  });
+});

package/src/features/apps/managers/app-package-operation-settlement.manager.ts

@@ -0,0 +1,80 @@
+import type { AppPackageOperationView } from '@nextclaw/client-sdk';
+import { toast } from 'sonner';
+import type { DocBrowserManager } from '@/shared/components/doc-browser/managers/doc-browser.manager';
+import { t } from '@/shared/lib/i18n';
+import { isAppPackageOperationActive } from '@/features/apps/hooks/use-app-packages';
+
+type RefetchPanels = () => Promise<{
+  data?: { entries: Array<{ id: string; packageId?: string }> };
+}>;
+
+export class AppPackageOperationSettlementManager {
+  private initialized = false;
+  private readonly knownTerminalOperationIds = new Set<string>();
+
+  constructor(private readonly docBrowserManager: DocBrowserManager) {}
+
+  readonly settle = ({
+    isLoaded,
+    operations,
+    refetchPackages,
+    refetchPanels,
+  }: {
+    isLoaded: boolean;
+    operations: AppPackageOperationView[];
+    refetchPackages: () => Promise<unknown>;
+    refetchPanels: RefetchPanels;
+  }): void => {
+    if (!isLoaded) return;
+    const terminal = operations.filter(
+      (entry) => !isAppPackageOperationActive(entry.status),
+    );
+    if (!this.initialized) {
+      terminal.forEach((entry) => this.knownTerminalOperationIds.add(entry.id));
+      this.initialized = true;
+      return;
+    }
+    terminal.forEach((operation) => {
+      if (this.knownTerminalOperationIds.has(operation.id)) return;
+      this.knownTerminalOperationIds.add(operation.id);
+      this.settleOperation(operation, refetchPackages, refetchPanels);
+    });
+  };
+
+  private readonly settleOperation = (
+    operation: AppPackageOperationView,
+    refetchPackages: () => Promise<unknown>,
+    refetchPanels: RefetchPanels,
+  ): void => {
+    if (operation.status === 'succeeded') {
+      toast.success(operationSuccessLabel(operation));
+      void Promise.all([refetchPackages(), refetchPanels()]).then(([, panelsResult]) => {
+        if (operation.action !== 'rollback' && operation.action !== 'update') return;
+        this.docBrowserManager.reloadByDedupeKeys(
+          panelsResult.data?.entries
+            .filter((entry) => entry.packageId === operation.appId)
+            .map((entry) => `panel-app:${entry.id}`) ?? [],
+        );
+      });
+      return;
+    }
+    if (operation.status === 'failed' || operation.status === 'interrupted') {
+      void refetchPackages();
+      void refetchPanels();
+      toast.error(operation.error ?? t('appPackagesActionFailed'));
+    }
+  };
+}
+
+function operationSuccessLabel(operation: AppPackageOperationView): string {
+  switch (operation.action) {
+    case 'install': return t('appPackagesInstallCompleted');
+    case 'update': return operation.result?.changed === false
+      ? t('appPackagesAlreadyCurrent')
+      : t('appPackagesUpdateCompleted');
+    case 'rollback': return operation.result?.changed === false
+      ? t('appPackagesAlreadyOnVersion')
+      : t('appPackagesRollbackCompleted');
+    case 'uninstall': return t('appPackagesUninstallCompleted');
+  }
+}