Add Google Business Profile as a supported social platform

.ai/rules/auth.md

@@ -0,0 +1,12 @@
+---
+paths:
+  - app/Http/Controllers/Auth/GoogleBusinessController.php
+---
+
+# Auth
+
+## Clear google_business_oauth on every terminal connect path
+google_business_oauth holds access and refresh tokens until the user picks a location. Forget it on every terminal select() exit, including the generic Exception catch, and in ConnectPopupException::render() alongside social_connect_workspace. Leaving it after uploadFromUrl / fetchLocationPhoto / connectIdentity failures leaks tokens into the session. On reconnect, keep the existing refresh_token when Google omits a new one.
+
+## Forget google_business_oauth on every popupCallback
+Override popupCallback to forgetOauthSession() so single-location success and every error path drop the token bag. Do not forget before the multi-location redirect to the picker — that is the only request that still needs it. select() finally and ConnectPopupException::render() also forget; a second forget is fine.

.ai/rules/google-business.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - 'app/Enums/GoogleBusiness/**'
+  - app/Jobs/PublishToSocialPlatform.php
+  - app/Jobs/ReconcileGoogleBusinessPost.php
+  - app/Console/Commands/ReconcileGoogleBusinessPosts.php
+  - app/Services/Social/GoogleBusinessPublisher.php
+  - app/Support/PostPlatformMetaRules.php
+  - app/Services/Social/GoogleBusinessAnalytics.php
+---
+
+# Google Business
+
+## GBP Local Posts v4 values are enums
+LocalPost.state, topicType, and callToAction.actionType live on App\Enums\GoogleBusiness\{LocalPostState,TopicType,CtaAction}. Compare cases / helpers (isPendingReview, isLive, requiresEvent, allowsCallToAction, requiresUrl) — never raw PROCESSING/SCHEDULED/STANDARD/OFFER strings. Do not ship Google-deprecated Local Post values: no GET_OFFER CTA, no ALERT/COVID_19 topic, no PRODUCT topic, no localPosts.reportInsights. Missing state defaults to Processing; Unspecified (LOCAL_POST_STATE_UNSPECIFIED) is pending review, not published. Missing topic defaults to Standard. Rejected targets have no retry — the user must duplicate the post. The Show/Edit publishing overlay must use isActivelyPublishing (in-flight platforms only); pending_review keeps post.status=publishing and would hide the page for up to 24h.
+
+## GBP publish result uses tryFrom not fromApi
+PublishToSocialPlatform::recordPublishResult must use LocalPostState::tryFrom, never fromApi. Other publishers omit `state`; fromApi(null) is Processing and would park LinkedIn/X/… in pending review. The GBP publisher always returns `$state->value` after fromApi, so the job only sees a known case.
+
+## GBP event title is 58 characters, coupon is not
+LocalPost event.title is capped at TopicType::TITLE_MAX_LENGTH (58) — Google returns Must be at most 58 characters even though the v4 schema page omits the limit. Do not reuse 58 on offer.coupon_code / terms; those have no published cap. Mirror the title cap in resources/js/types/google-business.ts as GOOGLE_BUSINESS_EVENT_TITLE_MAX. requiredMetaViolation() must reject a stored title over 58 — MCP PublishPostTool never re-runs rules(). Do not apply the cap to leftover titles on STANDARD.
+
+## GBP reconcile refreshes on 401
+ReconcileGoogleBusinessPost must call ConnectionVerifier::verify() after a TokenExpiredException from fetchLocalPost and retry the GET once. If refresh also fails, mark the SocialAccount token-expired, then deferOrGiveUp. Do not park a 401 in pending_review for 24h while a refresh would settle it. RecoverStuckPosts times the 24h ceiling from submitted_at only — never created_at.
+
+## GBP analytics must not cache a failed fetch
+GoogleBusinessAnalytics caches only a successful array. An HTTP failure or a missing location returns false and is not written to cache — a 500 must not blank the dashboard for an hour. Publish/verify/analytics require both location_id (v4) and location_name (v1) via GoogleBusinessResourceName::connectedLocation().
+
+## Local Posts 401 after a live BI verify does not expire the account
+retryAfterExpiredToken calls ConnectionVerifier::verify() then retries fetchRemote. markAsTokenExpired only when verify() itself throws TokenExpiredException. If BI verify succeeds and Local Posts still 401s, deferOrGiveUp without disconnecting — the token still works for the house verify. ReconcileGoogleBusinessPosts only dispatches enabled() pending_review rows. ReconcileGoogleBusinessPost::handle() giveUps immediately when socialAccount is null — disconnect nulls the FK and fetchRemote would TypeError until the 24h ceiling.

.ai/rules/index.md

@@ -0,0 +1,13 @@
+# Project Rules Index
+
+Before planning or editing, find the row whose globs match the file's path and read that rule file.
+
+| Applies to | Rule file |
+| --- | --- |
+| app/Http/Controllers/Auth/GoogleBusinessController.php | .ai/rules/auth.md |
+| app/Enums/GoogleBusiness/**, app/Jobs/PublishToSocialPlatform.php, app/Jobs/ReconcileGoogleBusinessPost.php, app/Console/Commands/ReconcileGoogleBusinessPosts.php, app/Services/Social/GoogleBusinessPublisher.php, app/Support/PostPlatformMetaRules.php, app/Services/Social/GoogleBusinessAnalytics.php | .ai/rules/google-business.md |
+| app/Jobs/ReconcileGoogleBusinessPost.php, app/Console/Commands/RecoverStuckPosts.php | .ai/rules/jobs.md |
+| app/Actions/Post/FinalizePostPublication.php, app/Jobs/PublishPost.php, app/Actions/Post/UpdatePost.php | .ai/rules/post.md |
+| app/Enums/SocialAccount/Platform.php | .ai/rules/social-account.md |
+| app/Services/Social/GoogleBusinessPublisher.php, app/Support/Social/GoogleBusinessDerivativeCleaner.php, app/Actions/Post/DeletePost.php, app/Actions/Post/UpdatePost.php, app/Support/Social/AbandonGoogleBusinessReview.php, app/Actions/Workspace/PurgeWorkspace.php, app/Http/Controllers/Auth/SocialController.php | .ai/rules/social.md |
+| app/Support/PostPlatformMetaRules.php | .ai/rules/support.md |

.ai/rules/jobs.md

@@ -0,0 +1,10 @@
+---
+paths:
+  - app/Jobs/ReconcileGoogleBusinessPost.php
+  - app/Console/Commands/RecoverStuckPosts.php
+---
+
+# Jobs
+
+## GBP reconcile must settle permanent API errors
+ReconcileGoogleBusinessPost must not rethrow GoogleBusinessPublishException. Permanent categories (NOT_FOUND, PERMISSION_DENIED, INVALID_ARGUMENT, Unknown) reject the target immediately and call FinalizePostPublication. Only ServerError, RateLimit, and ConnectionException defer until REVIEW_CEILING_HOURS. Throwing leaves last_reconciled_at stale, the 5-minute sweep re-dispatches, RecoverStuckPosts treats PendingReview as still-active, and the post sticks forever. failed() is the safety net if the worker dies mid-review — it must deferOrGiveUp (respect the 24h ceiling), never giveUp immediately. Job $timeout must exceed HasSocialHttpClient's 120s HTTP timeout. RecoverStuckPosts may only fail PendingReview after the same 24h ceiling timed from submitted_at — never created_at (a scheduled draft can be days old before it enters review) and never the 1h publishing timeout. Reconcile must refresh-and-retry on TokenExpiredException the same way PublishToSocialPlatform does; if verify() itself dies, mark the social account token-expired before deferring. If Business Information verify succeeds and Local Posts still 401s, defer without markAsTokenExpired — the token is still valid for the house verify. A 401 must not sit in review for 24h while a refresh would have settled it. JPEG derivatives stay on disk while LocalPostState is Processing/Scheduled so Google can fetch sourceUrl; settle(), RecoverStuckPosts' 1h publishing timeout, a disabled GBP target, and the expired-review path prune them. Reconcile must giveUp immediately when socialAccount is null (disconnect nulls the FK and would TypeError in fetchRemote). When RecoverStuckPosts finishes a post (no still-active targets), call FinalizePostPublication so the owner is notified — do not mark the post Failed/Published by hand. Never compare raw PROCESSING/SCHEDULED/LIVE strings — use App\Enums\GoogleBusiness\LocalPostState.

.ai/rules/post.md

@@ -0,0 +1,20 @@
+---
+paths:
+  - app/Actions/Post/FinalizePostPublication.php
+  - app/Jobs/PublishPost.php
+  - app/Actions/Post/UpdatePost.php
+---
+
+# Post
+
+## FinalizePostPublication is the only post settler
+handle() takes the Post, not a dummy PostPlatform. Every path that can finish the last enabled target must call it: PublishToSocialPlatform, ReconcileGoogleBusinessPost, RecoverStuckPosts, PublishPost::failed, and AbandonGoogleBusinessReview (disconnect / disable during pending_review). No enabled targets on a draft or scheduled post is a no-op — do not mark the post published. A Publishing post with no enabled targets is abandoned in-flight: mark it Failed so it does not sit non-editable forever. Do not mark the post Published / PartiallyPublished / Failed by hand outside Finalize.
+
+## In-app publish notice uses owner locale
+SendNotification title/body are stored already-resolved. Resolve them through lang/*/notifications.php (post_published / post_failed) with $owner->preferredLocale() — the worker locale is English. Mailables stay untranslated at dispatch; Mail::to($owner) applies HasLocalePreference. Do not hardcode English title/body here.
+
+## Finalize is idempotent once the post is settled
+handle() lockForUpdates the post and returns without notifying when status is already Published, PartiallyPublished, or Failed (Status::isSettled()). RecoverStuckPosts and ReconcileGoogleBusinessPost can both finish the last target at the 24h ceiling; the second call must not send a second email or toast. Dispatch SendNotification only after the transaction commits.
+
+## Target disabled is not account inactive
+Abandoning a GBP pending_review because the post destination was unchecked uses posts.errors.target_disabled. posts.errors.account_inactive stays for PublishToSocialPlatform when social_accounts.is_active is false. Do not reuse the account copy on a switched-off target.

.ai/rules/social-account.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - app/Enums/SocialAccount/Platform.php
+---
+
+# Social Account
+
+## Adding a platform: grep for exhaustive Platform matches beyond the known touch-point list
+Adding a new Platform enum case breaks any `match ($platform) { ... }` elsewhere in the codebase that enumerates every case with no `default` arm — these throw UnhandledMatchError only at runtime/test time, not statically. Known example found the hard way: `app/Services/Media/MediaOptimizer.php`'s per-platform image optimization settings match, which isn't part of the "usual" platform touch-point list (Platform enum, ContentType enum, config, PostPlatformMetaRules, publisher, controller, frontend registry). Before considering a new platform done, run the full test suite (`php artisan test --compact --parallel`) — a missing arm surfaces as a clean, unambiguous UnhandledMatchError failure, not a silent bug.

.ai/rules/social.md

@@ -0,0 +1,15 @@
+---
+paths:
+  - app/Services/Social/GoogleBusinessPublisher.php
+  - app/Support/Social/GoogleBusinessDerivativeCleaner.php
+  - app/Actions/Post/DeletePost.php
+  - app/Actions/Post/UpdatePost.php
+  - app/Support/Social/AbandonGoogleBusinessReview.php
+  - app/Actions/Workspace/PurgeWorkspace.php
+  - app/Http/Controllers/Auth/SocialController.php
+---
+
+# Social
+
+## GBP JPEG must outlive PROCESSING
+Google fetches Local Post sourceUrl after create while LocalPostState is Processing/Scheduled/Unspecified. Keep the JPEG derivative on disk until reconcile settle() or RecoverStuckPosts fails the target. Deleting in publish() finally races PHOTO_FETCH_FAILED. Live/Rejected on the create response may prune immediately. Path is deterministic: google-business-derivatives/{postPlatformId}.jpg. Wire values live on App\Enums\GoogleBusiness\LocalPostState — never compare raw PROCESSING/SCHEDULED strings. RecoverStuckPosts must prune the JPEG on the 1h Publishing/Pending/Retrying timeout (the worker can die after writing the file and before PendingReview), on a disabled GBP target (reconcile and the 24h ceiling skip `enabled=false`), and again on the 24h review ceiling. UpdatePost mass-updates `enabled=false` (observers never fire): abandon any GBP still in pending_review that is not in the kept set, then prune leftover JPEGs after commit. Disconnect must abandon pending_review rows before the account delete (nullOnDelete would otherwise leave reconcile TypeErroring until the 24h ceiling). DeletePost and PurgeWorkspace must prune every Google Business PostPlatform JPEG before the row disappears — a user delete during pending_review or a workspace wipe would otherwise leak the file, and a DB cascade on post_platforms does not fire Eloquent observers.

.ai/rules/support.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - app/Support/PostPlatformMetaRules.php
+---
+
+# Support
+
+## Never use a cross-field Laravel rule (required_unless, required_if, etc.) for a single platform's conditional meta field
+`rules()` is shared by every platform via `platforms.*.meta.*` wildcards. Rules like `required_unless`/`required_if` are Laravel "implicit" rules — they validate even when the field itself is absent from the request. Adding one scoped in spirit to a single platform (e.g. `call_to_action.url` required_unless action_type is NONE/CALL, meant only for Google Business Profile) breaks every OTHER platform's create/update through web, API, and MCP, because their requests never send that field at all and the implicit rule still fires. The correct pattern (already used by Pinterest's `board_id`, Discord's `channel_id`): keep the field's `rules()` entry unconditional (`sometimes|nullable|...`), and enforce "required" semantics only in `requiredMetaViolation()`'s `match(true)` block, which is evaluated per the resolved `Platform` of the row being checked. This bug shipped once (fixed in commit 8887b3f3) and broke Pinterest/Discord/TikTok post updates — the task reviewer that approved the original `rules()` entry didn't catch it because it only reviewed Google Business's own test coverage, not sibling platforms'.

.env.example

@@ -158,6 +158,12 @@ GOOGLE_CLIENT_SECRET=
 GOOGLE_CLIENT_REDIRECT="${APP_URL}/accounts/youtube/callback"
 GOOGLE_AUTH_CALLBACK="${APP_URL}/auth/google/callback"
 
+# Google Business Profile (https://console.cloud.google.com)
+# Dedicated OAuth app, isolated from YouTube
+GOOGLE_BUSINESS_CLIENT_ID=
+GOOGLE_BUSINESS_CLIENT_SECRET=
+GOOGLE_BUSINESS_CLIENT_REDIRECT="${APP_URL}/accounts/google-business/callback"
+
 # GitHub (https://github.com/settings/developers)
 # Used for GitHub login/signup
 GITHUB_AUTH_ENABLED=false
@@ -283,6 +289,7 @@ NIGHTWATCH_TOKEN=
 # MASTODON_ENABLED=true
 # BLUESKY_ENABLED=true
 # TELEGRAM_ENABLED=true
+# GOOGLE_BUSINESS_ENABLED=true
 
 # Media Services
 UNSPLASH_ACCESS_KEY=

CLAUDE.md

@@ -575,6 +575,7 @@ Browser tests live in `tests/Browser` and run on `pestphp/pest-plugin-browser` d
 - **Bluesky / AT Protocol**: official lexicons — https://github.com/bluesky-social/atproto/tree/main/lexicons/com/atproto/repo ; HTTP API reference — https://docs.bsky.app
 - **Discord**: Webhook resource (used for our webhook-based publishing) — https://docs.discord.com/developers/resources/webhook
 - **Telegram**: Bot API — https://core.telegram.org/bots/api
+- **Google Business Profile**: Business Information API, Account Management API, Business Profile Performance API — https://developers.google.com/my-business/reference/rest ; legacy but still-active Local Posts v4 API (the only endpoint for creating/updating/deleting Local Posts) — https://developers.google.com/my-business/reference/rest/v4/accounts.locations.localPosts
 
 ## TryPost.it Documentation
 

app/Actions/Post/DeletePost.php

@@ -4,13 +4,20 @@
 
 namespace App\Actions\Post;
 
+use App\Enums\SocialAccount\Platform;
 use App\Events\PostDeleted;
 use App\Models\Post;
+use App\Support\Social\GoogleBusinessDerivativeCleaner;
 
 class DeletePost
 {
     public static function execute(Post $post): void
     {
+        $post->postPlatforms()
+            ->where('platform', Platform::GoogleBusiness)
+            ->pluck('id')
+            ->each(fn (string $id) => app(GoogleBusinessDerivativeCleaner::class)->cleanup($id));
+
         $postId = $post->id;
         $workspaceId = $post->workspace_id;
 

app/Actions/Post/FinalizePostPublication.php

@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\Post;
+
+use App\Enums\Notification\Channel;
+use App\Enums\Notification\Type;
+use App\Enums\Post\Status as PostStatus;
+use App\Enums\PostPlatform\Status as PostPlatformStatus;
+use App\Jobs\SendNotification;
+use App\Mail\PostPublished;
+use App\Mail\PostPublishFailed;
+use App\Models\Post;
+use App\Models\PostPlatform;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Settles a post once every enabled target has reached a terminal state, and
+ * notifies the owner once. Shared by PublishToSocialPlatform, PublishPost::failed,
+ * RecoverStuckPosts, and ReconcileGoogleBusinessPost.
+ */
+class FinalizePostPublication
+{
+    public function handle(Post $post): void
+    {
+        /** @var array{post: Post, successful: bool, platforms: Collection<int, PostPlatform>}|null $outcome */
+        $outcome = DB::transaction(function () use ($post): ?array {
+            $post = Post::query()
+                ->with(['workspace.owner', 'postPlatforms.socialAccount'])
+                ->whereKey($post->id)
+                ->lockForUpdate()
+                ->first();
+
+            if (! $post instanceof Post || $post->status->isSettled()) {
+                return null;
+            }
+
+            $targets = $post->postPlatforms->where('enabled', true);
+
+            if ($targets->isEmpty()) {
+                if ($post->status !== PostStatus::Publishing) {
+                    return null;
+                }
+
+                $post->markAsFailed();
+
+                return [
+                    'post' => $post,
+                    'successful' => false,
+                    'platforms' => $post->postPlatforms->filter(
+                        fn (PostPlatform $target): bool => $target->status->isFinished(),
+                    ),
+                ];
+            }
+
+            $finished = $targets->filter(fn (PostPlatform $target): bool => $target->status->isFinished());
+            $published = $finished->where('status', PostPlatformStatus::Published);
+            $failed = $finished->reject(fn (PostPlatform $target): bool => $target->status === PostPlatformStatus::Published);
+
+            if ($finished->count() < $targets->count()) {
+                return null;
+            }
+
+            $successful = $failed->isEmpty();
+
+            if ($successful) {
+                $post->markAsPublished();
+            } elseif ($published->isNotEmpty()) {
+                $post->markAsPartiallyPublished();
+            } else {
+                $post->markAsFailed();
+            }
+
+            return [
+                'post' => $post,
+                'successful' => $successful,
+                'platforms' => $successful ? $published : $failed,
+            ];
+        });
+
+        if ($outcome === null) {
+            return;
+        }
+
+        $this->notify($outcome['post'], $outcome['successful'], $outcome['platforms']);
+    }
+
+    /**
+     * @param  Collection<int, PostPlatform>  $platforms
+     */
+    private function notify(Post $post, bool $successful, Collection $platforms): void
+    {
+        $owner = $post->workspace->owner;
+
+        if (! $owner) {
+            return;
+        }
+
+        $type = $successful ? Type::PostPublished : Type::PostFailed;
+        $locale = $owner->preferredLocale();
+
+        SendNotification::dispatch(
+            user: $owner,
+            workspaceId: $post->workspace_id,
+            type: $type,
+            channel: Channel::Both,
+            title: __("notifications.{$type->value}.title", [], $locale),
+            body: __("notifications.{$type->value}.body", [
+                'platforms' => $platforms->map->notificationLabel()->implode(', '),
+            ], $locale),
+            data: ['post_id' => $post->id],
+            mailable: $successful ? new PostPublished($post) : new PostPublishFailed($post),
+        );
+    }
+}