This is the multi-page printable view of this section. Click here to print.
X article publication
1 - x-article-publication Specification
Purpose
Create an X Article draft from a converted Markdown post, resolving referenced images through the media upload endpoint. The uploader creates drafts only; it never publishes an article.
Requirements
Requirement: Authenticated requests to X Articles
The publisher SHALL authenticate to the X API with credentials supplied at run time through the repository’s secret-injection flow. Credential values MUST NOT be recorded in source, committed configuration, logs, or command history.
Authentication SHALL use OAuth 1.0a user context, because the existing media and Articles endpoints accept it and its user-context token does not expire on a fixed schedule the way an OAuth 2.0 user token does, so draft creation does not depend on a rotating refresh token. OAuth 1.0a needs four credential fields — the API key, the API secret, the access token, and the access token secret — and the publisher SHALL sign each request with HMAC-SHA1 per RFC 5849 using the repository’s standard library rather than adding a signing dependency. The publisher SHALL fail when any of the four fields is absent, rather than sending a partially signed request.
Scenario: Create a draft with injected credentials
- WHEN the publisher runs with credentials supplied through the injection flow
- THEN it signs its requests to the X API with OAuth 1.0a user context
- AND it does not print the credential values
Scenario: Credentials are unavailable
- WHEN the publisher runs without any one of the four required credential fields
- THEN it fails with a diagnostic naming the missing credential reference
- AND it does not retry with a partial or empty credential
Requirement: Draft-only uploads
The uploader SHALL create X Article drafts and MUST NOT publish an article. It
SHALL NOT call the Articles publish endpoint or expose a way to request
publication, so no invocation of this tool can make a post publicly visible.
Draft creation SHALL send the title that conversion parsed from the source front
matter, and MUST NOT invent, default, or omit it, because the draft endpoint
requires a title that content_state does not carry.
Scenario: Create a draft
- WHEN draft creation is requested for a converted document
- THEN the publisher reads the draft article identifier from the v2 response envelope’s
data.id - AND no post becomes publicly visible
- AND the request carries the title parsed from the source front matter
Scenario: A draft response omits the identifier
- WHEN the draft endpoint returns a 2xx response whose
data.idis missing or empty - THEN the publisher fails rather than reporting a successful draft with no identifier to review
- AND it does not treat the zero-value response as a created draft
Scenario: Draft creation is requested without a parsed title
- WHEN draft creation is requested for a document with no parsed title
- THEN the publisher fails with a diagnostic
- AND it does not send a placeholder or empty title
Requirement: Image media upload
The publisher SHALL upload each referenced image through the X media upload
endpoint and reference the returned media_id in an image entity, because
that entity carries no document URL. Uploading MUST happen before the draft
that references the media is created.
The publisher SHALL obtain the image bytes from the locator the draft artifact
records beside the document, not by re-parsing the source Markdown, because the
API’s entity data object rejects additional properties and so cannot carry a
path. It SHALL resolve the recorded relative path against the post package the
locator records, so the artifact stays resolvable after it is moved. It SHALL
reject a locator that escapes the post’s directory or whose bytes do not match
the digest the locator records, rather than uploading a different image. It
SHALL enforce that containment by resolving the name through a
descriptor-anchored directory handle that rejects a symlink escaping the root,
rather than by checking a pathname and then re-opening it, so the object whose
containment is checked is the object read.
Scenario: Upload an image and resolve its media identifier
- WHEN a converted document references an unuploaded image
- THEN the publisher reads the image bytes from the artifact’s locator and
obtains a
media_id - AND the created draft references that
media_idin itsimageentity
Scenario: Reuse an already uploaded image
- WHEN the same image content has a ready upload in the current credential context and a usable lifetime
- THEN the publisher reuses the recorded
media_idrather than uploading the same bytes again
Scenario: Reuse an upload in a later run
- WHEN draft creation runs again in a new process for an image this tool already uploaded
- THEN it reuses the identifier only when the cache schema, endpoint, media category, credential context, content digest, and conservative expiry all match
- AND it stays correct when the cache is absent or the recorded digest no longer matches the artifact’s, by uploading again rather than reusing a stale identifier
Scenario: Decode the media upload response
- WHEN the media upload endpoint returns the v2 response envelope
- THEN the publisher reads the media identifier from the envelope’s
data.id - AND the created draft references that identifier rather than an empty one
Scenario: A media upload response omits the identifier
- WHEN the media upload endpoint returns a 2xx response whose
data.idis missing or empty - THEN the publisher fails rather than resolving the image to an empty identifier
- AND it does not send an entity that references a missing media identifier
Scenario: Expire a cached upload
- WHEN the recorded lifetime of a cached media identifier has passed before image resolution begins
- THEN the cached entry is treated as a miss and the image is uploaded again
- AND an entry with enough lifetime for draft submission is still reused
Scenario: An image cannot be uploaded
- WHEN an image upload fails
- THEN the publisher fails and reports the failing image
- AND it does not create a draft that references a missing or placeholder media identifier
Scenario: An artifact names an unusable image locator
- WHEN an artifact’s locator escapes the recorded post package or names bytes whose digest does not match the recorded one
- THEN the publisher fails with a diagnostic naming the locator
- AND it uploads no replacement image in its place
Scenario: An unresolved image entity has no locator
- WHEN an artifact retains an
imageentity withoutmedia_itemsbut records no locator that resolves it - THEN the publisher fails before uploading any image or creating a draft, naming the unresolved entity
- AND it does not send an image entity without a media item
Scenario: A locator does not name a distinct image entity
- WHEN an artifact’s locator names an entity that is missing, is not an image, or is already named by another locator
- THEN the publisher fails before uploading any image rather than discovering the mismatch after paying for uploads
Scenario: Two entities share one numeric key
- WHEN an artifact contains more than one entity with the same numeric key
- THEN the publisher fails before uploading any image, because one locator could resolve only the first and leave the other without
media_items
Scenario: An image entity carries a malformed media_items entry
- WHEN an image entity’s
media_itemsis present but its entry has an empty or absentmedia_id, or a missing or incorrectmedia_category - THEN the entity is treated as unresolved, so the publisher requires a locator rather than sending the invalid entry to X
Scenario: An image entity carries a usable entry beside a malformed one
- WHEN an image entity’s
media_itemsholds a usable entry next to an empty, non-object, or incorrectly categorized one - THEN the entity is treated as unresolved, because every supplied entry must be usable
- AND the publisher does not send the malformed array merely because one entry looked valid
Scenario: An image entity carries no usable key
- WHEN an artifact contains an image entity whose
keyis missing, non-numeric, fractional, or negative - THEN the publisher fails before uploading any image, because the entity is invisible to locator coverage
- AND it does not send an unresolved image to X
Scenario: The cache cannot be written
- WHEN the cache cannot be recorded, such as a cache path in a read-only directory or over an existing directory
- THEN draft creation continues and the draft is created from the uploads that already succeeded
- AND the failure costs a later re-upload rather than aborting draft creation
Requirement: Reporting and failure handling
The publisher SHALL report the identifier it obtained and SHALL fail loudly rather than report success when a request was rejected. Failures MUST identify which operation failed and MUST NOT be retried automatically.
For every non-2xx API response, including HTTP 503, the error SHALL preserve and
display the original operation, status, body, and only these response headers:
X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset,
X-User-Limit-24hour-Limit, X-User-Limit-24hour-Remaining,
X-User-Limit-24hour-Reset, and Retry-After. It SHALL preserve every value of
those headers and SHALL NOT copy authorization, cookies, or other headers into
the error. A rejected response whose body cannot be completely read SHALL
retain its status and headers alongside the body-read error cause.
Valid Unix reset timestamps SHALL also be displayed as human-readable UTC.
A combined rate-limit retry not-before boundary SHALL be reported only when
known exhausted windows have valid, future reset times at response receipt.
A window SHALL count as exhausted only when its unambiguous remaining value
is zero. The boundary SHALL use the latest reset among those windows, extended
by a valid later Retry-After value interpreted as decimal seconds from receipt
or an HTTP date. Missing, malformed, ambiguous, or already-elapsed reset data
for an exhausted window SHALL prevent a combined boundary. A positive remaining
count or Retry-After alone MUST NOT imply upload eligibility. The diagnostic
SHALL distinguish a not-before boundary from guaranteed service recovery or
request success, and SHALL preserve raw values when timing is unknown.
Scenario: Report the created identifier
- WHEN a draft is created
- THEN the publisher reports the draft’s article identifier
Scenario: The API rejects a request
- WHEN an API request is rejected
- THEN the publisher reports the failing operation and the API’s error
- AND it does not report the operation as successful or retry automatically
Scenario: Service unavailable with remaining allowance
- WHEN a 503 response includes remaining allowance and reset headers
- THEN the error retains those headers and displays readable UTC resets
- AND it does not claim that the resets guarantee service recovery
Scenario: Both rate windows are exhausted
- WHEN both remaining counts are zero and both resets are valid future times
- THEN the rate-limit boundary is no earlier than the later reset
- AND valid later Retry-After advice extends that boundary
Scenario: Timing evidence is incomplete or invalid
- WHEN an exhausted window has a missing, malformed, ambiguous, or elapsed reset
- THEN the diagnostic reports that a current retry time is unknown
- AND it keeps the original header values without inventing an exact time
Scenario: A rejected response body is truncated
- WHEN a non-2xx response terminates before its declared body length
- THEN the error retains the operation, status, partial body, and allowlisted headers
- AND callers can still inspect the body-read error cause
Scenario: Validation runs without network access
- WHEN the project’s checks validate conversion
- THEN they run without contacting the X API
- AND no test requires live credentials
Requirement: Article banner media
Draft creation SHALL upload a selected banner through the media API and send
its identifier in the optional cover_media object with
media_category: tweet_image. The publisher SHALL share its digest-based media
cache between banner and body images, reusing an unexpired identifier for the
same bytes. It SHALL validate all banner and body image locators, bytes,
digests, and media types before any upload or draft request.
Scenario: Reuse one upload for banner and body
- WHEN the banner and a body image contain the same bytes
- THEN at most one media upload resolves both references
- AND the draft request carries that ID in
cover_mediaand the body entity
Scenario: Upload distinct banner and body images
- WHEN the selected banner has different bytes from every body image
- THEN it receives its own media upload or cached identifier
- AND all media resolves before the draft request is sent
Scenario: Create a draft without a banner
- WHEN the artifact has no banner locator
- THEN the request omits
cover_media
Scenario: Invalid image prevents every request
- WHEN any banner or body locator is malformed, escapes its package, names missing bytes, or has a mismatched digest or media type
- THEN draft creation fails before any media or draft HTTP request
Requirement: Media readiness before draft creation
The publisher SHALL inspect media processing information before using an upload identifier. A response without processing information or with succeeded state SHALL require no status request. Pending or in-progress processing SHALL use read-only signed status requests, respect the reported delay, and stop within a bounded deadline. Failed, unknown, inconsistent, or incomplete processing state, partial upload errors, and rejected status requests SHALL prevent draft creation. Neither upload nor draft POST requests SHALL be replayed by this workflow.
Scenario: A static upload is immediately usable
- WHEN upload succeeds without processing information or with succeeded state
- THEN the publisher makes no processing-status request
- AND the media identifier can be attached to the draft
Scenario: Media processing remains pending
- WHEN the upload reports pending or in-progress processing
- THEN the publisher checks status after the prescribed delay within a finite budget
- AND it creates a draft only after observing succeeded state
Scenario: Processing cannot establish usable media
- WHEN processing fails, exceeds its deadline, returns errors, or supplies inconsistent state
- THEN the publisher reports the media failure without creating a draft
- AND it does not retry the upload POST
Requirement: Credential-scoped media cache validity
Persistent media reuse SHALL be scoped to the upload endpoint, media category, and OAuth credential context without persisting plaintext credentials or requesting account identity merely to name the cache. Changing any credential field SHALL prevent reuse from the prior context. Unscoped legacy entries SHALL be treated as misses.
A persisted entry SHALL have a known positive lifetime, conservatively anchored before upload and accounting for processing time and a submission reserve. Missing or zero lifetime SHALL permit reuse only within the current resolution, never across resolutions or processes. Negative or already unusable upload lifetimes SHALL fail before draft creation.
Scenario: A token or account changes
- WHEN identical image bytes are submitted using a different credential context
- THEN the earlier context’s cached identifier is not reused
- AND the cache contains no credential values
Scenario: A response provides no known lifetime
- WHEN an upload response omits its lifetime or reports zero
- THEN identical banner and body images may share that fresh identifier within one resolution
- AND a later resolution uploads the bytes again
Scenario: Uploading or processing consumes the usable lifetime
- WHEN a positive reported lifetime has insufficient time remaining for submission
- THEN draft creation stops instead of attaching the expired or near-expiry identifier
Scenario: An earlier image expires before its later duplicate is resolved
- WHEN uploading another image consumes the usable lifetime of an identifier already selected for a banner or body image
- AND a later body image references those same bytes
- THEN resolution stops without uploading the duplicate again or creating a draft
- AND a replacement cache entry cannot mask the expired identifier already selected for the draft