Response Contract

VibeFlui feedback works best when handlers and endpoints return a backend-style response object.

Recommended shape

type FluiKitMutationResponse<TData = unknown> = {
  status: boolean | string;
  code?: number | string;
  message?: string;
  data?: TData;
};

FluiKitMutationResponse is exported from @vibeflui/core.

For generated examples and production handlers, prefer returning status, code, and message together because that makes feedback intent and copy explicit. At runtime only status is required by this shape, and VibeFlui can also infer feedback from code-only responses for compatibility.

Success

{
  "status": true,
  "code": 200,
  "message": "User created successfully.",
  "data": {
    "id": "usr_001",
    "name": "Ada Lovelace"
  }
}

status: true always resolves to success feedback.

String statuses such as "success", "succeeded", "ok", and "accepted" also resolve to success.

Warning

{
  "status": false,
  "code": 422,
  "message": "Email is already registered."
}

{
  "status": false,
  "code": 409,
  "message": "The workspace owner cannot be deleted."
}

Use warning feedback for expected business-rule rejections, validation conflicts, workflow locks, or permission-like responses where the request completed but the operation was not accepted.

String statuses "warning" and "rejected" also resolve to warning.

Error

{
  "status": false,
  "code": 500,
  "message": "Unable to delete the user."
}

Use error feedback for server failures, unavailable dependencies, malformed responses, or unexpected runtime errors.

String statuses "failed", "failure", "fail", and "error" also resolve to error.

Nested response support

VibeFlui can resolve feedback from:

• { status, code, message }
• { data: { status, code, message } }
• { response: { data: { status, code, message } } }

This makes it compatible with plain fetch adapters and HTTP-client error objects.

Compatibility fallback

{
  "code": 204,
  "message": "Invitation sent."
}

When status is missing, VibeFlui can infer status from code. Treat this as legacy compatibility, not the recommended response contract.