Skip to content
ContractSpec
Start here

Package manual · integrations

·Integrations and provider selection

integration.provider-x

Official X API read and scoped native publication adapters for ContractSpec.

integrationsintegrationv2.1.4experimentalservernode
@lssm-tech/integration.provider-x
bun add @lssm-tech/integration.provider-x
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Official X API v2 adapter and XSocialTrackingSource for explicitly connected users. It normalizes creator/post counters, timeline sync, and Account Activity webhook events. OAuth tokens are resolved through opaque references and never serialized; historical analytics remain explicitly unavailable.

Provider and tracking reads preserve the configured API prefix (including /2) for resource-relative paths. Origin substitution, path traversal and credential-bearing base URLs are rejected. Reads reject redirects and have a 30-second timeout. These repairs preserve the existing read surface. Native publication uses the separate adapter below.

./native-publication exposes XNativePublicationProvider for the scoped V2 social provider port. It supports one post or a self-reply thread with reviewed text, explicit AI/paid-partnership disclosure flags and pre-uploaded image/video/GIF assets. Media materialization includes both native IDs and media keys; confirmation checks attached keys/types rather than assuming that a successful create attached every asset.

A mandatory durable part store reserves the immutable plan and claims every part before POST. Creation IDs, submission times, scoped request digests, grant/authority references and read-confirmation facts remain persisted. Unknown requests are never resent. A read-only exact-request evidence loader may resolve an unknown ID; text similarity is not evidence. Explicitly authorized continuation sends only pending parts. The host rechecks the named publishing grant, rights, native access, reply eligibility, weighted text limits and per-part metering immediately before each post.

Use SqlXPublicationStore and configure this provider under providersV2.x. The canonical parent intent requires claimContinuation for interrupted thread execution. Native HTTP callbacks receive a separate immutable trace context; use it to bind recovery artifacts without adding internal IDs to API payloads or logging credentials.

Account-tier qualification and live publication remain installation work. Existing X reads and OAuth defaults are unchanged; no cookie or scraping fallback is provided. Native protocol references: create posts and media expansions.

./native-upload exposes XNativeUploadProvider for image, video and GIF uploads. Supply an approved immutable asset/chunk manifest, a SqlXUploadStore, current rights and account authority, scoped asset reads and credentials. Bounded run(plan, maxSteps) calls initialize, append verified chunks, finalize and poll native processing. Continue from the same plan/key; uncertain steps need exact request-bound transport evidence. The store retains references and hashes, not file bytes, bearer tokens or signed URLs.

xUploadedAsset in the library-owned x-upload-state contract checks scope, readiness and native expiry before producing the ID/key consumed by publication materialization. Hosts recheck rights at publication time and schedule polling from nextPollAt. Failed or expired uploads are terminal; replacing an asset requires a newly reviewed job key. Up to 500 chunks of 5 MB are supported; account/format-specific limits must be qualified before initialization. Cancellation and automatic retry of uncertain writes are unavailable.

Protocol: initialize, append, finalize, status.

./native-withdrawal implements the content-withdrawal provider port for a single bound X post. The host must verify the revoked use, historical account ownership, current removal authority and immutable job-to-post mapping. The adapter rechecks that binding after credential resolution and sends one official DELETE with no redirects/retries. Read-only recovery accepts only exact resource-not-found evidence; 401/403 and ambiguous responses remain unknown. Use with ContentWithdrawalWorker for durable dispatch claims. Official protocol: delete posts. Live account qualification and other-platform withdrawal adapters remain separate requirements.

Standalone declaration exports keep their existing public subpath names. The shared builder preserves their original declaration suffix and copies checked source declarations into dist, without overwriting emitted implementation types.

TS-01-P-SOCIAL

Weighted text qualifier (./text-weight, twitter-text, 280 weighted limit, refuse-never-rewrite), thread access qualification (qualifyXPublicationPlan, opt-in via deps.qualification), reply reader (./comments, 7-day window) and fixtures (./testing).

TS-01-SOC

Native publication re-fences member approvals: a request for a different publication kind or with a changed connectionVersion is refused before any provider request; X re-checks before every thread part and resume reports ambiguous. Supply currentConnectionVersion in the publication dependencies so the adapter can compare the approved connection version with the current one.

Relationships

THIS PACKAGEintegration.provider-x27 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

4 declarations

Declared capabilities

Integration Provider X

Official X API read adapters for ContractSpec.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • devcontractspec-bun-build dev
  • lint:checknode ../../../scripts/biome.cjs check .
  • lint:fixnode ../../../scripts/biome.cjs check --write .
  • prebuildcontractspec-bun-build prebuild
  • testbun test
  • typechecktsgo --noEmit