@spec from_base64(String.t(), String.t()) :: t()

Build an %Image{} from a base64-encoded string plus an explicit MIME type.

Pure data — does NOT validate that encoded is well-formed base64. Standard base64 with padding is the documented contract; URL-safe base64 (-/_) or unpadded variants may produce a struct whose to_data_uri/1 fast-path emits a data: URI a downstream consumer rejects. mime_type: nil raises FunctionClauseError.

Examples

iex> img = ALLM.Image.from_base64("aGk=", "image/png")
iex> img.source
{:base64, "aGk="}
iex> img.mime_type
"image/png"

@spec from_binary(binary(), String.t()) :: t()

Build an %Image{} from raw bytes plus an explicit MIME type.

Both arguments are required and must be binaries — mime_type: nil raises FunctionClauseError (the is_binary(mime_type) runtime guard backs the @spec so callers don't get silently-nil-mime structs).

Examples

iex> img = ALLM.Image.from_binary(<<137, 80>>, "image/png")
iex> img.source
{:binary, <<137, 80>>}
iex> img.mime_type
"image/png"

@spec from_file(Path.t()) :: t()

Build an %Image{} from a local filesystem path.

Pure data — does NOT call File.read/1. The path is stored verbatim and the filesystem is only touched at to_binary/1 / to_data_uri/1 time. The :mime_type is inferred from the lowercased extension against the closed set [".png", ".jpg", ".jpeg", ".webp", ".gif"]; unknown or missing extensions leave :mime_type as nil.

Examples

iex> img = ALLM.Image.from_file("/tmp/cat.png")
iex> img.source
{:file, "/tmp/cat.png"}
iex> img.mime_type
"image/png"

iex> ALLM.Image.from_file("/tmp/noext").mime_type
nil

@spec from_url(String.t()) :: t()

Build an %Image{} from a URL string.

Pure data — does NOT inspect or fetch the URL. The :mime_type is nil; the adapter that consumes the image resolves the type at request-build time. URL fetching is banned in Layer A (Decision #2 / phasing principle #8).

Examples

iex> img = ALLM.Image.from_url("https://example.com/x.png")
iex> img.source
{:url, "https://example.com/x.png"}
iex> img.mime_type
nil

@spec to_binary(t()) ::
  {:ok, binary()} | {:error, :remote_source | :invalid_base64 | File.posix()}

Resolve the image's :source to raw bytes.

• {:binary, b} returns {:ok, b} verbatim.
• {:base64, s} decodes via Base.decode64/1; invalid base64 returns {:error, :invalid_base64}.
• {:url, _} returns {:error, :remote_source} — Layer A NEVER fetches URLs (Decision #2). Adapters fetch at request-build time.
• {:file, path} reads the file via File.read/1 and returns its {:ok, _} | {:error, posix()} shape directly (:enoent on missing, etc.).

Examples

iex> ALLM.Image.to_binary(ALLM.Image.from_binary(<<1, 2>>, "image/png"))
{:ok, <<1, 2>>}

iex> ALLM.Image.to_binary(ALLM.Image.from_base64("aGVsbG8=", "image/png"))
{:ok, "hello"}

iex> ALLM.Image.to_binary(ALLM.Image.from_url("https://example.com/x.png"))
{:error, :remote_source}

@spec to_data_uri(t()) ::
  {:ok, String.t()}
  | {:error,
     :remote_source | :missing_mime_type | :invalid_base64 | File.posix()}

Resolve the image to a data:<mime>;base64,<...> URI.

• {:binary, b} with a :mime_type Base64-encodes the bytes.
• {:base64, s} with a :mime_type forwards s verbatim — fast path, no decode-then-re-encode.
• {:file, path} with a :mime_type reads + Base64-encodes.
• {:url, _} returns {:error, :remote_source} (Decision #6) — a data: URI and an https: URI are different addressing schemes; passing the URL through verbatim would surprise.
• Missing :mime_type returns {:error, :missing_mime_type} — there is no default like application/octet-stream.

Examples

iex> ALLM.Image.to_data_uri(ALLM.Image.from_binary("hi", "image/png"))
{:ok, "data:image/png;base64,aGk="}

iex> ALLM.Image.to_data_uri(ALLM.Image.from_base64("aGk=", "image/png"))
{:ok, "data:image/png;base64,aGk="}

iex> ALLM.Image.to_data_uri(ALLM.Image.from_url("https://example.com/x.png"))
{:error, :remote_source}