Metadata-Version: 2.4
Name: navig-social
Version: 0.2.0
Summary: NAVIG Social module — compose, schedule & publish across social networks (Studio + one-call fan-out). A first-party navig plugin (free, toggleable).
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,automation,plugin,social,publishing,tiktok,instagram
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.15.0
Requires-Dist: navig-vault>=0.7.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: requests>=2.25.0
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Dynamic: license-file

# navig-social

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Compose, schedule & publish across social networks (Studio + one-call fan-out).

**Works on its own** — its own CLI, no navig required · v0.2.0 · [PyPI](https://pypi.org/project/navig-social/)

**On its own** (no navig needed)

```bash
pip install navig-social
navig-social --help   # no navig needed
```

**With navig**

```bash
pip install "navig[social]"
navig social --help
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig facebook backup` | Download EVERY uploaded photo at full resolution + a manifest. Do this before deleting. |
| `navig facebook caption` | Edit one photo's caption (best-effort; some photos reject edits). |
| `navig facebook check` | Verify the token works and show which Page it controls. |
| `navig facebook delete` | Delete a single photo (permanent). |
| `navig facebook delete-all` | Delete every uploaded photo that is already backed up (never un-backed ones). |
| `navig facebook info` | Show the Page's current about / description / category / contact fields. |
| `navig facebook photos` | Count and preview the Page's uploaded photos. |
| `navig facebook set-about` | Update the Page's about / description / category text. |
| `navig fb backup` | Download EVERY uploaded photo at full resolution + a manifest. Do this before deleting. |
| `navig fb caption` | Edit one photo's caption (best-effort; some photos reject edits). |
| `navig fb check` | Verify the token works and show which Page it controls. |
| `navig fb delete` | Delete a single photo (permanent). |
| `navig fb delete-all` | Delete every uploaded photo that is already backed up (never un-backed ones). |
| `navig fb info` | Show the Page's current about / description / category / contact fields. |
| `navig fb photos` | Count and preview the Page's uploaded photos. |
| `navig fb set-about` | Update the Page's about / description / category text. |
| `navig social connect` | Authorize an account and store its access token in the vault. |
| `navig social disconnect` | Remove a provider's stored access token (app credentials are kept). |
| `navig social engagement` | Record engagement for a campaign — the *measure* side of the loop. |
| `navig social fan-out` | Publish ONE brief to many networks (X · Facebook · Dev.to · Telegram) with UTM tags. |
| `navig social presence crawl` | Crawl every account in a space's registry and record what moved. |
| `navig social presence trend` | First → latest movement for every tracked account, across all snapshots. |
| `navig social receipts` | What we've published — a campaign-tagged ledger of every live fan-out. |
| `navig social redirect-uri` | Print the redirect URLs to register in each provider's app settings. |
| `navig social refresh` | Renew an expiring access token in place (uses stored refresh/app creds). |
| `navig social report` | Campaign scorecard — how did it do? Joins what you published (receipts) with |
| `navig social stats` | Public follower / subscriber / view counts for ANY handle — no space, no linked account. |
| `navig social status` | Show which networks are connected (and, with --check, whether tokens work). |
| `navig social sync` | Pull live view/like counts from each network → the report's CTR goes real. |
| `navig social upload` | Upload a video file to YouTube (fan-out publishes text; this publishes a file). |

</details>

<!-- navig:plugin-card:end -->

NAVIG **Social** — compose and publish across social networks, track what each post did, and
watch your own accounts over time. It runs on its own as `navig-social`, and inside navig as
`navig social` / `navig facebook`.

## On its own

```bash
pip install navig-social                          # adds the `navig-social` command
navig-social connect linkedin                     # OAuth in the browser; the token goes to the vault
navig-social fan-out --file brief.json --to x,linkedin,devto --dry-run
navig-social stats youtube @mkbhd --only-public   # public counts for any handle
navig-social facebook info                        # Facebook Page tools (`navig facebook` inside navig)
```

Tokens live in the shared encrypted vault (`navig-vault`), the same one navig reads. App
credentials for `connect` come from the vault or the environment (`LINKEDIN_CLIENT_ID`,
`LINKEDIN_CLIENT_SECRET`, …); non-secret settings such as a Facebook page id come from
`config.yaml` or `NAVIG_FACEBOOK_PAGE_ID`-style variables. Receipts and engagement are recorded
in the same databases navig uses, so nothing moves when you install navig later.

Part of navig, and they say so when used without it: posting to **Telegram / Discord** (navig's
own bot), the **Studio** deck and its scheduler (navig's daemon), and **browser-backed stats**
(navig's managed browser; `--only-public` needs no browser). `presence` takes a space's folder
path on its own (`--space ./my-space`); space names need navig.

## Inside navig

## What it does

- **Publish** to X/Twitter, Facebook Page, LinkedIn, Reddit, Instagram, Threads,
  Pinterest, Dev.to (and Telegram) through a common `BasePublisher` framework.
- **Fan-out** — publish one brief to many networks in a single call, with per-platform
  adaptation + UTM tagging: `navig social fan-out --file brief.json --to x,facebook,devto,telegram`.
- **Connect** — one-command OAuth: `navig social connect <network>` (vault-backed tokens).
- **Facebook Page admin** — `navig facebook` (`fb`): check/info/set-about/photos/backup/caption/delete.
- **Studio** — the deck composer + scheduler (`/api/deck/studio/*`), fed by the background
  `ScheduledPostService`.

## Commands

```
navig social status [--check]            # connected networks
navig social connect <network>           # OAuth connect (vault-backed)
navig social fan-out --file brief.json --to x,facebook,devto,telegram [--dry-run]
navig social stats <platform> <handle>   # PUBLIC follower/view counts for ANY handle (no account link)
navig social presence crawl --space <s>  # crawl YOUR whole roster → dated snapshot + deltas
navig social presence trend  --space <s> # first → latest movement, no re-crawl
navig facebook check | info | photos | backup | caption | delete   (alias: navig fb)
```

## Presence — your own accounts, over time

`stats` answers *"what is this handle's count right now"*. `presence` answers the question a
portfolio owner actually asks: *"what are ALL my accounts, and what moved since last time?"*

It reads the roster from `<space>/.navig/memory/account-registry.json`, crawls each account
through the same engine, and writes `<space>/analytics/raw/_snapshots/presence-YYYY-MM-DD.json`,
diffing against the previous snapshot so no verdict is ever made on numbers of unknown age.

```
navig social presence crawl --space human-presence --only-public   # no browser, API/public only
navig social presence crawl --space human-presence --brand somaleto --dry-run
navig social presence trend  --space human-presence --platform telegram
```

- `--only-public` keeps it to plain HTTPS + official APIs — no CDP, no login, cron-safe.
- Successful counts are written back to the registry (`--no-write-registry` to skip). A failed or
  login-walled fetch **never** overwrites the last number actually observed.
- Accounts marked `"snapshot_status": "dead"` are skipped, so a retired handle stops being
  re-crawled and stops counting as a failure.
- Public metadata only. No tokens, cookies or session data are read from or written to the space.

Schedule it so the numbers are never stale:

```
navig cron add --name presence-weekly --schedule "0 9 * * 1" \
  --command "navig social presence crawl --space human-presence --only-public"
```

## Install

Bundled with a full `navig` install (the `social` extra); standalone:
`navig store install pip:navig-social` — or `pip install navig-social` once published.
Requires `navig-core` in the same environment.

Credentials live in the NAVIG vault (`navig vault`) + config `adapters.social.<network>.*`.
Tokens are never printed.
