@happyvertical/smrt-social

Social media account management for multi-platform publishing in the s-m-r-t ecosystem. Manages OAuth connections, post scheduling, and analytics tracking across YouTube, Threads, X (Twitter), and Bluesky.

Installation

pnpm add @happyvertical/smrt-social

Usage

import { SocialAccount, SocialPost, OAuthState } from '@happyvertical/smrt-social';

// Connect a social account
const account = new SocialAccount({
  name: 'Bentley News YouTube',
  platform: 'youtube',
  platformUsername: 'Bentley News',
  accessToken: 'encrypted-token',
  refreshToken: 'encrypted-refresh',
  tokenExpiresAt: new Date('2026-06-01'),
  defaultHashtags: ['news', 'local'],
  linkBehavior: 'description',
});
await account.save();

// Check readiness before publishing (active + connected + token present + not expired)
if (account.isReady) {
  const post = new SocialPost({
    socialAccountId: account.id,
    title: 'Breaking News from Bentley',
    description: 'Latest updates from the town council meeting.',
    hashtags: ['news', 'local', 'bentley'],
    linkUrl: 'https://example.com/article',
    scheduledAt: new Date('2026-03-05T18:00:00Z'),
    status: 'scheduled',
  });
  await post.save();
}

// OAuth flow: create state, redirect user, verify callback
const state = new OAuthState({
  platform: 'youtube',
  state: OAuthState.generateState(),
  codeVerifier: OAuthState.generateCodeVerifier(),
  redirectUri: 'https://app.example.com/oauth/callback',
  scopes: ['youtube.upload', 'youtube.readonly'],
});
await state.save();
// On callback: state.verifyState(callbackState), then exchange code for tokens

API

Models

Export	Description
SocialAccount	Connected platform account with OAuth credentials and publishing settings
SocialPost	Scheduled or published post with analytics tracking
OAuthState	Temporary OAuth flow state with CSRF protection and PKCE support

Types

Export	Description
SocialPlatformType	Platform identifier: youtube, threads, x, bluesky
AccountStatus	Connection status: connected, expired, error
PostStatus	Lifecycle status: draft, scheduled, publishing, published, failed
LinkBehavior	Link handling strategy: description, reply, none
PostAnalytics	Engagement metrics: views, likes, comments, shares, clicks
SocialAccountOptions	Account creation options
SocialPostOptions	Post creation options
OAuthStateOptions	OAuth state creation options

Key Computed Properties

• SocialAccount.isReady -- gate check: active + connected + token present + not expired
• SocialAccount.isTokenExpired -- checks with 5-minute buffer before actual expiry
• SocialPost.isEditable -- true when draft or failed
• SocialPost.fullText -- description + formatted hashtags
• OAuthState.isValid -- not expired and state token present
• OAuthState.verifyState(callback) -- CSRF verification for OAuth callbacks
• OAuthState.generateCodeChallenge(verifier) -- PKCE S256 challenge generation

Dependencies

• @happyvertical/smrt-core -- ORM and code generation
• @happyvertical/smrt-config -- configuration loading
• @happyvertical/smrt-content -- content models
• @happyvertical/smrt-tenancy -- multi-tenant scoping
• @happyvertical/smrt-video -- video content references