Publish outcomes
The most important page here. A publish returns one of five outcomes, and they are chosen so an agent can report the truth without polling anything.
The five
live — serving now.
held — queued for a person to look at. Nothing to do; nothing went wrong.
failed — it did not publish, and the reason comes with it.
unpublished — not currently being served.
pending — still going. Ask get_site for the settled answer.
Why the job status is not the answer
The single most important thing on this page.
Extraction and publishing run as a job, and that job can complete successfully while the site does not serve. The commonest case is the one every new account hits: the first publish is held for review, the job finishes fine, and the site returns 404.
An agent that reports job status therefore tells its user “published!” about a site that doesn’t load. That is why the outcome is read from the site and its hold rather than from the job — and why you should never reconstruct “success” from a job result yourself.
live sometimes comes without a URL
If a site is live but private, the outcome is live — correctly, because it
is serving — and there is no URL to give, because the address returns 404 to
everyone, including its owner.
This looks like a bug to an agent that assumes success implies a link. It isn’t. Report it as live, say it’s private, and point at the dashboard preview.
failed and unpublished are different on purpose
failed means a publish was attempted and did not work. There is a reason and
you should show it.
unpublished means the site is simply not being served. That covers three
situations — the owner switched it off, it never published in the first place, or
the system gated it — and they read identically. That is deliberate. Do not
try to infer which one you are in, and do not guess on the user’s behalf.
pending is not a verdict
pending is the absence of an answer, not a bad one. A bounded wait that ran
out says pending, and so does any read that finds the publish still in flight.
Do not translate it to failed (nothing went wrong) or to unpublished
(nothing was decided). Say it is still going, and offer to check again.
Reporting these to a person
Roughly:
| Outcome | Say something like |
|---|---|
live | “It’s live: <url>” |
live, private | “Published, but it’s private — preview it from your dashboard.” |
held | “Published and queued for review. First sites always are; nothing to do.” |
failed | “It didn’t publish: <reason>” |
pending | “Still publishing — want me to check again?” |
The one to get right is held. Presented as an error it reads as a rejection;
presented as success it reads as a live site that isn’t there.