adloop 0.32.0__tar.gz → 0.33.0__tar.gz

{adloop-0.32.0 → adloop-0.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: adloop
-Version: 0.32.0
+Version: 0.33.0
 Summary: The AI command center for Google Ads, Reddit Ads, GA4, and tracking code.
 Keywords: mcp,google-ads,reddit-ads,google-analytics,ga4,cursor,marketing
 Author: Daniel Klose

{adloop-0.32.0 → adloop-0.33.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.32.0"
+version = "0.33.0"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 requires-python = ">=3.11"

{adloop-0.32.0 → adloop-0.33.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "adloop"
-version = "0.32.0"
+version = "0.33.0"
 description = "The AI command center for Google Ads, Reddit Ads, GA4, and tracking code."
 readme = "README.md"
 authors = [

{adloop-0.32.0 → adloop-0.33.0}/src/adloop/ads/conversion_actions.py

@@ -25,6 +25,7 @@ import hashlib
 import math
 import re
 import threading
+from dataclasses import dataclass
 from datetime import datetime, timezone as _tz
 from typing import TYPE_CHECKING, Callable
 
@@ -1009,8 +1010,16 @@ _CSV_COMMENT_PREFIX = "#"
 _MAX_CSV_BYTES = 5 * 1024 * 1024
 
 
+@dataclass(frozen=True)
+class UploadedCsv:
+    """A conversion CSV that arrived as an upload instead of a local path."""
+
+    name: str
+    data: bytes
+
+
 def _read_upload_csv(
-    csv_path: str,
+    csv_path: "str | UploadedCsv",
 ) -> tuple[list[tuple[int, list[str]]], list[str], str]:
     """Read an upload CSV into ``(source_line, cells)`` records (header first).
 
@@ -1020,8 +1029,9 @@ def _read_upload_csv(
     Counting records instead would drift as soon as a comment or a bad row is
     dropped.
 
-    Local-only by design: the path is read from the machine running AdLoop, so
-    the tool refuses in server mode before it gets here. Errors name the file
+    ``csv_path`` is a path on the machine running AdLoop (refused in server
+    mode before it gets here) or an :class:`UploadedCsv` from the upload
+    store, which a hosted server reads instead. Errors name the file
     and the schema, never file *content* — a hosted runtime can read files the
     caller is not allowed to see.
     """
@@ -1036,15 +1046,21 @@ def _read_upload_csv(
     # which is what timestamps without an offset are resolved against.
     timezone = ""
 
-    path = Path(csv_path).expanduser()
-    if not path.is_file():
-        return [], [f"CSV not found or not a regular file: {path}"], ""
-    if path.suffix.lower() != ".csv":
-        return [], [f"CSV must be a .csv file, got: {path.name}"], ""
-    try:
-        size = path.stat().st_size
-    except OSError as exc:
-        return [], [f"CSV could not be read: {exc.strerror or exc}"], ""
+    import io
+
+    if isinstance(csv_path, UploadedCsv):
+        path = None
+        size = len(csv_path.data)
+    else:
+        path = Path(csv_path).expanduser()
+        if not path.is_file():
+            return [], [f"CSV not found or not a regular file: {path}"], ""
+        if path.suffix.lower() != ".csv":
+            return [], [f"CSV must be a .csv file, got: {path.name}"], ""
+        try:
+            size = path.stat().st_size
+        except OSError as exc:
+            return [], [f"CSV could not be read: {exc.strerror or exc}"], ""
     if size > _MAX_CSV_BYTES:
         return [], [
             f"CSV is {size / 1_048_576:.1f} MB; the limit is "
@@ -1053,7 +1069,11 @@ def _read_upload_csv(
         ], ""
 
     try:
-        with path.open("r", newline="", encoding="utf-8-sig") as handle:
+        with (
+            io.StringIO(csv_path.data.decode("utf-8-sig"), newline="")
+            if path is None
+            else path.open("r", newline="", encoding="utf-8-sig")
+        ) as handle:
             position = {"line": 0}
 
             def _lines():
@@ -1164,7 +1184,7 @@ def _pad_to_header(raw: list[str], columns: int) -> list[str]:
 
 
 def _parse_call_conversion_csv(
-    csv_path: str, default_region: str = ""
+    csv_path: "str | UploadedCsv", default_region: str = ""
 ) -> tuple[list[dict], list[str], list[str], list[dict]]:
     """Read the call-conversions CSV (local file) and normalize each row.
 
@@ -1310,7 +1330,8 @@ def draft_upload_call_conversions(
     config: AdLoopConfig,
     *,
     customer_id: str = "",
-    csv_path: str,
+    csv_path: str = "",
+    upload_id: str = "",
     default_region: str = "",
     consent: dict | None = None,
 ) -> dict:
@@ -1353,12 +1374,17 @@ def draft_upload_call_conversions(
         operation="upload_call_conversions",
         default_region=default_region,
         consent=consent,
+        csv_path=csv_path,
+        upload_id=upload_id,
     )
+    if error:
+        return error
+    source, error = _csv_source(csv_path, upload_id)
     if error:
         return error
 
     rows, parse_advisories, skipped, error = _upload_parse_result(
-        *_parse_call_conversion_csv(csv_path, default_region),
+        *_parse_call_conversion_csv(source, default_region),
         empty_message="CSV contained zero conversion rows",
     )
     if error:
@@ -1493,7 +1519,7 @@ def draft_upload_call_conversions(
         apply_only_payload={"rows": frozen_rows},
     )
     store_plan(plan)
-    return plan.to_preview()
+    return _consume_upload(plan.to_preview(), upload_id)
 
 
 def _resolve_upload_action(
@@ -1714,6 +1740,8 @@ def _upload_draft_preflight(
     operation: str,
     default_region: str,
     consent: dict | None,
+    csv_path: str = "",
+    upload_id: str = "",
 ) -> tuple[str, dict | None, dict | None]:
     """The guards both upload drafts run before they touch the CSV.
 
@@ -1724,12 +1752,19 @@ def _upload_draft_preflight(
     from adloop.runtime import deployment_mode
     from adloop.safety.guards import SafetyViolation, check_blocked_operation
 
-    if deployment_mode() == "server":
+    if bool(csv_path) == bool(upload_id):
+        return "", None, {
+            "error": (
+                "Pass exactly one of csv_path (a file on the machine running "
+                "AdLoop) or upload_id (a CSV uploaded with upload_conversion_csv)."
+            )
+        }
+    if csv_path and deployment_mode() == "server":
         return "", None, {
             "error": (
-                "This tool uploads conversions from a CSV file on the machine "
-                "running AdLoop and is not available on the hosted server. "
-                "Use the self-hosted AdLoop MCP server for conversion uploads."
+                "csv_path names a file on the machine running AdLoop, which on "
+                "the hosted server is not yours. Upload the CSV with "
+                "upload_conversion_csv and pass its upload_id instead."
             )
         }
 
@@ -1754,6 +1789,37 @@ def _upload_draft_preflight(
     return region, consent_norm, None
 
 
+def _csv_source(csv_path: str, upload_id: str) -> "tuple[str | UploadedCsv | None, dict | None]":
+    """The CSV to parse: the local path, or the uploaded file's bytes."""
+    if not upload_id:
+        return csv_path, None
+    from adloop.uploads import UploadError, current_tenant, get_upload_store
+
+    try:
+        upload, data = get_upload_store().get(current_tenant(), upload_id, kind="csv")
+    except UploadError as exc:
+        return None, {"error": f"{exc}. Upload the CSV again with upload_conversion_csv."}
+    return UploadedCsv(name=upload.name, data=data), None
+
+
+def _consume_upload(preview: dict, upload_id: str) -> dict:
+    """Delete an uploaded CSV once its plan holds the rows.
+
+    The plan carries everything apply needs, so the raw file (phone numbers,
+    emails) has no reason to stay. A draft that failed keeps the file, so a
+    retry with another default_region needs no new upload.
+    """
+    if upload_id:
+        from adloop.uploads import current_tenant, get_upload_store
+
+        get_upload_store().delete(current_tenant(), upload_id)
+        preview["source_upload"] = (
+            f"{upload_id} was read and deleted; the plan holds the rows. A new "
+            "draft needs a new upload."
+        )
+    return preview
+
+
 def _upload_parse_result(
     rows: list[dict],
     errors: list[str],
@@ -2262,7 +2328,7 @@ _OPTIONAL_EC_HEADERS = [
 
 
 def _parse_ec_for_leads_csv(
-    csv_path: str, default_region: str = ""
+    csv_path: "str | UploadedCsv", default_region: str = ""
 ) -> tuple[list[dict], list[str], list[str], list[dict]]:
     """Parse the EC-for-Leads CSV (local file) and hash PII at parse time.
 
@@ -2463,7 +2529,8 @@ def draft_upload_enhanced_conversions_for_leads(
     config: AdLoopConfig,
     *,
     customer_id: str = "",
-    csv_path: str,
+    csv_path: str = "",
+    upload_id: str = "",
     default_region: str = "",
     consent: dict | None = None,
 ) -> dict:
@@ -2501,12 +2568,17 @@ def draft_upload_enhanced_conversions_for_leads(
         operation="upload_enhanced_conversions_for_leads",
         default_region=default_region,
         consent=consent,
+        csv_path=csv_path,
+        upload_id=upload_id,
     )
+    if error:
+        return error
+    source, error = _csv_source(csv_path, upload_id)
     if error:
         return error
 
     rows, parse_advisories, skipped, error = _upload_parse_result(
-        *_parse_ec_for_leads_csv(csv_path, default_region),
+        *_parse_ec_for_leads_csv(source, default_region),
         empty_message="CSV contained zero conversion rows",
     )
     if error:
@@ -2735,7 +2807,7 @@ def draft_upload_enhanced_conversions_for_leads(
         apply_only_payload={"rows": frozen_rows},
     )
     store_plan(plan)
-    return plan.to_preview()
+    return _consume_upload(plan.to_preview(), upload_id)
 
 
 def _apply_upload_enhanced_conversions_for_leads(

{adloop-0.32.0 → adloop-0.33.0}/src/adloop/ads/write.py

@@ -3351,7 +3351,7 @@ def image_payloads(
         from adloop.uploads import UploadError, current_tenant, get_upload_store
 
         try:
-            upload, _data = get_upload_store().get(current_tenant(), upload_id)
+            upload, _data = get_upload_store().get(current_tenant(), upload_id, kind="image")
         except UploadError as exc:
             errors.append(f"Upload {index + 1}: {exc}")
             continue
@@ -5135,7 +5135,7 @@ def load_image_bytes(payload: dict) -> tuple[bytes, PurePath]:
     if payload.get("upload_id"):
         from adloop.uploads import current_tenant, get_upload_store
 
-        upload, image_bytes = get_upload_store().get(current_tenant(), str(payload["upload_id"]))
+        upload, image_bytes = get_upload_store().get(current_tenant(), str(payload["upload_id"]), kind="image")
         if upload.sha256 != payload.get("sha256"):
             raise ValueError(f"upload {upload.upload_id} changed since the preview; draft again.")
         return image_bytes, PurePosixPath(upload.name)

{adloop-0.32.0 → adloop-0.33.0}/src/adloop/merchant/read.py

@@ -216,7 +216,17 @@ def get_merchant_feed_health(
             f"severity — CRITICAL means offers stop serving entirely: "
             + "; ".join(i["title"] for i in critical[:3])
         )
-    if not account_issues and not totals["disapproved"]:
+    if not serving_total:
+        # Zero products is not a healthy feed: Shopping and Performance Max
+        # have nothing to advertise.
+        insights.append(
+            "The account has no products at all (0 approved, pending or "
+            "disapproved), so Shopping and Performance Max campaigns have "
+            "nothing to show. Either no feed or data source is set up yet, "
+            "products were added in the last ~30 minutes (status lags), or "
+            "the products live in another Merchant Center account."
+        )
+    elif not account_issues and not totals["disapproved"]:
         insights.append("No disapprovals or account issues — feed is healthy.")
 
     return {

{adloop-0.32.0 → adloop-0.33.0}/src/adloop/rules/adloop.md

@@ -249,6 +249,21 @@ For images that have no public URL: a file on the user's computer, or an image t
 - **Using an upload:** `draft_image_assets(upload_ids=["up_..."])` for Google Ads; `"upload:up_..."` as `image_url`, `thumbnail_url` or a carousel card's `image_url` in `draft_reddit_ad` (AdLoop Cloud only, because Reddit downloads the image from a short-lived public link). Videos cannot be uploaded.
 - Uploads expire after 24 hours. Self-hosted without a card, pass local files directly (`image_paths`).
 
+### Offline Conversion Uploads
+
+Conversions that happen offline (a sales call, a lead that turned into a deal) go back to Google Ads from a CSV in Google's upload template.
+
+| Tool | When to Use | Key Parameters |
+|------|-------------|----------------|
+| `upload_conversion_csv` | The CSV is not on the machine running AdLoop (always on AdLoop Cloud). Shows the upload card, or returns an upload link | (none) |
+| `draft_upload_call_conversions` | Calls from call assets or call-tracking numbers that became a conversion; matched by the caller's phone number | exactly one of `csv_path` (local file) or `upload_id`; `default_region` for numbers without a country code; `consent` |
+| `draft_upload_enhanced_conversions_for_leads` | Form leads that became a conversion; matched by hashed email, phone or name and address | exactly one of `csv_path` or `upload_id`; `default_region`; `consent` |
+
+- The conversion action named in the CSV's `Conversion Name` column must exist and be of type UPLOAD_CALLS (calls) or UPLOAD_CLICKS (leads); the draft checks it against the account.
+- **The CSV holds personal data** (phone numbers, emails, names). An uploaded file lasts two hours at most and is deleted as soon as a draft has read it, so a second draft needs a new upload; a failed draft keeps it for a retry (for example with `default_region`). Lead identifiers are hashed while drafting. Never ask the user to paste rows into the chat.
+- EEA traffic needs consent signals: pass `consent` or fill the CSV's `Ad User Data` / `Ad Personalization` columns. Present the preview's `consent_summary`, `skipped_rows` and `dedup_warnings`.
+- Apply sends batches of 2,000 rows. `PARTIAL_UPLOAD` means some batches are already in the account: the plan is retired, and a new draft continues at `resume_from_line`. Don't re-upload rows that went through.
+
 ### Planning Tools
 
 | Tool | When to Use | Key Parameters |

{adloop-0.32.0 → adloop-0.33.0}/src/adloop/server.py

@@ -4590,10 +4590,15 @@ def upload_images() -> dict:
     draft_image_assets, or as "upload:<id>" into the image fields of
     draft_reddit_ad. Returns the current uploads and how to add more.
     """
+    return _upload_tool_result("image")
+
+
+def _upload_tool_result(kind: str):
+    """The upload card (with its code) or the upload link, for ``kind``."""
     from adloop.uploads import upload_instructions
 
     shows_cards = client_shows_cards()
-    result = upload_instructions(shows_cards)
+    result = upload_instructions(shows_cards, kind)
     if not shows_cards:
         return result
     from fastmcp.tools import ToolResult
@@ -4609,6 +4614,29 @@ def upload_images() -> dict:
     )
 
 
+@_tool(
+    title="Upload a conversion CSV",
+    annotations=_READONLY,
+    tags={"ads"},
+    meta={"ui": {"resourceUri": UPLOAD_CARD_URI}},
+)
+@_safe
+def upload_conversion_csv() -> dict:
+    """Let the user upload a conversion CSV for an offline conversion upload.
+
+    For the CSV behind draft_upload_call_conversions or
+    draft_upload_enhanced_conversions_for_leads when the file is not on the
+    machine running AdLoop, as on AdLoop Cloud. Apps that show AdLoop's
+    cards display an upload card where the user drops the .csv file; the
+    card then posts the upload id into the chat. Other apps on AdLoop Cloud
+    get an upload link for the user (or a coding agent, with curl). The
+    file holds personal data (phone numbers, emails), so it is kept for two
+    hours at most and deleted as soon as a draft has read it. Returns the
+    CSV uploads waiting to be used and how to add one.
+    """
+    return _upload_tool_result("csv")
+
+
 @_tool(
     title="Store an uploaded image",
     annotations=_WRITE,
@@ -4616,16 +4644,19 @@ def upload_images() -> dict:
     meta={"ui": {"resourceUri": UPLOAD_CARD_URI, "visibility": ["app"]}},
 )
 @_safe
-def store_image_upload(name: str, data_base64: str, code: str = "") -> dict:
-    """Store an image dropped on the AdLoop upload card.
+def store_image_upload(name: str, data_base64: str, code: str = "", kind: str = "image") -> dict:
+    """Store a file dropped on the AdLoop upload card.
 
     Called only by the upload card; AI apps keep this tool out of the
-    model's tool list. Returns the upload's id, type and dimensions.
+    model's tool list. Returns the upload's id, type and size (dimensions
+    for images, lines for CSVs).
 
     Args:
         name: The file name, used for the asset name.
         data_base64: The file content, base64-encoded.
-        code: The upload card's code from upload_images.
+        code: The upload card's code from upload_images or
+            upload_conversion_csv.
+        kind: "image" (default) or "csv" for a conversion CSV.
     """
     import base64
     import binascii
@@ -4637,20 +4668,21 @@ def store_image_upload(name: str, data_base64: str, code: str = "") -> dict:
     except (binascii.Error, ValueError):
         return {"error": "The file did not arrive intact; upload it again."}
     try:
-        upload = get_upload_store().put(current_tenant(), name, data)
+        upload = get_upload_store().put(current_tenant(), name, data, kind=kind)
     except UploadError as exc:
         return {"error": f"{name}: {exc}"}
     return {"status": "UPLOADED", **upload.summary()}
 
 
-@_tool(title="List uploaded images", annotations=_READONLY, tags={"core"})
+@_tool(title="List uploads", annotations=_READONLY, tags={"core"})
 @_safe
 def list_uploads() -> dict:
-    """List the images the user uploaded to AdLoop that have not expired.
+    """List the files the user uploaded to AdLoop that have not expired.
 
-    Returns each upload's upload_id, name, type, dimensions, size and hours
-    until it expires (uploads last a day): the ids of files the user sent
-    through the upload link, or of earlier uploads.
+    Returns each upload's upload_id, kind (image or csv), name, type, size,
+    dimensions (images) or lines (CSVs) and hours until it expires: images
+    last a day, conversion CSVs two hours or until a draft reads them. The
+    ids of files the user sent through an upload link show up here.
     """
     from adloop.uploads import current_tenant, get_upload_store
 
@@ -4660,7 +4692,8 @@ def list_uploads() -> dict:
         "usage": (
             "draft_image_assets(upload_ids=[...]) for Google Ads; "
             "\"upload:<upload_id>\" as image_url, thumbnail_url or a carousel card's "
-            "image_url in draft_reddit_ad (AdLoop Cloud only)."
+            "image_url in draft_reddit_ad (AdLoop Cloud only). CSV uploads: upload_id in "
+            "draft_upload_call_conversions or draft_upload_enhanced_conversions_for_leads."
         ),
     }
 
@@ -6141,7 +6174,8 @@ def draft_remove_conversion_action(
 @_tool(title="Draft call conversion upload", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_upload_call_conversions(
-    csv_path: str,
+    csv_path: str = "",
+    upload_id: str = "",
     default_region: str = "",
     consent: dict | None = None,
     customer_id: str = "",
@@ -6157,8 +6191,9 @@ def draft_upload_call_conversions(
     drafting, so a typo fails here rather than after the upload. Optional
     `Ad User Data` and `Ad Personalization` columns carry consent per row.
 
-    Local file only: on the hosted server this tool refuses, because it would
-    read a path on the server rather than the caller's machine.
+    The CSV comes from csv_path (a file on the machine running AdLoop) or
+    from upload_id (a file uploaded with upload_conversion_csv, the only way
+    on AdLoop Cloud). An uploaded file is deleted once the draft has read it.
 
     PII: the caller phone number is required RAW by Google (it cannot be
     hashed), so it lives in the plan's apply-only payload — the preview shows
@@ -6181,8 +6216,10 @@ def draft_upload_call_conversions(
 
     Args:
         csv_path: Path of the CSV file holding the upload rows, read on the
-            machine that runs AdLoop. The hosted server refuses this tool
-            rather than reading a path of its own.
+            machine that runs AdLoop. Refused on the hosted server; use
+            upload_id there.
+        upload_id: Id of a CSV uploaded with upload_conversion_csv (up_...),
+            instead of csv_path.
         default_region: ISO 3166-1 alpha-2 country assumed for phone numbers
             that carry no country code, e.g. "DE" for "0151 12345678". Empty
             leaves such numbers unusable and the row is skipped.
@@ -6202,6 +6239,7 @@ def draft_upload_call_conversions(
         current_config(),
         customer_id=customer_id or current_config().ads.customer_id,
         csv_path=csv_path,
+        upload_id=upload_id,
         default_region=default_region,
         consent=consent,
     )
@@ -6210,7 +6248,8 @@ def draft_upload_call_conversions(
 @_tool(title="Draft enhanced conversions upload", annotations=_WRITE, tags={"ads"})
 @_safe
 def draft_upload_enhanced_conversions_for_leads(
-    csv_path: str,
+    csv_path: str = "",
+    upload_id: str = "",
     default_region: str = "",
     consent: dict | None = None,
     customer_id: str = "",
@@ -6235,8 +6274,9 @@ def draft_upload_enhanced_conversions_for_leads(
     sharing an Order ID count once at Google; two rows with different Order
     IDs are two real orders and are not reported.
 
-    Local file only: on the hosted server this tool refuses, because it would
-    read a path on the server rather than the caller's machine.
+    The CSV comes from csv_path (a file on the machine running AdLoop) or
+    from upload_id (a file uploaded with upload_conversion_csv, the only way
+    on AdLoop Cloud). An uploaded file is deleted once the draft has read it.
 
     Returns a preview with a plan_id, the row counts, the consent the rows
     actually carry (`consent_summary`) and the skipped rows; nothing is
@@ -6244,8 +6284,10 @@ def draft_upload_enhanced_conversions_for_leads(
 
     Args:
         csv_path: Path of the CSV file holding the upload rows, read on the
-            machine that runs AdLoop. The hosted server refuses this tool
-            rather than reading a path of its own.
+            machine that runs AdLoop. Refused on the hosted server; use
+            upload_id there.
+        upload_id: Id of a CSV uploaded with upload_conversion_csv (up_...),
+            instead of csv_path.
         default_region: ISO 3166-1 alpha-2 country assumed for phone numbers
             that carry no country code, e.g. "DE" for "0151 12345678". Empty
             leaves such numbers unusable; the row still uploads when its email
@@ -6266,6 +6308,7 @@ def draft_upload_enhanced_conversions_for_leads(
         current_config(),
         customer_id=customer_id or current_config().ads.customer_id,
         csv_path=csv_path,
+        upload_id=upload_id,
         default_region=default_region,
         consent=consent,
     )

{adloop-0.32.0 → adloop-0.33.0}/src/adloop/upload_card.html

@@ -90,6 +90,11 @@
       drop: "Drop images here", or: "or", pick: "Choose files",
       uploading: "Uploading…", done: "Uploaded", tooBig: "Over 5 MB", wrongType: "Not PNG, JPEG or GIF",
       message: "I uploaded images to AdLoop:\n{list}\nUse these upload ids for the ad.",
+      brandCsv: "AdLoop · conversion CSV", titleCsv: "Upload your conversion CSV",
+      subCsv: "A .csv file in Google's upload template, up to 5 MB. It is deleted once AdLoop has read it, after two hours at the latest.",
+      dropCsv: "Drop the CSV here", pickCsv: "Choose file", wrongTypeCsv: "Not a .csv file",
+      messageCsv: "I uploaded a conversion CSV to AdLoop:\n{list}\nDraft the conversion upload with this upload_id.",
+      lines: "lines",
     },
     de: {
       brand: "AdLoop · Bilder hochladen", title: "Bilder für deine Anzeigen hochladen",
@@ -97,16 +102,30 @@
       drop: "Bilder hierher ziehen", or: "oder", pick: "Dateien auswählen",
       uploading: "Wird hochgeladen…", done: "Hochgeladen", tooBig: "Größer als 5 MB", wrongType: "Kein PNG, JPEG oder GIF",
       message: "Ich habe Bilder bei AdLoop hochgeladen:\n{list}\nNutze diese Upload-IDs für die Anzeige.",
+      brandCsv: "AdLoop · Conversion-CSV", titleCsv: "Conversion-CSV hochladen",
+      subCsv: "Eine .csv-Datei in Googles Upload-Vorlage, bis 5 MB. Sie wird gelöscht, sobald AdLoop sie gelesen hat, spätestens nach zwei Stunden.",
+      dropCsv: "CSV hierher ziehen", pickCsv: "Datei auswählen", wrongTypeCsv: "Keine .csv-Datei",
+      messageCsv: "Ich habe eine Conversion-CSV bei AdLoop hochgeladen:\n{list}\nErstelle den Conversion-Upload mit dieser upload_id.",
+      lines: "Zeilen",
     },
   };
 
   let lang = "en";
+  // "image" or "csv": upload_images and upload_conversion_csv share this card.
+  let kind = "image";
   document.documentElement.dataset.theme =
     window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
   let nextId = 1;
   const pending = new Map();
   const $ = (id) => document.getElementById(id);
-  const t = (key) => (STRINGS[lang] || STRINGS.en)[key] || STRINGS.en[key] || key;
+  const pick = (key) => (STRINGS[lang] || STRINGS.en)[key] || STRINGS.en[key];
+  const t = (key) => (kind === "csv" && pick(key + "Csv")) || pick(key) || key;
+  const accepted = (file) => kind === "csv" ? /\.csv$/i.test(file.name) : TYPES.includes(file.type);
+  function render() {
+    for (const el of document.querySelectorAll("[data-t]")) el.textContent = t(el.dataset.t);
+    $("file").accept = kind === "csv" ? ".csv,text/csv" : TYPES.join(",");
+    $("file").multiple = kind !== "csv";
+  }
 
   function post(message) { window.parent.postMessage(message, "*"); }
   function request(method, params) {
@@ -126,7 +145,7 @@
     const vars = ctx.styles && ctx.styles.variables;
     if (vars) for (const [k, v] of Object.entries(vars)) if (v) document.documentElement.style.setProperty(k, v);
     if (typeof ctx.locale === "string" && ctx.locale.toLowerCase().startsWith("de")) lang = "de";
-    for (const el of document.querySelectorAll("[data-t]")) el.textContent = t(el.dataset.t);
+    render();
   }
 
   function payloadOf(result) {
@@ -152,6 +171,7 @@
   }
 
   function describe(u) {
+    if (u.kind === "csv") return u.upload_id + " · " + u.lines + " " + t("lines") + " · " + u.size_kb + " KB";
     return u.upload_id + " · " + u.width + "×" + u.height + " · " + u.size_kb + " KB";
   }
 
@@ -167,12 +187,12 @@
   async function upload(files) {
     const stored = [];
     for (const file of files) {
-      const row = addRow(file.name, TYPES.includes(file.type) ? URL.createObjectURL(file) : "");
-      if (!TYPES.includes(file.type)) { row.state.textContent = t("wrongType"); row.state.classList.add("bad"); continue; }
+      const row = addRow(file.name, kind === "image" && accepted(file) ? URL.createObjectURL(file) : "");
+      if (!accepted(file)) { row.state.textContent = t("wrongType"); row.state.classList.add("bad"); continue; }
       if (file.size > MAX_BYTES) { row.state.textContent = t("tooBig"); row.state.classList.add("bad"); continue; }
       row.state.textContent = t("uploading");
       try {
-        const result = await request("tools/call", { name: TOOL, arguments: { name: file.name, data_base64: await readBase64(file), code } });
+        const result = await request("tools/call", { name: TOOL, arguments: { name: file.name, data_base64: await readBase64(file), code, kind } });
         const r = payloadOf(result);
         if ((result && result.isError) || r.error || !r.upload_id) throw new Error(r.error || "upload failed");
         row.meta.textContent = describe(r);
@@ -209,6 +229,7 @@
     if (shownExisting || !result) return;
     shownExisting = true;
     const r = payloadOf(result);
+    if (r.upload_kind === "csv") { kind = "csv"; render(); }
     for (const u of r.uploads || []) {
       const row = addRow(u.name, "");
       row.meta.textContent = describe(u);

{adloop-0.32.0 → adloop-0.33.0}/src/adloop/uploads.py

@@ -1,4 +1,4 @@
-"""Image uploads: files a user hands to AdLoop without a public URL.
+"""Uploads: files a user hands to AdLoop without a public URL or a local path.
 
 AI apps cannot pass a file from the chat to a tool, so an upload reaches
 AdLoop on its own path: the upload card (MCP Apps) calls the app-only
@@ -8,7 +8,13 @@ opens a one-time upload link. Either way the image lands in an
 ``draft_image_assets(upload_ids=[...])`` for Google Ads, ``upload:<id>`` in
 the media fields of ``draft_reddit_ad``.
 
-Uploads are short-lived: they expire after a day and exist to be turned
+Conversion CSVs take the same path (``upload_conversion_csv``) and go into
+the ``upload_id`` of the conversion upload drafts. They hold personal data
+(phone numbers, emails), so they live two hours at most and are deleted as
+soon as a draft has read them; a hosted store also encrypts every file at
+rest (:class:`LocalUploadStore` ``cipher``).
+
+Uploads are short-lived: images expire after a day and exist to be turned
 into ad assets, not to be kept. Self-hosted, the store is a folder under
 ``~/.adloop/uploads``. A hosted runtime sets its own store and the links
 (:func:`set_upload_links`): the upload page and the short-lived public file
@@ -32,6 +38,9 @@ UPLOAD_CARD_URI = "ui://adloop/upload-card.html"
 STORE_UPLOAD_TOOL = "store_image_upload"
 MAX_UPLOAD_BYTES = 5120 * 1024  # Google's image asset limit; Reddit takes more
 DEFAULT_TTL_SECONDS = 24 * 3600
+# Conversion CSVs carry personal data; they are read once by a draft.
+CSV_TTL_SECONDS = 2 * 3600
+KINDS = ("image", "csv")
 MAX_FILES_PER_TENANT = 50
 MAX_BYTES_PER_TENANT = 100 * 1024 * 1024
 _ID_PATTERN = re.compile(r"^up_[A-Za-z0-9_-]{8,40}$")
@@ -48,17 +57,26 @@ class Upload:
     sha256: str
     created_at: float
     expires_at: float
+    # Stored metadata from before CSV uploads has no kind: those are images.
+    kind: str = "image"
+    # Data rows of a CSV (lines that are not the header, blank or comments
+    # are not told apart here; the draft counts precisely).
+    lines: int = 0
 
     def summary(self) -> dict:
-        return {
+        out = {
             "upload_id": self.upload_id,
+            "kind": self.kind,
             "name": self.name,
             "mime_type": self.mime_type,
-            "width": self.width,
-            "height": self.height,
             "size_kb": round(self.size_bytes / 1024, 1),
             "expires_in_hours": max(0, round((self.expires_at - time.time()) / 3600, 1)),
         }
+        if self.kind == "csv":
+            out["lines"] = self.lines
+        else:
+            out["width"], out["height"] = self.width, self.height
+        return out
 
 
 class UploadError(ValueError):
@@ -66,8 +84,8 @@ class UploadError(ValueError):
 
 
 class UploadLinks(Protocol):
-    def upload_page(self, tenant: str) -> tuple[str, int]:
-        """A URL where the user uploads files for ``tenant``, and its lifetime in seconds."""
+    def upload_page(self, tenant: str, kind: str = "image") -> tuple[str, int]:
+        """A URL where the user uploads files of ``kind`` for ``tenant``, and its lifetime in seconds."""
 
     def public_file(self, tenant: str, upload_id: str) -> str:
         """A short-lived public URL serving the upload (for Reddit to download)."""
@@ -95,10 +113,45 @@ def inspect_image(data: bytes) -> tuple[str, int, int]:
         raise UploadError(f"not a usable image: {exc} (PNG, JPEG or GIF)") from exc
 
 
+def inspect_csv(name: str, data: bytes) -> int:
+    """Line count of a conversion CSV; raises UploadError for anything else.
+
+    Only the container is checked here (a .csv name, UTF-8 text, the size).
+    The columns are the draft's business: it names every problem with its
+    line, which a refusal at upload time could not.
+    """
+    if not data:
+        raise UploadError("the file is empty")
+    if len(data) > MAX_UPLOAD_BYTES:
+        raise UploadError(
+            f"the file is {len(data) / 1024:.0f} KB; CSV uploads can be at most "
+            f"{MAX_UPLOAD_BYTES // 1024} KB (Google takes 2,000 rows per request anyway)"
+        )
+    if not str(name or "").lower().endswith(".csv"):
+        raise UploadError("conversion uploads must be .csv files (Google's upload template)")
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError as exc:
+        raise UploadError("the CSV is not UTF-8 text; export it as CSV UTF-8") from exc
+    if "\x00" in text:
+        raise UploadError("the file is not a text CSV")
+    return sum(1 for line in text.splitlines() if line.strip())
+
+
+class UploadCipher(Protocol):
+    """Encryption at rest for a hosted store (the file bytes, not the metadata)."""
+
+    def encrypt(self, data: bytes) -> bytes: ...
+
+    def decrypt(self, data: bytes) -> bytes: ...
+
+
 class LocalUploadStore:
     """Uploads as files in a folder, one subfolder per tenant.
 
     Expired files are removed whenever the store is used; there is no timer.
+    With a ``cipher`` every file is stored encrypted (hosted runtimes);
+    self-hosted, the files sit on the user's own machine as they are.
     """
 
     def __init__(
@@ -106,13 +159,17 @@ class LocalUploadStore:
         root: str | Path,
         *,
         ttl_seconds: int = DEFAULT_TTL_SECONDS,
+        csv_ttl_seconds: int = CSV_TTL_SECONDS,
         max_files: int = MAX_FILES_PER_TENANT,
         max_bytes: int = MAX_BYTES_PER_TENANT,
+        cipher: UploadCipher | None = None,
     ) -> None:
         self.root = Path(root)
         self.ttl_seconds = ttl_seconds
+        self.csv_ttl_seconds = csv_ttl_seconds
         self.max_files = max_files
         self.max_bytes = max_bytes
+        self.cipher = cipher
 
     def _dir(self, tenant: str) -> Path:
         key = hashlib.sha256(str(tenant or "local").encode()).hexdigest()[:24]
@@ -143,13 +200,20 @@ class LocalUploadStore:
             except FileNotFoundError:
                 pass
 
-    def put(self, tenant: str, name: str, data: bytes) -> Upload:
-        mime_type, width, height = inspect_image(data)
+    def put(self, tenant: str, name: str, data: bytes, *, kind: str = "image") -> Upload:
+        if kind not in KINDS:
+            raise UploadError(f"unknown upload kind '{kind}'")
+        lines = 0
+        if kind == "csv":
+            lines = inspect_csv(name, data)
+            mime_type, width, height = "text/csv", 0, 0
+        else:
+            mime_type, width, height = inspect_image(data)
         existing = self._entries(tenant)
         digest = hashlib.sha256(data).hexdigest()
         for upload in existing:
-            if upload.sha256 == digest:
-                return upload  # the same image twice is one upload
+            if upload.sha256 == digest and upload.kind == kind:
+                return upload  # the same file twice is one upload
         if len(existing) >= self.max_files:
             raise UploadError(
                 f"this workspace already holds {len(existing)} uploads; they expire after a day"
@@ -169,30 +233,46 @@ class LocalUploadStore:
             size_bytes=len(data),
             sha256=digest,
             created_at=now,
-            expires_at=now + self.ttl_seconds,
+            expires_at=now + (self.csv_ttl_seconds if kind == "csv" else self.ttl_seconds),
+            kind=kind,
+            lines=lines,
         )
         folder = self._dir(tenant)
         folder.mkdir(parents=True, exist_ok=True)
-        for suffix, payload in ((".bin", data), (".json", json.dumps(asdict(upload)).encode())):
+        stored = self.cipher.encrypt(data) if self.cipher else data
+        for suffix, payload in ((".bin", stored), (".json", json.dumps(asdict(upload)).encode())):
             tmp = folder / f".{upload.upload_id}{suffix}.tmp"
             tmp.write_bytes(payload)
             os.replace(tmp, folder / f"{upload.upload_id}{suffix}")
         return upload
 
-    def get(self, tenant: str, upload_id: str) -> tuple[Upload, bytes]:
+    def get(self, tenant: str, upload_id: str, *, kind: str | None = None) -> tuple[Upload, bytes]:
         upload_id = str(upload_id or "").strip()
         if not _ID_PATTERN.match(upload_id):
             raise UploadError(f"'{upload_id}' is not an upload id (they look like up_...)")
         for upload in self._entries(tenant):
             if upload.upload_id == upload_id:
+                if kind and upload.kind != kind:
+                    raise UploadError(
+                        f"upload {upload_id} is a {upload.kind} upload, not a {kind} upload"
+                    )
                 data = (self._dir(tenant) / f"{upload_id}.bin").read_bytes()
+                if self.cipher:
+                    data = self.cipher.decrypt(data)
                 return upload, data
         raise UploadError(
-            f"upload {upload_id} was not found; uploads expire after a day (see list_uploads)"
+            f"upload {upload_id} was not found; uploads expire (images after a day, "
+            "CSVs after two hours or once a draft has read them; see list_uploads)"
         )
 
-    def list(self, tenant: str) -> list[Upload]:
-        return self._entries(tenant)
+    def delete(self, tenant: str, upload_id: str) -> None:
+        """Remove an upload now (a CSV once a draft has read it)."""
+        upload_id = str(upload_id or "").strip()
+        if _ID_PATTERN.match(upload_id):
+            self._remove(self._dir(tenant), upload_id)
+
+    def list(self, tenant: str, *, kind: str | None = None) -> list[Upload]:
+        return [u for u in self._entries(tenant) if kind is None or u.kind == kind]
 
 
 _store: LocalUploadStore | None = None
@@ -243,42 +323,60 @@ def public_url_for(upload_id: str) -> str:
             "upload: references need a public link Reddit can download, which only AdLoop "
             "Cloud provides. Self-hosted, pass a public image URL instead."
         )
-    get_upload_store().get(current_tenant(), upload_id)  # exists and not expired
+    get_upload_store().get(current_tenant(), upload_id, kind="image")  # exists, not expired
     return links.public_file(current_tenant(), upload_id)
 
 
-def upload_instructions(shows_cards: bool) -> dict:
-    """What ``upload_images`` returns: current uploads plus the way to add more."""
+def upload_instructions(shows_cards: bool, kind: str = "image") -> dict:
+    """What ``upload_images`` / ``upload_conversion_csv`` return: current
+    uploads of that kind plus the way to add more."""
     tenant = current_tenant()
-    result: dict = {"uploads": [u.summary() for u in get_upload_store().list(tenant)]}
-    use = (
-        "Use the ids as upload_ids in draft_image_assets, or as \"upload:<upload_id>\" in "
-        "the image fields of draft_reddit_ad."
-    )
+    result: dict = {
+        "upload_kind": kind,
+        "uploads": [u.summary() for u in get_upload_store().list(tenant, kind=kind)],
+    }
+    if kind == "csv":
+        what, example = "the CSV", 'curl -T "conversions.csv" "{url}/"'
+        use = (
+            "Pass the id as upload_id to draft_upload_call_conversions or "
+            "draft_upload_enhanced_conversions_for_leads. The file is deleted once a draft "
+            "has read it, and after two hours at the latest."
+        )
+        local = (
+            "This app shows no upload card. Self-hosted, pass the file directly: the "
+            "conversion upload drafts take csv_path, a file on this machine."
+        )
+    else:
+        what, example = "the images", 'curl -T "logo.png" "{url}/"'
+        use = (
+            "Use the ids as upload_ids in draft_image_assets, or as \"upload:<upload_id>\" in "
+            "the image fields of draft_reddit_ad."
+        )
+        local = (
+            "This app shows no upload card. Self-hosted, pass the files directly: "
+            "draft_image_assets(image_paths=[...]) takes local files; Reddit ads need a "
+            "public image URL."
+        )
     if shows_cards:
         result["upload"] = "card"
         result["instructions"] = (
-            "The user sees an AdLoop upload card and drops the images there. The card posts "
+            f"The user sees an AdLoop upload card and drops {what} there. The card posts "
             "the upload ids into the chat when it is done; wait for that. " + use
         )
         return result
     links = get_upload_links()
     if links is None:
-        result["instructions"] = (
-            "This app shows no upload card. Self-hosted, pass the files directly: "
-            "draft_image_assets(image_paths=[...]) takes local files; Reddit ads need a "
-            "public image URL."
-        )
+        result["instructions"] = local
         return result
-    url, lifetime = links.upload_page(tenant)
+    url, lifetime = links.upload_page(tenant, kind)
     minutes = max(1, lifetime // 60)
     result.update({
         "upload_url": url,
         "expires_in_minutes": minutes,
-        "curl_example": f'curl -T "logo.png" "{url}/"',
+        "curl_example": example.format(url=url),
         "instructions": (
             f"Give the user this upload link (valid {minutes} minutes): they open it in the "
-            "browser and drop the images, then tell you they are done; call list_uploads for "
+            f"browser and drop {what}, then tell you they are done; call list_uploads for "
             "the ids. A coding agent with the files on disk can upload them itself with curl "
             "(curl_example; one call per file). " + use
         ),