Social Media Management

# Social Media

**Nexus One / Odoo 17 module**
**Author:** Brand Works App
**Technical name:** `nexus_one_social_media`

Social Media gives users a Later-style publishing workspace inside Nexus One: connected profiles above a reusable media library on the left, a drag-and-drop social calendar in the center, and a modern post composer for drafting, scheduling, and publishing.

## What is included

- Custom Nexus One OWL dashboard with Month, Week, and List views.
- Drag creatives from the left media library onto a calendar day; Nexus One calculates the date and 30-minute time from the drop position and opens the composer already filled in.
- Existing unpublished posts can also be dragged to a new date and time.
- Multiple connected social profiles with OAuth handshake status.
- Image and video media library with secure provider-download URLs and byte-range support.
- Multi-select creative management with select-all-visible, clear selection, and protected bulk deletion.
- Draft, scheduled, immediate, published, partial, failed, and cancelled states.
- One post can target multiple connected profiles.
- Per-destination publication result, external ID, external URL, response, and error.
- One-minute scheduled publishing cron.
- Token refresh support for X, Pinterest, YouTube, and TikTok when a refresh token is available.
- Provider API settings, profile management, backend post views, media views, and audit history.
- Company-based security rules and Social Media User / Social Media Manager groups.

## Supported publishing in this release

| Network | Connection | Publishing support |
|---|---|---|
| Facebook Pages | Meta OAuth | Text, link, image, multi-image, video |
| Instagram Professional | Meta OAuth through linked Facebook Page | Image, carousel, Reel/video |
| LinkedIn member profile | LinkedIn OAuth | Text, link, one image |
| X | OAuth 2.0 PKCE | Text and links |
| Pinterest | Pinterest OAuth | Image Pin to the selected default board |
| YouTube | Google OAuth | Video upload; defaults to private |
| TikTok | TikTok OAuth | Video Direct Post by pull-from-URL |

Platform access is governed by each network. Public production use can require app review, product approval, business verification, verified domains, or paid API access.

## Install

1. Copy `nexus_one_social_media` into a Nexus One addons directory.
2. Restart the Nexus One service/container.
3. Update the Apps list.
4. Install **Social Media**.
5. Give staff either **Social User** or **Social Manager** in user access rights.
6. Open **Social Media → Configuration → API Settings**.

Example Docker update:

```bash
docker exec -it <nexus_container> bash -lc \
"python3 /opt/NexusOne/odoo-bin -c /etc/odoo/nexusmain.conf -d '<database>' -u nexus_one_social_media --stop-after-init"
```

Use the actual container, configuration path, and database name for the Nexus One environment.

## Required base URL

Set Nexus One's `web.base.url` to the public HTTPS domain before copying callback URLs:

```text
https://your-nexus-domain.com
```

Every API Settings record displays its exact callback URL. The standard routes are:

```text
https://your-nexus-domain.com/nexus_social/oauth/meta/callback
https://your-nexus-domain.com/nexus_social/oauth/linkedin/callback
https://your-nexus-domain.com/nexus_social/oauth/x/callback
https://your-nexus-domain.com/nexus_social/oauth/pinterest/callback
https://your-nexus-domain.com/nexus_social/oauth/youtube/callback
https://your-nexus-domain.com/nexus_social/oauth/tiktok/callback
```

## Keys and platform setup

### Meta — Facebook and Instagram

Enter:

- **Client ID:** Meta App ID
- **Client Secret:** Meta App Secret
- **Optional API version:** the Graph API version enabled for the app

Requested permissions:

```text
pages_show_list
pages_read_engagement
pages_manage_posts
instagram_basic
instagram_content_publish
business_management
```

Nexus One exchanges the initial Meta token for a long-lived user token. The Meta user must manage a Facebook Page. Instagram publishing requires a professional Instagram account linked to that Page. Add the Meta callback URL to the app's valid OAuth redirect URIs and complete the permissions/app review required for accounts outside app roles.

### LinkedIn

Enter:

- **Client ID:** LinkedIn Client ID
- **Client Secret:** LinkedIn Client Secret
- **API version:** seeded as `202606`; update this field when LinkedIn retires or replaces that REST version

Requested scopes:

```text
openid profile email w_member_social
```

Enable Sign In with LinkedIn using OpenID Connect and the Share on LinkedIn product. This release connects and publishes to a member profile. Company Page publishing requires LinkedIn organization products and additional approved scopes.

### X

Enter:

- **Client ID:** OAuth 2.0 Client ID
- **Client Secret:** OAuth 2.0 Client Secret

Requested scopes:

```text
tweet.read tweet.write users.read offline.access
```

Configure an OAuth 2.0 Web App, add the callback URL, and ensure the app has write access. X access and pricing are controlled by the selected X developer plan. The first release intentionally restricts X to text and links until media-write access is configured.

### Pinterest

Enter:

- **Client ID:** Pinterest App ID
- **Client Secret:** Pinterest App Secret

Requested scopes:

```text
boards:read,pins:read,pins:write,user_accounts:read
```

Add the callback URL in the Pinterest app. During connection Nexus One imports boards and assigns the first board as the default. Open the connected profile to change its **Default Board / Container ID**.

### YouTube

Enter:

- **Client ID:** Google OAuth Web Client ID
- **Client Secret:** Google OAuth Web Client Secret

Enable **YouTube Data API v3** in the Google Cloud project and add the callback URL to the OAuth Web client.

Requested scopes:

```text
openid
email
profile
https://www.googleapis.com/auth/youtube.readonly
https://www.googleapis.com/auth/youtube.upload
```

Nexus One requests offline access and forces a consent prompt so Google can return a refresh token. Video uploads default to `private`. The profile's provider metadata can later be extended with `privacy_status` values such as `private`, `unlisted`, or `public`, subject to Google policy and verification.

### TikTok

Enter:

- **Client ID field:** TikTok Client Key
- **Client Secret field:** TikTok Client Secret

Requested scopes:

```text
user.info.basic,video.publish
```

Enable the Content Posting API, configure the callback URL, obtain approval for `video.publish`, and verify the public Nexus One media domain for pull-from-URL posting. Until TikTok completes the necessary review/audit, visibility may be restricted to `SELF_ONLY`.

## How users work with it

1. A manager configures platform keys in **API Settings** and enables the provider.
2. The user clicks **Connect Profile**.
3. The provider opens its consent screen.
4. The provider returns to the Nexus One callback.
5. Nexus One validates the one-time OAuth state, exchanges the code, discovers profiles, and displays a successful connected handshake.
6. Users upload media, then either create a post normally or drag a creative from the left library directly onto the calendar.
7. The composer opens with the creative, date, and calculated 30-minute time already selected.
8. Users select profiles, write the caption, and confirm the schedule.
9. The one-minute cron publishes due posts and records a result for each destination.
10. Failed destinations can be inspected and retried without losing successful destination history.

## Production checklist

- Use HTTPS and a correct `web.base.url`.
- Keep Nexus One behind a trusted reverse proxy and pass the original host/protocol headers.
- Never expose provider client secrets in screenshots or support logs.
- Back up the database; OAuth tokens are operational credentials.
- Restrict **Social Manager** to trusted administrators.
- Confirm outbound HTTPS access from the Nexus One container/server.
- Set the reverse proxy upload limit high enough for the configured media limit (250 MB by default).
- Keep the publishing cron active.
- Configure provider review, business verification, and domain verification before onboarding customers.
- Review provider rate limits, quotas, pricing, and content rules.

## Security notes

- OAuth requests use a short-lived one-time state token.
- X uses PKCE.
- Public media URLs use an HMAC signature and support byte ranges for provider video downloads.
- Provider secrets and access tokens are hidden from normal Social Users through field-level groups.
- Standard Nexus One database storage is used. For environments requiring encrypted token storage at rest, add database/disk encryption or a dedicated secrets-vault integration.

## Technical extension points

- `services/oauth_clients.py` handles code exchange and profile discovery.
- `services/publishers.py` contains one publisher adapter per destination.
- `nexus.social.post.line` stores per-profile results.
- `nexus.social.post._cron_publish_due()` processes the queue.
- `/nexus_social/media/<asset>/<signature>` serves provider-readable media.

The adapter layout is intentionally modular so Brand Works App can add Threads, Bluesky, Google Business Profile, Mastodon, platform analytics, comment inboxes, approval workflows, or Bellum AI caption generation without rewriting the dashboard.


## Validation performed for this package

- Python source compilation completed successfully.
- Every XML data, security, view, and OWL template file parsed successfully.
- The OWL JavaScript entrypoint passed Node syntax validation.
- A live provider handshake still requires real developer applications, approved scopes, public HTTPS callbacks, and an installed Nexus One/Odoo 17 database.

## 17.0.1.6.0

- Added creative-to-calendar drag and drop from the always-visible left media library.
- The calendar calculates a 30-minute time from the vertical drop position in Month and Week views.
- Dropping a creative opens the post composer with the media, date, and time prefilled.
- Added drop-target highlighting, live time previews, grab cursors, and a confirmation banner in the composer.
- Existing unpublished posts now move to both the dropped date and dropped time.

## 17.0.1.7.0

- Added multi-select mode to the Media Library.
- Added select-all-visible, clear selection, and bulk delete controls.
- Added selected-card outlines and accessible selection checkboxes.
- Bulk deletion protects media attached to scheduled, publishing, or published posts.
- Media removed from editable posts automatically updates the post media type.

## 17.0.1.5.0

- Fixed backend asset stylesheet compatibility and applied the Nexus One megaphone icon throughout the app.

## 17.0.1.4.0

- Fixed Nexus One 17 view validation for single-company users by removing company-dependent field domains from the social post form.
- Company isolation remains enforced by Nexus One record rules and the post company-consistency constraint.