import { AttachmentPolicy } from "../contracts/attachment-policy.type.mjs";
import { Attachment } from "../contracts/attachment.type.mjs";
import { ContentPart } from "../contracts/content-part.type.mjs";

//#region ../ai/src/utils/prepare-attachment-part.d.ts
/**
 * Convert a user-supplied `Attachment` into a provider-ready
 * `ContentPart` the model adapter can consume without doing any I/O of
 * its own.
 *
 * Kind resolution:
 * - Tagged `{ type: "image", source }` / `{ type: "text", source }`
 *   trusts the caller's intent.
 * - Shorthand (raw string / `StorageFileShape`) infers from the file
 *   extension. Image extensions (`.png`/`.jpg`/`.jpeg`/`.webp`/`.gif`)
 *   map to `"image"`. `.txt` maps to `"text"`. Anything else throws
 *   `InvalidRequestError` — silent inference on ambiguous inputs
 *   causes silent bugs.
 *
 * Local paths are read from disk; images are base64-encoded inline,
 * text files are read as UTF-8 strings and returned as a `text`
 * `ContentPart`. Remote URLs for image attachments are passed through
 * unchanged; remote URLs for text attachments are fetched so the
 * adapter never needs network access.
 *
 * @example
 * await prepareAttachmentPart("./photo.png");
 * // → { type: "image", source: { base64: "...", mediaType: "image/png" } }
 *
 * @example
 * await prepareAttachmentPart({ type: "text", source: "./notes.txt" });
 * // → { type: "text", text: "<file contents>" }
 *
 * **Trust boundary (S1).** Attachment references are often user-controlled,
 * so server-side I/O is policy-gated by `policy` ({@link AttachmentPolicy}):
 * remote text fetches are default-deny and, when enabled, run through the
 * shared `OutboundPolicy` (scheme/host/private-IP/max-bytes/timeout); local
 * reads honor an `allowedRoots` sandbox; bare-string local paths warn
 * (staged deprecation). URL *image* attachments are passed to the provider
 * untouched (never fetched here).
 */
declare function prepareAttachmentPart(attachment: Attachment, policy?: AttachmentPolicy): Promise<ContentPart>;
//#endregion
export { prepareAttachmentPart };
//# sourceMappingURL=prepare-attachment-part.d.mts.map