@usesocial/cli 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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
+
+- [#32](https://github.com/usesocial/monorepo/pull/32) [`b2ca106`](https://github.com/usesocial/monorepo/commit/b2ca106f970bfe73d776f3f10225df7c6c7a1b80) Thanks [@CyrusNuevoDia](https://github.com/CyrusNuevoDia)! - Use cursor pagination for `social linkedin posts` so the CLI matches the LinkedIn
+  posts provider contract.
+
 ## 0.7.0
 
 ### Minor 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
@@ -115,10 +142,9 @@ profile lookup is needed.
 | `disconnect x <account>` | Disconnect an X account. | write |
 | `billing` | Show seats, subscription, and current usage billing. | |
 | `billing portal` | Open the hosted billing portal and print its URL. | |
-| `usage` | Aggregate proxy usage and billing stats. | |
+| `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`
 
@@ -126,17 +152,17 @@ profile lookup is needed.
 | --- | --- | --- |
 | `profile [target]` | Fetch a profile; omit target for your own account. | |
 | `posts <target>` | Live posts for a person or company; target required. | |
-| `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. | |
+| `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 |
@@ -175,24 +201,25 @@ profile lookup is needed.
 ## Built for agents
 
 - Everything speaks JSON: success on stdout, structured errors on stderr.
-- One envelope: lists use `.items[]`, single resources use `.data`, metadata
-  lives under `.meta`.
+- Platform reads return one envelope: lists use `.items[]`, single resources use
+  `.data`, metadata lives under `.meta`. `social account` service commands return
+  bare JSON; `account logs` returns `{ items, meta: { cursor } }`.
 - Schema-backed planning: `social schema --list` is the compact runnable index.
 - Local SQL is the free surface for your own synced data.
 
 ```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.
-social linkedin posts profile_id:<profile-id> --limit 25 --offset 0 > /tmp/recent-posts.json
+social linkedin posts profile_id:<profile-id> --limit 25 > /tmp/recent-posts.json
 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]'
 ```
 
@@ -205,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
 
@@ -229,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}'
 ```
@@ -262,17 +285,19 @@ 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
-social linkedin posts profile_id:<profile-id> --limit 25 --offset 0
+PAGE1=$(social linkedin posts profile_id:<profile-id> --limit 25)
+NEXT=$(echo "$PAGE1" | jq -r '.meta.cursor // empty')
+[ -n "$NEXT" ] && social linkedin posts profile_id:<profile-id> --limit 25 --cursor "$NEXT"
 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"
 
@@ -290,7 +315,8 @@ echo "Loved your launch notes." | social linkedin requests send profile_id:<prof
 social account billing
 social account billing portal
 social account usage
-social account logs --limit 20 --from 2026-05-01T00:00:00Z
+social account logs --limit 20 --from 2026-05-01T00:00:00Z \
+  | jq -r '.items[] | [.createdAt, .platform, .method, .path, .responseStatus, .cacheStatus, .credits] | @tsv'
 
 # Command schema.
 social schema