feat(tokmetric): complete governed TikTok video publishing flow

[support371]

Summary

Completes the governed, application-side TikTok Direct Post video workflow required for sandbox demonstration and Content Posting API review.

End-to-end publishing flow

• Authenticate through the existing TokMetric session and workspace permission model
• Select an approved content version and connected TikTok Content Posting connector
• Query current TikTok creator information immediately before posting
• Display the connected creator nickname, duration limit, privacy options, and interaction restrictions
• Require the user to manually select privacy; no privacy value is preselected
• Present Allow Comment, Allow Duet, and Allow Stitch controls unchecked by default and disable them when TikTok reports the feature unavailable
• Display a real preview of the selected video before transmission
• Keep the caption, hashtags, and mentions editable
• Provide TikTok-compliant commercial-content disclosure with Your brand and Branded content choices
• Prevent third-party branded content from using SELF ONLY visibility
• Provide the TikTok Music Usage Confirmation and Branded Content Policy declarations
• Require explicit upload consent, visual rights, music rights, and processing acknowledgement
• Support Direct Post with FILE_UPLOAD for local MP4, MOV, and WebM files
• Upload local files directly from the browser to TikTok using sequential chunks and retry transient failures
• Support PULL_FROM_URL only for configured domains verified in TikTok URL Properties
• Permit best-effort cancellation only for an ongoing PULL_FROM_URL download
• Poll TikTok publishing status and preserve internal and external job state, safe attempts, audit events, and domain events

Security and governance

• Access and refresh tokens remain encrypted server-side
• TikTok upload URLs are not persisted in audit metadata or browser storage
• Exact-version approval, workspace permissions, emergency locks, OAuth scope checks, and idempotency are enforced
• Sandbox and production activation flags only work when they match the active TikTok environment
• Sandbox posting is restricted to SELF ONLY and requires a private test account
• OAuth requests only the demonstrated scopes: user.info.basic and video.publish

App-review resources

• Dedicated real publishing page at /tokmetric/publishing
• Final form copy in docs/tokmetric/tiktok-app-review-submission.md
• End-to-end recording sequence in docs/tokmetric/media-publishing.md
• Chunk-boundary, gate-mismatch, file-size, and verified-domain regression tests

External activation requirements

A real sandbox recording still requires:

1. TikTok sandbox client credentials and approved user.info.basic / video.publish scopes
2. An authorized private TikTok test account
3. A database workspace with publishing enabled and an approved current content version
4. Matching Vercel environment variables
5. A successful deployed build on the verified GEM domain

Validation status

• PR is mergeable and has no unresolved review threads.
• Static repository review has been completed against TikTok’s current Direct Post and Content Sharing Guidelines.
• GitHub Actions continues to fail before producing any job steps because of the existing account/runner issue.
• Most connected Vercel projects are rejecting builds at the build-rate-limit layer. One external build is still pending, but its team logs are not accessible through the connected Vercel account.

This PR remains draft until an actual TypeScript/production build completes successfully. It must not be merged based only on quota-failed checks.

Summary by Sourcery

Implement a governed end-to-end TikTok Direct Post video publishing workflow in TokMetric, including a dedicated operational UI, backend services, and documentation to support sandbox app review and controlled activation.

New Features:

• Add a dedicated TokMetric TikTok video publishing page with a guided UI for selecting workspaces, approved content, connected TikTok accounts, and configuring creator-specific post settings.
• Introduce a browser-based Direct Post flow that uploads local MP4/MOV/WebM videos to TikTok using chunked FILE_UPLOAD, or PULL_FROM_URL for verified domains, with status polling and limited cancellation for URL pulls.
• Provide new backend publishing services and API routes to initialize TikTok Direct Post requests, validate gates and approvals, track publish jobs and attempts, and refresh or cancel publishing status.
• Expose authorized TikTok connector credentials with automatic token refresh and scope checks dedicated to the Content Posting API.

Enhancements:

• Tighten TikTok OAuth configuration by simplifying endpoint selection and restricting Content Posting scopes to the minimum required user.info.basic and video.publish.
• Document the implemented TikTok media publishing flow, activation gates, transfer modes, and app-review recording steps for sandbox demonstrations.

Tests:

• Add regression tests for TikTok chunk upload planning, publishing activation gate configuration mismatches, and verified media host URL validation.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
gem-enterprise	Canceled		Jul 5, 2026 11:59pm
gem-enterprise-in	Error		Jul 5, 2026 11:59pm
project-dtrl6	Ready	Preview, Comment	Jul 5, 2026 11:59pm
v0-continue-conversation-3875	Error		Jul 5, 2026 11:59pm
v0-deployment-alignment-task	Error		Jul 5, 2026 11:59pm
v0-my-website	Ready	Preview, Comment, Open in v0	Jul 5, 2026 11:59pm
v0-v0-geraldhoeven-4141-ff89f7f-5	Ready	Preview, Comment, Open in v0	Jul 5, 2026 11:59pm

[sourcery-ai]

Reviewer's Guide

Implements the governed end-to-end TikTok Direct Post publishing flow in TokMetric, including a dedicated publishing page, client-side uploader with chunked file transfer and consent UX, server-side publishing service and TikTok API integration, verified-domain URL pulls, cancellation for URL-based uploads, environment-aware activation gates, and supporting docs and tests.

Sequence diagram for governed TikTok Direct Post publishing flow

sequenceDiagram
  actor Operator
  participant BrowserPublisher as TokMetricVideoPublisherV3
  participant ContextRoute as api_publishing_context
  participant CreatorRoute as api_publishing_creator_info
  participant InitRoute as api_publishing_init
  participant UploadCompleteRoute as api_publishing_upload_complete
  participant StatusRoute as api_publishing_status
  participant Service as publishing_service
  participant TikTokAPI as TikTok_content_posting_API
  participant TikTokUpload as TikTok_upload_url

  Operator->>BrowserPublisher: Open /tokmetric/publishing
  BrowserPublisher->>ContextRoute: GET /api/tokmetric/publishing/context
  ContextRoute->>Service: getVideoPublishingContext
  Service-->>ContextRoute: publishingContext
  ContextRoute-->>BrowserPublisher: context JSON

  Operator->>BrowserPublisher: Query creator settings
  BrowserPublisher->>CreatorRoute: POST /api/tokmetric/publishing/creator-info
  CreatorRoute->>Service: getCreatorInfoForPublishing
  Service->>TikTokAPI: queryTikTokCreatorInfo
  TikTokAPI-->>Service: TikTokCreatorInfo
  Service-->>CreatorRoute: creatorInfo
  CreatorRoute-->>BrowserPublisher: creatorInfo JSON

  Operator->>BrowserPublisher: Send video to TikTok
  BrowserPublisher->>InitRoute: POST /api/tokmetric/publishing/init
  InitRoute->>Service: initializeVideoPublish
  Service->>TikTokAPI: initializeTikTokDirectPost
  TikTokAPI-->>Service: publishId, uploadUrl
  Service-->>InitRoute: InitResult
  InitRoute-->>BrowserPublisher: InitResult JSON

  alt source == FILE_UPLOAD
    BrowserPublisher->>TikTokUpload: PUT chunked video upload
    BrowserPublisher->>UploadCompleteRoute: POST /api/tokmetric/publishing/upload-complete
    UploadCompleteRoute->>Service: markVideoUploadComplete
    Service-->>UploadCompleteRoute: updatedPublishJob
    UploadCompleteRoute-->>BrowserPublisher: job JSON
  else source == PULL_FROM_URL
    Service->>TikTokAPI: initializeTikTokDirectPost PULL_FROM_URL
    TikTokAPI-->>Service: processing started
  end

  loop status polling
    BrowserPublisher->>StatusRoute: POST /api/tokmetric/publishing/status
    StatusRoute->>Service: refreshVideoPublishStatus
    Service->>TikTokAPI: fetchTikTokPublishStatus
    TikTokAPI-->>Service: TikTokPublishStatus
    Service-->>StatusRoute: StatusResult
    StatusRoute-->>BrowserPublisher: StatusResult JSON
  end

Loading

File-Level Changes

Change	Details	Files
Add a governed client-side TikTok video publishing UI that drives the new Direct Post workflow.	Replace the generic TokMetric workspace publishing page with a dedicated /tokmetric/publishing layout and description for TikTok Content Posting API. Introduce TokMetricVideoPublisherV3 React client component to orchestrate workspace/connector/content selection, creator info fetching, privacy and interaction controls, consent checkboxes, source selection between local file and verified URL, local metadata/preview, chunked upload to TikTok, status polling, and best-effort URL cancellation. Wire a thin TokMetricVideoPublisher wrapper component that re-exports the V3 publisher for the page.	src/app/tokmetric/publishing/page.tsx src/components/tokmetric/TokMetricVideoPublisherV3.tsx src/components/tokmetric/TokMetricVideoPublisher.tsx
Introduce a backend publishing service layer and HTTP API for TikTok Direct Post initialization, upload completion, status polling, cancellation, and context loading.	Create publishing/service.ts implementing publishing context retrieval, creator info fetch with OAuth credential handling, verified media URL validation, job creation with idempotency and approval enforcement, TikTok Direct Post initialization, upload completion transitions, status refresh, and generic cancellation helpers. Add publishing/tiktok.ts as a TikTok API client for creator info, Direct Post init, and status fetch with schema validation and robust error mapping. Add publishing/gates.ts to compute/enforce environment-aware sandbox/production publishing gates based on TikTok environment and app flags. Add publishing/pullCancel.ts implementing best-effort cancellation restricted to PULL_FROM_URL jobs using TikTok’s cancel endpoint and job attempt/audit recording. Expose REST endpoints for context, creator-info, init, upload-complete, status, and cancel routes under /api/tokmetric/publishing/*, including input validation, auth, permission checks, idempotency header enforcement, and TokMetric error wrapping.	src/lib/tokmetric/publishing/service.ts src/lib/tokmetric/publishing/tiktok.ts src/lib/tokmetric/publishing/gates.ts src/lib/tokmetric/publishing/pullCancel.ts src/app/api/tokmetric/publishing/context/route.ts src/app/api/tokmetric/publishing/creator-info/route.ts src/app/api/tokmetric/publishing/init/route.ts src/app/api/tokmetric/publishing/upload-complete/route.ts src/app/api/tokmetric/publishing/status/route.ts src/app/api/tokmetric/publishing/cancel/route.ts
Extend OAuth connector handling to support TikTok Direct Post with scope validation and environment awareness.	Export StoredTikTokCredential type for reuse. Add getAuthorizedTikTokCredential helper that loads connector credentials for the active TikTok environment, refreshes tokens when expiring, validates required scopes, and returns a normalized credential bundle. Simplify TikTok OAuth config URLs to environment-agnostic constants and restrict Content Posting API scopes to user.info.basic and video.publish.	src/lib/tokmetric/oauth/connectors.ts src/lib/tokmetric/oauth/config.ts
Define core TikTok publishing types and client-side chunk-planning logic shared between front end and back end.	Create publishing/types.ts containing TikTok MIME types, privacy types, creator info and status models, video source enumeration, and chunk-planning helpers with TikTok size limits encoded (5 MiB min chunk, 64 MiB normal, 128 MiB final, 4 GiB max, 1000 chunks max). Implement calculateTikTokChunkPlan and chunkByteRange utilities with validation that are used in both the client uploader and server service. Add vitest coverage for chunk planning edge cases, gate misconfiguration handling, and verified media URL rules including HTTPS-only, host allowlist, and fail-closed behavior when no hosts are configured.	src/lib/tokmetric/publishing/types.ts src/__tests__/tokmetric-video-publishing.test.ts
Document the implemented TikTok publishing workflow, activation gates, transfer modes, and TikTok App Review guidance.	Expand docs/tokmetric/media-publishing.md with a concrete implemented flow description, activation gate env var examples for sandbox vs production, FILE_UPLOAD vs PULL_FROM_URL behavior, operational API routes, and a recommended app-review recording walkthrough. Add docs/tokmetric/tiktok-app-review-submission.md containing copy for TikTok’s review form, selected products/scopes, recording steps, and pre-submission checklist. Ensure docs highlight security/governance guarantees such as fail-closed behavior, verified-domain requirements, and token/upload URL non-persistence.	docs/tokmetric/media-publishing.md docs/tokmetric/tiktok-app-review-submission.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[vercel]

Deployment failed with the following error:

Resource is limited - try again in 24 hours (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/carolinasuarez8419-9338s-projects?upgradeToPro=build-rate-limit

[vercel]

Deployment failed with the following error:

Resource is limited - try again in 1 day (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/geraldhoeven-4141s-projects?upgradeToPro=build-rate-limit

[support371]

@sourcery-ai review

Please review the latest head with special attention to TypeScript compatibility, Prisma enum/state assignments, TikTok API request/response typing, browser chunk-upload logic, OAuth scope minimization, idempotency, and authorization boundaries.

[vercel]

Deployment failed with the following error:

Resource is limited - try again in 1 day (more than 100, code: "api-deployments-free-per-day").

Learn More: https://vercel.com/admin-25521151s-projects?upgradeToPro=build-rate-limit

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The new generic cancellation helpers in publishing/service.ts and publishing/tiktok.ts look unused now that cancelPullFromUrlPublish and /api/tokmetric/publishing/cancel handle the only supported flow; consider removing or clearly marking them as deprecated to avoid future confusion.
• Verified-media-host handling is currently implemented in both getVideoPublishingContext and validateVerifiedMediaUrl; centralizing this parsing/normalization logic in a shared helper would reduce duplication and keep the API response consistent with the enforcement path.
• In TokMetricVideoPublisherV3, the client-side duration cap is hard-coded to 600 seconds via the API schema while the actual limit comes from TikTok (maxVideoPostDurationSec); consider aligning the payload validation with the dynamic creator-specific limit to avoid rejecting valid long-duration posts for some accounts.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The new generic cancellation helpers in `publishing/service.ts` and `publishing/tiktok.ts` look unused now that `cancelPullFromUrlPublish` and `/api/tokmetric/publishing/cancel` handle the only supported flow; consider removing or clearly marking them as deprecated to avoid future confusion.
- Verified-media-host handling is currently implemented in both `getVideoPublishingContext` and `validateVerifiedMediaUrl`; centralizing this parsing/normalization logic in a shared helper would reduce duplication and keep the API response consistent with the enforcement path.
- In `TokMetricVideoPublisherV3`, the client-side duration cap is hard-coded to 600 seconds via the API schema while the actual limit comes from TikTok (`maxVideoPostDurationSec`); consider aligning the payload validation with the dynamic creator-specific limit to avoid rejecting valid long-duration posts for some accounts.

## Individual Comments

### Comment 1
<location path="docs/tokmetric/tiktok-app-review-submission.md" line_range="30" />
<code_context>
+Record one continuous MP4 or MOV video showing:
+
+1. The browser address bar displaying the verified GEM domain.
+2. Sign-in to the GEM Enterprise review account.
+3. Open `/tokmetric/publishing`.
+4. Select the review workspace.
</code_context>
<issue_to_address>
**issue (typo):** Use the verb phrase "Sign in" instead of the noun form "Sign-in" here for correct grammar and consistency.

Other references in the docs use "Sign in" as a verb (e.g., "Sign in to the GEM Enterprise demo account" and "The review account can sign in successfully"). Update this step to match: "Sign in to the GEM Enterprise review account."

```suggestion
2. Sign in to the GEM Enterprise review account.
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

issue (typo): Use the verb phrase "Sign in" instead of the noun form "Sign-in" here for correct grammar and consistency.

Other references in the docs use "Sign in" as a verb (e.g., "Sign in to the GEM Enterprise demo account" and "The review account can sign in successfully"). Update this step to match: "Sign in to the GEM Enterprise review account."

Suggested change

	2. Sign-in to the GEM Enterprise review account.
	2. Sign in to the GEM Enterprise review account.

[support371]

Final implementation and activation handoff

PR #138 was merged into main at commit 744147d6bcf495b92b66025233862e942c06cda3.

Validation completed

• Exact feature head 498764fef7cef2b2212de951771629aaa5a42998 received a successful Vercel build status.
• PR was mergeable and had no unresolved review threads.
• TikTok UX was aligned with the current Content Sharing Guidelines: no default privacy, interactions off by default, creator nickname and limits displayed, real video preview, editable caption, commercial disclosure, policy declarations, explicit consent, processing notice, and status polling.
• Direct Post OAuth scopes were reduced to user.info.basic and video.publish.
• Upload chunk planning now enforces multiple chunks above 64 MiB and a final chunk no larger than 128 MiB.

Production deployment blocker

The custom-domain Vercel project support371-gem-enterprise (prj_VDGqnA7wZt2E65LLvT94ZOpnYc2Z) rejected the merged main build at the build-rate-limit layer. Its current production alias is still on an older commit.

After the quota clears, trigger a fresh production build from current main, then confirm /api/health reports branch main and commit 744147d6bcf4 or a later commit.

Required sandbox activation

Set and verify:

TIKTOK_ENVIRONMENT=sandbox
TOKMETRIC_TIKTOK_OAUTH_ENABLED=true
TOKMETRIC_SANDBOX_PUBLISHING_ENABLED=true
TOKMETRIC_LIVE_PUBLISHING_ENABLED=false
TIKTOK_CLIENT_KEY=<sandbox client key>
TIKTOK_CLIENT_SECRET=<sandbox client secret>
TIKTOK_REDIRECT_URI=https://gemcybersecurityassist.com/api/tokmetric/oauth/callback
TOKMETRIC_TOKEN_ENCRYPTION_KEY=<production-grade encryption key>

The review workspace must have publishing enabled, no global emergency lock, a connected private TikTok test account with user.info.basic and video.publish, and an approved current content version with a matching approval hash.

Use docs/tokmetric/tiktok-app-review-submission.md for the form text and docs/tokmetric/media-publishing.md for the recording sequence.