Socialize

Documentation Map

• Application hub
• Application API surface
• Machine system JSON
• Machine application JSON
• applications/socialize

What It Is

Social publishing and campaign tooling with brand-scoped workflows and Nexus-managed provider app credential and connection inventory.

API Reference

Coverage: curated

Source: Apps/business/TopoloSocialize/packages/worker/openapi.yaml

Source exists in repo: no

The worker remains the primary API owner, and the authenticated web workspace renders through `TopoloAppShell`, inheriting shared Improve Topolo and TopoloNotify chrome while keeping brand workflows Socialize-owned. Browser, mobile, API worker, API-key, seed-sync, billing-webhook, and launcher flows resolve the Auth-owned `topolo-socialize` service slug at runtime instead of storing concrete service IDs in source, worker variables, or static assets. The browser app-switcher lane now reads Auth-owned catalog data through same-origin /api/auth/* on the Socialize host. `POST /api/brands/:brandId/transfer-organization` moves an existing brand to another accessible Topolo Auth organization by updating `brands.topolo_org_id` without changing the brand ID or content records. `PUT /api/posts/:id` supports reverting scheduled posts to drafts by clearing the schedule and returning draft state before the browser reports success, and now preserves explicit Facebook Page or Group, LinkedIn organization, Instagram account, and Threads account target metadata during browser edits. Scheduled publishing resolves the target platform connection at the brand level, preferring the post author's active connection when present and otherwise using another active brand connection so approved brand content can publish even when the connected account belongs to a different brand member. YouTube OAuth requests `youtube.upload` plus `youtube.readonly`, stores the authorized channel identity, refreshes expired access tokens through the same internal API-worker refresh lane as X, and sends channel profile hydration plus private-by-default video uploads through Nexus `/platform/youtube/*` so Google Data API quota units are centrally attributed. X OAuth requests read, write, media-upload, and offline-refresh scopes, and profile hydration tries `api.x.com` before the legacy `api.twitter.com` API host. The scheduler rehydrates the latest post row before publishing so edited copy and rescheduled times remain authoritative over older queued snapshots, thread posts expose `GET /api/posts?threadId=...` for detail navigation, later thread posts wait until the previous Socialize post is confirmed `published` with a delivered platform post ID before sending, failed scheduled publish attempts remain in `failed` status with failure fields populated for the Posts failed filter, and failed posts can be rescheduled back into the queue by clearing the failure fields and setting a new future schedule. Expired X tokens refresh through the API worker's internal `SOCIALIZE_INTERNAL_SERVICE_TOKEN` route so provider OAuth client secrets stay on the API surface. `GET /api/integrations` now returns eligible Facebook Groups alongside Pages from the stored connection metadata and reports whether each provider is production-ready, sandbox-only, setup-required, or still planned without exposing raw Cloudflare secret names to brand users; already-connected accounts are not downgraded into setup-required cards just because reconnect credentials need operator attention. Production OAuth readiness uses dedicated X, LinkedIn, LinkedIn Company, Facebook, Instagram, Threads, and YouTube Cloudflare secrets, Instagram connect now uses Instagram Login against `instagram.com/oauth/authorize`, exchanges tokens through `api.instagram.com`, publishes through `graph.instagram.com`, requests `instagram_business_basic` and `instagram_business_content_publish`, and exposes Meta-signed Instagram Business Login deauthorization and data-deletion callbacks. Threads connect uses `threads.net/oauth/authorize`, requests `threads_basic` and `threads_content_publish`, exchanges short-lived access tokens for long-lived Threads tokens, and publishes text or image posts through the Threads media-container then publish flow. YouTube connect uses Google OAuth, stores the authorized channel identity, and publishes private-by-default video uploads through Nexus-metered `videos.insert`. TikTok sandbox credentials stay scoped to staging only and production sandbox mode stays disabled. `POST /api/integrations/{platform}/connect` now rejects non-connectable providers up front instead of generating placeholder OAuth redirects. Nexus now supplies the org-wide image-generation default and allowed image-model catalog for Socialize image tools, Socialize service-token calls identify with the registered `app_socialize` app ID, inline model overrides remain request-scoped and permission-gated instead of mutating the stored org setting, trusted operator automation can generate post media through an internal Socialize image route that still uses the same image handlers and R2 storage path as browser-generated media, and upstream image rate limits are surfaced as rate limits rather than generic 500 retry loops. Every API response is normalized at the worker boundary so allowed staging and production browser origins receive matching CORS headers even when individual route modules return static headers. Trend discovery refresh requests bypass cache and the parser keeps current trends that mention prior-year context in summaries instead of discarding the whole provider response. Media-library loading no longer clears the grid after a fixed timeout, saved-generation cards hide broken preview URLs, the desktop content-feed review surface is embedded in the dashboard, and billing/referrals are no longer reachable Socialize workspace or API surfaces because billing, referrals, and subscription rewards are platform-level concerns. The worker now also exposes authenticated `GET /api/widget` for TopoloOne live workspace. Embedded password-login success completes through Socialize app navigation after shared Auth token persistence, login controls stay interactive while background auth bootstrap runs, and same-tab session-storage access-token restore preserves normal browser refreshes before cookie refresh completes. Socialize mobile resolves `topolo_auth_flutter` from the canonical Auth repo git package path and does not preload Auth identity from SharedPreferences.

App API page: /reference/apps/socialize

This system currently relies on a curated or README-derived contract surface instead of a source-controlled OpenAPI spec.

Auth and Permissions

Depends on Topolo Auth: yes

Service IDs:

API key scopes

Service permissions

accounts:read, accounts:write, analytics:read, api_keys:write, calendar:read, calendar:write, dashboard:read, posts:read, posts:write

Data Ownership

No storage bindings were derived from wrangler configuration.

Deployments

Deployment environments: default only or not declared

Routes: workers.dev or Pages-only delivery

Observability enabled: no explicit setting found

Failure Modes

• No wrangler.toml surface was discovered under the registered repo paths.
• The registered contract source is missing: Apps/business/TopoloSocialize/packages/worker/openapi.yaml
• Neither OpenAPI nor README-derived interface detail was found.

Debugging Runbooks

Start with these entrypoints:

• Apps/business/TopoloSocialize/packages/worker/openapi.yaml

Change Log / Verification

Lifecycle: active

Last verified: 2026-05-14

Any code change to this system is expected to update the canonical docs in PlatformApplications/TopoloDocs and refresh the verification date.