Functions API (Internal)

All Cloud Functions are deployed under your project region, e.g., https://<region>-<project>.cloudfunctions.net. Orchestrators and provider publish functions are invoked internally via Cloud Tasks. OAuth start/callback endpoints are called by the web app client.

---

Authentication

• OAuth endpoints require Authorization: Bearer <Firebase ID token> header
• Publish functions are invoked by Cloud Tasks (internal, no user auth needed)
• Webhook endpoints validate platform-specific signatures (Stripe, Meta)

---

OAuth Endpoints (per platform)

Each platform follows the same pattern: *AuthStart initiates OAuth, *AuthCallback exchanges the code for tokens.

Facebook

Endpoint	Method	Description
/fbAuthStart	GET	Initiates Facebook OAuth. Params: redirect=1, return_to=<url>. Requires ID token.
/fbAuthCallback	GET	Exchanges code for tokens, selects managed Page, stores credentials.

Instagram

Endpoint	Method	Description
/igAuthStart	GET	Initiates Instagram OAuth (via Facebook Business). Requires ID token.
/igAuthCallback	GET	Exchanges code, maps IG Business Account via Page.

Threads

Endpoint	Method	Description
/thAuthStart	GET	Initiates Threads OAuth (via Meta). Requires ID token.
/thAuthCallback	GET	Exchanges code for tokens.

X (Twitter)

Endpoint	Method	Description
/xAuthStart	GET	OAuth 2.0 PKCE flow. Requires ID token.
/xAuthCallback	GET	Exchanges code for tokens.
/xAuth1Start	GET	Optional chained OAuth 1.0a (for v1.1 API media endpoints). Params: sid=<session>.
/xAuth1Callback	GET	Exchanges OAuth 1.0a verifier for tokens.

TikTok

Endpoint	Method	Description
/ttAuthStart	GET	Initiates TikTok OAuth. Add ?desktop=1 for desktop auth flow. Requires ID token.
/ttAuthCallback	GET	Exchanges code for access/refresh tokens, fetches creator info.
/ttRefreshNow	POST	Refreshes a specific account's token on demand.

YouTube

Endpoint	Method	Description
/ytAuthStart	GET	Initiates Google OAuth with offline access. Requires ID token.
/ytAuthCallback	GET	Exchanges code for access/refresh tokens.
/ytRefreshNow	POST	Refreshes a specific account's token on demand.

LinkedIn

Endpoint	Method	Description
/liAuthStart	GET	Initiates LinkedIn OAuth 2.0. Requires ID token.
/liAuthCallback	GET	Exchanges code for tokens.

Snapchat

Endpoint	Method	Description
/snapAuthStart	GET	Initiates Snapchat OAuth 2.0. Requires ID token.
/snapAuthCallback	GET	Exchanges code for access/refresh tokens.
/snapRefreshNow	POST	Refreshes a specific account's token on demand.

---

Publish Functions (Cloud Tasks)

These are invoked internally by the orchestrator via Cloud Tasks. Each receives { userId, postSubmissionId, request } in the body.

Function	Platform	Notes
publishFacebook	Facebook	Pages feed posting via Graph API
publishInstagram	Instagram	Container creation + publish for images/video
publishThreads	Threads	Text and image posting
publishX	X	Tweet creation via v2 API
publishTiktok	TikTok	Direct publish for video/photo with status polling
publishYoutube	YouTube	Video upload via Data API v3
publishLinkedin	LinkedIn	UGC Posts API
snapPost	Snapchat	Snap post creation

---

Orchestrators

Function	Description
publishOrchestrator	Fan-out orchestration via Cloud Tasks. Body: { userId, postSubmissionId, request }
repostOrchestrator	Automated repost flow. Body: { userId, postId }
clipperOrchestrator	Media transformation (image-to-video conversion)

---

User-Facing Functions

Function	Method	Description
publishPost	POST	Requires Firebase ID token. Body: { post, scheduledTime? }. Creates submission and orchestrates.
cancelScheduledPost	POST	Cancels a previously scheduled post submission.
transcribeMedia	POST	AI transcription via OpenAI Whisper.
reportAiUsage	POST	Reports AI feature usage for analytics.
convertImageToVideo	POST	Converts static image to video format.

---

Media & Webhooks

Function	Method	Description
media	GET/HEAD	Media proxy: /media/{id}[.{ext}] — streams from Firebase Storage
stripeWebhook	POST	Stripe events: subscription lifecycle, invoices
metaWebhook	GET/POST	Meta verification (GET) and event receiver (POST)
api	*	Express app serving all /v1/* Public API routes

---

Scheduled Functions

Function	Schedule	Purpose
ttRefreshSweep	Periodic	Refresh expiring TikTok tokens
ytRefreshSweep	Periodic	Refresh expiring YouTube tokens
snapRefreshSweep	Periodic	Refresh expiring Snapchat tokens
scheduledTikTokPoll	Periodic	Poll TikTok for new organic posts
scheduledInstagramPoll	Periodic	Poll Instagram for new organic posts
scheduledXPoll	Periodic	Poll X for new posts
scheduledYouTubePoll	Periodic	Poll YouTube for new videos
scheduledTikTokMetrics	Periodic	Collect TikTok post metrics
scheduledFacebookMetrics	Periodic	Collect Facebook post metrics
scheduledThreadsMetrics	Periodic	Collect Threads post metrics
scheduledRateLimitCleanup	Periodic	Remove expired rate limit entries
scheduledDailyMetricsSnapshot	Daily	Snapshot aggregate metrics
integrationsHealthSweep	Periodic	Check all integration connection health

---

Firestore Triggers

Function	Trigger	Purpose
onOrganicPostCreated	organicPosts/* write	Initiates repost workflows
onFacebookAccountCreated	Integration account create	Post-connection setup
onInstagramAccountCreated	Integration account create	Post-connection setup
onTiktokAccountCreated	Integration account create	Post-connection setup
onXAccountCreated	Integration account create	Post-connection setup
onLinkedinAccountCreated	Integration account create	Post-connection setup
onIntegrationAccountAvatarChange	Avatar field update	Host avatar on Firebase Storage
onAccountDeleted	Account deletion	Clean up related workflows
onWorkflowWritten	Workflow doc write	Sync source account metadata
onWorkflowDeleted	Workflow doc delete	Clean up source account sync
onTemplateWritten	Template doc write	Generate template previews
onLibraryAssetUploaded	Library asset upload	Generate thumbnails

---

Error Handling

All API responses follow a structured error format:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "timestamp": "2025-08-29T00:02:14.654Z",
    "requestId": "abb6930d-2b57-4d44-9d63-19d5a9c8d077"
  }
}

Common Error Codes

Code	Status	Description
unauthorized	401	Missing or invalid authentication
forbidden	403	Insufficient permissions or inactive subscription
not_found	404	Resource not found
validation_error	400	Request validation failed (Zod schema errors)
rate_limit_exceeded	429	Too many requests
internal_error	500	Server error

Request Tracking

Include X-Request-ID header for request correlation across logs:

curl -H "X-Request-ID: debug-123" \
     -H "soku-api-key: your_key" \
     https://api.example.com/v1/posts

Errors are logged to the errorLogs Firestore collection and to stdout for Cloud Logging. Set NODE_ENV=development for detailed error responses with stack traces.

---

Frontend Integration

The web app interacts with these functions through:

• useConnectIntegration hook — calls startAuth(platform, idToken, returnTo, isLocal) and navigates to the returned authUrl
• Integration context — reads connected accounts from users/{uid}/integrations/*
• Publish hooks — submit posts via the Public API (/v1/posts), which internally orchestrates to the publish functions above

---

Related docs

• Public API v1 — External-facing API documentation
• Orchestration — Publishing flow details
• Provider Integrations — Per-platform details
• Cloud Tasks Topology — Queue configuration