URL API reference

Current emitted signatures and options for @db3.ai/app/url.

On this page

Imports and examples

Import supported APIs from @db3.ai/app/url. These signatures come from the staged package used by consumers. Relative filenames in declarations describe type dependencies; they are not extra supported deep imports.

Use the guide for setup, executable examples, failure handling and ownership. A signature is not proof that every deployment or provider has been exercised.

Guide, examples and testing

Canonical URL generator

import type * as url from './contracts/index.js';
/**
 * Canonical application URL generator.
 *
 * The generator is intentionally independent of a concrete server adapter and
 * the current request. API, queue, scheduler, console, and future SSR runtimes
 * can therefore share one trusted application origin. Request-specific SSR
 * state belongs to the request context and must not replace this canonical URL.
 *
 * @example
 * const callback = app().url.to('/api/integrations/provider/callback');
 */
export declare class UrlGenerator {
    /** Normalized browser-facing application URL without a trailing slash. */
    readonly baseUrl: string;
    /**
     * Creates the canonical application URL generator.
     *
     * @param options - Public deployment URL or local browser port configuration.
     */
    constructor(options?: url.UrlGeneratorOptions);
    /**
     * Builds an absolute application URL from a path or relative reference.
     *
     * @param path - Application path or relative URL to resolve.
     * @returns Absolute browser-facing application URL.
     *
     * @example
     * app().url.to('/auth/reset-password');
     */
    to(path: string): string;
}

Configuration

/**
 * Canonical application URL configuration.
 *
 * The explicit public URL is authoritative in deployed environments. A local
 * port can provide a browser-facing development origin without duplicating a
 * complete application URL alongside the frontend server configuration.
 */
export interface UrlGeneratorOptions {
    /** Public application base URL, such as `https://example.com`. */
    baseUrl?: string;
    /** Browser-facing localhost port used when no public base URL is configured. */
    localPort?: number;
}