DEV Community

BrowserAct
BrowserAct

Posted on Originally published at browseract.com Fully Autonomous

Model receipt exports as observed state transitions, not a successful click

A worker requests a receipt export and marks the job complete. The interface is still generating the files. When the next worker runs, it either starts another export or assumes the archive already exists.

The missing boundary is between requesting an export and receiving its artifacts.

I work on BrowserAct. Our LinkedIn Ads receipt guide describes a native workflow that selects payment records, chooses PDF or CSV, waits for generation, and then downloads the result. That sequence is a useful example for application state design. The code here operates on synthetic observations; it does not visit Campaign Manager, request a real export, download receipts, or test a BrowserAct Bot.

Name the observations that permit progress

A successful click is not evidence that generation finished. A ready download is not evidence that a file was saved. A saved file is not evidence that it belongs to the requested account and receipts.

Use separate application states with a concrete observation for each transition:

From Observed event To
requested Generation has started for this request generating
generating This export is ready ready
ready Its artifact was saved saved
saved The saved artifact passed the required review verified
generating Generation failure was observed blocked

These labels are an internal model, not LinkedIn status values or documented API events. An adapter must supply evidence from the actual permitted workflow. If the page does not establish readiness, keep the job generating or request review; do not invent an event after an arbitrary sleep.

The receipt guide also separates card receipts from monthly invoices and distinguishes receipt PDFs from CSV details. The requested output type and selected receipt manifest belong to the job definition. Switching format or account should create a new job rather than reusing the old readiness state.

Bind every event to one account and export request

An account reference and application job ID identify the work below. The job ID is created by the application; the example does not assume the portal exposes a durable export ID.

The record also has a version. A producer includes the version it observed, so a stale observation cannot overwrite a newer state silently. This is especially useful after a delayed worker resumes or two observers report the same readiness event.

TRANSITIONS = {
    ("requested", "generation_started"): "generating",
    ("generating", "generation_ready"): "ready",
    ("ready", "artifact_saved"): "saved",
    ("saved", "artifact_verified"): "verified",
    ("generating", "generation_failed"): "blocked",
}


def advance(record, event):
    for field in ("account", "job"):
        value = record.get(field)
        if not isinstance(value, str) or not value.strip():
            raise ValueError("Missing job identity")
        if event.get(field) != value:
            raise ValueError("Observation belongs to another job")
    version = record.get("version")
    if (type(version) is not int or version < 0
            or type(event.get("expected_version")) is not int
            or event["expected_version"] != version):
        raise ValueError("Read the current record before applying an event")
    evidence = event.get("evidence_ref")
    if not isinstance(evidence, str) or not evidence.strip():
        raise ValueError("Observation evidence is required")
    kind = event.get("kind")
    target = TRANSITIONS.get((record.get("state"), kind))
    if target is None:
        raise ValueError("Transition is not allowed")
    result = dict(record)
    if kind in ("artifact_saved", "artifact_verified"):
        artifact = event.get("artifact_ref")
        if not isinstance(artifact, str) or not artifact.strip():
            raise ValueError("Saved-artifact reference is required")
        if kind == "artifact_verified" and artifact != record.get("artifact_ref"):
            raise ValueError("Review does not identify the saved artifact")
        result["artifact_ref"] = artifact
    result.update(state=target, version=version + 1,
                  last_evidence_ref=evidence)
    return result
Enter fullscreen mode Exit fullscreen mode

The pure function returns a new record and leaves its input unchanged. It does not persist the result. Production storage must perform a conditional update against the expected version atomically; checking a version in Python and then doing an unconditional database write would still allow a race.

This example rejects a stale event rather than making it idempotently successful. The caller should reread the ledger and reconcile existing evidence. It should not interpret the error as permission to request another portal export.

Treat verification as a separate trust boundary

artifact_verified means a qualified upstream review supplied evidence for the same saved artifact reference. The reducer cannot inspect a PDF or decide whether a CSV contains every selected receipt.

The review needs to compare account, document type, identifiers, and requested membership. Preserve the original selection manifest and the saved output references. A PDF batch may contain separate receipt files, so a package reference is only a handle to the reviewable artifact set; it does not prove that every member passed inspection.

Likewise, a CSV report does not fill a PDF requirement merely because it lists the same charges. Historical document unavailability is another kind of exception. Starting a new generation job cannot establish that a no-longer-available original PDF can be recovered.

Test skipped and stale transitions

Local synthetic checks cover the full successful chain, generation failure, stale versions, wrong accounts and jobs, missing evidence, attempts to skip readiness, and a review for the wrong saved artifact. They test this reducer rather than the supplier interface or any real receipt content.

The blocked state has no automatic outgoing transition in this example. Keep the failure evidence and obtain a specific recovery decision before creating fresh work. Do not turn every timeout into a new export request.

For a job still generating, use bounded observation and retain the last known state. If a later run finds the original output ready, continue from that observation. If the result is uncertain, reconcile the original request before submitting another one.

No payment, advertising, or permission change is needed to implement this ledger. It is a way to report progress truthfully while a separately authorized native retrieval process does the actual work.

The completion badge should describe accepted artifact evidence, not the last button the worker clicked.

Source and native retrieval context: Download LinkedIn Ads receipts: PDF and CSV guide.

Top comments (0)