docs: refine Java SDK copy (#56)

Signed-off-by: kriptoburak <kriptoburak@users.noreply.github.com>
Co-authored-by: kriptoburak <kriptoburak@users.noreply.github.com>

Author: Burak Bayır

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.10.2"
+  ".": "0.10.3"
 }

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.10.3 (2026-08-21)
+
+Full Changelog: [v0.10.2...v0.10.3](https://github.com/Xquik-dev/x-twitter-scraper-java/compare/v0.10.2...v0.10.3)
+
+### Documentation
+
+* tighten Java setup and API guidance
+
 ## 0.10.2 (2026-08-20)
 
 Full Changelog: [v0.10.1...v0.10.2](https://github.com/Xquik-dev/x-twitter-scraper-java/compare/v0.10.1...v0.10.2)

OPENSSF.md

@@ -8,11 +8,7 @@ Assessment date: 2026-07-24.
 
 ## Eligibility
 
-This public Java SDK is active and released.
-
-It is eligible for the OpenSSF Best Practices badge.
-
-No OpenSSF-defined ineligibility applies.
+This active, public Java SDK qualifies for the OpenSSF Best Practices badge.
 
 ## Verified Technical Controls
 
@@ -36,17 +32,11 @@ No OpenSSF-defined ineligibility applies.
 | CI | Pull requests and pushes run pinned, least-privilege workflows |
 | Two-factor authentication | The Xquik-dev organization requires 2FA |
 
-The maintained-source gate covers 1,198 of 1,319 executable lines.
-
-That result is 90.83% line coverage.
+The maintained-source gate covers 1,198 of 1,319 executable lines (90.83%).
 
 It covers 424 of 520 branches, or 81.54%.
 
-The raw report keeps untouched generated-source coverage visible.
-
-It covers 104,652 of 110,632 generated-inclusive lines, or 94.59%.
-
-It covers 27,560 of 30,010 generated-inclusive branches, or 91.84%.
+The raw report covers 104,652 of 110,632 generated-inclusive lines (94.59%) and 27,560 of 30,010 branches (91.84%).
 
 Exclusions use the repository-owned, provider-neutral generated-source header prefix.
 
@@ -68,15 +58,15 @@ The license report covers 100 resolved runtime and test components.
 
 Jazzer completed 3,544,654 retry-header iterations during this assessment.
 
-Maven Central published `v0.5.2` from the exact release tag.
+Maven Central published `v0.10.2` from the exact release tag.
 
 All 15 public files verify with this OpenPGP fingerprint:
 
 `6965 E561 C0AC EE32 060A B961 D203 7E41 57E6 2A59`
 
 The root JAR SHA-256 is:
 
-`87a9b770f16b32d016fac4220a5ec626d32871e692d9b7bc8d261be8e0a58e89`
+`7c0ba8741e41eae3c13f5d47e91e100668862b1ae03f57832bfa513e9e5b2393`
 
 ## Outstanding Gold Blockers
 

README.md

@@ -3,31 +3,28 @@
 [![CI](https://github.com/Xquik-dev/x-twitter-scraper-java/actions/workflows/ci.yml/badge.svg)](https://github.com/Xquik-dev/x-twitter-scraper-java/actions/workflows/ci.yml)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13735/badge)](https://www.bestpractices.dev/projects/13735)
 
-Use the Xquik Java SDK for Twitter search, timelines, profiles & followers.
-Manage media, webhooks & X automation with typed Java methods.
-It provides a Twitter API alternative through documented Xquik REST routes.
+Search Twitter, read timelines, fetch profiles & export followers with Xquik.
+Use typed Java methods for media, webhooks & X automation.
 
-[API Reference](https://docs.xquik.com/api-reference/overview) | [Authentication](https://xquik.com/auth.md) | [Javadocs](https://javadoc.io/doc/com.xquik.api/x-twitter-scraper-java)
+[API Reference](https://docs.xquik.com/api-reference/overview) | [Authentication](https://xquik.com/auth.md) | [Javadocs](https://javadoc.io/doc/com.xquik.api/x-twitter-scraper-java-core)
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.xquik.api/x-twitter-scraper-java)](https://central.sonatype.com/artifact/com.xquik.api/x-twitter-scraper-java/0.10.2)
-[![Javadocs](https://javadoc.io/badge2/com.xquik.api/x-twitter-scraper-java/0.10.2/javadoc.svg)](https://javadoc.io/doc/com.xquik.api/x-twitter-scraper-java/0.10.2)
+[![Maven Central](https://img.shields.io/maven-central/v/com.xquik.api/x-twitter-scraper-java)](https://central.sonatype.com/artifact/com.xquik.api/x-twitter-scraper-java/0.10.3)
+[![Javadocs](https://javadoc.io/badge2/com.xquik.api/x-twitter-scraper-java-core/0.10.3/javadoc.svg)](https://javadoc.io/doc/com.xquik.api/x-twitter-scraper-java-core/0.10.3)
 
 <!-- x-release-please-end -->
 
-## Choose the Java SDK
+## Java Client
 
-Choose this client for Java services using builders and typed models.
+Use this SDK for Java services with builders and typed models.
 Use synchronous calls or `client.async()` for `CompletableFuture` pipelines.
 
 ## Common Twitter & X Tasks
 
-Map each task to its REST route and Java service.
-
 | Task | REST Route | Java Service |
 | --- | --- | --- |
-| Search tweets without the X API | `GET /x/tweets/search` | `client.x().tweets()` |
+| Run an advanced Twitter search | `GET /x/tweets/search` | `client.x().tweets()` |
 | Retrieve tweets, threads, replies, or quotes | `GET /x/tweets/{id}`, `GET /x/tweets/{id}/thread` | `client.x().tweets()` |
 | Search X or Twitter users | `GET /x/users/search` | `client.x().users()` |
 | Scrape an X profile timeline | `GET /x/users/{id}/tweets` | `client.x().users()` |
@@ -55,7 +52,7 @@ Map each task to its REST route and Java service.
 Gradle:
 
 ```kotlin
-implementation("com.xquik.api:x-twitter-scraper-java:0.10.2")
+implementation("com.xquik.api:x-twitter-scraper-java:0.10.3")
 ```
 
 Maven:
@@ -64,7 +61,7 @@ Maven:
 <dependency>
   <groupId>com.xquik.api</groupId>
   <artifactId>x-twitter-scraper-java</artifactId>
-  <version>0.10.2</version>
+  <version>0.10.3</version>
 </dependency>
 ```
 
@@ -96,7 +93,7 @@ export X_TWITTER_SCRAPER_API_KEY="your-api-key"
 
 OAuth users can set `X_TWITTER_SCRAPER_BEARER_TOKEN` instead.
 
-Create 1 client and reuse it:
+Create one client and reuse it:
 
 ```java
 import com.x_twitter_scraper.api.client.XTwitterScraperClient;
@@ -105,7 +102,7 @@ import com.x_twitter_scraper.api.client.okhttp.XTwitterScraperOkHttpClient;
 XTwitterScraperClient client = XTwitterScraperOkHttpClient.fromEnv();
 ```
 
-You can also pass credentials directly:
+Pass credentials directly when needed:
 
 ```java
 XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
@@ -123,7 +120,7 @@ Supported client settings:
 
 System properties override environment variables.
 
-## Search Posts
+## Search Tweets
 
 ```java
 import com.x_twitter_scraper.api.models.x.tweets.TweetSearchParams;
@@ -165,7 +162,7 @@ XTwitterScraperClient client = XTwitterScraperOkHttpClient.builder()
     .build();
 ```
 
-Xquik may return a successful HTTP response with a structured API error. Handle its documented code.
+Successful HTTP responses can contain structured API errors. Handle documented codes.
 
 ## Read Raw Responses
 

build.gradle.kts

@@ -36,7 +36,7 @@ licenseReport {
 
 allprojects {
     group = "com.xquik.api"
-    version = "0.10.2" // x-release-please-version
+    version = "0.10.3" // x-release-please-version
 
     dependencyLocking {
         lockAllConfigurations()

scripts/fast-format

@@ -6,43 +6,34 @@
 
 set -euo pipefail
 
-echo "Script started with $# arguments"
-echo "Arguments: $*"
-echo "Script location: $(dirname "$0")"
-
 cd "$(dirname "$0")/.."
-echo "Changed to directory: $(pwd)"
 
 if [ $# -eq 0 ]; then
     echo "Usage: $0 <file-with-paths> [additional-formatter-args...]"
-    echo "The file should contain one file path per line"
+    echo "Provide one file path per line."
     exit 1
 fi
 
 FILE_LIST="$1"
 
-echo "Looking for file: $FILE_LIST"
-
 if [ ! -f "$FILE_LIST" ]; then
-    echo "Error: File '$FILE_LIST' not found"
+    echo "File list not found: $FILE_LIST. Check the path."
     exit 1
 fi
 
 if ! command -v ktfmt &> /dev/null; then
-    echo "Error: ktfmt not found"
+    echo "ktfmt is unavailable. Install it first."
     exit 1
 fi
 
 # Process Kotlin files
-echo "==> Looking for Kotlin files"
 kt_files=$(grep -E '\.kt$' "$FILE_LIST" | grep -v './buildSrc/build/' || true)
-echo "==> Done looking for Kotlin files"
 
 if [[ -n "$kt_files" ]]; then
-    echo "==> will format Kotlin files"
+    echo "==> Formatting Kotlin files"
     echo "$kt_files" | tr '\n' '\0' | xargs -0 ktfmt --kotlinlang-style "$@"
 else
-    echo "No Kotlin files to format -- expected outcome during incremental formatting"
+    echo "No Kotlin files found. Nothing to format."
 fi
 
 # TODO(mbudayr): support palantir-java-format