API surface

Cloud separates APIs by runtime. Use the entry point for the code you are writing.

Supported means application code may depend on the documented use. It does not make every symbol in a mixed barrel an application API. Platform-owned is for Cloud itself. Advanced paths are public exports, but application code should use them only when a feature guide gives the exact import.

Application entry points

Use the barrels above by default. Use a subpath when the specialized-entry table below links its feature guide.

Define the application

Import defineApp() from the package root:

import { defineApp } from "@k2b/cloud";

The returned application's ssr renders pages and exposes ssr.access for browser-route rejections and ssr.error(c, status, options?) for terminal HTML errors. See SSR pages and routing.

The root also exports the types bound to an application declaration. This includes typed settings and notification definitions. Registry, heartbeat, and runtime-composition exports from the same barrel are platform-owned.

See Define an application.

Handle server requests

Import request APIs from @k2b/cloud/server:

import {
  type AppContext,
  auth,
  middleware,
  respond,
  v,
} from "@k2b/cloud/server";

This entry point contains Hono context types, middleware, actor helpers, validation, resource access, and response helpers.

See Server APIs for the request path.

Use platform services

Code outside an HTTP request uses asynchronous feature services:

import { logger } from "@k2b/cloud/services";

const log = logger("inventory");
log.info("Import completed", { itemCount: 42 });

Use the capability guide to choose the narrow API:

• Settings
• Notifications
• Logging
• App capabilities
• Universal search
• Document extraction

Raw stores, runtime starters, gateway telemetry, migrations, and platform composition helpers from the same barrel are maintainer APIs unless a guide names them.

linuxIdentities is a platform-owned administration service from this barrel. It checks administrator access on reads and writes. See Linux identities for configuration, explicit provisioning, and the compatible FreeIPA mirror.

Share types with the browser

Export the Hono router type from the server. Use it with the browser client.

import { api } from "@k2b/cloud/browser";
import type { InventoryApi } from "../server";

export const inventoryApi = api.create<InventoryApi>({
  baseUrl: "/api/inventory",
});

See Browser clients and mutations.

Use query and mutation from @k2b/stdlib/solid for owner-local reads and user-initiated writes. See Server-backed state.

The clipboard, copyToClipboard, url, and isImageUrl exports are utility helpers outside the documented typed-client contract. Do not choose them as application APIs unless a guide names them.

Mixed barrels

Some barrels serve more than one audience. Use this boundary instead of inferring support from autocomplete.

@k2b/cloud/config exports env.APP_SECRET, env.PORT, env.IS_DEVELOPMENT, and env.ADMIN_LOGIN_TOKEN. The runtime configuration guide documents all process variables; that larger list is not the shape of env.

Specialized entry points

Every app-facing specialized row has a guide. Platform-owned and Advanced rows are exported for Cloud itself or for a narrowly documented integration; their presence is not an application support promise.

Platform-owned and limited surfaces

“Limited” means the path is exported but not part of the documented web application contract. It is not a promise of instability.

Compatibility-only surfaces

See Deprecations for migration steps.

Avoid internal imports

Do not import from package source paths such as:

import { something } from "@k2b/cloud/src/...";

Those paths are implementation details.

requiresAuth and the other requires* values describe OpenAPI security. They do not protect a route. Use auth middleware.