@gigadrive/sdk 0.1.1 → 0.2.0

package/dist/index.d.mts

@@ -1,2 +1,2524 @@
+/** The result of a credential provider's token fetch. */
+interface TokenResult {
+    /** The access token to use in API requests. */
+    accessToken: string;
+    /** Epoch milliseconds when the token expires, or `null` for tokens that never expire (e.g. static bearer tokens). */
+    expiresAt: number | null;
+    /** A refresh token for obtaining new access tokens, if the provider supports token rotation. */
+    refreshToken?: string;
+}
+/**
+ * A strategy for obtaining access tokens. The SDK ships with four built-in
+ * providers (see {@link resolveCredentialProvider} for automatic selection),
+ * but you can implement this interface for custom auth flows.
+ */
+interface CredentialProvider {
+    /** A string identifying the provider type (e.g. `"oauth2-client-credentials"`, `"bearer"`). */
+    readonly type: string;
+    /** Fetch a new access token. May perform network requests (e.g. OAuth2 token exchange). */
+    getToken(): Promise<TokenResult>;
+}
 
-export {  }
+/**
+ * Manages the access-token lifecycle: caching, automatic expiry detection,
+ * proactive refresh, and concurrent-call deduplication.
+ *
+ * When multiple API requests fire simultaneously with an expired token, only
+ * a single refresh call is made — all concurrent callers await the same
+ * pending Promise. This prevents a "thundering herd" of token requests.
+ *
+ * @internal Used internally by {@link HttpClient}. Not part of the public API.
+ */
+declare class TokenManager {
+    private readonly provider;
+    private cachedToken;
+    private expiresAt;
+    private pendingRefresh;
+    constructor(provider: CredentialProvider);
+    /**
+     * Returns a valid access token. Uses the cached token if still valid,
+     * otherwise fetches a new one from the credential provider.
+     *
+     * Concurrent calls are deduplicated — only one refresh runs at a time.
+     */
+    getToken(): Promise<string>;
+    /**
+     * Invalidates the cached token. The next `getToken()` call will trigger a refresh.
+     */
+    invalidate(): void;
+    private refresh;
+}
+
+/**
+ * A paginated API response. List endpoints return this shape.
+ *
+ * @typeParam T - The type of each item in the list.
+ */
+interface Paginated<T> {
+    /** The items on the current page. */
+    items: T[];
+    /** The total number of items across all pages. */
+    total: number;
+    /** An opaque cursor for the next page, present on cursor-paginated endpoints when more items remain. */
+    nextCursor?: string;
+}
+/** A value that can be serialized into a query-string parameter. `undefined` values are omitted. */
+type QueryValue = string | number | boolean | undefined;
+/** Common pagination query parameters accepted by list endpoints. */
+interface ListQuery {
+    /** 1-indexed page number (for page/`perPage`-style pagination). */
+    page?: number;
+    /** Maximum number of items per page. */
+    perPage?: number;
+    /** Opaque cursor for cursor-based pagination (from a previous response's `nextCursor`). */
+    cursor?: string;
+}
+/** @internal */
+interface RequestOptions {
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Abort signal to cancel the request (and any 401-refresh retry). */
+    signal?: AbortSignal;
+}
+/**
+ * Low-level HTTP client used internally by all resource classes. Handles
+ * authentication header injection, JSON serialization, error mapping, and
+ * automatic retry on 401 responses.
+ *
+ * You do not need to use this class directly — interact with the API through
+ * the resource properties on {@link GigadriveClient} instead.
+ *
+ * @internal
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly tokenManager;
+    private readonly fetchFn;
+    constructor(baseUrl: string, tokenManager: TokenManager, fetchFn: typeof globalThis.fetch);
+    /** @internal */
+    get<T>(path: string, options?: Pick<RequestOptions, 'query' | 'signal'>): Promise<T>;
+    /** @internal */
+    post<T>(path: string, body?: unknown, options?: Pick<RequestOptions, 'headers' | 'query' | 'signal'>): Promise<T>;
+    /** @internal */
+    put<T>(path: string, body?: unknown, options?: Pick<RequestOptions, 'headers' | 'query' | 'signal'>): Promise<T>;
+    /** @internal */
+    patch<T>(path: string, body?: unknown, options?: Pick<RequestOptions, 'headers' | 'query' | 'signal'>): Promise<T>;
+    /** @internal */
+    delete<T>(path: string, options?: Pick<RequestOptions, 'query' | 'signal'>): Promise<T>;
+    /** @internal */
+    postRaw<T>(path: string, body: string | ArrayBuffer | Uint8Array | ReadableStream | Blob | FormData, headers?: Record<string, string>): Promise<T>;
+    /**
+     * Make an authenticated request and return the raw `Response` without parsing
+     * the body. Used for streamed (SSE) and binary responses.
+     *
+     * @throws {@link ApiError} if the response status is not OK.
+     * @internal
+     */
+    requestStream(method: string, path: string, options?: RequestOptions): Promise<Response>;
+    /**
+     * Make a raw fetch request to an arbitrary URL (e.g. presigned upload URLs
+     * or resumable upload endpoints). No auth header is injected and the base URL
+     * is not prepended.
+     *
+     * @param url - The full URL to fetch.
+     * @param init - Standard `RequestInit` options.
+     * @returns The raw `Response` object.
+     * @throws {@link ApiError} if the response status is not OK.
+     *
+     * @internal
+     */
+    fetchRaw(url: string, init: RequestInit): Promise<Response>;
+    private request;
+    /** Perform the request with auth injection and a single 401 refresh-retry. */
+    private fetchWithAuth;
+    private handleResponse;
+    private toApiError;
+    private buildUrl;
+}
+
+/**
+ * Base class for all API resource classes. Provides access to the shared
+ * HTTP client for making authenticated API requests.
+ *
+ * @internal
+ */
+declare class BaseResource {
+    protected readonly httpClient: HttpClient;
+    constructor(httpClient: HttpClient);
+}
+
+/**
+ * Types for the AI Gateway runtime endpoints (`/ai/v1`). The chat/responses
+ * shapes are OpenAI-compatible; additional fields are passed through, so request
+ * types include an index signature and responses surface the common fields.
+ */
+/** Provider routing preferences accepted by inference endpoints. */
+interface ProviderRouting {
+    /** Preferred provider order (e.g. `["openai", "anthropic"]`). */
+    order?: string[];
+    /** Whether the gateway may fall back to other providers. */
+    allow_fallbacks?: boolean;
+    /** Require zero-data-retention capable routing. */
+    require_zdr?: boolean;
+    /** Restrict routing to exactly the providers in `order`. */
+    restrict_to_order?: boolean;
+}
+/** A text or multi-part content part in a chat message. */
+type ChatCompletionContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+} | {
+    type: 'file';
+    file: {
+        filename?: string;
+        file_data?: string;
+        file_id?: string;
+    };
+};
+/** A message in a chat completion request or response. */
+interface ChatCompletionMessage {
+    /** The role of the message author (e.g. `"system"`, `"user"`, `"assistant"`). */
+    role: string;
+    /** The message content — plain text or an array of content parts. */
+    content: string | ChatCompletionContentPart[] | null;
+    /** Additional OpenAI-compatible fields (e.g. `tool_calls`) are passed through. */
+    [key: string]: unknown;
+}
+/** Request for an OpenAI-compatible chat completion. */
+interface ChatCompletionRequest {
+    /** The model ID (e.g. `"openai/gpt-4o"`). */
+    model: string;
+    /** The conversation messages. */
+    messages: ChatCompletionMessage[];
+    /** Sampling temperature (0–2). */
+    temperature?: number;
+    /** Nucleus sampling parameter (0–1). */
+    top_p?: number;
+    /** Maximum number of tokens to generate. */
+    max_tokens?: number;
+    /** Whether to stream the response. Prefer {@link AiGatewayResource.chatCompletionsStream}. */
+    stream?: boolean;
+    /** Tool/function definitions. */
+    tools?: unknown[];
+    /** Tool choice strategy. */
+    tool_choice?: unknown;
+    /** Provider routing preferences. */
+    provider?: ProviderRouting;
+    /** Additional OpenAI-compatible parameters are passed through. */
+    [key: string]: unknown;
+}
+/** Token usage statistics. */
+interface ChatCompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+/** A single completion choice. */
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatCompletionMessage;
+    finish_reason: string | null;
+}
+/** Response from an OpenAI-compatible chat completion. */
+interface ChatCompletionResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: ChatCompletionUsage;
+    system_fingerprint?: string;
+    /** Estimated cost of the request in micros of USD, when available. */
+    cost_micros?: number;
+    [key: string]: unknown;
+}
+/** A streamed chat completion chunk (`stream: true`). */
+interface ChatCompletionChunk {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: Array<{
+        index: number;
+        delta: {
+            role?: string;
+            content?: string | null;
+            [key: string]: unknown;
+        };
+        finish_reason: string | null;
+    }>;
+    [key: string]: unknown;
+}
+/** Request for the Open Responses-compatible endpoint. */
+interface ResponsesRequest {
+    model: string;
+    /** Provider routing preferences. */
+    provider?: ProviderRouting;
+    /** Whether to stream the response. */
+    stream?: boolean;
+    /** Additional Responses-compatible parameters are passed through. */
+    [key: string]: unknown;
+}
+/** Response from the Open Responses-compatible endpoint. */
+interface ResponsesResponse {
+    id: string;
+    object: string;
+    status: string;
+    [key: string]: unknown;
+}
+/** Capability flags for an AI model. */
+interface AiModelCapabilities {
+    chat: boolean;
+    streaming: boolean;
+    tools: boolean;
+    vision: boolean;
+    json_mode: boolean;
+}
+/** Display metadata for a routing provider that can serve a model. */
+interface AiModelRoutingProvider {
+    id: string;
+    name: string;
+    logoUrl?: string;
+    supportsZdr: boolean;
+}
+/** An AI model available through the gateway. */
+interface AiModel {
+    /** Model identifier to pass to inference endpoints (e.g. `"openai/gpt-4o"`). */
+    id: string;
+    /** Human-readable model name. */
+    name: string;
+    /** Primary provider family/owner. */
+    provider: string;
+    /** Logo URL for the primary provider, if available. */
+    providerLogoUrl?: string;
+    /** Capability flags. */
+    capabilities: AiModelCapabilities;
+    /** Supported input/output modalities, if declared. */
+    modalities?: {
+        input: string[];
+        output: string[];
+    };
+    /** Maximum combined input+output context window in tokens. */
+    contextWindow: number;
+    /** Maximum output tokens the gateway will request. */
+    maxOutputTokens: number;
+    /** Product-facing model summary, if configured. */
+    description?: string;
+    /** Provider route IDs that can serve this model. */
+    routingProviders: string[];
+    /** Display metadata for each routing provider. */
+    routingProviderDetails: AiModelRoutingProvider[];
+    /** Provider route IDs that support zero-data-retention. */
+    zdrProviders: string[];
+}
+/** Request for text-to-speech synthesis. */
+interface SpeechRequest {
+    model: string;
+    /** The text to synthesize. */
+    input: string;
+    /** The voice to use. */
+    voice: string;
+    /** Output audio format. */
+    response_format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm';
+    /** Playback speed (0.25–4.0). */
+    speed?: number;
+    /** Provider routing preferences. */
+    provider?: ProviderRouting;
+    [key: string]: unknown;
+}
+/** Request for speech-to-text transcription. */
+interface TranscriptionRequest {
+    model: string;
+    /** The audio file to transcribe. */
+    file: Blob | Uint8Array | ArrayBuffer;
+    /** Filename to send with the file part. */
+    filename?: string;
+    /** Spoken language hint (ISO-639-1). */
+    language?: string;
+    /** Optional prompt to guide transcription. */
+    prompt?: string;
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Response format. */
+    response_format?: string;
+    /** Additional fields are appended to the multipart form. */
+    [key: string]: unknown;
+}
+/** Response from a transcription request. */
+interface TranscriptionResponse {
+    text: string;
+    language?: string;
+    duration?: number;
+    segments?: unknown[];
+    [key: string]: unknown;
+}
+/** Request for video generation. */
+interface VideoGenerationRequest {
+    model: string;
+    prompt: string;
+    duration?: number;
+    resolution?: string;
+    fps?: number;
+    provider?: ProviderRouting;
+    [key: string]: unknown;
+}
+/** Response from a video generation request. */
+interface VideoGenerationResponse {
+    id: string;
+    status: string;
+    video?: {
+        url: string;
+        duration?: number;
+    };
+    created_at?: number;
+    expires_at?: number;
+    [key: string]: unknown;
+}
+/** Response from listing video models. */
+interface VideoModelList {
+    object: string;
+    data: Array<Record<string, unknown>>;
+}
+/** Per-request options for gateway calls (custom headers such as `X-Gigadrive-*`). */
+interface GatewayRequestOptions {
+    /** Additional request headers (e.g. `X-Gigadrive-Application-Id`, `X-Gigadrive-End-User-Id`). */
+    headers?: Record<string, string>;
+}
+/** A gateway result paired with its raw response and surfaced metadata headers. */
+interface GatewayResult<T> {
+    /** The parsed response body. */
+    data: T;
+    /** The raw `Response`, for reading additional headers. */
+    response: Response;
+    /** The `X-Gigadrive-Request-Id` header, if present. */
+    requestId?: string;
+    /** The `X-Gigadrive-Cost-Micros` header parsed as a number, if present. */
+    costMicros?: number;
+}
+
+/** Text-to-speech and speech-to-text endpoints. */
+declare class AiGatewayAudioResource extends BaseResource {
+    /**
+     * Synthesize speech from text. Returns the raw audio bytes.
+     *
+     * @returns The audio content as an `ArrayBuffer` (format per `response_format`).
+     */
+    speech(data: SpeechRequest, options?: GatewayRequestOptions): Promise<ArrayBuffer>;
+    /**
+     * Transcribe an audio file to text. The file is sent as multipart form data.
+     */
+    transcriptions(data: TranscriptionRequest, options?: GatewayRequestOptions): Promise<TranscriptionResponse>;
+}
+/** Video generation endpoints. */
+declare class AiGatewayVideosResource extends BaseResource {
+    /** Generate a video from a prompt. */
+    generations(data: VideoGenerationRequest, options?: GatewayRequestOptions): Promise<VideoGenerationResponse>;
+    /** List the video models available through the gateway. */
+    listModels(): Promise<VideoModelList>;
+}
+/**
+ * Interact with the Gigadrive AI Gateway — an OpenAI-compatible API that routes
+ * requests to multiple AI providers. Accessed via {@link GigadriveClient.aiGateway}.
+ *
+ * @example
+ * ```ts
+ * // Chat completion
+ * const res = await client.aiGateway.chatCompletions({
+ *   model: 'openai/gpt-4o',
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ * });
+ * console.log(res.choices[0].message.content);
+ *
+ * // Streamed chat completion
+ * for await (const chunk of client.aiGateway.chatCompletionsStream({
+ *   model: 'openai/gpt-4o',
+ *   messages: [{ role: 'user', content: 'Write a haiku.' }],
+ * })) {
+ *   process.stdout.write(chunk.choices[0]?.delta.content ?? '');
+ * }
+ * ```
+ */
+declare class AiGatewayResource extends BaseResource {
+    /** Text-to-speech and speech-to-text. */
+    readonly audio: AiGatewayAudioResource;
+    /** Video generation. */
+    readonly videos: AiGatewayVideosResource;
+    constructor(httpClient: HttpClient);
+    /**
+     * Create a chat completion using the OpenAI-compatible endpoint.
+     *
+     * @param data - The chat completion request (model, messages, options, provider routing).
+     * @param options - Custom headers (e.g. `X-Gigadrive-Application-Id`).
+     */
+    chatCompletions(data: ChatCompletionRequest, options?: GatewayRequestOptions): Promise<ChatCompletionResponse>;
+    /**
+     * Like {@link chatCompletions}, but also returns the raw response and the
+     * gateway request-id / cost headers.
+     */
+    chatCompletionsWithResponse(data: ChatCompletionRequest, options?: GatewayRequestOptions): Promise<GatewayResult<ChatCompletionResponse>>;
+    /**
+     * Stream a chat completion as Server-Sent Events. Yields each chunk as it
+     * arrives and ends when the gateway closes the stream.
+     */
+    chatCompletionsStream(data: ChatCompletionRequest, options?: GatewayRequestOptions): AsyncGenerator<ChatCompletionChunk>;
+    /**
+     * Create a response using the Open Responses-compatible endpoint.
+     */
+    responses(data: ResponsesRequest, options?: GatewayRequestOptions): Promise<ResponsesResponse>;
+    /**
+     * Stream a response using the Open Responses-compatible endpoint.
+     */
+    responsesStream(data: ResponsesRequest, options?: GatewayRequestOptions): AsyncGenerator<unknown>;
+    /**
+     * List all AI models available through the gateway.
+     */
+    listModels(): Promise<Paginated<AiModel>>;
+    /**
+     * Get details for a specific AI model by its ID.
+     *
+     * @param modelId - The model identifier (e.g. `"openai/gpt-4o"`).
+     */
+    getModel(modelId: string): Promise<AiModel>;
+}
+
+/** An environment variable attached to an organization, application, or environment. */
+interface EnvVar {
+    /** Unique identifier. */
+    id: string;
+    /** The variable name (e.g. `DATABASE_URL`). */
+    key: string;
+    /** The variable value. `null` when {@link sensitive} is `true` and the value is hidden from API responses. */
+    value: string | null;
+    /** When `true`, the value is redacted in API responses to protect secrets. */
+    sensitive: boolean;
+    /** The scope level at which this variable is defined. */
+    scope: 'organization' | 'application' | 'environment';
+    /** The environment ID, if this variable is scoped to a specific environment. */
+    environmentId: string | null;
+    /** The human-readable environment name, if scoped to a specific environment. */
+    environmentName: string | null;
+    /** ISO 8601 timestamp of when the variable was created. */
+    createdAt: string;
+    /** ISO 8601 timestamp of when the variable was last updated. */
+    updatedAt: string;
+}
+/** Input for creating a new environment variable. */
+interface CreateEnvVarInput {
+    /** The variable name (e.g. `DATABASE_URL`). Must be unique within its scope. */
+    key: string;
+    /** The variable value. */
+    value: string;
+    /** Mark the variable as sensitive to hide its value in API responses. */
+    sensitive?: boolean;
+    /** The scope level. Defaults to the parent resource's scope. */
+    scope?: 'organization' | 'application' | 'environment';
+    /** The environment ID, when creating an environment-scoped variable. */
+    environmentId?: string;
+}
+/** Input for updating an existing environment variable. All fields are optional — only provided fields are changed. */
+interface UpdateEnvVarInput {
+    /** New variable name. */
+    key?: string;
+    /** New variable value. */
+    value?: string;
+    /** Change the sensitive flag. */
+    sensitive?: boolean;
+}
+
+/**
+ * Manage environment variables scoped to an application.
+ * Accessed via `client.applications.envVars`.
+ */
+declare class ApplicationEnvVarsResource extends BaseResource {
+    /**
+     * List all environment variables for an application.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @returns A paginated list of environment variables.
+     *
+     * @example
+     * ```ts
+     * const { items } = await client.applications.envVars.list('app-id');
+     * for (const v of items) {
+     *   console.log(`${v.key}=${v.sensitive ? '***' : v.value}`);
+     * }
+     * ```
+     */
+    list(applicationId: string, query?: ListQuery): Promise<Paginated<EnvVar>>;
+    /**
+     * Create a new environment variable for an application.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param data - The variable key, value, and optional settings.
+     * @returns The newly created environment variable.
+     *
+     * @example
+     * ```ts
+     * const envVar = await client.applications.envVars.create('app-id', {
+     *   key: 'DATABASE_URL',
+     *   value: 'postgres://...',
+     *   sensitive: true,
+     * });
+     * ```
+     */
+    create(applicationId: string, data: CreateEnvVarInput): Promise<EnvVar>;
+    /**
+     * Update an existing environment variable. Only the fields you provide
+     * will be changed; omitted fields are left unchanged.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param envVarId - The environment variable ID (UUID).
+     * @param data - The fields to update.
+     * @returns The updated environment variable.
+     *
+     * @example
+     * ```ts
+     * await client.applications.envVars.update('app-id', 'var-id', {
+     *   value: 'postgres://new-host/db',
+     * });
+     * ```
+     */
+    update(applicationId: string, envVarId: string, data: UpdateEnvVarInput): Promise<EnvVar>;
+    /**
+     * Permanently delete an environment variable.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param envVarId - The environment variable ID (UUID).
+     *
+     * @example
+     * ```ts
+     * await client.applications.envVars.delete('app-id', 'var-id');
+     * ```
+     */
+    delete(applicationId: string, envVarId: string): Promise<void>;
+}
+
+/** A nested reference to the application that served a request. */
+interface NetworkRequestApplicationRef {
+    id: string;
+    name: string;
+}
+/** A nested reference to the deployment that served a request. */
+interface NetworkRequestDeploymentRef {
+    id: string;
+    status: string;
+}
+/** A nested reference to the function route that handled a request. */
+interface NetworkRequestFunctionRef {
+    id: string;
+    name: string | null;
+    path: string;
+    region: string | null;
+}
+/** A nested reference to the static asset that served a request. */
+interface NetworkRequestAssetRef {
+    id: string;
+    path: string;
+    objectKey: string;
+}
+/** A nested reference to the storage bucket involved in a request. */
+interface NetworkRequestBucketRef {
+    id: string;
+    name: string;
+    slug: string;
+}
+/** A nested reference to the storage object involved in a request. */
+interface NetworkRequestObjectRef {
+    id: string;
+    key: string;
+    contentType: string | null;
+}
+/** The HTTP request details captured for a network request. */
+interface NetworkRequestDetails {
+    method: string;
+    hostname: string;
+    path: string;
+    query: string | null;
+    protocol: string | null;
+    country: string | null;
+    userAgent: string | null;
+    referer: string | null;
+}
+/** The HTTP response details captured for a network request. */
+interface NetworkResponseDetails {
+    status: number | null;
+    cacheStatus: 'hit' | 'miss' | 'bypass' | 'revalidated' | 'stale' | 'updating' | null;
+    cacheHit: boolean | null;
+    region: string | null;
+    edgeLocation: string | null;
+}
+/** Byte and timing metrics for a network request. */
+interface NetworkRequestMetrics {
+    requestBodyBytes: number | null;
+    responseBodyBytes: number | null;
+    bytesSent: number | null;
+    durationMs: number | null;
+}
+/** A single observed request served through the Gigadrive Network edge (summary form). */
+interface NetworkRequestSummary {
+    id: string;
+    application: NetworkRequestApplicationRef;
+    deployment: NetworkRequestDeploymentRef | null;
+    deploymentFunction: NetworkRequestFunctionRef | null;
+    deploymentAsset: NetworkRequestAssetRef | null;
+    storageBucket: NetworkRequestBucketRef | null;
+    storageObject: NetworkRequestObjectRef | null;
+    request: NetworkRequestDetails;
+    response: NetworkResponseDetails;
+    metrics: NetworkRequestMetrics;
+    startedAt: string;
+    completedAt: string | null;
+}
+/** A full network request record, including sanitized request/response headers. */
+interface NetworkRequest extends NetworkRequestSummary {
+    /** Sanitized request headers captured for debugging. */
+    requestHeaders: Record<string, string>;
+    /** Sanitized response headers captured for debugging. */
+    responseHeaders: Record<string, string>;
+}
+/** Query filters for listing application requests. All fields are optional. */
+interface ListRequestsQuery {
+    /** Filter to requests served by one deployment. */
+    deploymentId?: string;
+    /** Filter to requests served by one function route. */
+    deploymentFunctionId?: string;
+    /** Filter to requests served by one static asset route. */
+    deploymentAssetId?: string;
+    /** Filter to storage delivery requests for one bucket. */
+    storageBucketId?: string;
+    /** Filter to storage delivery requests for one object. */
+    storageObjectId?: string;
+    /** Only include requests that started at or after this ISO 8601 timestamp. */
+    from?: string;
+    /** Only include requests that started before or at this ISO 8601 timestamp. */
+    to?: string;
+    /** Maximum number of records to return. */
+    limit?: number;
+    /** Opaque cursor from a previous response's `nextCursor`. */
+    cursor?: string;
+    /** Filter by HTTP method (e.g. `"GET"`). */
+    method?: string;
+    /** Filter by exact HTTP status code. */
+    status?: number;
+    /** Filter by status family (`2`, `3`, `4`, or `5`). */
+    statusFamily?: number;
+    /** Filter by request hostname. */
+    hostname?: string;
+    /** Filter to requests whose path starts with this prefix. */
+    pathPrefix?: string;
+    /** Filter by ISO 3166-1 alpha-2 country code. */
+    country?: string;
+    /** Filter by origin region. */
+    region?: string;
+    /** Filter by edge location. */
+    edgeLocation?: string;
+    /** Filter by CDN cache state. */
+    cacheStatus?: string;
+    /** Filter by whether the response was served from cache. */
+    cacheHit?: boolean;
+}
+/**
+ * Read observed traffic (request logs) for an application. Accessed via
+ * `client.applications.requests`.
+ *
+ * @example
+ * ```ts
+ * // Recent 5xx responses for a deployment
+ * const { items } = await client.applications.requests.list('app-id', {
+ *   deploymentId: 'dep-id',
+ *   statusFamily: 5,
+ *   limit: 100,
+ * });
+ * ```
+ */
+declare class ApplicationRequestsResource extends BaseResource {
+    /**
+     * List requests for an application, with rich filtering and cursor pagination.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param query - Optional filters and pagination.
+     * @returns A page of request summaries.
+     */
+    list(applicationId: string, query?: ListRequestsQuery): Promise<Paginated<NetworkRequestSummary>>;
+    /**
+     * Get a single request by ID, including sanitized request/response headers.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param requestId - The request record ID (UUID).
+     * @returns The full request record.
+     */
+    get(applicationId: string, requestId: string): Promise<NetworkRequest>;
+}
+
+/**
+ * Resolves the various accepted upload inputs (in-memory bytes, a Node.js file
+ * path, or a Node.js readable stream) into the concrete values the upload flow
+ * needs: the object tus-js-client consumes, the byte size, an inferred content
+ * type, and the required checksums.
+ *
+ * @internal
+ */
+
+/** A minimal Node.js `Readable`-like shape (avoids depending on `node:stream` types). */
+interface NodeReadableLike {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    pipe?: unknown;
+    read?: unknown;
+}
+/** In-memory data accepted by the upload helpers. `Buffer` is a `Uint8Array`. */
+type UploadData = Blob | ArrayBuffer | Uint8Array;
+/** The tus-js-client file input union. */
+type TusFile = File | Blob | Uint8Array | NodeReadableLike;
+
+/**
+ * Thin, injectable wrapper around `tus-js-client` that performs the resumable
+ * byte upload. Isolated here so the upload flow can be unit-tested with a fake
+ * transport (no real network I/O) and so abort/resume behaviour lives in one
+ * place.
+ *
+ * @internal
+ */
+
+/** A persistence backend for resumable upload fingerprints (matches tus-js-client's `UrlStorage`). */
+interface UploadUrlStorage {
+    findAllUploads(): Promise<unknown[]>;
+    findUploadsByFingerprint(fingerprint: string): Promise<unknown[]>;
+    removeUpload(urlStorageKey: string): Promise<void>;
+    addUpload(fingerprint: string, upload: unknown): Promise<string>;
+}
+/** Parameters for a single byte upload. */
+interface TusUploadParams {
+    /** The file/data passed to tus-js-client. */
+    data: TusFile;
+    /** Signed upload URL (already includes the short-lived upload token). */
+    uploadUrl: string;
+    /** Total upload size in bytes. */
+    uploadSize: number;
+    /** Headers to send with each request (must include `Tus-Resumable`). */
+    headers: Record<string, string>;
+    /** Maximum chunk size in bytes. Required for streamed inputs. */
+    chunkSize?: number;
+    /** Retry backoff in milliseconds. `null`/`[]` disables retries. */
+    retryDelays?: number[] | null;
+    /** Progress callback. */
+    onProgress?: (bytesSent: number, bytesTotal: number) => void;
+    /** Abort signal to cancel the upload. */
+    signal?: AbortSignal;
+    /** Persist a resumable fingerprint so the upload can resume later. */
+    resume?: boolean;
+    /** Custom storage for resumable fingerprints (defaults to the tus-js-client default for the runtime). */
+    urlStorage?: UploadUrlStorage;
+}
+/** Performs a single resumable byte upload. Resolves on success, rejects on error/abort. */
+type UploadTransport = (params: TusUploadParams) => Promise<void>;
+/** Options shared by the high-level upload entry points. */
+interface RunUploadOptions {
+    /** Maximum chunk size in bytes. */
+    chunkSize?: number;
+    /** Retry backoff in milliseconds. `null`/`[]` disables retries. */
+    retryDelays?: number[] | null;
+    /** Progress callback. */
+    onProgress?: (bytesSent: number, bytesTotal: number) => void;
+    /** Abort signal to cancel the upload. */
+    signal?: AbortSignal;
+    /** Persist a resumable fingerprint so the upload can resume later. */
+    resume?: boolean;
+    /** Custom storage for resumable fingerprints. */
+    urlStorage?: UploadUrlStorage;
+}
+
+/** A storage bucket belonging to an application. Buckets hold objects (files). */
+interface StorageBucket {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** The application this bucket belongs to. */
+    applicationId: string;
+    /** Human-readable bucket name. */
+    name: string;
+    /** Globally unique, hostname-safe label used to build the bucket's serving hostname. */
+    slug: string;
+    /** `"public"` buckets serve objects through the CDN hostname; `"private"` buckets require signed access URLs. */
+    visibility: 'public' | 'private';
+    /** The hostname clients use to read public objects or signed private-object URLs. */
+    cdnHostname: string;
+    /** The application environment this bucket is scoped to. */
+    environmentId: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** Input for creating a new storage bucket. */
+interface CreateStorageBucketInput {
+    /** Human-readable name for the bucket. */
+    name: string;
+    /** The application environment to scope this bucket to. */
+    environmentId: string;
+    /** Optional hostname-safe slug used in the generated serving hostname. Auto-generated when omitted. */
+    slug?: string;
+    /** Bucket visibility. Defaults to `"private"`. */
+    visibility?: 'public' | 'private';
+}
+/**
+ * Manage storage buckets for an application.
+ * Accessed via `client.applications.storage.buckets`.
+ *
+ * @example
+ * ```ts
+ * // Create a public bucket
+ * const bucket = await client.applications.storage.buckets.create('app-id', {
+ *   name: 'User Uploads',
+ *   environmentId: 'env-id',
+ *   visibility: 'public',
+ * });
+ *
+ * // List all buckets
+ * const { items } = await client.applications.storage.buckets.list('app-id');
+ * ```
+ */
+declare class StorageBucketsResource extends BaseResource {
+    /**
+     * List all storage buckets for an application.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param query - Optional pagination parameters.
+     * @returns A paginated list of storage buckets.
+     *
+     * @example
+     * ```ts
+     * const { items, total } = await client.applications.storage.buckets.list('app-id');
+     * console.log(`${total} buckets found`);
+     * ```
+     */
+    list(applicationId: string, query?: ListQuery): Promise<Paginated<StorageBucket>>;
+    /**
+     * Create a new storage bucket.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param data - Bucket name, environment, and optional slug/visibility.
+     * @returns The newly created bucket.
+     *
+     * @example
+     * ```ts
+     * const bucket = await client.applications.storage.buckets.create('app-id', {
+     *   name: 'Assets',
+     *   environmentId: 'env-id',
+     *   visibility: 'public',
+     * });
+     * console.log(`Bucket CDN: https://${bucket.cdnHostname}`);
+     * ```
+     */
+    create(applicationId: string, data: CreateStorageBucketInput): Promise<StorageBucket>;
+    /**
+     * Get a storage bucket by ID.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @returns The bucket details.
+     *
+     * @example
+     * ```ts
+     * const bucket = await client.applications.storage.buckets.get('app-id', 'bucket-id');
+     * console.log(`${bucket.name} (${bucket.visibility})`);
+     * ```
+     */
+    get(applicationId: string, bucketId: string): Promise<StorageBucket>;
+    /**
+     * Permanently delete a storage bucket and all its objects.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     *
+     * @example
+     * ```ts
+     * await client.applications.storage.buckets.delete('app-id', 'bucket-id');
+     * ```
+     */
+    delete(applicationId: string, bucketId: string): Promise<void>;
+}
+
+/** A file (object) stored in a storage bucket. */
+interface StorageObject {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** The bucket this object belongs to. */
+    bucketId: string;
+    /** The application this object belongs to. */
+    applicationId: string;
+    /** The upload session that created this object, or `null` for imported objects. */
+    uploadSessionId: string | null;
+    /** The object key (path) within the bucket (e.g. `"images/photo.jpg"`). */
+    key: string;
+    /** MIME content type (e.g. `"image/jpeg"`), or `null` if not set. */
+    contentType: string | null;
+    /** File size in bytes. */
+    contentLength: number;
+    /** SHA-1 checksum of the file contents, if available. */
+    checksumSha1: string | null;
+    /** SHA-256 checksum of the file contents, if available. */
+    checksumSha256: string | null;
+    /** MD5 checksum of the file contents, if available. */
+    checksumMd5: string | null;
+    /** ISO 8601 timestamp of when the upload was finalized. */
+    uploadedAt: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/**
+ * Access URL details for a storage object. For public buckets, the URL is a
+ * stable CDN URL. For private buckets, the URL is time-limited and signed.
+ */
+interface StorageObjectAccess {
+    /** `"public"` for stable CDN URLs, `"signed"` for time-limited signed URLs. */
+    accessType: 'public' | 'signed';
+    /** The URL to access the object. */
+    url: string;
+    /** ISO 8601 expiry timestamp for signed URLs. `null` for public URLs. */
+    expiresAt: string | null;
+}
+/** Query parameters for listing objects in a bucket. */
+interface ListStorageObjectsQuery {
+    /** Only return objects whose key starts with this prefix. */
+    prefix?: string;
+    /** Group keys by this delimiter into `commonPrefixes` (virtual folders). Defaults to `"/"`. */
+    delimiter?: string;
+    /** Opaque cursor from a previous response's `nextCursor`. */
+    cursor?: string;
+    /** Maximum number of objects to return (1–1000, default 200). */
+    limit?: number;
+}
+/** A page of storage objects, including any common (folder) prefixes. */
+interface StorageObjectList extends Paginated<StorageObject> {
+    /** Virtual "folder" prefixes at the current level when a delimiter is used. */
+    commonPrefixes: string[];
+}
+/**
+ * Read and delete objects in storage buckets, and generate access URLs.
+ * Accessed via `client.applications.storage.objects`.
+ *
+ * Objects are addressed by their object ID (UUID). If you only have the object
+ * key, use {@link getByKey} to resolve it, or read the `id` from a listing.
+ *
+ * To upload objects, use `client.applications.storage.upload()`.
+ *
+ * @example
+ * ```ts
+ * // List all objects in a bucket
+ * const { items } = await client.applications.storage.objects.list('app-id', 'bucket-id');
+ * for (const obj of items) {
+ *   console.log(`${obj.key} (${obj.contentLength} bytes)`);
+ * }
+ *
+ * // Get a signed download URL for a private object
+ * const { url } = await client.applications.storage.objects.getAccessUrl('app-id', 'bucket-id', 'object-id');
+ * ```
+ */
+declare class StorageObjectsResource extends BaseResource {
+    /**
+     * List objects in a storage bucket, optionally filtered by key prefix and
+     * grouped into virtual folders by a delimiter.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param query - Optional prefix/delimiter/cursor/limit parameters.
+     * @returns A page of objects plus any common (folder) prefixes and a `nextCursor`.
+     *
+     * @example
+     * ```ts
+     * // List the "images/" folder, one level deep
+     * const { items, commonPrefixes, nextCursor } = await client.applications.storage.objects.list(
+     *   'app-id', 'bucket-id', { prefix: 'images/', limit: 100 },
+     * );
+     * ```
+     */
+    list(applicationId: string, bucketId: string, query?: ListStorageObjectsQuery): Promise<StorageObjectList>;
+    /**
+     * Get metadata for a specific object by its object ID.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param objectId - The object ID (UUID) — not the object key. Use {@link getByKey} to resolve a key.
+     * @returns The object metadata.
+     *
+     * @example
+     * ```ts
+     * const obj = await client.applications.storage.objects.get('app-id', 'bucket-id', 'object-id');
+     * console.log(`${obj.key}: ${obj.contentLength} bytes, type: ${obj.contentType}`);
+     * ```
+     */
+    get(applicationId: string, bucketId: string, objectId: string): Promise<StorageObject>;
+    /**
+     * Resolve an object by its key (path) instead of its ID. Convenience over
+     * {@link list} — lists with the key as the prefix and returns the exact match,
+     * paging through results until found, or `null` if no object with that key
+     * exists. (The API has no get-by-key endpoint.)
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param key - The object key/path (e.g. `"images/photo.jpg"`).
+     * @returns The matching object, or `null` if not found.
+     */
+    getByKey(applicationId: string, bucketId: string, key: string): Promise<StorageObject | null>;
+    /**
+     * Permanently delete an object from a storage bucket.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param objectId - The object ID (UUID) — not the object key.
+     *
+     * @example
+     * ```ts
+     * await client.applications.storage.objects.delete('app-id', 'bucket-id', 'object-id');
+     * ```
+     */
+    delete(applicationId: string, bucketId: string, objectId: string): Promise<void>;
+    /**
+     * Get an access URL for a storage object. For objects in public buckets,
+     * returns a stable CDN URL. For private buckets, returns a time-limited
+     * signed URL.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param objectId - The object ID (UUID) — not the object key.
+     * @param options - Optional `expiresInSeconds` for signed URLs (60–86400).
+     * @returns The access URL and its type/expiry.
+     *
+     * @example
+     * ```ts
+     * const access = await client.applications.storage.objects.getAccessUrl('app-id', 'bucket-id', 'object-id', {
+     *   expiresInSeconds: 3600,
+     * });
+     * if (access.accessType === 'signed') {
+     *   console.log(`Signed URL expires at ${access.expiresAt}`);
+     * }
+     * console.log(`Download: ${access.url}`);
+     * ```
+     */
+    getAccessUrl(applicationId: string, bucketId: string, objectId: string, options?: {
+        expiresInSeconds?: number;
+    }): Promise<StorageObjectAccess>;
+}
+
+/**
+ * Represents an upload session for a storage object. Upload sessions track the
+ * lifecycle of a file upload from creation through completion.
+ */
+interface StorageUploadSession {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** The bucket this upload targets. */
+    bucketId: string;
+    /** The application this upload belongs to. */
+    applicationId: string;
+    /** The object key/path the file will be stored at (e.g. `"images/photo.jpg"`). */
+    key: string;
+    /** MIME content type declared at creation, or `null` if not specified. */
+    contentType: string | null;
+    /** Expected file size in bytes declared at creation, or `null`. */
+    contentLength: number | null;
+    /** SHA-1 checksum for server-side verification, if provided. */
+    checksumSha1: string | null;
+    /** SHA-256 checksum for server-side verification, if provided. */
+    checksumSha256: string | null;
+    /** MD5 checksum for server-side verification, if provided. */
+    checksumMd5: string | null;
+    /**
+     * Current session state:
+     * - `"pending"` — Session created, awaiting the first bytes.
+     * - `"ready"` — Receiving file data.
+     * - `"completed"` — Upload verified and storage object created.
+     * - `"failed"` — Upload failed or was rejected.
+     * - `"expired"` — Session exceeded its expiration time.
+     */
+    state: 'pending' | 'ready' | 'completed' | 'failed' | 'expired';
+    /** ISO 8601 timestamp when this session (and its upload URL) expires. */
+    expiresAt: string;
+    /** ISO 8601 timestamp when the upload was finalized, or `null`. */
+    uploadedAt: string | null;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** Input for creating a new upload session. */
+interface CreateUploadSessionInput {
+    /** The object key/path the file will be stored at (e.g. `"images/photo.jpg"`). 1–1024 characters. */
+    key: string;
+    /** File size in bytes. Required. */
+    contentLength: number;
+    /** Lowercase hex SHA-256 checksum (64 chars) of the content. Required for server-side verification. */
+    checksumSha256: string;
+    /** MIME content type of the file (e.g. `"image/jpeg"`). */
+    contentType?: string;
+    /** Optional lowercase hex SHA-1 checksum (40 chars). */
+    checksumSha1?: string;
+    /** Optional lowercase hex MD5 checksum (32 chars). */
+    checksumMd5?: string;
+}
+/**
+ * Response from creating an upload session. Contains both the session metadata
+ * and the resumable upload instructions (signed URL + headers).
+ */
+interface CreateUploadSessionResponse {
+    /** The created upload session. */
+    session: StorageUploadSession;
+    /** Resumable upload instructions — use these to send the file data. */
+    upload: {
+        /** The HTTP method for the byte upload (resumable upload protocol). */
+        method: 'PATCH';
+        /** Signed upload URL. Send your file data here. */
+        url: string;
+        /** Required headers to include with the upload request. */
+        headers: Record<string, string>;
+        /** The URL where the object will be accessible after upload (CDN URL for public buckets). */
+        publicObjectUrl: string;
+    };
+}
+/** A byte source for uploading directly to a known signed URL. */
+interface UploadByteSource {
+    /** In-memory data (`File`/`Blob`/`Buffer`/`Uint8Array`/`ArrayBuffer`). */
+    data?: UploadData;
+    /** A filesystem path to stream from (Node.js only). */
+    path?: string;
+    /** A readable stream (Node.js only). Requires `contentLength`. */
+    stream?: NodeReadableLike;
+    /** Byte size — required for `stream` inputs, computed otherwise. */
+    contentLength?: number;
+}
+/**
+ * Manage upload sessions and upload bytes to a signed upload URL using the
+ * resumable upload protocol. Accessed via
+ * `client.applications.storage.uploadSessions`.
+ *
+ * For most use cases, prefer the high-level `client.applications.storage.upload()`
+ * which creates the session, computes the required checksum, uploads the bytes,
+ * and returns the public URL.
+ */
+declare class StorageUploadSessionsResource extends BaseResource {
+    private readonly transport;
+    constructor(httpClient: ConstructorParameters<typeof BaseResource>[0], transport?: UploadTransport);
+    /**
+     * List upload sessions for a bucket.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param query - Optional pagination parameters.
+     * @returns A paginated list of upload sessions.
+     */
+    list(applicationId: string, bucketId: string, query?: ListQuery): Promise<Paginated<StorageUploadSession>>;
+    /**
+     * Create an upload session. Returns the session metadata and a signed upload
+     * URL for sending file data. This is the low-level method — for most use
+     * cases prefer `client.applications.storage.upload()` which also computes the
+     * required SHA-256 checksum for you.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param data - Object key, content length, SHA-256 checksum, and optional content type / extra checksums.
+     * @returns The session and resumable upload instructions (URL, method, headers).
+     */
+    create(applicationId: string, bucketId: string, data: CreateUploadSessionInput): Promise<CreateUploadSessionResponse>;
+    /**
+     * Get an upload session by ID. Use this to track server-side processing after
+     * an upload (poll until `state === 'completed'`).
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param sessionId - The upload session ID (UUID).
+     * @returns The current session state.
+     */
+    get(applicationId: string, bucketId: string, sessionId: string): Promise<StorageUploadSession>;
+    /**
+     * Upload bytes directly to a pre-existing signed upload URL — for example, a
+     * URL returned by {@link create} or handed to your client by a backend. Skips
+     * session creation and checksum computation.
+     *
+     * @param url - A signed upload URL.
+     * @param source - The bytes to upload.
+     * @param options - Chunk size, retry config, progress, abort signal, resume,
+     *   and any required `headers` returned with the upload session.
+     * @throws {@link UploadError} if the upload fails after all retries.
+     */
+    uploadToUrl(url: string, source: UploadByteSource, options?: RunUploadOptions & {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * Resume an interrupted upload to a previously issued signed upload URL. The
+     * resumable protocol negotiates the current offset and continues from there.
+     *
+     * @param url - The signed upload URL from the original {@link create} call.
+     * @param source - The full bytes to upload (the same content as the original).
+     * @param options - Chunk size, retry config, progress, abort signal.
+     */
+    resumeFromUrl(url: string, source: UploadByteSource, options?: RunUploadOptions & {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+}
+
+/** Options controlling whether and how to wait for an upload to finalize server-side. */
+interface WaitForCompletionOptions {
+    /** Maximum time to wait in milliseconds. Default: 60000. */
+    timeoutMs?: number;
+    /** How often to poll the session state, in milliseconds. Default: 1000. */
+    pollIntervalMs?: number;
+}
+/** Input for the high-level {@link ApplicationStorageResource.upload | upload()} method. */
+interface UploadFileInput {
+    /** The application ID (UUID). */
+    applicationId: string;
+    /** The target bucket ID (UUID). */
+    bucketId: string;
+    /** The object key/path in the bucket (e.g. `"images/logo.png"`). */
+    key: string;
+    /** In-memory data (browser `File`/`Blob`, Node `Buffer`, `Uint8Array`, `ArrayBuffer`). */
+    data?: UploadData;
+    /** A filesystem path to upload from (Node.js only). Size, checksum, and content type are derived automatically. */
+    path?: string;
+    /** A readable stream to upload from (Node.js only). Requires `contentLength` and `checksumSha256`. */
+    stream?: NodeReadableLike;
+    /** MIME content type. Inferred from `key` when omitted. */
+    contentType?: string;
+    /** Byte size. Required for `stream`; computed otherwise. */
+    contentLength?: number;
+    /** Pre-computed SHA-256 (skips hashing). Required for `stream`. */
+    checksumSha256?: string;
+    /** Also send a SHA-1 checksum. */
+    checksumSha1?: string;
+    /** Also send an MD5 checksum (Node.js only unless provided). */
+    checksumMd5?: string;
+    /** Maximum chunk size in bytes (for very large files / streams). */
+    chunkSize?: number;
+    /** Retry backoff in milliseconds; `null`/`[]` disables retries. */
+    retryDelays?: number[] | null;
+    /** Progress callback invoked during the byte upload. */
+    onProgress?: (bytesSent: number, bytesTotal: number) => void;
+    /** Abort signal to cancel the upload. */
+    signal?: AbortSignal;
+    /** Persist a resumable fingerprint so the upload can be resumed later. */
+    resume?: boolean;
+    /** Custom storage backend for resumable fingerprints. */
+    urlStorage?: UploadUrlStorage;
+    /** Wait until the object is finalized server-side before resolving. Pass options to tune polling. */
+    waitForCompletion?: boolean | WaitForCompletionOptions;
+}
+/** Result of a successful upload. */
+interface UploadFileResult {
+    /** The upload session. When `waitForCompletion` was set, `state` is `"completed"`. */
+    session: StorageUploadSession;
+    /** The public/CDN URL of the uploaded object. */
+    url: string;
+    /** The finalized storage object — present only when `waitForCompletion` was set. */
+    object?: StorageObject;
+}
+/** Options for {@link ApplicationStorageResource.uploadBatch | uploadBatch()}. */
+interface UploadBatchOptions {
+    /** Maximum number of concurrent uploads. Default: 4. */
+    concurrency?: number;
+    /** Called after each file settles, with the number completed and the total. */
+    onProgress?: (completed: number, total: number) => void;
+}
+/** The outcome of one file within a batch upload. Errors are isolated per file. */
+interface UploadBatchItemResult {
+    /** The input that produced this result. */
+    input: UploadFileInput;
+    /** The successful result, if the upload succeeded. */
+    result?: UploadFileResult;
+    /** The error, if this upload failed. */
+    error?: unknown;
+}
+/**
+ * Namespace for all storage operations on an application: bucket management,
+ * object listing/access, low-level upload sessions, and the high-level
+ * {@link upload} / {@link uploadBatch} helpers.
+ *
+ * Accessed via `client.applications.storage`.
+ *
+ * @example
+ * ```ts
+ * // High-level upload (Node.js, from a path — checksum/size/content-type inferred)
+ * const { url } = await client.applications.storage.upload({
+ *   applicationId: 'app-id',
+ *   bucketId: 'bucket-id',
+ *   key: 'photos/cat.jpg',
+ *   path: './cat.jpg',
+ * });
+ *
+ * // Browser upload from a file input, with progress and abort
+ * const controller = new AbortController();
+ * const { url } = await client.applications.storage.upload({
+ *   applicationId: 'app-id',
+ *   bucketId: 'bucket-id',
+ *   key: `uploads/${file.name}`,
+ *   data: file,
+ *   onProgress: (sent, total) => console.log(`${Math.round((sent / total) * 100)}%`),
+ *   signal: controller.signal,
+ * });
+ * ```
+ */
+declare class ApplicationStorageResource {
+    /** Create, list, get, and delete storage buckets. */
+    readonly buckets: StorageBucketsResource;
+    /** List, get, delete objects, and generate access URLs. */
+    readonly objects: StorageObjectsResource;
+    /** Low-level upload sessions and direct-to-URL byte uploads. */
+    readonly uploadSessions: StorageUploadSessionsResource;
+    private readonly transport;
+    constructor(httpClient: HttpClient, transport?: UploadTransport);
+    /**
+     * Upload a file to a storage bucket. Handles the full flow: computes the
+     * required SHA-256 checksum, creates an upload session, uploads the bytes with
+     * automatic retries (and optional progress/abort/resume), and returns the
+     * public URL.
+     *
+     * Accepts browser `File`/`Blob`, Node `Buffer`/`Uint8Array`/`ArrayBuffer`, a
+     * Node filesystem `path`, or a Node readable `stream` (with `contentLength`
+     * and `checksumSha256`). The content type is inferred from `key` when omitted.
+     *
+     * @param input - What and where to upload, plus optional transfer options.
+     * @returns The upload session and public object URL (and the finalized object when `waitForCompletion` is set).
+     * @throws {@link UploadError} if the byte upload fails.
+     * @throws {@link UploadSessionExpiredError} if the session expires mid-upload.
+     *
+     * @example
+     * ```ts
+     * const { session, url, object } = await client.applications.storage.upload({
+     *   applicationId, bucketId, key: 'reports/q1.pdf', path: './q1.pdf',
+     *   waitForCompletion: true,
+     * });
+     * console.log(object?.contentLength, 'bytes available at', url);
+     * ```
+     */
+    upload(input: UploadFileInput): Promise<UploadFileResult>;
+    /**
+     * Upload many files concurrently. Each file is uploaded independently; a
+     * failure for one file does not abort the others — inspect each item's
+     * `error`/`result`.
+     *
+     * @param inputs - The files to upload.
+     * @param options - Concurrency limit and an aggregated progress callback.
+     * @returns One result per input, in the same order.
+     *
+     * @example
+     * ```ts
+     * const results = await client.applications.storage.uploadBatch(
+     *   files.map((f) => ({ applicationId, bucketId, key: `uploads/${f.name}`, data: f })),
+     *   { concurrency: 6, onProgress: (done, total) => console.log(`${done}/${total}`) },
+     * );
+     * const failed = results.filter((r) => r.error);
+     * ```
+     */
+    uploadBatch(inputs: UploadFileInput[], options?: UploadBatchOptions): Promise<UploadBatchItemResult[]>;
+    /**
+     * Poll an upload session until the object is finalized server-side.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param bucketId - The bucket ID (UUID).
+     * @param sessionId - The upload session ID (UUID).
+     * @param options - Timeout and polling interval.
+     * @returns The completed session.
+     * @throws {@link UploadError} if the session fails, expires, or the timeout elapses.
+     */
+    waitForCompletion(applicationId: string, bucketId: string, sessionId: string, options?: WaitForCompletionOptions): Promise<StorageUploadSession>;
+}
+
+/** A `*.gigadrive.app` hostname assigned to an application or deployment. */
+interface Hostname {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** The fully-qualified hostname (e.g. `"my-app.gigadrive.app"`). */
+    hostname: string;
+    /** The kind of hostname: `"DEPLOYMENT"`, `"BRANCH"`, or `"APP"`. */
+    type: 'DEPLOYMENT' | 'BRANCH' | 'APP';
+    /** Whether this hostname currently routes traffic. */
+    active: boolean;
+    /** The deployment this hostname points to, if any. */
+    deploymentId: string | null;
+    /** The branch this hostname is associated with, if any. */
+    branchId: string | null;
+    /** Who created the hostname: `"system"` (automatic) or `"user"`. */
+    source: 'system' | 'user';
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+}
+/** A paginated list of application hostnames, plus the production label. */
+interface ApplicationHostnameList extends Paginated<Hostname> {
+    /** The application's production hostname label (`{label}.gigadrive.app`), or `null` if none is set. */
+    label: string | null;
+}
+/** The result of checking whether a production hostname label is available. */
+interface HostnameAvailability {
+    /** Whether the label is allowed and globally available. */
+    available: boolean;
+    /** When {@link available} is `false`, a human-readable reason (e.g. the label is reserved or already taken). */
+    reason?: string;
+}
+/** The result of setting an application's production hostname. */
+interface SetProductionHostnameResult {
+    /** The normalized production label that was saved. */
+    label: string;
+    /** The resulting `{label}.gigadrive.app` hostname. */
+    hostname: string;
+    /**
+     * Whether the hostname now routes traffic. `false` when the label is reserved
+     * but no active production deployment exists yet — the URL becomes live after
+     * the next production deployment.
+     */
+    live: boolean;
+}
+
+/** One bucket of an AI Gateway usage breakdown (by model, provider, or user). */
+interface AiGatewayUsageBreakdown {
+    /** Bucket label (a model, provider, or user identifier). */
+    label: string;
+    /** Number of requests in this bucket. */
+    requests: number;
+    /** Total tokens in this bucket. */
+    tokens: number;
+    /** Input tokens in this bucket. */
+    inputTokens: number;
+    /** Output tokens in this bucket. */
+    outputTokens: number;
+    /** Billable cost in micros of USD for this bucket. */
+    costMicros: number;
+}
+/** Aggregated AI Gateway usage over a time range, with breakdowns. */
+interface AiGatewayUsageSummary {
+    summary: {
+        requestCount: number;
+        successCount: number;
+        errorCount: number;
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        billableCostMicros: number;
+        avgLatencyMs: number;
+    };
+    byModel: AiGatewayUsageBreakdown[];
+    byProvider: AiGatewayUsageBreakdown[];
+    byUser: AiGatewayUsageBreakdown[];
+}
+/** One provider attempt recorded while routing an AI Gateway request. */
+interface AiGatewayProviderAttempt {
+    provider: string;
+    error?: string;
+    statusCode?: number;
+    tag?: string;
+}
+/** A single AI Gateway request event with full telemetry. */
+interface AiGatewayRequestEvent {
+    id: string;
+    requestId: string;
+    traceId: string | null;
+    billingSubjectType: 'organization' | 'application';
+    organizationId: string;
+    applicationId: string | null;
+    actorId: string | null;
+    actorType: string;
+    apiKeyId: string | null;
+    authenticatedUserId: string | null;
+    callerEndUserId: string | null;
+    modelRequested: string;
+    modelServed: string | null;
+    provider: string | null;
+    providerAttempts: AiGatewayProviderAttempt[] | null;
+    status: 'pending' | 'success' | 'error' | 'cancelled';
+    errorCode: string | null;
+    errorType: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    totalTokens: number;
+    usageSource: 'provider' | 'estimated' | 'none';
+    providerCostMicros: number;
+    billableCostMicros: number;
+    streaming: boolean;
+    latencyMs: number | null;
+    metadata: Record<string, string> | null;
+    startedAt: string;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** An AI Gateway spend/usage budget. */
+interface AiGatewayBudget {
+    id: string;
+    organizationId: string;
+    /** Application-specific target, or `null` for organization-wide. */
+    applicationId: string | null;
+    /** User-specific target, or `null` for all users. */
+    userId: string | null;
+    period: 'day' | 'month';
+    maxCostMicros: number | null;
+    maxRequests: number | null;
+    maxTokens: number | null;
+    maxRequestCostMicros: number | null;
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Input for one budget when replacing the budget set. */
+interface AiGatewayBudgetInput {
+    applicationId?: string;
+    userId?: string;
+    period?: 'day' | 'month';
+    maxCostMicros?: number | null;
+    maxRequests?: number | null;
+    maxTokens?: number | null;
+    maxRequestCostMicros?: number | null;
+    enabled?: boolean;
+}
+/** An AI Gateway governance policy. */
+interface AiGatewayPolicy {
+    id: string;
+    organizationId: string;
+    /** Application-specific target, or `null` for organization-wide. */
+    applicationId: string | null;
+    /** Allowed model IDs, or `null` to allow all. */
+    allowedModels: string[] | null;
+    /** Allowed provider IDs, or `null` to allow all. */
+    allowedProviders: string[] | null;
+    requireZdr: boolean;
+    allowFallbacks: boolean;
+    maxOutputTokens: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Input for creating or updating an AI Gateway policy. */
+interface AiGatewayPolicyInput {
+    applicationId?: string;
+    allowedModels?: string[] | null;
+    allowedProviders?: string[] | null;
+    requireZdr?: boolean;
+    allowFallbacks?: boolean;
+    maxOutputTokens?: number | null;
+}
+/** Query for usage summary. */
+interface AiGatewayUsageQuery {
+    /** Only include usage at or after this ISO 8601 timestamp. */
+    from?: string;
+    /** Only include usage before or at this ISO 8601 timestamp. */
+    to?: string;
+    /** Restrict to one application. */
+    applicationId?: string;
+}
+/** Query for the request-event log and CSV export. */
+interface AiGatewayRequestsQuery extends AiGatewayUsageQuery {
+    model?: string;
+    provider?: string;
+    status?: 'pending' | 'success' | 'error' | 'cancelled';
+    requestId?: string;
+    authenticatedUserId?: string;
+    callerEndUserId?: string;
+    limit?: number;
+    cursor?: string;
+}
+/** AI Gateway usage analytics for an organization. */
+declare class AiGatewayUsageResource extends BaseResource {
+    /** Get an aggregated usage summary with breakdowns by model, provider, and user. */
+    summary(organizationId: string, query?: AiGatewayUsageQuery): Promise<AiGatewayUsageSummary>;
+    /** List request-level usage events. */
+    requests(organizationId: string, query?: AiGatewayRequestsQuery): Promise<Paginated<AiGatewayRequestEvent>>;
+    /** Export request-level usage events as CSV text. */
+    export(organizationId: string, query?: AiGatewayRequestsQuery): Promise<string>;
+}
+/** AI Gateway budgets for an organization. */
+declare class AiGatewayBudgetsResource extends BaseResource {
+    /** List all budgets for an organization. */
+    list(organizationId: string): Promise<{
+        items: AiGatewayBudget[];
+    }>;
+    /**
+     * Replace the organization's entire budget set. Pass an empty array to clear
+     * all budgets.
+     */
+    replace(organizationId: string, budgets: AiGatewayBudgetInput[]): Promise<{
+        items: AiGatewayBudget[];
+    }>;
+}
+/** AI Gateway governance policies for an organization. */
+declare class AiGatewayPoliciesResource extends BaseResource {
+    /**
+     * Get the governance policy for an organization, or for a specific
+     * application when `applicationId` is provided. Returns `null` if no policy is set.
+     */
+    get(organizationId: string, options?: {
+        applicationId?: string;
+    }): Promise<AiGatewayPolicy | null>;
+    /** Create or update an AI Gateway policy. */
+    put(organizationId: string, data: AiGatewayPolicyInput): Promise<AiGatewayPolicy>;
+}
+/**
+ * Organization-scoped AI Gateway governance: usage analytics, budgets, and
+ * model/provider policies. Accessed via `client.organizations.aiGateway`.
+ */
+declare class OrganizationAiGatewayResource {
+    /** Usage analytics (summary, request log, CSV export). */
+    readonly usage: AiGatewayUsageResource;
+    /** Spend/usage budgets. */
+    readonly budgets: AiGatewayBudgetsResource;
+    /** Model/provider governance policies. */
+    readonly policies: AiGatewayPoliciesResource;
+    constructor(httpClient: HttpClient);
+}
+
+/**
+ * Manage environment variables scoped to an organization.
+ * Accessed via `client.organizations.envVars`.
+ */
+declare class OrganizationEnvVarsResource extends BaseResource {
+    /**
+     * List all environment variables for an organization.
+     *
+     * @param organizationId - The organization ID (UUID).
+     * @returns A paginated list of environment variables.
+     *
+     * @example
+     * ```ts
+     * const { items } = await client.organizations.envVars.list('org-id');
+     * for (const v of items) {
+     *   console.log(`${v.key}=${v.sensitive ? '***' : v.value}`);
+     * }
+     * ```
+     */
+    list(organizationId: string, query?: ListQuery): Promise<Paginated<EnvVar>>;
+    /**
+     * Create a new environment variable for an organization.
+     *
+     * @param organizationId - The organization ID (UUID).
+     * @param data - The variable key, value, and optional settings.
+     * @returns The newly created environment variable.
+     *
+     * @example
+     * ```ts
+     * const envVar = await client.organizations.envVars.create('org-id', {
+     *   key: 'STRIPE_SECRET',
+     *   value: 'sk_live_...',
+     *   sensitive: true,
+     * });
+     * ```
+     */
+    create(organizationId: string, data: CreateEnvVarInput): Promise<EnvVar>;
+    /**
+     * Update an existing environment variable. Only the fields you provide
+     * will be changed; omitted fields are left unchanged.
+     *
+     * @param organizationId - The organization ID (UUID).
+     * @param envVarId - The environment variable ID (UUID).
+     * @param data - The fields to update.
+     * @returns The updated environment variable.
+     *
+     * @example
+     * ```ts
+     * await client.organizations.envVars.update('org-id', 'var-id', {
+     *   value: 'new-value',
+     * });
+     * ```
+     */
+    update(organizationId: string, envVarId: string, data: UpdateEnvVarInput): Promise<EnvVar>;
+    /**
+     * Permanently delete an environment variable.
+     *
+     * @param organizationId - The organization ID (UUID).
+     * @param envVarId - The environment variable ID (UUID).
+     *
+     * @example
+     * ```ts
+     * await client.organizations.envVars.delete('org-id', 'var-id');
+     * ```
+     */
+    delete(organizationId: string, envVarId: string): Promise<void>;
+}
+
+/** A Gigadrive Network organization. */
+interface Organization {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** Display name of the organization. */
+    name: string;
+    /** URL-safe slug (e.g. `gigadrive`). */
+    slug: string;
+    /** Avatar / logo URL. */
+    imageUrl: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/**
+ * Manage organizations. Accessed via {@link GigadriveClient.organizations}.
+ *
+ * @example
+ * ```ts
+ * const { items: orgs } = await client.organizations.list();
+ * console.log(orgs.map((o) => o.name));
+ * ```
+ */
+declare class OrganizationsResource extends BaseResource {
+    /**
+     * Manage environment variables scoped to an organization.
+     *
+     * @example
+     * ```ts
+     * // List all env vars for an organization
+     * const { items } = await client.organizations.envVars.list('org-id');
+     *
+     * // Create a new env var
+     * await client.organizations.envVars.create('org-id', {
+     *   key: 'ANALYTICS_KEY',
+     *   value: 'ak_live_...',
+     *   sensitive: true,
+     * });
+     * ```
+     */
+    readonly envVars: OrganizationEnvVarsResource;
+    /**
+     * AI Gateway governance for an organization: usage analytics, budgets, and
+     * model/provider policies.
+     *
+     * @example
+     * ```ts
+     * const usage = await client.organizations.aiGateway.usage.summary('org-id', { from: '2026-06-01' });
+     * console.log(usage.summary.totalTokens);
+     * ```
+     */
+    readonly aiGateway: OrganizationAiGatewayResource;
+    constructor(...args: ConstructorParameters<typeof BaseResource>);
+    /**
+     * List organizations the authenticated actor has access to.
+     *
+     * @param query - Optional pagination.
+     * @returns A paginated list of organizations.
+     *
+     * @example
+     * ```ts
+     * const { items, total } = await client.organizations.list();
+     * console.log(`Found ${total} organizations`);
+     * ```
+     */
+    list(query?: ListQuery): Promise<Paginated<Organization>>;
+}
+
+/** A Gigadrive Network application, belonging to an {@link Organization}. */
+interface Application {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** The organization this application belongs to. */
+    organization: Organization;
+    /** Display name of the application. */
+    name: string;
+    /** Avatar / logo URL. */
+    imageUrl: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** Query filters for listing applications. */
+interface ListApplicationsQuery extends ListQuery {
+    /** Only return applications belonging to this organization. */
+    organizationId?: string;
+}
+/**
+ * Manage applications. Accessed via {@link GigadriveClient.applications}.
+ *
+ * @example
+ * ```ts
+ * const { items: apps } = await client.applications.list();
+ * console.log(apps.map((a) => `${a.name} (${a.organization.name})`));
+ * ```
+ */
+declare class ApplicationsResource extends BaseResource {
+    /**
+     * Manage environment variables scoped to an application.
+     *
+     * @example
+     * ```ts
+     * await client.applications.envVars.create('app-id', {
+     *   key: 'DATABASE_URL',
+     *   value: 'postgres://...',
+     *   sensitive: true,
+     * });
+     * ```
+     */
+    readonly envVars: ApplicationEnvVarsResource;
+    /**
+     * Manage storage buckets, objects, and file uploads for an application.
+     *
+     * @example
+     * ```ts
+     * // Upload a file
+     * const { url } = await client.applications.storage.upload({
+     *   applicationId: 'app-id',
+     *   bucketId: 'bucket-id',
+     *   key: 'images/logo.png',
+     *   data: fileData,
+     * });
+     *
+     * // List objects in a bucket
+     * const { items } = await client.applications.storage.objects.list('app-id', 'bucket-id');
+     * ```
+     */
+    readonly storage: ApplicationStorageResource;
+    /**
+     * Read observed traffic (request logs) for an application.
+     *
+     * @example
+     * ```ts
+     * const { items } = await client.applications.requests.list('app-id', { statusFamily: 5 });
+     * ```
+     */
+    readonly requests: ApplicationRequestsResource;
+    constructor(...args: ConstructorParameters<typeof BaseResource>);
+    /**
+     * List applications the authenticated actor has access to.
+     *
+     * Requires the `network:applications:read` scope.
+     *
+     * @param query - Optional organization filter and pagination.
+     * @returns A paginated list of applications.
+     *
+     * @example
+     * ```ts
+     * const { items, total } = await client.applications.list({ organizationId: 'org-id' });
+     * console.log(`Found ${total} applications`);
+     * ```
+     */
+    list(query?: ListApplicationsQuery): Promise<Paginated<Application>>;
+    /**
+     * List the `*.gigadrive.app` hostnames for an application (production alias
+     * and per-branch aliases).
+     *
+     * @param applicationId - The application ID (UUID).
+     * @returns The hostnames plus the production hostname `label`.
+     *
+     * @example
+     * ```ts
+     * const { items, label } = await client.applications.hostnames('app-id');
+     * console.log(`Production: ${label}.gigadrive.app`);
+     * ```
+     */
+    hostnames(applicationId: string): Promise<ApplicationHostnameList>;
+    /**
+     * Check whether a candidate production hostname label is allowed and globally
+     * available before setting it with {@link setProductionHostname}.
+     *
+     * Requires the `network:applications:read` scope.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param label - The candidate production hostname label (e.g. `"my-app"`).
+     * @returns Whether the label is available, plus a `reason` when it is not.
+     *
+     * @example
+     * ```ts
+     * const { available, reason } = await client.applications.checkHostnameAvailability('app-id', 'my-app');
+     * if (!available) console.log(`Unavailable: ${reason}`);
+     * ```
+     */
+    checkHostnameAvailability(applicationId: string, label: string): Promise<HostnameAvailability>;
+    /**
+     * Set the application's production hostname. The production alias
+     * `{label}.gigadrive.app` is re-pointed to the latest production deployment.
+     *
+     * Requires the `network:applications:write` scope. Deployment- and
+     * function-scoped tokens cannot change the production hostname.
+     *
+     * @param applicationId - The application ID (UUID).
+     * @param label - The production hostname label (e.g. `"my-app"`). It is
+     *   normalized (slugified) server-side.
+     * @returns The saved label, the resulting hostname, and whether it is live yet.
+     *
+     * @example
+     * ```ts
+     * const { hostname, live } = await client.applications.setProductionHostname('app-id', 'my-app');
+     * console.log(live ? `Live at ${hostname}` : `Reserved ${hostname} (deploy to go live)`);
+     * ```
+     */
+    setProductionHostname(applicationId: string, label: string): Promise<SetProductionHostnameResult>;
+}
+
+/**
+ * The lifecycle status of a deployment.
+ * - `"PENDING"` — Created, waiting for artifact upload.
+ * - `"QUEUED"` — Queued for processing.
+ * - `"STARTING"` — Processing is starting.
+ * - `"BUILDING"` — Build pipeline is running.
+ * - `"PROVISIONING"` — Infrastructure is being provisioned.
+ * - `"ACTIVE"` — Successfully deployed and serving traffic.
+ * - `"FAILED"` — Build or provisioning failed.
+ */
+type DeploymentStatus = 'PENDING' | 'QUEUED' | 'STARTING' | 'BUILDING' | 'PROVISIONING' | 'ACTIVE' | 'FAILED';
+/** The severity level of a deployment log entry. */
+type DeploymentLogType = 'INFO' | 'ERROR' | 'WARN';
+/** A deployment of an application to the Gigadrive Network. */
+interface Deployment {
+    /** Unique identifier (UUID). */
+    id: string;
+    /** The application this deployment belongs to. */
+    applicationId: string;
+    /** Current lifecycle status. */
+    status: DeploymentStatus;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 last-updated timestamp. */
+    updatedAt: string;
+}
+/** A single log entry from a deployment's build or provisioning pipeline. */
+interface DeploymentLog {
+    /** Unique identifier. */
+    id: string;
+    /** The log message text. */
+    message: string;
+    /** Severity level: `"INFO"`, `"ERROR"`, or `"WARN"`. */
+    type: DeploymentLogType;
+    /** ISO 8601 timestamp of when this log entry was created. */
+    createdAt: string;
+}
+/** A paginated page of deployment log entries. */
+interface DeploymentLogPage {
+    /** Total number of log entries for this deployment. */
+    totalItems: number;
+    /** Maximum number of entries per page. */
+    limit: number;
+    /** Number of entries skipped (for pagination). */
+    offset: number;
+    /** The log entries on this page. */
+    items: DeploymentLog[];
+}
+/** Input for creating a new deployment. */
+interface CreateDeploymentInput {
+    /** The application to deploy. */
+    applicationId: string;
+    /** Optional git source for the deployment. When omitted, the deployment expects an artifact upload. */
+    gitSource?: {
+        /** The git ref to deploy (e.g. `"main"`, `"v1.0.0"`). */
+        ref: string;
+        /** A specific commit SHA to deploy. If omitted, the HEAD of the ref is used. */
+        sha?: string;
+    };
+}
+/** Query filters for listing deployments. All fields are optional. */
+interface ListDeploymentsQuery {
+    /** Filter by organization ID. */
+    organizationId?: string;
+    /** Filter by application ID. */
+    applicationId?: string;
+    /** Filter by deployment status. */
+    status?: DeploymentStatus;
+}
+/** Query parameters for fetching deployment logs. */
+interface ListDeploymentLogsQuery {
+    /** Number of log entries to skip (for pagination). */
+    offset?: number;
+    /** Maximum number of log entries to return per page. */
+    limit?: number;
+    /** Only return log entries created after this ISO 8601 timestamp. Useful for tailing logs. */
+    'createdAt[gt]'?: string;
+}
+/** Result from starting a multipart deployment upload. */
+interface StartUploadResult {
+    /** The multipart upload ID. Pass this to subsequent `getPresignedUrl` and `completeUpload` calls. */
+    uploadId: string;
+}
+/** A presigned URL for uploading a single part of a multipart deployment upload. */
+interface PresignedUrlResult {
+    /** The presigned URL to PUT the part data to. */
+    url: string;
+}
+/** A successfully uploaded part, used to complete the multipart upload. */
+interface UploadPart {
+    /** The 1-based part number. */
+    partNumber: number;
+    /** The ETag returned by the storage provider after uploading this part. */
+    etag: string;
+}
+/**
+ * Manage deployments — create, monitor, upload artifacts, and read logs.
+ * Accessed via {@link GigadriveClient.deployments}.
+ *
+ * ## Deployment lifecycle
+ *
+ * 1. **Create** a deployment with {@link create}.
+ * 2. **Upload** build artifacts using the multipart upload flow
+ *    ({@link startUpload} → {@link getPresignedUrl} → {@link uploadPart} → {@link completeUpload}).
+ * 3. **Monitor** the build with {@link get} and {@link getLogs}.
+ *
+ * @example
+ * ```ts
+ * // Create a deployment
+ * const deployment = await client.deployments.create({ applicationId: 'app-id' });
+ *
+ * // Check status
+ * const updated = await client.deployments.get(deployment.id);
+ * console.log(`Status: ${updated.status}`);
+ *
+ * // Read build logs
+ * const logs = await client.deployments.getLogs(deployment.id, { limit: 50 });
+ * for (const entry of logs.items) {
+ *   console.log(`[${entry.type}] ${entry.message}`);
+ * }
+ * ```
+ */
+declare class DeploymentsResource extends BaseResource {
+    /**
+     * List deployments, optionally filtered by organization, application, or status.
+     *
+     * Requires the `network:deployments:read` scope.
+     *
+     * @param query - Optional filters.
+     * @returns A paginated list of deployments.
+     *
+     * @example
+     * ```ts
+     * // All deployments for an application
+     * const { items } = await client.deployments.list({ applicationId: 'app-id' });
+     *
+     * // Only active deployments
+     * const { items } = await client.deployments.list({ status: 'ACTIVE' });
+     * ```
+     */
+    list(query?: ListDeploymentsQuery): Promise<Paginated<Deployment>>;
+    /**
+     * Get a deployment by ID, including its current status.
+     *
+     * @param deploymentId - The deployment ID (UUID).
+     * @returns The deployment with its current status.
+     *
+     * @example
+     * ```ts
+     * const deployment = await client.deployments.get('deployment-id');
+     * if (deployment.status === 'ACTIVE') {
+     *   console.log('Deployment is live!');
+     * }
+     * ```
+     */
+    get(deploymentId: string): Promise<Deployment>;
+    /**
+     * Create a new deployment. The deployment starts in `"PENDING"` status,
+     * waiting for artifact upload. Use the multipart upload methods
+     * ({@link startUpload}, {@link getPresignedUrl}, {@link uploadPart},
+     * {@link completeUpload}) to upload build artifacts.
+     *
+     * Requires the `network:deployments:trigger` scope.
+     *
+     * @param data - The application ID and optional git source.
+     * @returns The newly created deployment.
+     *
+     * @example
+     * ```ts
+     * const deployment = await client.deployments.create({
+     *   applicationId: 'app-id',
+     * });
+     * console.log(`Created deployment ${deployment.id} (${deployment.status})`);
+     * ```
+     */
+    create(data: CreateDeploymentInput): Promise<Deployment>;
+    /**
+     * Start a multipart upload for deployment artifacts. This initiates a new
+     * multipart upload and returns an upload ID for subsequent part uploads.
+     *
+     * The deployment must be in `"PENDING"` status.
+     *
+     * @param deploymentId - The deployment ID (UUID).
+     * @returns An object containing the `uploadId` for subsequent calls.
+     *
+     * @example
+     * ```ts
+     * const { uploadId } = await client.deployments.startUpload('deployment-id');
+     * ```
+     */
+    startUpload(deploymentId: string): Promise<StartUploadResult>;
+    /**
+     * Get a presigned URL for uploading a single part of a multipart upload.
+     * The URL is temporary and should be used immediately with {@link uploadPart}.
+     *
+     * @param deploymentId - The deployment ID (UUID).
+     * @param uploadId - The multipart upload ID from {@link startUpload}.
+     * @param partNumber - The 1-based part number.
+     * @returns An object containing the presigned `url` to PUT the part data to.
+     *
+     * @example
+     * ```ts
+     * const { url } = await client.deployments.getPresignedUrl(
+     *   'deployment-id', uploadId, 1,
+     * );
+     * ```
+     */
+    getPresignedUrl(deploymentId: string, uploadId: string, partNumber: number): Promise<PresignedUrlResult>;
+    /**
+     * Upload a part to a presigned URL obtained from {@link getPresignedUrl}.
+     * This sends the chunk data directly to the backend storage service, not
+     * to the Gigadrive API. The returned `etag` is needed for
+     * {@link completeUpload}.
+     *
+     * @param presignedUrl - The presigned URL from {@link getPresignedUrl}.
+     * @param data - The chunk data to upload.
+     * @param partNumber - The 1-based part number (used for error messages).
+     * @returns The part number and ETag. Collect these for {@link completeUpload}.
+     * @throws {@link ApiError} if the PUT request fails.
+     * @throws Error if the storage provider does not return an ETag header.
+     *
+     * @example
+     * ```ts
+     * const chunk = fileBuffer.subarray(0, 10 * 1024 * 1024); // 10 MB
+     * const part = await client.deployments.uploadPart(presignedUrl, chunk, 1);
+     * // part = { partNumber: 1, etag: '"abc123..."' }
+     * ```
+     */
+    uploadPart(presignedUrl: string, data: ArrayBuffer | Uint8Array | Blob, partNumber: number): Promise<UploadPart>;
+    /**
+     * Complete a multipart upload after all parts have been uploaded via
+     * {@link uploadPart}. This signals the storage provider to assemble the
+     * parts into a single object and triggers the deployment build pipeline.
+     *
+     * @param deploymentId - The deployment ID (UUID).
+     * @param uploadId - The multipart upload ID from {@link startUpload}.
+     * @param parts - Array of `{ partNumber, etag }` from each {@link uploadPart} call.
+     *
+     * @example
+     * ```ts
+     * await client.deployments.completeUpload(deploymentId, uploadId, [
+     *   { partNumber: 1, etag: '"abc..."' },
+     *   { partNumber: 2, etag: '"def..."' },
+     * ]);
+     * ```
+     */
+    completeUpload(deploymentId: string, uploadId: string, parts: UploadPart[]): Promise<void>;
+    /**
+     * Fetch deployment logs. Supports pagination and filtering by timestamp
+     * for incremental log tailing.
+     *
+     * @param deploymentId - The deployment ID (UUID).
+     * @param query - Optional pagination and filter parameters.
+     * @returns A page of log entries with total count.
+     *
+     * @example
+     * ```ts
+     * // Get the first page of logs
+     * const page = await client.deployments.getLogs('deployment-id', {
+     *   offset: 0,
+     *   limit: 100,
+     * });
+     *
+     * for (const entry of page.items) {
+     *   const prefix = entry.type === 'ERROR' ? 'ERR' : entry.type === 'WARN' ? 'WRN' : 'INF';
+     *   console.log(`[${prefix}] ${entry.message}`);
+     * }
+     *
+     * // Tail new logs since last fetch
+     * const newLogs = await client.deployments.getLogs('deployment-id', {
+     *   'createdAt[gt]': lastEntry.createdAt,
+     * });
+     * ```
+     */
+    getLogs(deploymentId: string, query?: ListDeploymentLogsQuery): Promise<DeploymentLogPage>;
+    /**
+     * List the immutable `*.gigadrive.app` hostnames assigned to a deployment.
+     *
+     * @param deploymentId - The deployment ID (UUID).
+     * @returns A paginated list of hostnames.
+     *
+     * @example
+     * ```ts
+     * const { items } = await client.deployments.getHostnames('deployment-id');
+     * console.log(items.map((h) => h.hostname));
+     * ```
+     */
+    getHostnames(deploymentId: string): Promise<Paginated<Hostname>>;
+}
+
+/**
+ * Configuration for the {@link GigadriveClient}.
+ *
+ * Credentials are resolved in priority order: explicit config fields first,
+ * then environment variables. See {@link GigadriveClient} for the full
+ * resolution chain.
+ */
+interface GigadriveClientConfig {
+    /**
+     * OAuth2 client ID (the API key ID from the Gigadrive dashboard).
+     * Used for both client-credentials and refresh-token flows.
+     * Falls back to the `GIGADRIVE_CLIENT_ID` environment variable.
+     */
+    clientId?: string;
+    /**
+     * OAuth2 client secret (the API key secret from the Gigadrive dashboard).
+     * Used together with {@link clientId} for the client-credentials grant.
+     * Falls back to the `GIGADRIVE_CLIENT_SECRET` environment variable.
+     */
+    clientSecret?: string;
+    /**
+     * A pre-obtained bearer token (either an IDP or Network token).
+     * When set, the SDK sends this token directly without any OAuth exchange.
+     * The token is never refreshed — if it expires, requests will fail.
+     * Falls back to the `GIGADRIVE_BEARER_TOKEN` environment variable.
+     */
+    bearerToken?: string;
+    /**
+     * An IDP refresh token for automatic access-token renewal. Used together
+     * with {@link clientId}. The SDK will exchange this for short-lived access
+     * tokens and handle refresh-token rotation automatically.
+     * Falls back to the `GIGADRIVE_REFRESH_TOKEN` environment variable.
+     */
+    refreshToken?: string;
+    /**
+     * The IDP issuer URL used for OIDC discovery (fetching the
+     * `.well-known/openid-configuration`). Only needed for refresh-token and
+     * authorization-code flows.
+     * Falls back to `GIGADRIVE_IDP_ISSUER_URL`, default: `https://idp.gigadrive.de`.
+     */
+    idpIssuerUrl?: string;
+    /**
+     * Callback for the OAuth2 authorization code flow with PKCE. The SDK
+     * builds the authorization URL and passes it to this callback. Your code
+     * must present the URL to the user (e.g. open a browser), then return
+     * either the full redirect URL or just the authorization code.
+     *
+     * Requires {@link clientId} to be set.
+     *
+     * @param url - The authorization URL the user should visit.
+     * @returns The full redirect URL (including `?code=...&state=...`) or the
+     *          bare authorization code.
+     *
+     * @example
+     * ```ts
+     * const client = new GigadriveClient({
+     *   clientId: 'my-app',
+     *   onAuthorizationUrl: async (url) => {
+     *     console.log('Visit:', url);
+     *     return await readline.question('Paste the redirect URL: ');
+     *   },
+     * });
+     * ```
+     */
+    onAuthorizationUrl?: (url: string) => Promise<string>;
+    /**
+     * Redirect URI for the authorization code flow.
+     * Default: `urn:ietf:wg:oauth:2.0:oob` (out-of-band / manual copy-paste).
+     */
+    redirectUri?: string;
+    /**
+     * OAuth scopes to request during the authorization-code flow, in addition to
+     * the default identity scopes (`openid profile email offline_access`). Use
+     * this to request API capability scopes (e.g. `network:applications:read`) so
+     * the resulting token can call the corresponding endpoints.
+     */
+    scopes?: string[];
+    /**
+     * Base URL of the Gigadrive Network API.
+     * Falls back to `GIGADRIVE_API_BASE_URL`, default: `https://api.gigadrive.network`.
+     */
+    baseUrl?: string;
+    /**
+     * Custom `fetch` implementation. Useful for testing (injectable mock) or
+     * non-standard runtimes like Cloudflare Workers that provide their own
+     * `fetch`. Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * The main entry point for the Gigadrive Network SDK.
+ *
+ * Create an instance to interact with organizations, applications, deployments,
+ * storage, and the AI gateway. Authentication is handled automatically —
+ * tokens are obtained, cached, and refreshed behind the scenes.
+ *
+ * ## Credential resolution order
+ *
+ * The client resolves credentials in the following order, using the first
+ * match it finds:
+ *
+ * 1. Explicit `bearerToken` in config
+ * 2. Explicit `clientId` + `clientSecret` in config
+ * 3. Explicit `clientId` + `refreshToken` in config
+ * 4. Explicit `clientId` + `onAuthorizationUrl` callback in config
+ * 5. `GIGADRIVE_BEARER_TOKEN` environment variable
+ * 6. `GIGADRIVE_CLIENT_ID` + `GIGADRIVE_CLIENT_SECRET` environment variables
+ * 7. `GIGADRIVE_CLIENT_ID` + `GIGADRIVE_REFRESH_TOKEN` environment variables
+ *
+ * If no credentials are found, the constructor throws an
+ * {@link AuthenticationError}.
+ *
+ * @example
+ * ```ts
+ * // Credentials auto-detected from environment variables
+ * const client = new GigadriveClient();
+ *
+ * // Explicit API key (client credentials)
+ * const client = new GigadriveClient({
+ *   clientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+ *   clientSecret: 'sk_live_...',
+ * });
+ *
+ * // Pre-obtained bearer token
+ * const client = new GigadriveClient({ bearerToken: 'eyJ...' });
+ *
+ * // IDP refresh token — access tokens are renewed automatically
+ * const client = new GigadriveClient({
+ *   clientId: 'my-app',
+ *   refreshToken: 'rt_...',
+ * });
+ *
+ * // Use the client
+ * const orgs = await client.organizations.list();
+ * const deployment = await client.deployments.create({ applicationId: 'app-1' });
+ * ```
+ *
+ * @throws {@link AuthenticationError} if no valid credentials are found.
+ */
+declare class GigadriveClient {
+    /** Organization management (list, environment variables). */
+    readonly organizations: OrganizationsResource;
+    /** Application management (list, environment variables, storage). */
+    readonly applications: ApplicationsResource;
+    /** Deployment lifecycle (create, upload, status, logs). */
+    readonly deployments: DeploymentsResource;
+    /** AI Gateway — OpenAI-compatible chat completions and model listing. */
+    readonly aiGateway: AiGatewayResource;
+    constructor(config?: GigadriveClientConfig);
+}
+
+/**
+ * Base error class for all Gigadrive SDK errors. Every error thrown by the SDK
+ * extends this class, so you can catch all SDK errors with a single check.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.organizations.list();
+ * } catch (err) {
+ *   if (err instanceof GigadriveError) {
+ *     console.error('SDK error:', err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class GigadriveError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when authentication fails. This includes missing or invalid credentials,
+ * expired tokens, failed token refresh attempts, and failed token exchanges.
+ *
+ * Common causes:
+ * - No credentials provided and no environment variables set
+ * - Invalid `clientId`/`clientSecret` pair
+ * - Expired or revoked refresh token
+ * - API returned 401 even after an automatic token refresh retry
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const client = new GigadriveClient(); // no credentials
+ * } catch (err) {
+ *   if (err instanceof AuthenticationError) {
+ *     console.error('Auth failed:', err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class AuthenticationError extends GigadriveError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Gigadrive API returns a non-2xx HTTP response.
+ *
+ * Contains the HTTP {@link status} code and an optional machine-readable
+ * {@link code} parsed from the response body.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.deployments.get('non-existent-id');
+ * } catch (err) {
+ *   if (err instanceof ApiError) {
+ *     console.error(`API error ${err.status}: ${err.message}`);
+ *     // err.code may contain a machine-readable error code
+ *   }
+ * }
+ * ```
+ */
+declare class ApiError extends GigadriveError {
+    /** The HTTP status code of the failed response (e.g. 404, 500). */
+    readonly status: number;
+    /** An optional machine-readable error code from the API response body. */
+    readonly code: string | undefined;
+    constructor(message: string, status: number, code?: string);
+}
+/**
+ * Thrown when a file upload fails. The original cause (e.g. a network error or a
+ * transport-level error from the resumable upload) is preserved on
+ * {@link cause} for inspection.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.applications.storage.upload({ applicationId, bucketId, key, data });
+ * } catch (err) {
+ *   if (err instanceof UploadError) {
+ *     console.error('Upload failed:', err.message, err.cause);
+ *   }
+ * }
+ * ```
+ */
+declare class UploadError extends GigadriveError {
+    /** The underlying error that caused the upload to fail, if any. */
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when an upload cannot complete because its session (and the short-lived
+ * upload URL it was issued with) expired. Create a new upload to retry.
+ *
+ * The upload URL is only valid until `session.expiresAt`; very large uploads on
+ * slow connections can exceed that window.
+ */
+declare class UploadSessionExpiredError extends UploadError {
+    constructor(message?: string, cause?: unknown);
+}
+
+/**
+ * Lazily iterate every item across all pages of a cursor-paginated endpoint.
+ * Pass a function that fetches one page for a given cursor; iteration stops when
+ * the API stops returning a `nextCursor`.
+ *
+ * @typeParam T - The item type.
+ * @param fetchPage - Fetches a single page for the given cursor (`undefined` for the first page).
+ *
+ * @example
+ * ```ts
+ * for await (const object of paginate((cursor) =>
+ *   client.applications.storage.objects.list('app-id', 'bucket-id', { cursor }),
+ * )) {
+ *   console.log(object.key);
+ * }
+ * ```
+ */
+declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Paginated<T>>): AsyncGenerator<T>;
+
+/**
+ * Server-Sent Events (SSE) parsing for streamed API responses (e.g. streamed
+ * chat completions). Works in browsers and Node.js 18+ where `Response.body` is
+ * a web `ReadableStream`.
+ *
+ * @internal
+ */
+/**
+ * Parse an SSE stream, yielding each event's `data` payload parsed as JSON.
+ * The `[DONE]` sentinel and empty keep-alive events are skipped; iteration ends
+ * when the underlying stream closes.
+ *
+ * @typeParam T - The shape of each streamed JSON chunk.
+ * @param response - A streaming `fetch` response.
+ */
+declare function parseSSEStream<T = unknown>(response: Response): AsyncGenerator<T>;
+
+export { AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type Application, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, type CreateDeploymentInput, type CreateEnvVarInput, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, type EnvVar, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListQuery, type ListRequestsQuery, type ListStorageObjectsQuery, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, type Organization, OrganizationAiGatewayResource, OrganizationEnvVarsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProviderRouting, type QueryValue, type ResponsesRequest, type ResponsesResponse, type RunUploadOptions, type SetProductionHostnameResult, type SpeechRequest, type StartUploadResult, type StorageBucket, StorageBucketsResource, type StorageObject, type StorageObjectAccess, type StorageObjectList, StorageObjectsResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, type WaitForCompletionOptions, paginate, parseSSEStream };