@tidblink/server 0.0.0-stage → 0.4.0-rc.0

package/dist/events.js

@@ -0,0 +1,110 @@
+import { TiDBLinkError } from "./errors.js";
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isString = (value) => typeof value === "string";
+/** Turn events name their durable event in `data.event`. */
+const TURN_EVENTS = {
+    "agent.session.turn.started": ["turn_started"],
+    "agent.session.turn.output_text.snapshot": ["assistant_draft"],
+    "agent.session.turn.progress": ["progress"],
+    "agent.session.turn.item.added": ["assistant_message", "operation_step"],
+    "agent.session.turn.requires_action": ["client_tool_calls"],
+    "agent.session.turn.completed": ["turn_finished"],
+    "agent.session.turn.cancelled": ["turn_finished"],
+    "agent.session.turn.failed": ["turn_finished", "turn_error"],
+};
+const FINISHED_STATUS = {
+    "agent.session.turn.completed": "succeeded",
+    "agent.session.turn.cancelled": "interrupted",
+    "agent.session.turn.failed": "failed",
+};
+const isTextPayload = (payload) => isString(payload.text);
+/** Whether a `client_tool_calls` payload has the fields the SDK types. */
+export const isClientToolCallsPayload = (payload) => Array.isArray(payload.calls) &&
+    payload.calls.every((call) => isObject(call) &&
+        isString(call.callId) &&
+        isString(call.name) &&
+        isObject(call.arguments) &&
+        isString(call.deadlineAt) &&
+        (call.claimBy === undefined || isString(call.claimBy)));
+const isKnownTurnPayload = (name, payload, type) => {
+    switch (name) {
+        case "progress":
+        case "assistant_draft":
+            return isTextPayload(payload);
+        case "assistant_message":
+            return isTextPayload(payload) && isString(payload.messageId);
+        case "operation_step":
+            return (isString(payload.operationId) &&
+                isString(payload.status) &&
+                isString(payload.label));
+        case "client_tool_calls":
+            return isClientToolCallsPayload(payload);
+        case "turn_finished":
+            return payload.status === FINISHED_STATUS[type];
+        case "turn_error":
+            return isString(payload.code) && isString(payload.message);
+        default:
+            return true;
+    }
+};
+/**
+ * Narrow an event to one of the types the SDK knows. Returns `undefined` for
+ * any other type, and for a known type whose data lacks the fields the SDK
+ * types; such events are still delivered by the stream unchanged.
+ */
+export function asKnownSessionEvent(event) {
+    const { type, data } = event;
+    const turnEvents = TURN_EVENTS[type];
+    if (turnEvents) {
+        if (!isString(event.turnId) ||
+            !isString(data.event) ||
+            !turnEvents.includes(data.event) ||
+            !isObject(data.payload) ||
+            !isKnownTurnPayload(data.event, data.payload, type))
+            return undefined;
+        return event;
+    }
+    if (type === "agent.session.realtime.input_transcript.completed" ||
+        type === "agent.session.realtime.response.completed") {
+        const expected = type === "agent.session.realtime.input_transcript.completed"
+            ? "input_transcript"
+            : "response";
+        return data.type === expected &&
+            isString(data.id) &&
+            isString(data.text) &&
+            isString(data.realtimeConnectionId)
+            ? event
+            : undefined;
+    }
+    if (type === "agent.session.template_switch.succeeded" ||
+        type === "agent.session.template_switch.failed")
+        return isString(data.commandId) &&
+            isString(data.agentTemplateId) &&
+            typeof data.configurationEpoch === "number" &&
+            data.status === type.slice("agent.session.template_switch.".length)
+            ? event
+            : undefined;
+    if (type === "agent.session.idle")
+        return isString(data.id) && (data.turnId === null || isString(data.turnId))
+            ? event
+            : undefined;
+    return undefined;
+}
+/** Check one event envelope and attach its cursor. */
+export function sessionEventFrom(value, cursor, options = {}) {
+    const requestId = options.requestId === undefined ? {} : { requestId: options.requestId };
+    const event = value;
+    if (!isString(cursor) ||
+        !cursor ||
+        !isObject(event) ||
+        !isString(event.type) ||
+        !event.type ||
+        !isString(event.sessionId) ||
+        (options.sessionId !== undefined && event.sessionId !== options.sessionId) ||
+        (event.turnId !== null && !isString(event.turnId)) ||
+        !isString(event.createdAt) ||
+        !isObject(event.data))
+        throw new TiDBLinkError("Session event has an invalid envelope", requestId);
+    return { ...event, cursor };
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/files.d.ts

@@ -0,0 +1,129 @@
+import { HttpClient } from "./http.js";
+import { OutcomeUnknownError } from "./errors.js";
+import type { RequestOptions } from "./organization.js";
+export interface UserFile {
+    fileId: string;
+    originalName: string;
+    status: "uploading" | "ready" | "failed";
+    byteSize: number | null;
+    sha256: string | null;
+    checksumVerification: "whole" | "part_only" | null;
+    contentType: string | null;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+    source: {
+        kind: "user_upload";
+    } | {
+        kind: "artifact_revision";
+        artifactId: string;
+        revisionId: string;
+        revisionNumber: number;
+        sessionId: string;
+        turnId: string | null;
+        operationId: string | null;
+    };
+}
+export interface FileUploadCapabilities {
+    protocol: "tidb-link.user-files.v2";
+    inlineThreshold: number;
+    maxUploadBytes: number;
+    checksum: "sha-256";
+}
+export interface CreateFileUploadInput extends RequestOptions {
+    idempotencyKey: string;
+    originalName: string;
+    byteSize: number;
+    sha256: string;
+    contentType: string | null;
+}
+export interface UploadFileInput extends RequestOptions {
+    /** Persist with the original input before upload; reuse only for that exact file. */
+    idempotencyKey: string;
+    originalName: string;
+    bytes: Uint8Array;
+    contentType?: string | null;
+}
+export interface FileUpload {
+    uploadId: string;
+    file: UserFile;
+    mode: "tidb-link" | "s3";
+    expectedChecksumVerification: "whole";
+    expiresAt: string;
+    contentUrl?: string;
+    uploadUrl?: {
+        method: "PUT";
+        url: string;
+        headers: Record<string, string>;
+        expiresAt: string;
+    };
+    partSize?: number;
+    totalParts?: number;
+}
+export interface FileUploadStatus {
+    uploadId: string;
+    file: UserFile;
+    mode: "tidb-link" | "s3" | "initializing";
+    state: "active" | "completing" | "aborting" | "completed" | "aborted";
+    expiresAt: string;
+}
+export interface FileUploadPart {
+    number: number;
+    url: string;
+    size: number;
+    headers: Record<string, string>;
+    expiresAt: string;
+}
+export interface FileListOptions extends RequestOptions {
+    history?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+export interface FilePage {
+    files: UserFile[];
+    nextCursor: string | null;
+}
+export interface FileDownloadGrant {
+    url: string;
+    expiresAt: string;
+    byteSize: number;
+    sha256: string;
+}
+export type FileContent = {
+    type: "bytes";
+    bytes: Uint8Array;
+    contentType: string;
+} | {
+    type: "download";
+    grant: FileDownloadGrant;
+};
+export interface UploadedFilePart {
+    number: number;
+    etag: string;
+    sha256: string;
+}
+export declare class FileUploadOutcomeUnknownError extends OutcomeUnknownError {
+    readonly idempotencyKey: string;
+    readonly uploadId: string | undefined;
+    constructor(idempotencyKey: string, uploadId: string | undefined, cause: OutcomeUnknownError);
+}
+export declare class UserFiles {
+    #private;
+    constructor(http: HttpClient);
+    capabilities(options?: RequestOptions): Promise<FileUploadCapabilities>;
+    createUpload(input: CreateFileUploadInput): Promise<FileUpload>;
+    getUpload(uploadId: string, options?: RequestOptions): Promise<FileUploadStatus>;
+    uploadContent(uploadId: string, bytes: Uint8Array, options?: RequestOptions): Promise<UserFile>;
+    presignPart(uploadId: string, number: number, sha256: string, options?: RequestOptions): Promise<FileUploadPart>;
+    uploadPart(part: FileUploadPart, bytes: Uint8Array, options?: RequestOptions): Promise<UploadedFilePart>;
+    private transfer;
+    completeUpload(uploadId: string, parts?: UploadedFilePart[], options?: RequestOptions): Promise<UserFile>;
+    cancelUpload(uploadId: string, options?: RequestOptions): Promise<UserFile>;
+    upload(input: UploadFileInput): Promise<UserFile>;
+    list(options?: FileListOptions): Promise<FilePage>;
+    get(fileId: string, options?: RequestOptions): Promise<UserFile>;
+    getContent(fileId: string, options?: RequestOptions): Promise<FileContent>;
+    downloadFromGrant(grant: FileDownloadGrant, options?: RequestOptions): Promise<Uint8Array>;
+    download(fileId: string, options?: RequestOptions): Promise<Uint8Array>;
+}
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"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"}

package/dist/files.js

@@ -0,0 +1,388 @@
+import { requestOptions, HttpClient, requireKnownKeys } from "./http.js";
+import { OutcomeUnknownError, TiDBLinkError, TiDBLinkApiError, ConnectionError, } from "./errors.js";
+export class FileUploadOutcomeUnknownError extends OutcomeUnknownError {
+    idempotencyKey;
+    uploadId;
+    constructor(idempotencyKey, uploadId, cause) {
+        super("File upload outcome is unknown; recover the original upload before transferring again", { ...(cause.requestId ? { requestId: cause.requestId } : {}), cause });
+        this.idempotencyKey = idempotencyKey;
+        this.uploadId = uploadId;
+    }
+}
+const uploadPath = (id) => `/drive/uploads/${encodeURIComponent(id)}`;
+const digest = async (bytes) => {
+    const value = new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes)));
+    return {
+        hex: Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join(""),
+        base64: btoa(String.fromCharCode(...value)),
+    };
+};
+const fileReceipt = (value, requestId) => {
+    if (!value?.file?.fileId ||
+        !["uploading", "ready", "failed"].includes(value.file.status)) {
+        throw new OutcomeUnknownError("File operation returned no usable File; read the upload state", { requestId });
+    }
+    return value.file;
+};
+const requireReady = (file, byteSize, sha256) => {
+    if (file.status !== "ready" ||
+        file.byteSize !== byteSize ||
+        file.sha256 !== sha256 ||
+        file.checksumVerification !== "whole") {
+        throw new TiDBLinkError("File is not ready with the expected complete size and checksum");
+    }
+    return file;
+};
+const requireActiveGrant = (expiresAt) => {
+    if (!Number.isFinite(Date.parse(expiresAt)) ||
+        Date.parse(expiresAt) <= Date.now())
+        throw new TiDBLinkApiError({
+            status: 410,
+            code: "file_transfer_expired",
+            message: "File transfer credential expired; obtain a fresh credential for the original file",
+        });
+};
+const transferUrl = (url) => {
+    if (!["http:", "https:"].includes(url.protocol) ||
+        url.username ||
+        url.password ||
+        url.hash)
+        throw new TypeError("File transfer URL must be HTTP(S) without embedded credentials or a fragment");
+    return url;
+};
+export class UserFiles {
+    #http;
+    constructor(http) {
+        this.#http = http;
+    }
+    async capabilities(options) {
+        options = requestOptions(options);
+        return (await this.#http.get("/drive/upload-capabilities", options)).capabilities;
+    }
+    async createUpload(input) {
+        requireKnownKeys(input, [
+            "idempotencyKey",
+            "originalName",
+            "byteSize",
+            "sha256",
+            "contentType",
+            "signal",
+            "requestId",
+        ], "File upload");
+        if (typeof input.idempotencyKey !== "string" ||
+            !/^[\x21-\x7e]{1,255}$/.test(input.idempotencyKey))
+            throw new TypeError("File upload requires a stable idempotencyKey (1-255 visible ASCII characters)");
+        if (typeof input.originalName !== "string" ||
+            !input.originalName ||
+            input.originalName.length > 255 ||
+            !Number.isSafeInteger(input.byteSize) ||
+            input.byteSize < 0 ||
+            !/^[a-f0-9]{64}$/.test(input.sha256) ||
+            !(input.contentType === null ||
+                (typeof input.contentType === "string" &&
+                    input.contentType.length <= 255)))
+            throw new TypeError("File upload requires a name, nonnegative byteSize, complete SHA-256 and nullable contentType");
+        const { idempotencyKey, signal, requestId, ...body } = input;
+        const result = await this.#http.postResponse("/drive/uploads", body, {
+            idempotencyKey,
+            outcomeUnknown: true,
+            ...(signal ? { signal } : {}),
+            ...(requestId ? { requestId } : {}),
+        });
+        const upload = result.data?.upload;
+        if (!upload?.uploadId ||
+            upload.file?.fileId !== upload.uploadId ||
+            !["tidb-link", "s3"].includes(upload.mode) ||
+            !Number.isFinite(Date.parse(upload.expiresAt)) ||
+            upload.expectedChecksumVerification !== "whole")
+            throw new OutcomeUnknownError("File creation returned no usable upload; replay the same creation identity", { requestId: result.requestId });
+        return upload;
+    }
+    async getUpload(uploadId, options) {
+        options = requestOptions(options);
+        return (await this.#http.get(uploadPath(uploadId), options)).upload;
+    }
+    async uploadContent(uploadId, bytes, options) {
+        options = requestOptions(options);
+        const checksum = await digest(bytes);
+        const { response, requestId } = await this.#http.rawResponse(`${uploadPath(uploadId)}/content`, {
+            ...options,
+            method: "PUT",
+            body: Uint8Array.from(bytes),
+            headers: {
+                "content-type": "application/octet-stream",
+                "content-length": String(bytes.byteLength),
+                "content-digest": `sha-256=:${checksum.base64}:`,
+            },
+            outcomeUnknown: true,
+        });
+        try {
+            return fileReceipt(await response.json(), requestId);
+        }
+        catch (cause) {
+            if (cause instanceof OutcomeUnknownError)
+                throw cause;
+            throw new OutcomeUnknownError("Inline transfer returned no usable File; read the upload state", { requestId, cause });
+        }
+    }
+    async presignPart(uploadId, number, sha256, options) {
+        options = requestOptions(options);
+        if (!Number.isSafeInteger(number) ||
+            number < 1 ||
+            !/^[a-f0-9]{64}$/.test(sha256))
+            throw new TypeError("A part requires a positive number and SHA-256");
+        const result = await this.#http.postResponse(`${uploadPath(uploadId)}/parts/${number}/presign`, { sha256 }, { ...options, outcomeUnknown: true });
+        const part = result.data?.part;
+        if (part?.number !== number ||
+            !Number.isSafeInteger(part.size) ||
+            part.size < 0 ||
+            !part.url ||
+            !part.headers ||
+            !Number.isFinite(Date.parse(part.expiresAt)))
+            throw new OutcomeUnknownError("Part signing returned no usable grant; reconcile before transferring", { requestId: result.requestId });
+        return part;
+    }
+    async uploadPart(part, bytes, options) {
+        options = requestOptions(options);
+        if (bytes.byteLength !== part.size)
+            throw new TypeError("Part bytes do not match the signed size");
+        const checksum = await digest(bytes);
+        const signedChecksum = new Headers(part.headers).get("x-amz-checksum-sha256");
+        if (signedChecksum !== checksum.base64)
+            throw new TypeError("Part bytes do not match the signed checksum");
+        const response = await this.transfer(part.url, part.expiresAt, {
+            method: "PUT",
+            headers: { ...part.headers, "content-length": String(bytes.byteLength) },
+            body: Uint8Array.from(bytes),
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+        const etag = response.headers.get("etag");
+        await response.body?.cancel();
+        if (!etag)
+            throw new OutcomeUnknownError("Part transfer returned no ETag; reconcile before completing");
+        return { number: part.number, etag, sha256: checksum.hex };
+    }
+    async transfer(url, expiresAt, init) {
+        requireActiveGrant(expiresAt);
+        const destination = transferUrl(this.#http.resolveUrl(url));
+        init.signal?.throwIfAborted();
+        let response;
+        try {
+            response = await this.#http.fetch(destination, { ...init, redirect: "error" });
+        }
+        catch {
+            throw new OutcomeUnknownError("File transfer outcome is unknown; inspect the original upload");
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            if (response.status >= 500 || response.status === 408)
+                throw new OutcomeUnknownError("File transfer outcome is unknown; inspect the original upload");
+            throw new TiDBLinkApiError({
+                status: response.status,
+                code: "file_transfer_failed",
+                message: "File byte transfer was refused",
+            });
+        }
+        return response;
+    }
+    async completeUpload(uploadId, parts, options) {
+        options = requestOptions(options);
+        const result = await this.#http.postResponse(`${uploadPath(uploadId)}/complete`, parts === undefined ? {} : { parts }, { ...options, outcomeUnknown: true });
+        return fileReceipt(result.data, result.requestId);
+    }
+    async cancelUpload(uploadId, options) {
+        options = requestOptions(options);
+        const result = await this.#http.deleteResponse(uploadPath(uploadId), { ...options, outcomeUnknown: true });
+        return fileReceipt(result.data, result.requestId);
+    }
+    async upload(input) {
+        requireKnownKeys(input, [
+            "idempotencyKey",
+            "originalName",
+            "bytes",
+            "contentType",
+            "signal",
+            "requestId",
+        ], "File upload");
+        if (!(input.bytes instanceof Uint8Array))
+            throw new TypeError("File bytes must be a Uint8Array");
+        const { bytes: source, ...metadata } = input;
+        const bytes = Uint8Array.from(source);
+        const checksum = await digest(bytes);
+        const options = {
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.requestId ? { requestId: input.requestId } : {}),
+        };
+        let uploadId;
+        try {
+            const upload = await this.createUpload({
+                ...metadata,
+                contentType: input.contentType ?? null,
+                byteSize: bytes.byteLength,
+                sha256: checksum.hex,
+            });
+            uploadId = upload.uploadId;
+            if (upload.file.status === "ready")
+                return requireReady(upload.file, bytes.byteLength, checksum.hex);
+            requireActiveGrant(upload.expiresAt);
+            let parts;
+            if (upload.mode === "tidb-link") {
+                if (upload.uploadUrl) {
+                    const grant = upload.uploadUrl;
+                    if (grant.method !== "PUT" ||
+                        new Headers(grant.headers).get("content-digest") !==
+                            `sha-256=:${checksum.base64}:`)
+                        throw new TiDBLinkError("Inline upload grant does not match the complete file checksum");
+                    const response = await this.transfer(grant.url, grant.expiresAt, {
+                        method: "PUT",
+                        headers: {
+                            ...grant.headers,
+                            "content-length": String(bytes.byteLength),
+                        },
+                        body: bytes,
+                        ...(input.signal ? { signal: input.signal } : {}),
+                    });
+                    await response.body?.cancel();
+                }
+                else
+                    await this.uploadContent(uploadId, bytes, options);
+            }
+            else {
+                const { partSize, totalParts } = upload;
+                if (!partSize ||
+                    !Number.isSafeInteger(partSize) ||
+                    !Number.isSafeInteger(totalParts) ||
+                    totalParts !== Math.ceil(bytes.byteLength / partSize))
+                    throw new TiDBLinkError("Multipart upload plan does not cover the complete file");
+                parts = [];
+                for (let number = 1; number <= totalParts; number++) {
+                    const partBytes = bytes.subarray((number - 1) * partSize, number * partSize);
+                    const part = await this.presignPart(uploadId, number, (await digest(partBytes)).hex, options);
+                    parts.push(await this.uploadPart(part, partBytes, options));
+                }
+            }
+            return requireReady(await this.completeUpload(uploadId, parts, options), bytes.byteLength, checksum.hex);
+        }
+        catch (cause) {
+            if (cause instanceof OutcomeUnknownError)
+                throw new FileUploadOutcomeUnknownError(metadata.idempotencyKey, uploadId, cause);
+            throw cause;
+        }
+    }
+    list(options = {}) {
+        requireKnownKeys(options, ["history", "limit", "cursor", "signal", "requestId"], "File list options");
+        const query = new URLSearchParams();
+        if (options.history !== undefined)
+            query.set("history", String(options.history));
+        if (options.limit !== undefined)
+            query.set("limit", String(options.limit));
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        return this.#http.get(`/files${query.size ? `?${query}` : ""}`, options);
+    }
+    async get(fileId, options) {
+        options = requestOptions(options);
+        return (await this.#http.get(`/files/${encodeURIComponent(fileId)}`, options)).file;
+    }
+    async getContent(fileId, options) {
+        options = requestOptions(options);
+        const { response, requestId } = await this.#http.rawResponse(`/files/${encodeURIComponent(fileId)}/content`, options);
+        const contentType = response.headers.get("content-type") ?? "application/octet-stream";
+        try {
+            if (contentType.split(";")[0]?.trim().toLowerCase() ===
+                "application/vnd.tidb-link.file-download+json") {
+                const grant = await response.json();
+                if (!grant?.url ||
+                    !Number.isSafeInteger(grant.byteSize) ||
+                    grant.byteSize < 0 ||
+                    !/^[a-f0-9]{64}$/.test(grant.sha256) ||
+                    !Number.isFinite(Date.parse(grant.expiresAt)))
+                    throw new TiDBLinkError("File content returned no usable download grant", { requestId });
+                return { type: "download", grant };
+            }
+            return {
+                type: "bytes",
+                bytes: new Uint8Array(await response.arrayBuffer()),
+                contentType,
+            };
+        }
+        catch (cause) {
+            if (cause instanceof TiDBLinkError)
+                throw cause;
+            throw new ConnectionError("File content could not be read completely", {
+                requestId,
+            });
+        }
+    }
+    async downloadFromGrant(grant, options) {
+        options = requestOptions(options);
+        requireActiveGrant(grant.expiresAt);
+        let destination = transferUrl(this.#http.resolveUrl(grant.url));
+        options?.signal?.throwIfAborted();
+        let response;
+        try {
+            response = await this.#http.fetch(destination, {
+                redirect: "manual",
+                ...(options?.signal ? { signal: options.signal } : {}),
+            });
+            if ([301, 302, 303, 307, 308].includes(response.status)) {
+                const location = response.headers.get("location");
+                await response.body?.cancel();
+                if (!location)
+                    throw new TiDBLinkError("File download redirect omitted its destination");
+                destination = transferUrl(new URL(location, destination));
+                if (destination.protocol !== "https:")
+                    throw new TiDBLinkError("File download redirect requires HTTPS");
+                response = await this.#http.fetch(destination, {
+                    redirect: "error",
+                    ...(options?.signal ? { signal: options.signal } : {}),
+                });
+            }
+        }
+        catch (cause) {
+            if (cause instanceof TiDBLinkError)
+                throw cause;
+            throw new ConnectionError("File download could not be reached");
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new TiDBLinkApiError({
+                status: response.status,
+                code: "file_download_failed",
+                message: "File download was refused; obtain a fresh credential if it expired",
+            });
+        }
+        let bytes;
+        try {
+            bytes = new Uint8Array(await response.arrayBuffer());
+        }
+        catch {
+            throw new ConnectionError("File download ended before the complete body arrived");
+        }
+        if (bytes.byteLength !== grant.byteSize ||
+            (await digest(bytes)).hex !== grant.sha256)
+            throw new TiDBLinkError("Downloaded file does not match its complete size and checksum");
+        return bytes;
+    }
+    async download(fileId, options) {
+        options = requestOptions(options);
+        const file = await this.get(fileId, options);
+        if (file.status !== "ready" ||
+            file.byteSize === null ||
+            file.sha256 === null ||
+            file.checksumVerification !== "whole")
+            throw new TiDBLinkError("Only a ready, whole-file verified File can be downloaded");
+        const content = await this.getContent(fileId, options);
+        if (content.type === "download") {
+            if (content.grant.byteSize !== file.byteSize ||
+                content.grant.sha256 !== file.sha256)
+                throw new TiDBLinkError("Download grant does not match the selected File");
+            return this.downloadFromGrant(content.grant, options);
+        }
+        if (content.bytes.byteLength !== file.byteSize ||
+            (await digest(content.bytes)).hex !== file.sha256)
+            throw new TiDBLinkError("Downloaded file does not match its complete size and checksum");
+        return content.bytes;
+    }
+}
+//# sourceMappingURL=files.js.map