diff --git a/docs/superpowers/specs/2026-04-01-publishing-hardening-design.md b/docs/superpowers/specs/2026-04-01-publishing-hardening-design.md new file mode 100644 index 00000000..a3bc73e9 --- /dev/null +++ b/docs/superpowers/specs/2026-04-01-publishing-hardening-design.md @@ -0,0 +1,298 @@ +# Publishing Hardening β€” Best Practices from Postiz + +Improvements to the existing publishing flow. No new features β€” just making what we have more robust. + +## 1. Content Sanitization Before Publishing + +### Problem + +We send raw content to platform APIs. If the user pastes HTML from the editor or has formatting tags, they get sent as-is. Each platform has different rules: +- Instagram, TikTok, Pinterest, Bluesky: plain text only +- LinkedIn: supports bold/italic via Unicode characters +- X: plain text only +- Facebook, Threads: plain text only +- Mastodon: supports some HTML +- YouTube: plain text titles + +### Solution + +Create a `ContentSanitizer` service that strips/converts content per platform: + +```php +class ContentSanitizer +{ + public function sanitize(string $content, Platform $platform): string + { + return match ($platform) { + Platform::LinkedIn, Platform::LinkedInPage => $this->convertToUnicodeBold($this->stripHtml($content)), + Platform::Mastodon => $this->stripUnsafeHtml($content), + default => $this->stripHtml($content), + }; + } + + private function stripHtml(string $content): string + { + // Remove HTML tags, decode entities (& β†’ &,   β†’ space, etc.) + } + + private function convertToUnicodeBold(string $content): string + { + // Convert text to Unicode bold characters (𝗯𝗼𝗹𝗱) + // Convert text to Unicode underline (tΜ²eΜ²xΜ²tΜ²) + } + + private function stripUnsafeHtml(string $content): string + { + // Allow only safe tags:

, , , ,
+ // Strip everything else + } +} +``` + +Each publisher calls `$this->sanitizeContent($content, $platform)` before sending to the API. + +### Files Changed + +- Create: `app/Services/Social/ContentSanitizer.php` +- Modify: All 11 publishers β€” sanitize content before API call +- Test: `tests/Unit/Services/Social/ContentSanitizerTest.php` + +--- + +## 2. Backend Content Length Validation Before Publishing + +### Problem + +We validate content length in the frontend only. If the frontend has a bug or someone uses the API directly, content that exceeds platform limits goes through and fails with a cryptic API error. + +### Solution + +Validate content length in each publisher's `publish()` method before making any API calls: + +```php +// In each publisher, at the start of publish(): +$maxLength = $postPlatform->platform->maxContentLength(); + +if ($postPlatform->content && mb_strlen($postPlatform->content) > $maxLength) { + throw new \Exception("Content exceeds {$postPlatform->platform->label()} limit of {$maxLength} characters."); +} +``` + +Better: extract to the `HasSocialHttpClient` trait as a shared method: + +```php +protected function validateContentLength(PostPlatform $postPlatform): void +{ + $maxLength = $postPlatform->platform->maxContentLength(); + + if ($postPlatform->content && mb_strlen($postPlatform->content) > $maxLength) { + throw new \Exception( + "Content exceeds {$postPlatform->platform->label()} limit of {$maxLength} characters." + ); + } +} +``` + +### Files Changed + +- Modify: `app/Services/Social/Concerns/HasSocialHttpClient.php` β€” add `validateContentLength()` +- Modify: All 11 publishers β€” call `$this->validateContentLength($postPlatform)` at start of `publish()` +- Test: Add tests for content length validation + +--- + +## 3. Scope Verification Before Publishing + +### Problem + +We save scopes during OAuth connection but never verify them again. If the user revokes a permission (e.g., removes `instagram_business_content_publish` from the app), we only find out when the post fails with a confusing error. + +### Solution + +Add a `requiredScopes()` method to the `Platform` enum and verify before publishing: + +```php +// In Platform enum: +public function requiredPublishScopes(): array +{ + return match ($this) { + self::Instagram => ['instagram_business_content_publish'], + self::Facebook => ['pages_manage_posts'], + self::TikTok => ['video.publish'], + self::YouTube => ['https://www.googleapis.com/auth/youtube.upload'], + self::LinkedIn, self::LinkedInPage => ['w_member_social'], + self::X => ['tweet.write'], + self::Threads => ['threads_basic', 'threads_content_publish'], + self::Pinterest => ['pins:write'], + self::Bluesky => [], // no scopes, uses app password + self::Mastodon => ['write:statuses'], + }; +} +``` + +Check in `PublishToSocialPlatform` before calling the publisher: + +```php +$requiredScopes = $this->postPlatform->platform->requiredPublishScopes(); +$accountScopes = $this->postPlatform->socialAccount->scopes ?? []; + +$missingScopes = array_diff($requiredScopes, $accountScopes); + +if (! empty($missingScopes)) { + $this->postPlatform->markAsFailed( + 'Missing permissions: ' . implode(', ', $missingScopes) . '. Please reconnect your account.' + ); + $this->postPlatform->socialAccount->markAsDisconnected('Missing required scopes'); + return; +} +``` + +### Files Changed + +- Modify: `app/Enums/SocialAccount/Platform.php` β€” add `requiredPublishScopes()` +- Modify: `app/Jobs/PublishToSocialPlatform.php` β€” add scope check before publish +- Test: Add test for missing scopes scenario + +--- + +## 4. "Refresh Needed" State (separate from "Disconnected") + +### Problem + +When a token refresh fails, we immediately mark the account as "disconnected". This is too aggressive β€” the account isn't disconnected, it just needs a new token. The user sees "disconnected" and thinks something is broken, when they just need to re-authenticate. + +Postiz has three separate states: `connected`, `refreshNeeded`, `disabled`. + +### Solution + +Add a `TokenExpired` status to the SocialAccount status enum (we already have it but don't use it consistently): + +```php +enum Status: string +{ + case Connected = 'connected'; + case Disconnected = 'disconnected'; + case TokenExpired = 'token_expired'; // exists but underused +} +``` + +When token refresh fails during publishing: +1. First failure β†’ mark as `TokenExpired` (not `Disconnected`) +2. User gets notification: "Your Instagram token expired, please reconnect" +3. Daily `CheckSocialConnections` β†’ if still `TokenExpired`, try refresh again +4. If still failing after daily check β†’ then mark as `Disconnected` + +### Files Changed + +- Modify: `app/Jobs/PublishToSocialPlatform.php` β€” use `TokenExpired` instead of `Disconnected` on first failure +- Modify: `app/Jobs/VerifyWorkspaceConnections.php` β€” handle `TokenExpired` state +- Modify: Frontend β€” show different UI for `TokenExpired` vs `Disconnected` +- Test: Add tests for state transitions + +--- + +## 5. Error Context Saved in Database + +### Problem + +When a post fails, we save only `error_message` (the user-facing string). We have no record of what content/media was sent, what the API returned, etc. Debugging requires checking logs. + +### Solution + +Save structured error context in the existing `meta` JSON column on `post_platforms`: + +```php +// In PublishToSocialPlatform when marking as failed: +$this->postPlatform->update([ + 'status' => Status::Failed, + 'error_message' => $e->userMessage, + 'meta' => array_merge($this->postPlatform->meta ?? [], [ + 'error_context' => [ + 'category' => $e->category->value, + 'platform_error_code' => $e->platformErrorCode, + 'failed_at' => now()->toIso8601String(), + 'content_length' => mb_strlen($this->postPlatform->content ?? ''), + 'media_count' => $this->postPlatform->media->count(), + ], + ]), +]); +``` + +No raw API response in the database β€” that stays in logs only. Just enough context to understand what happened. + +### Files Changed + +- Modify: `app/Jobs/PublishToSocialPlatform.php` β€” save error context to meta +- Modify: `app/Models/PostPlatform.php` β€” add helper `markAsFailedWithContext()` +- Frontend: Show error context in post detail view (optional) + +--- + +## 6. Stuck Post Recovery + +### Problem + +If a post gets stuck in `publishing` status (job crashed, worker died, etc.), it stays there forever. The user sees "Publishing..." indefinitely. + +Postiz has `searchForMissingThreeHoursPosts()` that finds stuck posts and re-dispatches. + +### Solution + +Create a scheduled command that runs every 30 minutes: + +```php +class RecoverStuckPosts extends Command +{ + protected $signature = 'social:recover-stuck-posts'; + + public function handle(): void + { + // Find posts stuck in "publishing" for more than 1 hour + Post::query() + ->where('status', PostStatus::Publishing) + ->where('updated_at', '<=', now()->subHour()) + ->each(function (Post $post) { + // Check if any platform is still actively processing + $activeJobs = $post->postPlatforms() + ->where('enabled', true) + ->where('status', PostPlatformStatus::Publishing) + ->count(); + + if ($activeJobs === 0) { + // All platforms finished but post status wasn't updated (race condition) + $this->recalculatePostStatus($post); + } else { + // Mark stuck platforms as failed + $post->postPlatforms() + ->where('status', PostPlatformStatus::Publishing) + ->where('updated_at', '<=', now()->subHour()) + ->update([ + 'status' => PostPlatformStatus::Failed, + 'error_message' => 'Publishing timed out. Please try again.', + ]); + + $this->recalculatePostStatus($post); + } + }); + } +} +``` + +### Files Changed + +- Create: `app/Console/Commands/RecoverStuckPosts.php` +- Modify: `routes/console.php` β€” schedule every 30 minutes +- Test: `tests/Feature/Commands/RecoverStuckPostsTest.php` + +--- + +## Priority + +| # | Improvement | Impact | Effort | +|---|---|---|---| +| 1 | Content sanitization | High β€” prevents HTML in posts | Medium | +| 2 | Backend content length validation | High β€” prevents cryptic API errors | Low | +| 3 | Scope verification | Medium β€” early error detection | Low | +| 5 | Error context in database | Medium β€” easier debugging | Low | +| 6 | Stuck post recovery | High β€” prevents stuck UI | Low | +| 4 | Refresh needed state | Medium β€” better UX | Medium |