/**
 * URL construction helpers for dashboard and API URLs.
 *
 * These functions ensure consistent URL construction across the codebase
 * and derive the API URL from the dashboard URL to avoid duplicate env vars.
 */
import { type SurfaceId } from '@riverbankcms/surfaces';
/**
 * Get the public, user-facing dashboard origin from environment.
 *
 * This is intentionally separate from `CMS_API_URL`: that variable is a
 * server-only API origin and may point at an internal Docker/private-network
 * host that should never appear in emails, redirects, or browser links.
 *
 * @returns Dashboard base URL (e.g., 'http://localhost:4000')
 * @throws Error if neither NEXT_PUBLIC_DASHBOARD_URL nor NEXT_PUBLIC_CMS_API_URL is configured
 */
export declare function getDashboardBaseUrl(): string;
/**
 * Get the CMS API URL by appending /api to the dashboard URL
 * @returns API base URL (e.g., 'http://localhost:4000/api' or '/api' in browser)
 * @throws Error if neither NEXT_PUBLIC_DASHBOARD_URL nor NEXT_PUBLIC_CMS_API_URL is configured (server-side only)
 */
export declare function getCmsApiUrl(): string;
/**
 * Get a full dashboard URL for a path within the authenticated dashboard surface (`/dashboard/*`).
 *
 * Uses the public dashboard origin from `getDashboardBaseUrl()`, then appends `/dashboard`.
 * `CMS_API_URL` is intentionally ignored here because it may be an internal
 * server-to-server API origin.
 *
 * Prefer the `getAbsoluteDashboardUrl` name at call sites where both relative dashboard paths
 * and absolute dashboard URLs are in play, to avoid confusing it with the client-side helper in
 * `apps/dashboard/src/utils/routes/getDashboardUrl.ts`.
 *
 * Pass `options.surfaceId` to target a specific surface — the host is rewritten to that
 * surface's root host at the matching tier (local-dev vs production). Required for any link
 * that may be opened by a user whose site lives on a non-`core` surface (macadamia), since
 * the configured `NEXT_PUBLIC_DASHBOARD_URL` is typically the `core` origin.
 *
 * If `surfaceId` is provided but the configured dashboard origin doesn't resolve to a known
 * surface (i.e. misconfigured env), the helper silently falls back to the base URL so the
 * caller (typically an email send) still produces a usable link. Pass `onSurfaceFallback` to
 * observe this condition — it fires with the supplied surface id and the unresolved base URL
 * so the caller (which knows its own context, e.g. siteId) can emit a warning.
 *
 * @example
 * ```ts
 * getAbsoluteDashboardUrl() // -> 'http://localhost:4000/dashboard'
 * getAbsoluteDashboardUrl('sites/site-123/content/event/entry-456') // -> 'http://localhost:4000/dashboard/sites/site-123/content/event/entry-456'
 * getAbsoluteDashboardUrl('sites/site-123/forms/contact/submissions', { surfaceId: 'macadamia' })
 * //   prod: 'https://macadamia.studio/dashboard/sites/site-123/forms/contact/submissions'
 * //   dev:  'http://macadamia.localhost:4000/dashboard/sites/site-123/forms/contact/submissions'
 * ```
 */
export type GetAbsoluteDashboardUrlOptions = Readonly<{
    surfaceId?: SurfaceId;
    /**
     * Called when `surfaceId` was supplied but the configured dashboard origin
     * doesn't resolve to a known surface (so the resulting URL uses the
     * unrewritten base instead of the requested surface's host).
     */
    onSurfaceFallback?: (info: Readonly<{
        surfaceId: SurfaceId;
        dashboardOrigin: string;
    }>) => void;
}>;
export declare function getAbsoluteDashboardUrl(path?: string, options?: GetAbsoluteDashboardUrlOptions): string;
/**
 * @deprecated Prefer `getAbsoluteDashboardUrl()` at new call sites so its semantics are explicit.
 */
export declare const getDashboardUrl: typeof getAbsoluteDashboardUrl;
/**
 * Legacy: Get API URL, supporting old NEXT_PUBLIC_CMS_API_URL env var
 * @deprecated Use getCmsApiUrl() instead - this function is maintained for backwards compatibility
 */
export declare function resolveApiBaseUrl(): string;
