/**
 * `blobs` namespace — direct-to-S3 blob storage.
 *
 * `put` encapsulates the 3-step upload flow (init → PUT parts to S3 →
 * complete). The S3 PUT uses `client.fetch` directly (not the gateway's
 * `request`) so it bypasses gateway auth and path-rewriting. The client's
 * configured fetch still flows through any wrappers (e.g. test mocks).
 */
import type { Client } from "../kernel.js";
import type { BlobDiagnoseEnvelope, BlobLsOptions, BlobLsResult, BlobPutOptions, BlobPutResult, BlobPutSource, BlobSignOptions, BlobSignResult, BlobWaitFreshOptions, BlobWaitFreshResult } from "./assets.types.js";
export declare class Assets {
    private readonly client;
    constructor(client: Client);
    /**
     * Upload a blob via the 3-step direct-to-S3 flow. The bytes are PUT to
     * presigned S3 URLs — they do NOT pass through the gateway, so uploads
     * are not double-billed as API calls and large files stream efficiently.
     *
     * Pass `immutable: true` to produce a content-addressed URL. The SDK always
     * computes the SHA-256 digest required by the upload API; `immutable` only
     * controls URL/cache semantics.
     *
     * @throws {ProjectNotFound} if `projectId` is not in the provider.
     */
    put(projectId: string, key: string, source: BlobPutSource, opts?: BlobPutOptions): Promise<BlobPutResult>;
    /**
     * Diagnose a public blob URL. Returns a JSON envelope describing the live
     * CDN state (expected vs observed SHA, cache headers, recent invalidation
     * status, vantage). The gateway probes the URL once from us-east-1 with
     * `Range: bytes=0-0` and returns within 5 s even if the inner probe is
     * slow.
     *
     * **Vantage caveat:** the result reflects ONE CloudFront PoP at the time
     * of the call. Other PoPs may serve different cached states. The
     * `probeMayHaveWarmedCache: true` field reminds the agent that the probe
     * itself populates the cache, so a subsequent read may differ.
     *
     * The URL must belong to the requesting project — cross-project URLs are
     * rejected by the gateway with `403`. SSRF is enforced gateway-side: only
     * `*.run402.com` and the project's active custom domains are accepted.
     *
     * @example
     *   const diag = await client.blobs.diagnoseUrl("prj_abc", "https://app.run402.com/_blob/avatar.png");
     *   if (diag.observedSha256 !== diag.expectedSha256) console.log(diag.hint);
     */
    diagnoseUrl(projectId: string, url: string): Promise<BlobDiagnoseEnvelope>;
    /**
     * Poll the CDN until a mutable URL serves the expected SHA-256, or the
     * timeout elapses. **For mutable URLs only** — for immutable URLs (the
     * `immutableUrl` returned by `put`) no waiting is needed; they're bound
     * at upload time and never previously cached.
     *
     * Default `timeoutMs` is 60_000 (60 s). The helper polls the gateway's
     * diagnose endpoint with exponential backoff bounded by 1 s; each poll
     * may itself warm the cache for the probed PoP, so subsequent reads from
     * other PoPs may still be stale until invalidation propagation completes.
     *
     * @example
     *   await client.blobs.waitFresh("prj_abc", {
     *     url: result.url,           // the mutable URL from blobs.put
     *     sha256: result.contentSha256,
     *     timeoutMs: 30_000,
     *   });
     */
    waitFresh(projectId: string, opts: BlobWaitFreshOptions): Promise<BlobWaitFreshResult>;
    /**
     * Download a blob. Returns the raw `Response` so callers can stream to
     * disk, pipe to another sink, or buffer with `.bytes()` / `.arrayBuffer()`.
     * This avoids forcing large blobs through a JS buffer.
     *
     * @throws {ProjectNotFound} if `projectId` is not in the provider.
     * @throws {ApiError} on non-2xx (includes the error text from the response body).
     */
    get(projectId: string, key: string): Promise<Response>;
    /** List blobs with optional prefix + pagination + (v1.50) sort + filter.
     *  Unknown filter keys, invalid sort values, and other structural issues
     *  are rejected client-side BEFORE any HTTP call. */
    ls(projectId: string, opts?: BlobLsOptions): Promise<BlobLsResult>;
    /** Delete a blob and decrement the project's storage_bytes. */
    rm(projectId: string, key: string): Promise<void>;
    /** Generate a time-boxed S3 presigned GET URL for a blob. Default TTL 1 hour, max 7 days. */
    sign(projectId: string, key: string, opts?: BlobSignOptions): Promise<BlobSignResult>;
}
//# sourceMappingURL=assets.d.ts.map