@volter/twin-tiktok 0.1.37 → 1.0.0

package/open/src/semantics/shared.ts

@@ -0,0 +1,197 @@
+import { mp4Facts } from '../engine/mp4.ts';
+// What every family of the open lane shares beyond the vendor's (../../../src/semantics/shared.ts): the open platform's
+// envelope, the scopes its apps are granted, and who a request is.
+import type { HandlerContext } from '@volter/world-core';
+import { ACCESS, ACCESS_TTL, APP, CHUNK, CODE, PERSON, PUBLISH, REFRESH, REFRESH_TTL, VIDEO, appByKey, bySha, clientSecret, credential, mediaUrl, next, openIdOf, privacyOptions, seconds, sha256, type Row, unionIdOf, videoMoment, videoPage } from '../../../src/semantics/shared.ts';
+
+export * from '../../../src/semantics/shared.ts';
+export type { HandlerContext };
+
+/** The scopes an app on the developer site is granted: every product scope Postiz asks for (the World's app is set up
+ *  with the products it uses). */
+export const APP_SCOPES = ['user.info.basic', 'user.info.profile', 'user.info.stats', 'video.list', 'video.publish', 'video.upload'];
+/** The scopes a business app on the ads portal is granted: those Postiz's TikTok Business provider asks for. */
+export const BUSINESS_SCOPES = ['user.info.basic', 'user.info.username', 'user.info.stats', 'video.list', 'video.upload', 'video.publish'];
+
+// ── the envelope ───────────────────────────────────────────────────────────────────────────────
+// source: https://developers.tiktok.com/doc/content-posting-api-reference-query-creator-info "Any code other than"
+/** An answer: `{data, error: {code: 'ok', message: '', log_id}}`. */
+export const logId = (ctx: Pick<HandlerContext, 'crypto' | 'occurredAt'>, what: string): string =>
+  `${ctx.occurredAt.replace(/\D/g, '').slice(0, 14)}${ctx.crypto.digest('sha256', `${ctx.occurredAt}:${what}`, 'hex').slice(0, 20).toUpperCase()}`;
+export const ok = (ctx: Pick<HandlerContext, 'crypto' | 'occurredAt'>, data: unknown): Response =>
+  Response.json({ data, error: { code: 'ok', message: '', log_id: logId(ctx, JSON.stringify(data)) } });
+/** A refusal in the same envelope. */
+export const refuse = (ctx: Pick<HandlerContext, 'crypto' | 'occurredAt'>, status: number, code: string, message: string): Response =>
+  Response.json({ data: {}, error: { code, message, log_id: logId(ctx, code) } }, { status });
+
+/** Who a request is: the access token it bears, live, with its app, its person and its scopes. */
+export type Caller = { token: Row; app: Row; person: Row; scopes: string[]; openId: string };
+export function callerOf(ctx: HandlerContext): Caller | undefined {
+  const value = /^Bearer\s+(\S+)$/i.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1];
+  const token = value ? bySha(ctx, ACCESS, value) : undefined;
+  if (!token || token.kind === 'business' || token.revoked === true || Number(token.expires_at) <= seconds(ctx.occurredAt)) return undefined;
+  const app = ctx.row(APP, String(token.app));
+  const person = ctx.row(PERSON, String(token.person));
+  if (!app || !person) return undefined;
+  return { token, app, person, scopes: String(token.scope).split(','), openId: openIdOf(ctx, app, person) };
+}
+
+// source: https://developers.tiktok.com/doc/content-posting-api-reference-query-creator-info "The access_token is invalid or has expired."
+export const invalidToken = (ctx: HandlerContext): Response => refuse(ctx, 401, 'access_token_invalid', 'The access token is invalid or not found in the request.');
+/** The caller, or the refusal: no live token (401 access_token_invalid), or none of the scopes named (401
+ *  scope_not_authorized). */
+export function authorized(ctx: HandlerContext, ...scopes: string[]): Caller | Response {
+  const c = callerOf(ctx);
+  if (!c) return invalidToken(ctx);
+  // source: https://developers.tiktok.com/doc/content-posting-api-reference-query-creator-info "The access_token does not bear user's grant on"
+  if (scopes.length && !scopes.some((s) => c.scopes.includes(s))) return refuse(ctx, 401, 'scope_not_authorized', `The user did not authorize the scope required for completing this request (${scopes.join(' or ')}).`);
+  return c;
+}
+
+
+export const oauthError = (ctx: HandlerContext, error: string, description: string): Response =>
+  Response.json({ error, error_description: description, log_id: logId(ctx, error) }, { status: error === 'invalid_client' ? 401 : 400 });
+
+/** Whether a code's PKCE challenge refuses the verifier: TikTok's desktop flow sends the challenge as the verifier's
+ *  SHA-256 in hex; a code made without one is not checked. */
+export const pkceRefused = (ctx: HandlerContext, code: Row, verifier: unknown): boolean =>
+  typeof code.challenge === 'string' && ctx.crypto.digest('sha256', String(verifier ?? ''), 'hex') !== code.challenge;
+
+export async function issue(ctx: HandlerContext, app: Row, person: Row, scope: string): Promise<Response> {
+  const now = seconds(ctx.occurredAt);
+  const access = await credential(ctx, ACCESS, 'act', { app: app.id, person: person.id, scope, expires_at: now + ACCESS_TTL, revoked: false });
+  const refresh = await credential(ctx, REFRESH, 'rft', { app: app.id, person: person.id, scope, access: access.id, expires_at: now + REFRESH_TTL, used: false });
+  return Response.json({
+    access_token: access.value, expires_in: ACCESS_TTL, open_id: openIdOf(ctx, app, person), refresh_expires_in: REFRESH_TTL,
+    refresh_token: refresh.value, scope, token_type: 'Bearer',
+  });
+}
+
+// source: https://developers.tiktok.com/doc/tiktok-api-v2-get-user-info "The set of user fields to request for"
+export const FIELD_SCOPE: Record<string, string> = {
+  open_id: 'user.info.basic', union_id: 'user.info.basic', avatar_url: 'user.info.basic', avatar_url_100: 'user.info.basic', avatar_large_url: 'user.info.basic', display_name: 'user.info.basic',
+  bio_description: 'user.info.profile', profile_deep_link: 'user.info.profile', is_verified: 'user.info.profile', username: 'user.info.profile',
+  follower_count: 'user.info.stats', following_count: 'user.info.stats', likes_count: 'user.info.stats', video_count: 'user.info.stats',
+};
+
+export const videosObj = (v: unknown): Row => (v && typeof v === 'object' && !Array.isArray(v) ? v as Row : {});
+
+// source: https://developers.tiktok.com/doc/tiktok-api-v2-video-query "choose from"
+export const FIELDS = ['id', 'create_time', 'cover_image_url', 'share_url', 'video_description', 'duration', 'height', 'width', 'title', 'embed_html', 'embed_link', 'like_count', 'comment_count', 'share_count', 'view_count', 'is_aigc'];
+
+export function fieldsOf(ctx: HandlerContext): string[] | Response {
+  const fields = String(new URL(ctx.call.request.url).searchParams.get('fields') ?? '').split(',').map((f) => f.trim()).filter(Boolean);
+  const unknown = fields.filter((f) => !FIELDS.includes(f));
+  return !fields.length || unknown.length ? refuse(ctx, 400, 'invalid_params', `Invalid fields: ${unknown.join(',') || '(none)'}`) : fields;
+}
+
+export const project = (ctx: HandlerContext, v: Row, fields: string[]): Row => {
+  const served = ctx.get(VIDEO, String(v.id)) ?? {};
+  return Object.fromEntries(fields.map((f) => [f, served[f]]));
+};
+
+export const publishObj = (v: unknown): Row => (v && typeof v === 'object' && !Array.isArray(v) ? v as Row : {});
+
+export const MB = 1024 * 1024;
+
+export const UPLOAD_HOST = 'https://open-upload.tiktokapis.com';
+
+export const invalid = (ctx: HandlerContext, message: string): Response => refuse(ctx, 400, 'invalid_param', message);
+
+// source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "Each chunk must be at least 5 MB but no greater than 64 MB, except for the final chunk, which can be greater than"
+/** The chunk plan's refusal, or undefined when it holds: whole below 5 MB, chunks of 5–64 MB, floor(size/chunk) of
+ *  them, 1–1000, at most 4 GB in all, and the final chunk (the whole of a one-chunk plan) at most 128 MB. */
+export function chunkRefusal(size: number, chunk: number, count: number): string | undefined {
+  if (!Number.isInteger(size) || size <= 0) return 'video_size must be a positive integer';
+  // source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "Maximum of 4GB"
+  if (size > 4 * 1024 * MB) return 'video_size is over 4GB';
+  if (!Number.isInteger(chunk) || chunk <= 0 || !Number.isInteger(count)) return 'chunk_size and total_chunk_count are required for FILE_UPLOAD';
+  if (size < 5 * MB) return chunk === size && count === 1 ? undefined : 'a video under 5 MB is uploaded whole: chunk_size equal to video_size, total_chunk_count 1';
+  // source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "should be equal to"
+  if (count !== Math.floor(size / chunk)) return 'total_chunk_count must be video_size divided by chunk_size, rounded down';
+  if (count < 1 || count > 1000) return 'total_chunk_count must be between 1 and 1000';
+  if (count > 1 && (chunk < 5 * MB || chunk > 64 * MB)) return 'chunk_size must be between 5 MB and 64 MB';
+  // source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "which can be greater than"
+  if (size - chunk * (count - 1) > 128 * MB) return 'the final chunk must be at most 128 MB';
+  return undefined;
+}
+
+export async function initVideo(ctx: HandlerContext, direct: boolean): Promise<Response> {
+  const c = authorized(ctx, direct ? 'video.publish' : 'video.upload');
+  if (c instanceof Response) return c;
+  const b = publishObj(ctx.body);
+  const post = publishObj(b.post_info);
+  const source = publishObj(b.source_info);
+  if (direct) {
+    // source: https://developers.tiktok.com/doc/content-posting-api-reference-direct-post "privacy_level is not specified or not among the options from the privacy_level_options returned in /publish/creator_info/query/ API."
+    if (!privacyOptions(c.person).includes(String(post.privacy_level))) return refuse(ctx, 403, 'privacy_level_option_mismatch', 'privacy_level is not specified or not among the options from the privacy_level_options returned in /publish/creator_info/query/ API.');
+    // source: https://developers.tiktok.com/doc/content-posting-api-reference-direct-post "The maximum length is 2200 in UTF-16 runes."
+    if (typeof post.title === 'string' && post.title.length > 2200) return invalid(ctx, 'title is over 2200 characters');
+  }
+  // Where the twin stops: Postiz uploads its videos (FILE_UPLOAD); a video pulled from a URL is the twin's gap, refused
+  // as such, never answered as though pulled
+  if (source.source === 'PULL_FROM_URL') return invalid(ctx, 'the twin does not model PULL_FROM_URL video posts');
+  if (source.source !== 'FILE_UPLOAD') return invalid(ctx, 'source must be FILE_UPLOAD or PULL_FROM_URL');
+  const size = Number(source.video_size);
+  const bad = chunkRefusal(size, Number(source.chunk_size), Number(source.total_chunk_count));
+  if (bad) return invalid(ctx, bad);
+  const n = await next(ctx, 'publish');
+  const id = `${direct ? 'v_pub_file' : 'v_inbox_file'}~v2.${n}`;
+  const uploadId = String(7_300_000_000_000_000_000n + BigInt(n));
+  const token = (await ctx.secret(`tiktok-upload-token:${id}`)).replace(/[^A-Za-z0-9]/g, '').slice(0, 32);
+  await ctx.write(PUBLISH, id, {
+    status: 'PROCESSING_UPLOAD', fail_reason: '', publicaly_available_post_id: [], uploaded_bytes: 0,
+    _person: c.person.id, _app: c.app.id, _kind: direct ? 'direct' : 'inbox', _media: 'VIDEO', _post_info: direct ? post : {},
+    _video_size: size, _chunk_size: Number(source.chunk_size), _chunks: Number(source.total_chunk_count),
+    _upload_id: uploadId, _upload_token_sha256: sha256(ctx, token), _upload_expires: seconds(ctx.occurredAt) + 3600,
+  }, direct ? 'videoInit' : 'inboxVideoInit');
+  return ok(ctx, { publish_id: id, upload_url: `${UPLOAD_HOST}/video/?upload_id=${uploadId}&upload_token=${token}` });
+}
+
+/** A pull from URLs: each must be under a URL property the app verified (403 url_ownership_unverified); the vendor
+ *  pulls them through the World (ctx.vendorFetch, the World's one network) and a URL the World does not serve fails the
+ *  post (photo_pull_failed, video_pull_failed). */
+export async function pull(ctx: HandlerContext, c: Caller, kind: 'direct' | 'inbox', media: 'PHOTO', urls: string[], post: Row): Promise<Response> {
+  const app = ctx.row(APP, String(c.app.id))!;
+  const props = (app.url_properties as string[] | undefined) ?? [];
+  const verified = (url: string): boolean => {
+    let u: URL;
+    try { u = new URL(url); } catch { return false; }
+    // source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "The media URL must use"
+    if (u.protocol !== 'https:') return false;
+    return props.some((p) => (p.includes('/') ? url.startsWith(p) : u.hostname === p || u.hostname.endsWith(`.${p}`)));
+  };
+  // source: https://developers.tiktok.com/doc/content-posting-api-reference-direct-post "the developer must verify the ownership of the URL prefix or domain"
+  if (!urls.every(verified)) return refuse(ctx, 403, 'url_ownership_unverified', 'To use PULL_FROM_URL as the media transfer method, the developer must verify the ownership of the URL prefix or domain.');
+  const n = await next(ctx, 'publish');
+  const id = `p_${kind === 'direct' ? 'pub' : 'inbox'}_url~v2.${n}`;
+  await ctx.write(PUBLISH, id, {
+    status: 'PROCESSING_DOWNLOAD', fail_reason: '', publicaly_available_post_id: [], downloaded_bytes: 0,
+    _person: c.person.id, _app: c.app.id, _kind: kind, _media: media, _post_info: post, _urls: urls,
+  }, 'contentInit');
+  let downloaded = 0;
+  let failed = false;
+  for (const url of urls) {
+    try {
+      const r = await ctx.vendorFetch(url, { method: 'GET' });
+      if (!r.ok) { failed = true; break; }
+      downloaded += (await r.arrayBuffer()).byteLength;
+    } catch { failed = true; break; }
+  }
+  const to = failed ? 'FAILED' : kind === 'direct' ? 'PUBLISH_COMPLETE' : 'SEND_TO_USER_INBOX';
+  const refused = ctx.legal(PUBLISH, 'status', 'contentInit', 'PROCESSING_DOWNLOAD', to, id, 'vendor');
+  if (refused) throw new Error(refused.message);
+  const postId = !failed && kind === 'direct' && post.privacy_level === 'PUBLIC_TO_EVERYONE' ? String(7_400_000_000_000_000_000 + (await next(ctx, 'video')) * 1024) : undefined;
+  await ctx.write(PUBLISH, id, {
+    status: to, downloaded_bytes: downloaded, ...(failed ? { fail_reason: 'photo_pull_failed' } : {}),
+    ...(postId ? { publicaly_available_post_id: [Number(postId)] } : {}),
+  }, 'contentInit');
+  return ok(ctx, { publish_id: id });
+}
+
+/** A chunk that is not the last: its progress kept, answered 206 with the bytes so far. */
+// source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "There are additional chunks yet to be uploaded."
+export async function partialChunk(ctx: HandlerContext, id: string, now: number, size: number): Promise<Response> {
+  await ctx.write(PUBLISH, id, { uploaded_bytes: now }, 'uploadVideo');
+  return new Response(null, { status: 206, headers: { 'content-range': `bytes 0-${now - 1}/${size}` } });
+}

package/open/src/semantics/states.ts

@@ -0,0 +1,23 @@
+// TikTok's state machines, shared by its lanes (architecture, "State"; a lane imports its vendor's states): a post's
+// status, whether it came through the Content Posting API (the open lane) or the API for Business (the business lane).
+// Its transitions name no operation: each is the vendor's move whichever lane's call it follows.
+import type { StateField } from '@volter/world-core';
+
+const STATUS = 'https://developers.tiktok.com/doc/content-posting-api-reference-get-video-status';
+
+/** A post's `status`: an upload begins PROCESSING_UPLOAD ("Indicates that the upload is in process"), a pull from URL
+ *  PROCESSING_DOWNLOAD (written so at the post's start); the vendor finishes it when the last chunk arrives or the pull
+ *  ends. Not made by the twin: a post the creator makes from an inbox draft (PUBLISH_COMPLETE after SEND_TO_USER_INBOX,
+ *  the creator's move in the app), a moderation that fails a post, and a cancelled pull (the cancel is unmodeled). */
+export const publishStatus: StateField = {
+  initial: 'PROCESSING_UPLOAD',
+  transitions: [
+    { actor: 'vendor', from: ['PROCESSING_UPLOAD', 'PROCESSING_DOWNLOAD'], to: 'PUBLISH_COMPLETE', source: `${STATUS} "it indicates that the content has been posted"` },
+    { actor: 'vendor', from: ['PROCESSING_UPLOAD', 'PROCESSING_DOWNLOAD'], to: 'SEND_TO_USER_INBOX', source: `${STATUS} "Indicates that a notification has been sent to creator's inbox to complete the draft post using TikTok's editing flow."` },
+    { actor: 'vendor', from: ['PROCESSING_DOWNLOAD'], to: 'FAILED', source: `${STATUS} "Indicates that an error has occurred and the entire process has failed."` },
+  ],
+};
+
+export const publish = { state: { status: publishStatus }, notState: ['fail_reason', 'reason'] };
+
+export const states = { publish };

package/open/src/semantics/user.ts

@@ -0,0 +1,24 @@
+import type { HandlerContext } from '@volter/world-core';
+import { ACCESS, ACCESS_TTL, APP, CHUNK, CODE, FIELDS, FIELD_SCOPE, MB, PERSON, PUBLISH, REFRESH, REFRESH_TTL, UPLOAD_HOST, VIDEO, appByKey, authorized, bySha, chunkRefusal, clientSecret, credential, fieldsOf, initVideo, invalid, issue, logId, mediaUrl, next, oauthError, ok, openIdOf, partialChunk, pkceRefused, privacyOptions, project, publishObj, pull, refuse, seconds, sha256, type Caller, type Row, unionIdOf, videoMoment, videoPage, videosObj } from './shared.ts';
+import { mp4Facts } from '../engine/mp4.ts';
+
+// source: https://developers.tiktok.com/doc/tiktok-api-v2-get-user-info "endpoint returns some basic information for a given TikTok user."
+export async function userInfo(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx);
+  if (c instanceof Response) return c;
+  const fields = String(new URL(ctx.call.request.url).searchParams.get('fields') ?? '').split(',').map((f) => f.trim()).filter(Boolean);
+  const unknown = fields.filter((f) => !(f in FIELD_SCOPE));
+  if (!fields.length || unknown.length) return refuse(ctx, 400, 'invalid_params', `Invalid fields: ${unknown.join(',') || '(none)'}`);
+  const missing = [...new Set(fields.map((f) => FIELD_SCOPE[f]!))].filter((s) => !c.scopes.includes(s));
+  if (missing.length) return refuse(ctx, 401, 'scope_not_authorized', `The user did not authorize the scope required for completing this request (${missing.join(',')}).`);
+  const p = c.person;
+  // "The total number of publicly posted videos by the user": the person's public videos, counted from the set
+  const videos = ctx.rowsRaw(VIDEO).filter((v) => v.deleted !== true && v._person === p.id && v._public === true).length;
+  const avatar = mediaUrl(ctx, `avatar-${String(p.id)}`);
+  const all: Row = {
+    open_id: openIdOf(ctx, c.app, p), union_id: unionIdOf(ctx, p), avatar_url: avatar, avatar_url_100: avatar, avatar_large_url: avatar, display_name: p.display_name,
+    bio_description: p.bio_description ?? '', profile_deep_link: `https://www.tiktok.com/@${String(p.username)}`, is_verified: p.is_verified === true, username: p.username,
+    follower_count: Number(p.follower_count ?? 0), following_count: Number(p.following_count ?? 0), likes_count: Number(p.likes_count ?? 0), video_count: videos,
+  };
+  return ok(ctx, { user: Object.fromEntries(fields.map((f) => [f, all[f]])) });
+}

package/open/src/semantics/video.ts

@@ -0,0 +1,97 @@
+import type { HandlerContext } from '@volter/world-core';
+import { ACCESS, ACCESS_TTL, APP, CHUNK, CODE, FIELDS, FIELD_SCOPE, MB, PERSON, PUBLISH, REFRESH, REFRESH_TTL, UPLOAD_HOST, VIDEO, appByKey, authorized, bySha, chunkRefusal, clientSecret, credential, fieldsOf, initVideo, invalid, issue, logId, mediaUrl, next, oauthError, ok, openIdOf, partialChunk, pkceRefused, privacyOptions, project, publishObj, pull, refuse, seconds, sha256, type Caller, type Row, unionIdOf, videoMoment, videoPage, videosObj } from './shared.ts';
+import { mp4Facts } from '../engine/mp4.ts';
+
+// source: https://developers.tiktok.com/doc/tiktok-api-v2-video-list "sorted by"
+export async function videoList(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx, 'video.list');
+  if (c instanceof Response) return c;
+  const fields = fieldsOf(ctx);
+  if (fields instanceof Response) return fields;
+  const b = videosObj(ctx.body);
+  // source: https://developers.tiktok.com/doc/tiktok-api-v2-video-list "Default is 10. Maximum is 20."
+  const max = b.max_count === undefined ? 10 : Number(b.max_count);
+  if (!Number.isInteger(max) || max < 1 || max > 20) return refuse(ctx, 400, 'invalid_params', 'max_count must be between 1 and 20');
+  // source: https://developers.tiktok.com/doc/tiktok-api-v2-video-list "the cursor value is a"
+  const cursor = b.cursor === undefined ? Infinity : Number(b.cursor);
+  const { page, cursor: after, more } = videoPage(ctx, String(c.person.id), cursor, max);
+  return ok(ctx, { videos: page.map((v) => project(ctx, v, fields)), cursor: after, has_more: more });
+}
+
+// source: https://developers.tiktok.com/doc/tiktok-api-v2-video-query "verifies that the videos belong to the user and returns video details."
+export async function videoQuery(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx, 'video.list');
+  if (c instanceof Response) return c;
+  const fields = fieldsOf(ctx);
+  if (fields instanceof Response) return fields;
+  const ids = Array.isArray(videosObj(videosObj(ctx.body).filters).video_ids) ? (videosObj(videosObj(ctx.body).filters).video_ids as unknown[]).map(String) : [];
+  // source: https://developers.tiktok.com/doc/tiktok-api-v2-video-query "Up to 20 video IDs can be included per request."
+  if (!ids.length || ids.length > 20) return refuse(ctx, 400, 'invalid_params', 'filters.video_ids must hold 1 to 20 ids');
+  const mine = ctx.rowsRaw(VIDEO).filter((v) => v.deleted !== true && v._person === c.person.id && ids.includes(String(v.id)));
+  return ok(ctx, { videos: mine.map((v) => project(ctx, v, fields)) });
+}
+
+// source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "All parts are uploaded."
+export async function uploadVideo(ctx: HandlerContext): Promise<Response> {
+  const q = new URL(ctx.call.request.url).searchParams;
+  const p = ctx.rowsRaw(PUBLISH).find((x) => x.deleted !== true && x._upload_id === q.get('upload_id'));
+  // source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "TikTok cannot find a valid upload task given the"
+  if (!p || p._upload_token_sha256 !== sha256(ctx, q.get('upload_token') ?? '')) return new Response(null, { status: 404 });
+  // source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "has expired."
+  if (Number(p._upload_expires) <= seconds(ctx.occurredAt)) return new Response(null, { status: 403 });
+  const size = Number(p._video_size);
+  const id = String(p.id);
+  // the chunks received are one subject each; the progress is their sum, never a running total
+  const received = (): Row[] => ctx.rowsRaw(CHUNK).filter((k) => k.publish === id);
+  const uploaded = received().reduce((n, k) => n + Number(k.bytes), 0);
+  const range = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(ctx.call.request.headers.get('content-range') ?? '');
+  const bytes = new Uint8Array(await ctx.call.request.clone().arrayBuffer());
+  const progress = { 'content-range': `bytes 0-${Math.max(uploaded - 1, 0)}/${size}` };
+  if (!range) return new Response(null, { status: 400, headers: progress });
+  const [first, last, total] = [Number(range[1]), Number(range[2]), Number(range[3])];
+  // source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "does not reflect the actual upload progress."
+  if (p.status !== 'PROCESSING_UPLOAD' || first !== uploaded || total !== size) return new Response(null, { status: 416, headers: progress });
+  const chunk = Number(p._chunk_size);
+  const index = Math.floor(first / chunk);
+  const expected = index === Number(p._chunks) - 1 ? size - first : chunk;
+  // source: https://developers.tiktok.com/doc/content-posting-api-media-transfer-guide "does not reflect the true byte size of the binary in the request body."
+  if (last - first + 1 !== bytes.byteLength || bytes.byteLength !== expected) return new Response(null, { status: 400, headers: progress });
+  await ctx.blobs.put(`publish:${id}:${index}`, bytes);
+  await ctx.record(CHUNK, { publish: id, index, first, bytes: bytes.byteLength }, `${id}:${index}`);
+  const now = received().reduce((n, k) => n + Number(k.bytes), 0);
+  if (now < size) return partialChunk(ctx, id, now, size);
+  // the last chunk: the whole file is kept, and the post moves
+  const parts: Uint8Array[] = [];
+  for (let i = 0; i < Number(p._chunks); i++) parts.push((await ctx.blobs.get(`publish:${id}:${i}`)) ?? new Uint8Array(0));
+  const whole = new Uint8Array(size);
+  let at = 0;
+  for (const part of parts) { whole.set(part, at); at += part.byteLength; }
+  const direct = p._kind === 'direct';
+  const to = direct ? 'PUBLISH_COMPLETE' : 'SEND_TO_USER_INBOX';
+  const refused = ctx.legal(PUBLISH, 'status', 'uploadVideo', 'PROCESSING_UPLOAD', to, id, 'vendor');
+  if (refused) throw new Error(refused.message);
+  const post = publishObj(p._post_info);
+  let postIds: number[] = [];
+  if (direct) {
+    const facts = mp4Facts(whole);
+    const n = await next(ctx, 'video');
+    const videoId = String(7_400_000_000_000_000_000 + n * 1024);
+    const person = ctx.row('_person', String(p._person));
+    const isPublic = post.privacy_level === 'PUBLIC_TO_EVERYONE';
+    const title = typeof post.title === 'string' ? post.title : '';
+    // a video as the Video Object answers it ("Max length: 150" for title and description)
+    await ctx.write(VIDEO, videoId, {
+      id: videoId, create_time: seconds(ctx.occurredAt), _moment: videoMoment(ctx, String(person?.id ?? p._person)), cover_image_url: mediaUrl(ctx, `cover-${videoId}`), share_url: `https://www.tiktok.com/@${String(person?.username)}/video/${videoId}`,
+      video_description: title.slice(0, 150), duration: facts.duration, height: facts.height, width: facts.width, title: title.slice(0, 150),
+      embed_html: `<blockquote class="tiktok-embed" cite="https://www.tiktok.com/@${String(person?.username)}/video/${videoId}" data-video-id="${videoId}"></blockquote>`,
+      embed_link: `https://www.tiktok.com/player/v1/${videoId}`, like_count: 0, comment_count: 0, share_count: 0, view_count: 0, is_aigc: post.is_aigc === true,
+      _person: p._person, _public: isPublic, _publish: id,
+    }, 'video.publish');
+    // source: https://developers.tiktok.com/doc/content-posting-api-reference-get-video-status "is returned only if the post is published for public viewership"
+    if (isPublic) postIds = [Number(videoId)];
+  }
+  await ctx.write(PUBLISH, id, { status: to, uploaded_bytes: now, publicaly_available_post_id: postIds }, 'uploadVideo');
+  await ctx.blobs.put(`publish:${id}`, whole);
+  for (let i = 0; i < Number(p._chunks); i++) await ctx.blobs.remove(`publish:${id}:${i}`);
+  return new Response(null, { status: 201, headers: { 'content-range': `bytes 0-${now - 1}/${size}` } });
+}

package/package.json

@@ -1,40 +1,32 @@
 {
   "name": "@volter/twin-tiktok",
-  "version": "0.1.37",
-  "description": "Local TikTok twin — the real tiktok.com authorization page, the full Login Kit OAuth round trip (token, refresh, revoke, client_credentials) and the Display API user/video reads with TikTok's own comma-separated scopes, per-app open_id, field-level scope gating and both of its error envelopes, so an unmodified TikTok integration completes sign-in-with-TikTok against it. Built on @volter/world-core.",
+  "version": "1.0.0",
+  "description": "TikTok twin (Protocol 3): Login Kit's authorize page and tokens, the Content Posting API (videos by chunked upload, direct and to the inbox; photos pulled from verified URLs; post status) and the Display API (user info and stats, videos), as Postiz calls them. Built on @volter/world-core.",
   "keywords": [
     "twin",
-    "local",
-    "mock",
-    "mirror",
-    "simulator",
-    "fixtures",
-    "testing",
-    "oauth",
-    "oauth2",
     "tiktok",
-    "login-kit",
-    "display-api",
-    "identity",
-    "sign-in-with-tiktok"
+    "content-posting",
+    "login-kit"
   ],
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
   "files": [
     "src",
-    "client",
+    "journeys",
+    "business",
+    "open",
     "README.md",
     "LICENSE",
     "!**/*.test.ts",
-    "!**/*.test.tsx",
-    "dist"
+    "dist",
+    "generated"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/volter-ai/twin.git",
-    "directory": "packages/twin/tiktok"
+    "url": "git+https://github.com/volter-ai/twin-packs-p3.git",
+    "directory": "tiktok"
   },
-  "homepage": "https://world.volter.ai/twins/tiktok",
+  "homepage": "https://github.com/volter-ai/twin-packs-p3/tree/main/tiktok#readme",
   "type": "module",
   "exports": {
     ".": {
@@ -45,28 +37,8 @@
   "bin": {
     "world-tiktok": "dist/src/cli.js"
   },
-  "scripts": {
-    "test": "bun test src/*.test.ts",
-    "typecheck": "tsc --noEmit",
-    "build": "node ../../../scripts/publish/build.mjs",
-    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
-    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
-  },
-  "dependencies": {
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
-  },
   "peerDependencies": {
-    "@volter/world-core": "2.0.37"
-  },
-  "devDependencies": {
-    "@types/bun": "^1.2.20",
-    "@types/node": "^24.0.0",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@volter/world-core": "2.0.37",
-    "@volter/world-tooling": "0.1.0",
-    "typescript": "^5.9.0"
+    "@volter/world-core": "^3.0.38"
   },
   "engines": {
     "node": ">=22.3"

package/src/cli.ts

@@ -1,43 +1,22 @@
 #!/usr/bin/env node
-// world-tiktok CLI: serve the TikTok twin, or run conformance.
-//
-// `serve` starts the twin. `mirror` starts the same twin with tiktok.com's profile and player in
-// front of it (tiktok-mirror-ui.ts: the shell at `/`, everything else the twin's own fetch adapter),
-// and prints both screens an operator asks to "see": the mirror, and a ready-to-open authorize URL
-// for the authorization page the twin serves at the vendor's own path.
+// world-tiktok: serve the tiktok twin.
 import { hasFlag, optionValue } from '@volter/world-core/args';
 import { keepProcessAlive } from '@volter/world-core/lifecycle';
-import { createTikTokTwinServer } from './tiktok-server.ts';
-import { createTiktokMirrorServer } from './tiktok-mirror-ui.ts';
-import { DEFAULT_CLIENT_KEY, defaultRedirectUris } from './tiktok-store.ts';
+import { createTiktokTwinServer } from './server.ts';
 
 const [cmd, ...rest] = process.argv.slice(2);
 const port = Number(optionValue(rest, '--port', '0')) || undefined;
 const root = optionValue(rest, '--root') || undefined;
-const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+const readOnly = hasFlag(rest, '--read-only');
+// the World's managed Postgres, which the runtime binds a pack declaring managedDatabase to
+const database = optionValue(rest, '--database') || undefined;
+// the World's scenario file, for a model vendor's turns
+const scenarioPath = optionValue(rest, '--scenario') || undefined;
 
-if (cmd === 'serve' || cmd === 'mirror') {
-  const options = { readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) };
-  const s = cmd === 'mirror' ? await createTiktokMirrorServer(options) : await createTikTokTwinServer(options);
-  const origin = `http://127.0.0.1:${s.port}`;
-  process.stdout.write(`tiktok twin (Login Kit OAuth + Display API + Content Posting)${readOnly ? ' [read-only]' : ''} at ${origin}\n`);
-  if (cmd === 'mirror') {
-    process.stdout.write(`mirror (tiktok.com profile + player): ${origin}/\n`);
-    const url = new URL(`${origin}/v2/auth/authorize`);
-    url.searchParams.set('client_key', DEFAULT_CLIENT_KEY);
-    url.searchParams.set('response_type', 'code');
-    url.searchParams.set('redirect_uri', defaultRedirectUris(origin)[0]!);
-    url.searchParams.set('scope', 'user.info.basic,user.info.profile,video.list');
-    url.searchParams.set('state', 'twin-demo-state');
-    process.stdout.write(`authorization page: ${url.toString()}\n`);
-  }
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createTiktokTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {}) });
+  process.stdout.write(`tiktok twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
   await keepProcessAlive();
-} else if (cmd === 'conformance') {
-  // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
-  const { checkTikTokConformance } = await import('./tiktok-conformance.ts');
-  const report = await checkTikTokConformance({ ...(root ? { root } : {}) });
-  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-  if (!report.ok) process.exitCode = 1;
 } else {
-  process.stdout.write('Usage: world-tiktok serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+  process.stdout.write('Usage: world-tiktok serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]\n');
 }

package/src/fetch.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the vendor's discovery door and
+// sends each request to the lane its manifest's routes name (architecture, "Other wires: lanes").
+import { createVendorFetch, type DerivedFetch, type PackFetchOptions } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import { createBusinessLaneFetch, manifest as business_manifest } from '../business/src/index.ts';
+import { createOpenLaneFetch, manifest as open_manifest } from '../open/src/index.ts';
+
+export function createTiktokFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createVendorFetch(manifest, { "business": { fetch: createBusinessLaneFetch(options), manifest: business_manifest }, "open": { fetch: createOpenLaneFetch(options), manifest: open_manifest } });
+}