# URL API reference

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

- Package: `@db3.ai/app/url`
- Canonical page: [https://db3.ai/docs/url-api](https://db3.ai/docs/url-api)
- Markdown: [https://db3.ai/docs/url-api.md](https://db3.ai/docs/url-api.md)
- Framework source of truth: `packages/app/src/url/README.md`

<a id="start"></a>

## 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](https://db3.ai/docs/url.md)

<a id="generator"></a>

## Canonical URL generator

### Canonical URL generator

```typescript
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;
}
```

<a id="options"></a>

## Configuration

### Configuration

```typescript
/**
 * 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;
}
```

## Related documentation
- [Application URLs](https://db3.ai/docs/url.md): Give email, workers and HTTP routes one trusted application address. A URL resolver is not a redirect policy.

## Guidance for AI tools
Use the documented public import `@db3.ai/app/url` and its exported types. Prefer the source-backed examples and behavioural outcomes above over invented APIs or source-relative internal imports.