Ga naar hoofdinhoud

useSetupStatus

Composable that reports an app's first-time-setup status (ADR-042). Backs CnAppRoot's setup phase (gate on required-unmet) and drives CnSetupWizard.

Signature​

import { useSetupStatus } from '@conduction/nextcloud-vue'

const { requiredUnmet, optionalUnmet, completed, loading, refresh } = useSetupStatus(appId, manifest)
ArgumentTypeDescription
appIdstringNextcloud app id (e.g. 'procest').
manifestobjectThe app manifest; reads manifest.setup.steps[].required and .requires.

It fetches GET /apps/{appId}/api/setup/status → { version, completed, steps: { <id>: { done, detail } } }, caches the result per appId for the page lifetime, and cross-references the manifest's required flags. On error it falls back to "nothing done" so a failed lookup never crashes the shell.

One error is treated as an answer rather than a failure. A 401/403 means the caller may not read setup state — setup endpoints are admin-only — so completed reports true and the wizard stays out of the way. Without that, every non-admin user of an app with a setup block met a wizard they had no permission to complete instead of the app itself. Any other error (network, 500) stays unknown and still falls back to "nothing done", so an admin can always reach the wizard.

A step that declares requires: [appId, ...] is not applicable while any of those apps is not installed and enabled. CnSetupWizard skips such a step, so it is neither done nor unmet here: it never appears in requiredUnmet or optionalUnmet, and it is listed in notApplicable instead. The app check is the wizard's own: the dependency_statuses initial state first, then useAppStatus.

Return value​

KeyTypeDescription
stepsComputedRef<object[]>The manifest steps merged with their server done/detail, plus applicable and missingApps (the absent app ids from requires).
statusRef<object>The raw server status payload.
requiredUnmetComputedRef<object[]>Required steps that are not yet done — non-empty ⇒ gate the app.
optionalUnmetComputedRef<object[]>Optional steps not yet done — auto-open the wizard once (dismissible).
optionalUnmetReportedComputedRef<object[]>The optional unmet steps the server reported as not done.
notApplicableComputedRef<object[]>Steps the wizard skips because an app in their requires is absent.
completedComputedRef<boolean>Server completion flag, never true while a required step is unmet — but always true when forbidden.
enabledbooleanWhether the manifest declares an active setup block.
loadingRef<boolean>true while the status fetch is in flight.
errorRef<Error|null>The last fetch error, if any.
forbiddenRef<boolean>true when the server answered 401/403 — the caller is not an admin, so setup is not their concern.
refresh() => Promise<void>Re-fetch the status (call after a step completes).

Notes​

  • Mirrors useAppStatus: one shared fetch + reactive state per appId.
  • Gating uses requiredUnmet; the optional auto-open uses optionalUnmet + completed.