Artifacts
=========

Publish one self-contained HTML file and share its stable Account link::

    from qbraid_core.services.artifacts import ArtifactsClient

    client = ArtifactsClient()
    artifact = client.publish("report.html", title="Results")
    client.share(artifact.slug, "colleague@example.com")
    mine = client.list_artifacts(page=1, limit=20)
    client.update(artifact.slug, visibility="public")

Private artifacts are owner-only. Shared artifacts require an invited signed-in
qBraid user. Public artifacts are accessible through their individual link;
there is no public catalog. Unpublish with ``visibility="private"``; this also
clears all invitations. Sharing again requires inviting each viewer anew.
Revoking a named grant does not disable public viewing. Previously issued signed
content links may remain usable until they expire, up to five minutes.

HTML is limited to 5 MiB; embed scripts, styles, images, fonts, and data. File
uploads must be regular ``.html`` or ``.htm`` files, not symbolic links. Renamed
plain-text files are rejected; HTML fragments and leading comments are accepted.
Uploads containing private-key markers or the client's exact active or saved qBraid authentication
credentials are rejected before publication. These checks prevent common accidental
uploads; they are not a general secret scanner or a sandbox for agent code.

``get_artifact()`` returns ``content_url``, a signed link to the HTML that expires
after 5 minutes. It is served from ``qbraidusercontent.com`` with a ``sandbox``
content policy that restricts scripts to inline execution and blocks external
assets and network APIs. Do not treat CSP as a guarantee against every navigation
channel. Call ``get_artifact()`` again for a fresh link.

.. automodule:: qbraid_core.services.artifacts
   :members:
   :no-index:

Publishing is immediate. The API deduplicates each owner's normalized HTML,
title and access with no time limit. Publishing the same values returns the
existing stable link with ``artifact.created is False``; a new publication has
``created is True``. Pass ``duplicate=True`` only to explicitly create a copy.
There is no client-supplied publication ID. Updates preserve the public slug
while changing the deduplication key; conflicting updates return HTTP 409.

No mutations are retried automatically. A normal publish can be deliberately
retried with identical input to recover an uncertain result. For an uncertain
explicit copy, update or deletion, inspect the owner listing before taking
another action.

Roll out the API/storage and qbraidusercontent.com sandbox response headers
before this Core release, then the CLI and Lab clients. Run the API's deployed
smoke gate for signed-link isolation, permission changes and two-account access.
These documentation and unit tests do not establish that deployment is ready.

Malformed API responses raise ``ArtifactsServiceRequestError`` without including
private response data. Visibility is validated before a publishing or update
request is sent.