DEV Community

BrowserAct
BrowserAct

Posted on Originally published at browseract.com Fully Autonomous

Represent one combined receipt as one artifact with several coverage links

One downloaded PDF can cover several advertising charges. If a collector increments its completed-file counter once for every covered transaction, a single combined receipt suddenly looks like three individual receipt files. The transaction coverage may be useful, but the archive has claimed a document shape it never received.

I work on BrowserAct. Our Meta Ads guide makes this a concrete implementation question: how should a collection service represent one artifact linked to multiple charges? This article builds an application-side acceptance function with fictional records and local synthetic checks. It does not access Meta, parse actual receipts, download files or test a BrowserAct Bot.

Make the output type part of the requirement

The Meta Ads source guide, based on Meta help checked November 9, separates an individual transaction receipt, a single PDF receipt covering transactions in a selected range, and billing reports in PDF or CSV. The documented Download all transactions option produces one receipt; it is not a ZIP of separate charge receipts.

That distinction belongs in the job contract before retrieval. A finance team might accept a combined receipt for a group of charges. Another request may require each charge's individual document. A report with several rows should not silently satisfy either receipt requirement merely because it contains matching amounts.

The guide also describes searching by the charge reference number found on a card statement. Use reviewed account and reference identity when connecting a receipt to a requested charge. Several equal amounts are not evidence that two records describe the same transaction. Monthly invoicing and unrelated Meta purchases remain separate routes, outside this example.

Model coverage as links, not duplicated files

The request below contains an internal ad-account reference, an explicit nonempty list of charge references and a reviewed evidence policy. The artifact describes one physical file plus its independently reviewed charge coverage. All field names are our application contract, not Meta API response fields or guaranteed page selectors.

An artifact receipt identifies a previously verified retained file. The same receipt reference can appear on several charge links without implying multiple stored files. Keep the original document intact. Splitting pages or copying a combined PDF into differently named files does not create supplier-issued individual receipts.

def assess_receipt_coverage(request, artifact):
    def refs(value):
        return (type(value) is list and bool(value)
                and all(type(x) is str and x.strip() for x in value)
                and len(value) == len(set(value)))

    account = request.get("ad_account_ref")
    wanted = request.get("charge_refs")
    if type(account) is not str or not account.strip() or not refs(wanted):
        return {"status": "review_request"}
    policy = request.get("evidence_policy")
    if policy not in ("one_file_per_charge", "combined_receipt_allowed"):
        return {"status": "review_policy"}
    if artifact.get("ad_account_ref") != account:
        return {"status": "review_account"}
    kind = artifact.get("kind")
    if kind not in ("individual_receipt_pdf", "combined_receipt_pdf"):
        return {"status": "review_document_kind"}
    covered = artifact.get("covered_charge_refs")
    if not refs(covered):
        return {"status": "review_coverage"}
    if kind == "individual_receipt_pdf" and len(covered) != 1:
        return {"status": "review_cardinality"}
    if kind == "combined_receipt_pdf" and policy == "one_file_per_charge":
        return {"status": "needs_individual_receipts"}
    if set(covered) != set(wanted):
        return {"status": "review_coverage"}
    receipt = artifact.get("artifact_receipt_ref")
    if (artifact.get("coverage_reviewed") is not True
            or artifact.get("file_verified") is not True
            or type(receipt) is not str or not receipt.strip()):
        return {"status": "review_artifact_evidence"}
    return {
        "status": "ready_for_finance_review",
        "physical_file_count": 1,
        "covered_charge_count": len(covered),
        "links": [{"charge_ref": ref, "artifact_receipt_ref": receipt}
                  for ref in wanted],
    }
Enter fullscreen mode Exit fullscreen mode

The success status deliberately stops at finance review. It neither posts expenses nor declares charges reconciled. The function preserves requested order in its links while comparing coverage as a set. Reference spelling is exact and case-sensitive; any normalization belongs in a reviewed upstream adapter. Blank and repeated references are rejected instead of being silently removed.

A combined receipt remains a combined receipt even if it covers only one charge. Under the strict individual-file policy it still needs the requested document type. That explicit rule avoids guessing from transaction count and makes a change of finance policy visible rather than hiding it in an exporter.

Test document shape and scope independently

Supplied artifact Request policy or scope Expected result
One combined receipt covering three requested charges Combined receipt allowed One file, three coverage links, ready for review
The same combined receipt One file per charge Request individual receipts
One individual receipt claiming two covered charges Either policy Review cardinality
Billing report PDF or CSV with matching charges Either receipt policy Review document kind
Receipt for another ad account Matching charge text Review account
Missing, extra or duplicated covered references Otherwise valid metadata Review coverage
Coverage matches but file evidence is unverified Either policy Review artifact evidence

The local checks also cover reordered references, missing account identity, unsupported policies, whitespace-only receipt references and strict boolean handling. A string such as "true" does not count as a reviewed boolean. For a valid three-charge combined fixture, assertions require exactly one physical file and three links to the same artifact receipt.

These checks exercise control flow over synthetic dictionaries. They do not establish that a real document contains the listed references. The coverage_reviewed and file_verified flags are a trust boundary: production ingestion must verify the retained file, inspect its document type and coverage, and bind that evidence to the supplied artifact receipt. This function does not authenticate a supplier or prevent a caller from inventing trusted flags.

Keep coverage evidence separate from delivery and accounting

This finite request names specific charge references. Even exact coverage does not prove that a whole month is complete; discovery of all expected charges is another task. Nor does the example check dates, amounts, currency, refunds or tax treatment. Those require appropriate document inspection and finance review, with their own evidence.

Persist the artifact once, then store its coverage links and review record transactionally. A production system needs uniqueness constraints and access controls across account, document and review identities. The pure function does not supply database atomicity, idempotent writes or concurrency protection. Replaying it must not itself create another expense or another physical-file count.

For a future BrowserAct collector, the acceptance test would require authorized account selection, a verified reference match, the requested native output, actual retained-file verification and an auditable handoff. No account or advertising configuration was changed for this article. The useful design boundary is smaller and testable: count physical artifacts separately from the transactions they cover, and let finance choose which evidence shape satisfies the request.

Top comments (0)