@usesocial/cli 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @usesocial/cli
 
+## 0.8.0
+
+### Minor Changes
+
+- [#33](https://github.com/usesocial/monorepo/pull/33) [`abb6401`](https://github.com/usesocial/monorepo/commit/abb64017354f4607a25d321f115d5063ad3d4117) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Remove `social account config cache mode`; configure live-read proxy caching with `social account config cache ttl` only.
+
+- [#33](https://github.com/usesocial/monorepo/pull/33) [`2c315ba`](https://github.com/usesocial/monorepo/commit/2c315ba6ba0f8279b9bad05928450d5666476627) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Add sync `--timeout` rate-limit wait budgets and resumable rate-limit abort guidance.
+
+- [#33](https://github.com/usesocial/monorepo/pull/33) [`76d03f2`](https://github.com/usesocial/monorepo/commit/76d03f21d6e2e2214f85338c8cb13c4eae2a96c3) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Rebuild the local SQL mirror as curated views and slim the schema surfaces.
+
+  - Every cache table is now a view over a `<name>_raw` physical table. Views drop `raw`/`synced_at` (a `SELECT *` row is ~5× smaller) and normalize names across platforms: `username`/`name`/`avatar_url` everywhere, `created_at` (was `timestamp`), `conversation_id` (was `chat_id`/`dm_conversation_id`), `last_message_at`, `is_mentioned`, `*_distance`. Upstream JSON stays queryable in the `_raw` twins via `json_extract(raw, '$.field')`. Existing caches migrate automatically.
+  - Promoted raw fields: `li_requests.message` (invitation note text) and `x_profiles.receives_your_dm`.
+  - `li_posts` is a curated ~29-column view; the quoted-post/permissions long tail lives in `li_posts_raw`.
+  - Bare `social <platform> sql` now prints compact schema metadata — column lists, row counts, `synced_at`, `query_ready`, indexed columns, join hints, and enum values — instead of raw `CREATE TABLE` statements (~35% smaller).
+  - `social schema` output is leaner: the redundant `params` field is gone (use `args`/`flags`/`inputSchema`), `schemaVersion` prints once at the root, and empty `subCommands` are omitted (`--leaves` is ~26% smaller).
+  - `sql` contract examples are projected queries on `x_followers`, `x_following`, and `li_connections`.
+
 ## 0.7.1
 
 ### Patch Changes

package/README.md

@@ -25,6 +25,12 @@ Published as `@usesocial/cli` on npm; the binary is `social`.
 curl -fsSL https://usesocial.dev/install.sh | bash
 ```
 
+Or with Homebrew:
+
+```sh
+brew install usesocial/tap/cli
+```
+
 ## Quickstart
 
 ```sh
@@ -56,7 +62,7 @@ marked **local** update local CLI state or the local mirror.
 
 ### Targets
 
-Targets accept handles, profile/post/conversation/company URLs, LinkedIn URNs,
+Targets accept usernames, profile/post/conversation/company URLs, LinkedIn URNs,
 or typed IDs such as `profile_id:<id>`, `post_id:<id>`, `chat_id:<id>`,
 `conversation_id:<id>`, `company_id:<id>`, and `request_id:<id>`. Bare IDs are
 not accepted.
@@ -69,25 +75,46 @@ freeform text from stdin. There is no text positional:
 ```sh
 echo "gm" | social x post
 social linkedin post < draft.md
-social linkedin requests send @handle < note.txt
+social linkedin requests send @username < note.txt
 ```
 
 Pipe a JSON object for advanced payload fields.
 
-## Your data is local
+### Pagination
+
+Live list reads take `--limit`. X lists and LinkedIn `posts`/`connections`
+continue with `--cursor` from `.meta.cursor`; LinkedIn `search`, `comments`,
+`reactions`, and `jobs` continue with `--offset`. `sql` does not paginate —
+use SQL `LIMIT` and `ORDER BY`.
+
+### Your data is local
 
 `sync` pulls your own data down; it is explicit and costs credits. `sql` queries
 that local mirror; it is free, instant, and read-only. Named read commands call
 the live network and cost credits; `x tweets <target>` and
 `linkedin posts <target>` require a target. Writes act.
 
+`sync <collection> --since 2026-05-04` (ISO date or datetime) pulls only newer
+items where the bare `sync` listing shows `supportsSince: true` — cheaper than a
+full re-pull. `sync <collection> --reset` clears a collection's local
+rows and sync state so the next sync rebuilds it.
+`sync <collection> --timeout 900` opts into a wall-clock wait budget, in seconds,
+for rate-limit handling. LinkedIn sync may sleep and retry while the next wait
+fits the budget; X keeps its current no-new-retry behavior.
+
+Rate-limit JSON includes `retryAfterSeconds`, `resumeAt`, `retryCommand`,
+`hint`, and `syncResume`. When `syncResume.cursorPersisted` is true, already
+synced pages are saved and the listed `retryCommand` resumes from the saved
+cursor. For parent/child message syncs, the hint says when an exact cursor
+resume is not safe and the re-run may re-fetch unfinished pages.
+
 ```sh
 social x sync messages
-social x sql "SELECT sender_handle, text, datetime(created_at/1000,'unixepoch') AS at FROM x_messages ORDER BY created_at DESC LIMIT 20" \
+social x sql "SELECT sender_username, text, datetime(created_at/1000,'unixepoch') AS at FROM x_messages ORDER BY created_at DESC LIMIT 20" \
   | jq '.items[]'
 ```
 
-The X inbox query gets `sender_handle` from the `x_messages` view; no extra
+The X inbox query gets `sender_username` from the `x_messages` view; no extra
 profile lookup is needed.
 
 ### Top level
@@ -117,26 +144,25 @@ profile lookup is needed.
 | `billing portal` | Open the hosted billing portal and print its URL. | |
 | `usage` | Aggregate proxy calls and credits. | |
 | `logs` | Recent proxy calls. | |
-| `config cache mode` | Read or set the live-read proxy cache mode. | |
-| `config cache ttl` | Set a live-read proxy cache TTL in seconds. | |
+| `config cache ttl` | Read or set the live-read proxy cache TTL in seconds. | |
 
 ### `social linkedin`
 
 | Command | Description | |
 | --- | --- | --- |
 | `profile [target]` | Fetch a profile; omit target for your own account. | |
-| `posts <target>` | Live posts for a person or company; target required. Supports `--limit` and `--cursor` from `.meta.cursor`. | |
-| `comments <target>` | List a post's comments; supports `--limit` and `--offset`. | |
-| `reactions <target>` | List a post's reactions; supports `--limit` and `--offset`. | |
-| `connections [target]` | Live connection graph read; omit target for your own account. Supports `--limit` and `--cursor` from `.meta.cursor`. Costs credits. | |
+| `posts <target>` | Live posts for a person or company; target required. | |
+| `comments <target>` | List a post's comments. | |
+| `reactions <target>` | List a post's reactions. | |
+| `connections [target]` | Live connection graph read; omit target for your own account. Costs credits. | |
 | `company <target>` | Fetch a company profile. | |
-| `jobs <target>` | List a company's job postings; supports `--limit` and `--offset`. | |
-| `search people\|posts\|jobs\|companies <keywords>` | Search LinkedIn; live offset-paginated reads. | |
+| `jobs <target>` | List a company's job postings. | |
+| `search people\|posts\|jobs\|companies <keywords>` | Search LinkedIn. | |
 | `sync [collection]` | Pull your own `connections`, `posts`, `messages`, or `requests` into the local mirror; costs credits. | local |
-| `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints the schema. | |
+| `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints compact schema metadata. | |
 | `post` | Create a post (body from stdin). | write |
 | `comment <target>` | Comment on a post (body from stdin). | write |
-| `react <target>` | React to a post or comment; use `--type` for non-like reactions. | write |
+| `react <target>` | React to a post; use `--type` for non-like reactions. | write |
 | `requests send <target>` | Send a connection request (optional note from stdin). | write |
 | `requests accept request_id:<id>` | Accept a received connection request. | write |
 | `requests cancel request_id:<id>` | Cancel a sent request or refuse a received connection request. | write |
@@ -163,7 +189,7 @@ profile lookup is needed.
 | `likers <target>` | List users who liked a post. | |
 | `reposters <target>` | List users who reposted a post. | |
 | `sync [collection]` | Pull your own `tweets`, `followers`, `following`, `bookmarks`, or `messages` into the local mirror; costs credits. | local |
-| `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints the schema. | |
+| `sql [query]` | Query your synced local mirror with read-only SQL - free; bare `sql` prints compact schema metadata. | |
 | `post` | Create a post (body from stdin). | write |
 | `message <recipients>` | Send a DM (body from stdin). | write |
 | `like <target>` / `unlike <target>` | Like or unlike a post. | write |
@@ -184,7 +210,7 @@ profile lookup is needed.
 ```sh
 # SQL insight: synced contacts you have never messaged.
 # Run `social linkedin sync connections` and `social linkedin sync messages` first.
-social linkedin sql "SELECT c.user_display_name, c.user_public_identifier, c.user_profile_url FROM li_connections c LEFT JOIN li_messages m ON m.sender_id = c.user_id WHERE m.id IS NULL ORDER BY c.created_at DESC LIMIT 100" \
+social linkedin sql "SELECT c.user_name, c.user_username, c.user_profile_url FROM li_connections c LEFT JOIN li_messages m ON m.sender_id = c.user_id WHERE m.id IS NULL ORDER BY c.created_at DESC LIMIT 100" \
   | jq '.items[]'
 
 # Live fan-out: review recent posts, fan out to reactions, rank warm contacts.
@@ -192,8 +218,8 @@ social linkedin posts profile_id:<profile-id> --limit 25 > /tmp/recent-posts.jso
 jq -r '.items[].id' /tmp/recent-posts.json \
   | xargs -I{} social linkedin reactions post_id:{} --limit 100 --offset 0 \
   | jq -s '[ .[] | .items[] ]
-            | group_by(.actor.id // .reactor.id // .profile_id)
-            | map({person: (.[0].actor // .[0].reactor), signals: length})
+            | group_by(.sender.id)
+            | map({person: .[0].sender, signals: length})
             | sort_by(-.signals) | .[0:15]'
 ```
 
@@ -206,7 +232,7 @@ jq -r '.items[].id' /tmp/recent-posts.json \
 | `3` | Not found | Check the resource ID or pick a different item. |
 | `4` | Auth or scope error | Run `social account login`, or log out and choose the needed scope. |
 | `5` | API, proxy, or unexpected error | Retry later or surface the server error. |
-| `7` | Rate limited | Back off, using `retryAfterSeconds` when present. |
+| `7` | Rate limited | Back off, using `retryAfterSeconds`, `resumeAt`, and `retryCommand` when present. |
 
 ## Auth
 
@@ -230,26 +256,22 @@ The proxy cache applies to live reads only. Cache hits are free; fresh upstream
 reads are metered. Configure the default:
 
 ```sh
-social account config cache mode
-social account config cache mode live
-social account config cache mode analytical
-social account config cache mode historical
 social account config cache ttl 3600
 ```
 
 Override one live read when the command lists `--header`:
 
 ```sh
-social linkedin profile @handle -H "Cache-Control: no-cache"
-social linkedin profile @handle -H "Cache-Control: no-store"
-social linkedin profile @handle -H "Cache-Control: max-age=60"
+social linkedin profile @username -H "Cache-Control: no-cache"
+social linkedin profile @username -H "Cache-Control: no-store"
+social linkedin profile @username -H "Cache-Control: max-age=60"
 ```
 
 The local mirror is separate: run `sync` when you want newer local data, then
 query it with `sql`. SQL reads show local freshness in `meta.cache.tables`:
 
 ```sh
-social x sql "SELECT sender_handle, text FROM x_messages ORDER BY created_at DESC LIMIT 5" \
+social x sql "SELECT sender_username, text FROM x_messages ORDER BY created_at DESC LIMIT 5" \
   | jq '{cost: .meta.cost, cache: .meta.cache}'
 social x timeline --limit 20 | jq '{cost: .meta.cost, cursor: .meta.cursor, cache: .meta.cache}'
 ```
@@ -263,8 +285,8 @@ Agents should watch `.meta.cost` during high-fanout loops, use
 ```sh
 # LinkedIn local mirror.
 social linkedin sync messages
-social linkedin sql "SELECT sender_display_name, text, datetime(timestamp/1000,'unixepoch') AS at FROM li_messages ORDER BY timestamp DESC LIMIT 20"
-social linkedin sql "SELECT user_display_name, user_public_identifier FROM li_requests WHERE type='received' ORDER BY created_at DESC LIMIT 25"
+social linkedin sql "SELECT sender_name, text, datetime(created_at/1000,'unixepoch') AS at FROM li_messages ORDER BY created_at DESC LIMIT 20"
+social linkedin sql "SELECT user_name, user_username FROM li_requests WHERE type='received' ORDER BY created_at DESC LIMIT 25"
 
 # LinkedIn live reads.
 social linkedin profile
@@ -275,7 +297,7 @@ social linkedin reactions post_id:<post-id> --limit 100 --offset 0
 
 # X local mirror.
 social x sync messages
-social x sql "SELECT sender_handle, text FROM x_messages ORDER BY created_at DESC LIMIT 20"
+social x sql "SELECT sender_username, text FROM x_messages ORDER BY created_at DESC LIMIT 20"
 social x sql "SELECT text, url FROM x_bookmarks ORDER BY created_at DESC LIMIT 50"
 social x sql "SELECT username, name, followers_count FROM x_followers ORDER BY followers_count DESC LIMIT 100"