@volter/twin-tiktok 0.1.37 → 1.0.0

package/business/spec/sources.json

@@ -0,0 +1,84 @@
+{
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "These return codes take precedence over HTTP status codes": true,
+      "The interface (endpoint) has not been implemented.": true,
+      "Invalid authorization code.": true,
+      "Invalid or incorrect refresh token.": true,
+      "Successful": true,
+      "Invalid or incorrect access token.": true,
+      "The access token is empty.": true,
+      "The access token has expired.": true,
+      "No permission to perform the related operation.": true,
+      "App ID or secret is incorrect.": true
+    }
+  },
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1738084387220481&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "The code is valid for 10 minutes and can only be used once.": true,
+      "Use this endpoint to renew a TikTok account access token by": true
+    }
+  },
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1762228399168514&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Requested fields. If not set, returns the": true,
+      "Use this endpoint to access detailed analytics and insights about a TikTok account": true
+    }
+  },
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1762228421622786&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "you need to at least include": true,
+      "Maximum value": true
+    }
+  },
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1762228496095234&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "This field is required, even if you don't want to use any of the additional parameters": true
+    }
+  },
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1803630424390658&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "A list of up to 35 publicly accessible HTTP(s) URLs for the photo content to be published.": true,
+      "Length limit: 90 runes (UTF-16 code units).": true
+    }
+  },
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1816387106635778&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "The publishing status of the TikTok post.": true,
+      "Returned only when": true
+    }
+  },
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1825119063013505&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Commercial Music Library": true,
+      "Default value": true
+    }
+  },
+  "https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1870580030749698&language=ENGLISH": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "Length limit: 100 characters.": true
+    }
+  },
+  "https://developers.tiktok.com/doc/content-posting-api-reference-get-video-status": {
+    "status": 200,
+    "checked": "2026-10-03"
+  }
+}

package/business/src/fetch.ts

@@ -0,0 +1,14 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,
+// the World's doors, the vendor's screens and the API from the pack's parts (architecture, "The pack contract").
+import { createPackFetch, type DerivedFetch, type DerivedSurface, type PackFetchOptions } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { businessSemantics } from './semantics/index.ts';
+
+export function createBusinessLaneFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createPackFetch({
+    manifest,
+    surface: surface as DerivedSurface,
+    handlers: businessSemantics,
+  }, options);
+}

package/business/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi.json","format":"openapi","version":"v1.3","resources":[],"operations":[{"id":"businessGet","method":"get","path":"/open_api/v1.3/business/get/","pathParams":[],"query":[{"name":"business_id","type":"string","required":true},{"name":"fields","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"businessPhotoPublish","method":"post","path":"/open_api/v1.3/business/photo/publish/","pathParams":[],"query":[],"body":[{"name":"business_id","type":"string","required":false},{"name":"photo_cover_index","type":"integer","required":false},{"name":"photo_images","type":"array","required":false},{"name":"post_info","type":"object","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"businessPublishLocation","method":"get","path":"/open_api/v1.3/business/publish/location/","pathParams":[],"query":[{"name":"business_id","type":"string","required":true},{"name":"search_query","type":"string","required":true}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"businessPublishStatus","method":"get","path":"/open_api/v1.3/business/publish/status/","pathParams":[],"query":[{"name":"business_id","type":"string","required":true},{"name":"publish_id","type":"string","required":true}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"businessVideoList","method":"get","path":"/open_api/v1.3/business/video/list/","pathParams":[],"query":[{"name":"business_id","type":"string","required":true},{"name":"cursor","type":"integer","required":false},{"name":"fields","type":"string","required":false},{"name":"max_count","type":"integer","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"businessVideoPublish","method":"post","path":"/open_api/v1.3/business/video/publish/","pathParams":[],"query":[],"body":[{"name":"business_id","type":"string","required":false},{"name":"custom_thumbnail_url","type":"string","required":false},{"name":"post_info","type":"object","required":false},{"name":"video_url","type":"string","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"discoveryCmlTrendingList","method":"get","path":"/open_api/v1.3/discovery/cml/trending_list/","pathParams":[],"query":[{"name":"business_id","type":"string","required":true},{"name":"genre","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"ttUserOauth2RefreshToken","method":"post","path":"/open_api/v1.3/tt_user/oauth2/refresh_token/","pathParams":[],"query":[],"body":[{"name":"client_id","type":"string","required":false},{"name":"client_secret","type":"string","required":false},{"name":"grant_type","type":"string","required":false},{"name":"refresh_token","type":"string","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"ttUserOauth2Revoke","method":"post","path":"/open_api/v1.3/tt_user/oauth2/revoke/","pathParams":[],"query":[],"body":[{"name":"access_token","type":"string","required":false},{"name":"client_id","type":"string","required":false},{"name":"client_secret","type":"string","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"ttUserOauth2Token","method":"post","path":"/open_api/v1.3/tt_user/oauth2/token/","pathParams":[],"query":[],"body":[{"name":"auth_code","type":"string","required":false},{"name":"client_id","type":"string","required":false},{"name":"client_secret","type":"string","required":false},{"name":"grant_type","type":"string","required":false},{"name":"redirect_uri","type":"string","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"},{"id":"ttUserTokenInfoGet","method":"post","path":"/open_api/v1.3/tt_user/token_info/get/","pathParams":[],"query":[],"body":[{"name":"access_token","type":"string","required":false},{"name":"app_id","type":"string","required":false}],"bodyEncoding":"json","successStatus":200,"class":"non-resource"}]}

package/business/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"publish":{"actions":[],"states":{"status":["FAILED","PROCESSING_DOWNLOAD","PROCESSING_UPLOAD","PUBLISH_COMPLETE","SEND_TO_USER_INBOX"]},"embeds":{}},"video":{"actions":[],"states":{},"embeds":{}},"_access_token":{"actions":[],"states":{},"embeds":{}},"_refresh_token":{"actions":[],"states":{},"embeds":{}},"_seq_publish":{"actions":[],"states":{},"embeds":{}},"_seq_video":{"actions":[],"states":{},"embeds":{}}}}

package/business/src/index.ts

@@ -0,0 +1,3 @@
+// The business lane of the tiktok pack: the vendor's manifest routes its requests here.
+export { createBusinessLaneFetch } from './fetch.ts';
+export { manifest } from './manifest.ts';

package/business/src/manifest.ts

@@ -0,0 +1,38 @@
+// The business lane's manifest: the vendor facts its spec (../spec, written from the API for Business v1.3 pages) does
+// not carry. Served is what Postiz's TikTok Business provider calls (../../journeys/demand.json,
+// ../../journeys/decisions.json); revoking and the token's scopes are `unmodeled`.
+import type { DerivedManifest } from '@volter/world-core';
+import { states } from './semantics/states.ts';
+
+export const manifest: DerivedManifest = {
+  vendor: 'tiktok',
+  // the vendor's one store: the open lane's apps, people, codes, posts and videos are these too
+  service: 'tiktok',
+  body: { json: 'always' },
+  ids: { template: '{uuid}' },
+  time: 'unix',
+  // "Every Business API endpoint (except OAuth) ... wraps the payload in {code, message, data}" (Postiz reads it so):
+  // a refusal is a non-zero code, answered HTTP 200
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "These return codes take precedence over HTTP status codes"
+  error: { code: '{code}', message: '{message}', request_id: '{id}', data: {} },
+  errorsAnsweredAs: { status: 200, below: 500 },
+  readOnly: { status: 200, message: 'This twin was started read-only; writes are refused.' },
+  notFound: { status: 200, code: 40008, message: "The interface (endpoint) has not been implemented." },
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "The interface (endpoint) has not been implemented."
+  // Where documentation stops: token errors do not establish an authentication gate before unknown-route resolution.
+  gap: { status: 200, code: 40008, message: "The interface (endpoint) has not been implemented." },
+  deleted: {},
+  resources: {
+    publish: { idPrefix: '', ...states.publish },
+    video: { idPrefix: '' },
+    _access_token: { idPrefix: 'act_', ids: '{prefix}{n}' },
+    _refresh_token: { idPrefix: 'rft_', ids: '{prefix}{n}' },
+    _seq_publish: { idPrefix: '', ids: '{n}' },
+    _seq_video: { idPrefix: '', ids: '{n}' },
+  },
+  unmodeled: ['ttUserOauth2Revoke', 'ttUserTokenInfoGet'],
+  discovery: {
+    twinOf: "TikTok's API for Business v1.3 as a TikTok account's owner uses it: its tokens, its profile, its posts, publishing videos and photos by URL, the publishing status, location tags and the Commercial Music Library's popular tracks",
+    stores: "the vendor's one store (the open lane's): apps, people, codes and tokens, posts and videos, and the World's location tags and tracks",
+  },
+};

package/business/src/semantics/index.ts

@@ -0,0 +1,16 @@
+// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families' files (each
+// handler named as its operation). Do not edit; add a handler to its family's file and generate again.
+import type { Handler } from '@volter/world-core';
+import * as open_api from './open_api.ts';
+
+export const businessSemantics: Record<string, Handler> = {
+  businessGet: open_api.businessGet,
+  businessPhotoPublish: open_api.businessPhotoPublish,
+  businessPublishLocation: open_api.businessPublishLocation,
+  businessPublishStatus: open_api.businessPublishStatus,
+  businessVideoList: open_api.businessVideoList,
+  businessVideoPublish: open_api.businessVideoPublish,
+  discoveryCmlTrendingList: open_api.discoveryCmlTrendingList,
+  ttUserOauth2RefreshToken: open_api.ttUserOauth2RefreshToken,
+  ttUserOauth2Token: open_api.ttUserOauth2Token,
+};

package/business/src/semantics/open_api.ts

@@ -0,0 +1,142 @@
+import type { HandlerContext } from '@volter/world-core';
+import { ACCESS, ACCESS_TTL, APP, CODE, DEFAULT, NO_PERMISSION, PARAM, PERSON, PUBLISH, REFRESH, REFRESH_TTL, VIDEO, appOf, authorized, bodyOf, bySha, clientSecret, credential, issue, jsonArray, madeVideo, mediaUrl, next, ok, openIdOf, postsFields, privacyOptions, profileFields, publish, publishObj, pullAll, refuse, seconds, type Row, videoMoment, videoPage } from './shared.ts';
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1738084387220481&language=ENGLISH "The code is valid for 10 minutes and can only be used once."
+export async function ttUserOauth2Token(ctx: HandlerContext): Promise<Response> {
+  const app = await appOf(ctx);
+  if (app instanceof Response) return app;
+  const b = bodyOf(ctx);
+  if (b.grant_type !== 'authorization_code') return refuse(ctx, PARAM, 'grant_type must be authorization_code.');
+  const code = typeof b.auth_code === 'string' ? bySha(ctx, CODE, b.auth_code) : undefined;
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "Invalid authorization code."
+  if (!code || code.used === true || code.app !== app.id || Number(code.expires_at) <= seconds(ctx.occurredAt)) return refuse(ctx, 40110, 'Invalid authorization code. The auth_code is canceled, already used or expired.');
+  if (typeof b.redirect_uri === 'string' && b.redirect_uri !== code.redirect_uri) return refuse(ctx, PARAM, 'redirect_uri does not match the one the code was issued for.');
+  await ctx.record(CODE, { ...code, used: true }, String(code.id));
+  return issue(ctx, app, ctx.row(PERSON, String(code.person))!, String(code.scope));
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1738084387220481&language=ENGLISH "Use this endpoint to renew a TikTok account access token by"
+export async function ttUserOauth2RefreshToken(ctx: HandlerContext): Promise<Response> {
+  const app = await appOf(ctx);
+  if (app instanceof Response) return app;
+  const b = bodyOf(ctx);
+  if (b.grant_type !== 'refresh_token') return refuse(ctx, PARAM, 'grant_type must be refresh_token.');
+  const held = typeof b.refresh_token === 'string' ? bySha(ctx, REFRESH, b.refresh_token) : undefined;
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "Invalid or incorrect refresh token."
+  if (!held || held.used === true || held.kind !== 'business' || held.app !== app.id || Number(held.expires_at) <= seconds(ctx.occurredAt)) return refuse(ctx, 40107, 'Invalid or incorrect refresh token.');
+  await ctx.record(REFRESH, { ...held, used: true }, String(held.id));
+  return issue(ctx, app, ctx.row(PERSON, String(held.person))!, String(held.scope));
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1762228399168514&language=ENGLISH "Use this endpoint to access detailed analytics and insights about a TikTok account"
+export async function businessGet(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx);
+  if (c instanceof Response) return c;
+  const asked = jsonArray(ctx, 'fields');
+  if (asked instanceof Response) return asked;
+  const fields = asked ?? DEFAULT;
+  const unknown = fields.filter((f) => !profileFields.includes(f));
+  if (unknown.length) return refuse(ctx, PARAM, `Invalid fields: ${unknown.join(', ')}`);
+  const p = c.person;
+  const all: Row = {
+    display_name: p.display_name, profile_image: mediaUrl(ctx, `avatar-${String(p.id)}`), username: p.username, profile_deep_link: `https://www.tiktok.com/@${String(p.username)}`,
+    bio_description: p.bio_description ?? '', is_verified: p.is_verified === true, followers_count: Number(p.follower_count ?? 0), following_count: Number(p.following_count ?? 0),
+    total_likes: Number(p.likes_count ?? 0),
+    // the account's public videos, counted from the set
+    videos_count: ctx.rowsRaw(VIDEO).filter((v) => v.deleted !== true && v._person === p.id && v._public === true).length,
+  };
+  return ok(ctx, Object.fromEntries(fields.map((f) => [f, all[f]])));
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1762228421622786&language=ENGLISH "you need to at least include"
+export async function businessVideoList(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx);
+  if (c instanceof Response) return c;
+  const asked = jsonArray(ctx, 'fields');
+  if (asked instanceof Response) return asked;
+  const fields = asked ?? ['item_id'];
+  if (!fields.includes('item_id') || fields.some((f) => !postsFields.includes(f))) return refuse(ctx, PARAM, 'fields must include item_id and name only the supported fields.');
+  const q = new URL(ctx.call.request.url).searchParams;
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1762228421622786&language=ENGLISH "Maximum value"
+  const max = q.get('max_count') === null ? 10 : Number(q.get('max_count'));
+  if (!Number.isInteger(max) || max < 1 || max > 20) return refuse(ctx, PARAM, 'max_count must be between 1 and 20.');
+  const cursor = q.get('cursor') === null ? Infinity : Number(q.get('cursor'));
+  const { page, cursor: after, more } = videoPage(ctx, String(c.person.id), cursor, max);
+  const post = (v: Row): Row => {
+    const all: Row = {
+      item_id: v.id, create_time: v.create_time, thumbnail_url: v.cover_image_url, share_url: v.share_url, embed_url: v.embed_link, caption: v.video_description,
+      video_duration: v.duration, likes: v.like_count, comments: v.comment_count, shares: v.share_count, video_views: v.view_count,
+    };
+    return Object.fromEntries(fields.map((f) => [f, all[f]]));
+  };
+  return ok(ctx, { videos: page.map(post), cursor: after, has_more: more });
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1762228496095234&language=ENGLISH "This field is required, even if you don't want to use any of the additional parameters"
+export async function businessVideoPublish(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx, 'video.publish');
+  if (c instanceof Response) return c;
+  const b = bodyOf(ctx);
+  if (typeof b.video_url !== 'string' || !/^https?:\/\//.test(b.video_url)) return refuse(ctx, PARAM, 'video_url must be an http(s) URL.');
+  if (b.post_info === undefined || typeof b.post_info !== 'object') return refuse(ctx, PARAM, 'post_info is required.');
+  const post = publishObj(b.post_info);
+  if (typeof post.is_brand_organic !== 'boolean' || typeof post.is_branded_content !== 'boolean') return refuse(ctx, PARAM, 'post_info.is_brand_organic and post_info.is_branded_content are required.');
+  return publish(ctx, 'VIDEO', [b.video_url], post, post.upload_to_draft === true, c.person);
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1803630424390658&language=ENGLISH "A list of up to 35 publicly accessible HTTP(s) URLs for the photo content to be published."
+export async function businessPhotoPublish(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx, 'video.publish');
+  if (c instanceof Response) return c;
+  const b = bodyOf(ctx);
+  const images = Array.isArray(b.photo_images) ? (b.photo_images as unknown[]).map(String) : [];
+  if (images.length < 1 || images.length > 35) return refuse(ctx, PARAM, 'photo_images must hold 1 to 35 URLs.');
+  const cover = Number(b.photo_cover_index ?? 0);
+  if (!Number.isInteger(cover) || cover < 0 || cover >= images.length) return refuse(ctx, PARAM, 'photo_cover_index must index photo_images.');
+  const post = publishObj(b.post_info);
+  const draft = post.is_draft === true;
+  if (typeof post.is_brand_organic !== 'boolean' || typeof post.is_branded_content !== 'boolean') return refuse(ctx, PARAM, 'post_info.is_brand_organic and post_info.is_branded_content are required.');
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1803630424390658&language=ENGLISH "Length limit: 90 runes (UTF-16 code units)."
+  if (typeof post.title === 'string' && post.title.length > 90) return refuse(ctx, PARAM, 'post_info.title is over 90 characters.');
+  if (!draft && !privacyOptions(c.person).includes(String(post.privacy_level))) return refuse(ctx, PARAM, 'post_info.privacy_level must be one of the account\'s privacy levels.');
+  return publish(ctx, 'PHOTO', images, post, draft, c.person);
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1816387106635778&language=ENGLISH "The publishing status of the TikTok post."
+// post_ids are "Returned only when" the status is PUBLISH_COMPLETE, the reason when FAILED
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1816387106635778&language=ENGLISH "Returned only when"
+export async function businessPublishStatus(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx);
+  if (c instanceof Response) return c;
+  const id = String(ctx.params.publish_id ?? '');
+  const p = ctx.row(PUBLISH, id);
+  if (!p || p.deleted === true) return refuse(ctx, PARAM, 'publish_id does not exist.');
+  if (p._person !== c.person.id) return refuse(ctx, NO_PERMISSION, 'No permission to read this publishing task.');
+  return ok(ctx, { status: p.status, ...(p.status === 'PUBLISH_COMPLETE' ? { post_ids: p.post_ids ?? [] } : {}), ...(p.status === 'FAILED' ? { reason: p.reason } : {}) });
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1870580030749698&language=ENGLISH "Length limit: 100 characters."
+export async function businessPublishLocation(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx);
+  if (c instanceof Response) return c;
+  const q = String(ctx.params.search_query ?? '');
+  if (!q || q.length > 100) return refuse(ctx, PARAM, 'search_query must be 1 to 100 characters.');
+  const words = q.toLowerCase().split(/\s+/).filter(Boolean);
+  const found = ctx.rowsRaw('_location').filter((l) => words.every((w) => `${String(l.location_name)} ${String(l.location_address)}`.toLowerCase().includes(w)));
+  return ok(ctx, { locations: found.map((l) => ({ location_id: l.id, location_name: l.location_name, location_address: l.location_address })) });
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1825119063013505&language=ENGLISH "Commercial Music Library"
+export async function discoveryCmlTrendingList(ctx: HandlerContext): Promise<Response> {
+  const c = authorized(ctx);
+  if (c instanceof Response) return c;
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1825119063013505&language=ENGLISH "Default value"
+  const genre = typeof ctx.params.genre === 'string' && ctx.params.genre.toUpperCase() !== 'ALL' ? ctx.params.genre.toUpperCase() : undefined;
+  const tracks = ctx.rowsRaw('_track').filter((t) => !genre || t.genre === genre);
+  return ok(ctx, {
+    list: tracks.map((t) => ({
+      commercial_music_id: t.id, commercial_music_name: t.name, artist: t.artist, thumbnail_url: t.thumbnail_url, duration: t.duration, preview_url: t.preview_url, genre: t.genre,
+      full_duration_song_clip: { song_clip_id: t.song_clip_id, duration: t.duration, preview_url: t.preview_url },
+    })),
+  });
+}

package/business/src/semantics/shared.ts

@@ -0,0 +1,119 @@
+// What every family of the business lane shares beyond the vendor's (../../../src/semantics/shared.ts): the API for
+// Business's envelope (`{code, message, request_id, data}`, a refusal a non-zero code at HTTP 200) and who a request is
+// (its Access-Token, a business app's, and the business_id it names).
+import type { HandlerContext } from '@volter/world-core';
+import { ACCESS, ACCESS_TTL, APP, CODE, PERSON, PUBLISH, REFRESH, REFRESH_TTL, VIDEO, bodyOf, bySha, clientSecret, credential, mediaUrl, next, openIdOf, privacyOptions, seconds, type Row, videoMoment, videoPage } from '../../../src/semantics/shared.ts';
+
+export * from '../../../src/semantics/shared.ts';
+export type { HandlerContext };
+
+/** A request's id, as the API answers it. */
+const requestId = (ctx: Pick<HandlerContext, 'crypto' | 'occurredAt'>, what: string): string =>
+  `${ctx.occurredAt.replace(/\D/g, '').slice(0, 14)}${ctx.crypto.digest('sha256', `${ctx.occurredAt}:business:${what}`, 'hex').slice(0, 18).toUpperCase()}`;
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "Successful"
+export const ok = (ctx: Pick<HandlerContext, 'crypto' | 'occurredAt'>, data: unknown): Response =>
+  Response.json({ code: 0, message: 'OK', request_id: requestId(ctx, JSON.stringify(data)), data });
+/** A refusal: its code and message, at HTTP 200. */
+export const refuse = (ctx: Pick<HandlerContext, 'crypto' | 'occurredAt'>, code: number, message: string): Response =>
+  Response.json({ code, message, request_id: requestId(ctx, `${code}:${message}`), data: {} });
+
+// the codes the lane answers (Appendix - Return codes)
+export const PARAM = 40002;
+export const NO_PERMISSION = 40001;
+
+/** Who a request is: the business access token its Access-Token header bears, live, with its app and its person. */
+export type Caller = { token: Row; app: Row; person: Row; scopes: string[]; openId: string };
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "Invalid or incorrect access token."
+export function authorized(ctx: HandlerContext, scope?: string): Caller | Response {
+  const value = ctx.call.request.headers.get('access-token') ?? '';
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "The access token is empty."
+  if (!value) return refuse(ctx, 40104, 'The access token is empty.');
+  const token = bySha(ctx, ACCESS, value);
+  if (!token || token.kind !== 'business' || token.revoked === true) return refuse(ctx, 40105, 'Invalid or incorrect access token.');
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "The access token has expired."
+  if (Number(token.expires_at) <= seconds(ctx.occurredAt)) return refuse(ctx, 40102, 'The access token has expired.');
+  const app = ctx.row(APP, String(token.app))!;
+  const person = ctx.row(PERSON, String(token.person))!;
+  const openId = openIdOf(ctx, app, person);
+  const businessId = String(ctx.params.business_id ?? '');
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "No permission to perform the related operation."
+  if (businessId !== openId) return refuse(ctx, NO_PERMISSION, 'No permission to operate this TikTok account: business_id is not the access token\'s.');
+  const scopes = String(token.scope).split(',');
+  if (scope && !scopes.includes(scope)) return refuse(ctx, NO_PERMISSION, `No permission: the TikTok account did not grant ${scope}.`);
+  return { token, app, person, scopes, openId };
+}
+
+/** A JSON-array query parameter (`fields`, as Postiz sends it), or the refusal. */
+export function jsonArray(ctx: HandlerContext, name: string): string[] | undefined | Response {
+  const raw = new URL(ctx.call.request.url).searchParams.get(name);
+  if (raw === null) return undefined;
+  try {
+    const v = JSON.parse(raw) as unknown;
+    if (Array.isArray(v) && v.every((x) => typeof x === 'string')) return v as string[];
+  } catch { /* the refusal below */ }
+  return refuse(ctx, PARAM, `${name} must be a JSON array of strings.`);
+}
+
+export async function appOf(ctx: HandlerContext): Promise<Row | Response> {
+  const b = bodyOf(ctx);
+  const app = ctx.rowsRaw(APP).find((a) => a.deleted !== true && a.kind === 'business' && a.client_key === b.client_id);
+  // source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1737172488964097&language=ENGLISH "App ID or secret is incorrect."
+  if (!app || b.client_secret !== await clientSecret(ctx, app)) return refuse(ctx, 40131, 'App ID or secret is incorrect.');
+  return app;
+}
+
+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', { kind: 'business', app: app.id, person: person.id, scope, expires_at: now + ACCESS_TTL, revoked: false });
+  const refresh = await credential(ctx, REFRESH, 'rft', { kind: 'business', app: app.id, person: person.id, scope, access: access.id, expires_at: now + REFRESH_TTL, used: false });
+  return ok(ctx, { access_token: access.value, token_type: 'Bearer', scope, expires_in: ACCESS_TTL, refresh_token: refresh.value, refresh_token_expires_in: REFRESH_TTL, open_id: openIdOf(ctx, app, person) });
+}
+
+// source: https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b&doc_id=1762228399168514&language=ENGLISH "Requested fields. If not set, returns the"
+export const DEFAULT = ['display_name', 'profile_image'];
+
+export const profileFields = ['display_name', 'profile_image', 'username', 'profile_deep_link', 'bio_description', 'is_verified', 'followers_count', 'following_count', 'total_likes', 'videos_count'];
+
+export const postsFields = ['item_id', 'create_time', 'thumbnail_url', 'share_url', 'embed_url', 'caption', 'video_duration', 'likes', 'comments', 'shares', 'video_views'];
+
+export const publishObj = (v: unknown): Row => (v && typeof v === 'object' && !Array.isArray(v) ? v as Row : {});
+
+/** Pull each URL through the World; the bytes pulled, or undefined when one fails. */
+export async function pullAll(ctx: HandlerContext, urls: string[]): Promise<number | undefined> {
+  let n = 0;
+  for (const url of urls) {
+    try {
+      const r = await ctx.vendorFetch(url, { method: 'GET' });
+      if (!r.ok) return undefined;
+      n += (await r.arrayBuffer()).byteLength;
+    } catch { return undefined; }
+  }
+  return n;
+}
+
+/** The video a completed pull makes (the Video Object, as the open lane makes them), public; its id. */
+export async function madeVideo(ctx: HandlerContext, publishId: string, post: Row, person: Row): Promise<string> {
+  const videoId = String(7_400_000_000_000_000_000 + (await next(ctx, 'video')) * 1024);
+  const caption = typeof post.caption === 'string' ? post.caption : '';
+  await ctx.write(VIDEO, videoId, {
+    id: videoId, create_time: seconds(ctx.occurredAt), _moment: videoMoment(ctx, String(person.id)), cover_image_url: mediaUrl(ctx, `cover-${videoId}`), share_url: `https://www.tiktok.com/@${String(person.username)}/video/${videoId}`,
+    video_description: caption.slice(0, 150), duration: 0, height: 0, width: 0, title: caption.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_ai_generated === true,
+    _person: person.id, _public: true, _publish: publishId,
+  }, 'video.publish');
+  return videoId;
+}
+
+export async function publish(ctx: HandlerContext, media: 'VIDEO' | 'PHOTO', urls: string[], post: Row, draft: boolean, person: Row): Promise<Response> {
+  const n = await next(ctx, 'publish');
+  const id = `${media === 'VIDEO' ? 'v' : 'p'}_pub_url~v2.${n}`;
+  await ctx.write(PUBLISH, id, { status: 'PROCESSING_DOWNLOAD', post_ids: [], _person: person.id, _media: media, _urls: urls, _post_info: post, _draft: draft, _lane: 'business' }, media === 'VIDEO' ? 'businessVideoPublish' : 'businessPhotoPublish');
+  const pulled = await pullAll(ctx, urls);
+  const to = pulled === undefined ? 'FAILED' : draft ? 'SEND_TO_USER_INBOX' : 'PUBLISH_COMPLETE';
+  const refused = ctx.legal(PUBLISH, 'status', 'publish.pull', 'PROCESSING_DOWNLOAD', to, id, 'vendor');
+  if (refused) throw new Error(refused.message);
+  const postIds = to === 'PUBLISH_COMPLETE' && media === 'VIDEO' ? [await madeVideo(ctx, id, post, person)] : [];
+  await ctx.write(PUBLISH, id, { status: to, post_ids: postIds, ...(to === 'FAILED' ? { reason: media === 'VIDEO' ? 'video_pull_failed' : 'photo_pull_failed' } : {}) }, 'publish.pull');
+  return ok(ctx, { share_id: id });
+}

package/business/src/semantics/states.ts

@@ -0,0 +1,3 @@
+// Both lanes import the vendor’s one publish status declaration.
+import { publish } from '../../../src/semantics/shared.ts';
+export const states = { publish };

package/dist/business/spec/SOURCE.md

@@ -0,0 +1,17 @@
+# TikTok API for Business v1.3: the Accounts API and Discovery
+
+- **Why this document:** TikTok publishes no OpenAPI document of these endpoints (its SDK repository's yml files,
+  tiktok/tiktok-business-api-sdk @ f809c39652, are the Marketing API's). This document is written from the v1.3
+  documentation, one operation per endpoint. The portal (business-api.tiktok.com/portal/docs) renders in the browser;
+  each page's text is its docs gateway's answer, which each operation names (`externalDocs`) and the pack cites:
+  `https://business-api.tiktok.com/gateway/api/doc/client/node/get/v2/?identify_key=<v1.3>&doc_id=<page>&language=ENGLISH`
+  (the v1.3 key `c0138ffadd90a955c1f0670a56fe348d1d40680b3c89461e09f78ed26785164b`, from the portal's own bundle). Pages: Accounts API Authentication (1738084387220481),
+  Authorization (1738083939371009), Get profile data (1762228399168514), Get post data (1762228421622786), Publish a
+  public video post (1762228496095234), Publish a photo post (1803630424390658), Get the publishing status
+  (1816387106635778), Get the location tags (1870580030749698), Get popular tracks from the Commercial Music Library
+  (1825119063013505), Get TikTok account permission scopes (1765927978092545), Appendix - Return codes
+  (1737172488964097), fetched 2026-09-30.
+- **Its host:** business-api.tiktok.com.
+- **Corrections:** none.
+- **Read by:** the twin orchestrator, 2026-09-30.
+- **Vendored bytes (sha256):** `openapi.json` `ad0a7a19e49fba66c359b3ef12dbe8daeb112a36e1cc0a14f0e28f94fb26d4f9`.