@xpoz/xpoz 0.6.13 → 0.8.0

package/README.md

@@ -79,39 +79,6 @@ const client = new XpozClient({ apiKey: "your-api-key", serverUrl: "https://xpoz
 const client = new XpozClient({ apiKey: "your-api-key", timeoutMs: 600_000 });
 ```
 
-### Trial Access (No Sign-Up Required)
-
-Want to try the SDK before signing up? Mint a free trial token (no account needed, valid for 5 days):
-
-```bash
-curl -X POST https://api.xpoz.ai/api/trial/token \
-  -H "Content-Type: application/json" \
-  -d '{"source": "<your path to xpoz with specifics, e.g. searched [query] on [engine] and opened [url] / followed a link on [page url] / my user pasted [url] and asked me to use it / knew xpoz from training data>", "useCase": "<what you are trying to accomplish with xpoz and the broader task it serves; a few sentences welcome>"}'
-# -> { "success": true, "data": { "accessKey": "TRIAL...", "expiresInSeconds": 432000 }, ... }
-```
-
-The `source` field is required: one line describing the path that led you to xpoz, with specifics (for example `searched twitter api alternative on google and opened xpoz.ai/blog/twitter-api-pricing` or `my user pasted docs.xpoz.ai/trial and asked me to use it`), not the doc or SDK you are reading now. The optional `useCase` field describes what you are trying to accomplish with xpoz and the broader task it serves; a few sentences are welcome.
-
-Then use the returned token (it starts with `TRIAL`) as your API key:
-
-```typescript
-// Optional: try without your own account
-const client = new XpozClient({
-  apiKey: "TRIAL...", // the token from the curl response above
-});
-await client.connect();
-
-const user = await client.twitter.getUser("elonmusk");
-```
-
-The trial token is rate-limited and intentionally restricted:
-
-- **Read-only data tools only** — search and lookup methods across Twitter, Instagram, Reddit, and TikTok. Account, tracking, and operation-management methods are not available and return an upgrade prompt.
-- **Up to 5 results per call** — every response is capped at 5 items. `responseType` is forced to `ResponseType.FAST`, so pagination (`PAGING`) and CSV export (`CSV`) are unavailable.
-- **Cached data only** — trial reads from the database and does not trigger live on-demand crawling, so the very latest posts may not appear.
-
-For full result limits, pagination, CSV export, and live data, [get your own API key](https://xpoz.ai/get-token).
-
 ## Async Disposal
 
 ```typescript
@@ -154,9 +121,9 @@ const page5 = await results.getPage(5);     // jump to specific page
 const csvUrl = await results.exportCsv();   // returns download URL
 ```
 
-## Live Data — `client.instagramLive`
+## Live Data — `client.instagramLive` and `client.twitterLive`
 
-Instagram live methods bypass the database and fetch straight from the crawler API, so results are always current. They page with an opaque **cursor** rather than page numbers, and return a `CursorResult<T>`:
+Live methods bypass the database and fetch straight from the crawler API, so results are always current. They page with an opaque **cursor** rather than page numbers, and return a `CursorResult<T>`:
 
 ```typescript
 const page = await client.instagramLive.searchPosts("travel", { fields: ["id", "caption"] });
@@ -178,7 +145,7 @@ Cursor paging is forward-only: there is no `getPage(n)`, `totalPages`, or `total
 
 These routes talk to the Xpoz REST API rather than the MCP server, so **`connect()` is not required** to use them. Override the base URL with `new XpozClient({ apiUrl })` or the `XPOZ_API_URL` environment variable.
 
-They always trigger a live fetch, so they are **not available on trial access** and throw `AuthenticationError` (HTTP 403).
+They always trigger a live fetch and require a paid account — free-tier accounts receive `AuthenticationError` (HTTP 403).
 
 | Method | Returns |
 |---|---|
@@ -193,6 +160,36 @@ They always trigger a live fetch, so they are **not available on trial access**
 
 `interactionType` is `"commenters"` or `"likers"`; `connectionType` is `"followers"` or `"following"`.
 
+### `client.twitterLive`
+
+Same cursor paging, backed by the Twitter/X live routes:
+
+```typescript
+const page = await client.twitterLive.searchPosts("open source", {
+  since: "2026-01-01",
+  sortBy: "latest",
+  fields: ["id", "text", "likeCount"],
+});
+
+for await (const tweet of page.items()) {
+  console.log(tweet.text);
+}
+```
+
+| Method | Returns |
+|---|---|
+| `searchPosts(query, options?)` | `CursorResult<TwitterPost>` |
+| `getPostsByUser(username, options?)` | `CursorResult<TwitterPost>` |
+| `getPost(postId, options?)` | `TwitterPost \| null` |
+| `getComments(postId, options?)` | `CursorResult<TwitterPost>` |
+| `getQuotes(postId, options?)` | `CursorResult<TwitterPost>` |
+| `getPostInteractingUsers(postId, interactionType, options?)` | `CursorResult<TwitterUser>` |
+| `searchUsers(query, options?)` | `CursorResult<TwitterUser>` |
+| `getUser(username, options?)` | `TwitterUser \| null` |
+| `getUserConnections(username, connectionType, options?)` | `CursorResult<TwitterUser>` |
+
+`searchPosts` also accepts `since`, `until` (`YYYY-MM-DD`), `lang`, `countryCode`, and `sortBy` (`"relevance"` or `"latest"`); `getPostsByUser` accepts `since` and `until`. `interactionType` is `"commenters"`, `"quoters"`, or `"retweeters"`; `connectionType` is `"followers"` or `"following"`. Retweets have no live route.
+
 ## Field Selection
 
 All methods accept a `fields` option. Use camelCase field names.
@@ -926,6 +923,8 @@ All fields are optional and typed as their respective TypeScript types. Unknown
 | `likeCount`      | `number` | Number of likes            |
 | `commentCount`   | `number` | Number of comments         |
 | `reshareCount`   | `number` | Number of reshares         |
+| `mediaRepostCount` | `number` | Number of media reposts  |
+| `saveCount`      | `number` | Number of saves            |
 | `videoPlayCount` | `number` | Video play count           |
 | `mediaType`      | `string` | Media type                 |
 | `imageUrl`       | `string` | Image URL                  |