@volter/twin-tiktok 0.1.37 → 1.0.0

package/dist/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/dist/business/src/fetch.d.ts

@@ -0,0 +1,2 @@
+import { type DerivedFetch, type PackFetchOptions } from '@volter/world-core';
+export declare function createBusinessLaneFetch(options?: PackFetchOptions): DerivedFetch;

package/dist/business/src/fetch.js

@@ -0,0 +1,13 @@
+// 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 } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { businessSemantics } from "./semantics/index.js";
+export function createBusinessLaneFetch(options = {}) {
+    return createPackFetch({
+        manifest,
+        surface: surface,
+        handlers: businessSemantics,
+    }, options);
+}

package/dist/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/dist/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/dist/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/dist/business/src/index.d.ts

@@ -0,0 +1,2 @@
+export { createBusinessLaneFetch } from './fetch.js';
+export { manifest } from './manifest.js';

package/dist/business/src/index.js

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

package/dist/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/dist/business/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedManifest } from '@volter/world-core';
+export declare const manifest: DerivedManifest;

package/dist/business/src/manifest.js

@@ -0,0 +1,33 @@
+import { states } from "./semantics/states.js";
+export const manifest = {
+    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/dist/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/dist/business/src/semantics/index.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from '@volter/world-core';
+export declare const businessSemantics: Record<string, Handler>;

package/dist/business/src/semantics/index.js

@@ -0,0 +1,12 @@
+import * as open_api from "./open_api.js";
+export const businessSemantics = {
+    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/dist/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/dist/business/src/semantics/open_api.d.ts

@@ -0,0 +1,10 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function ttUserOauth2Token(ctx: HandlerContext): Promise<Response>;
+export declare function ttUserOauth2RefreshToken(ctx: HandlerContext): Promise<Response>;
+export declare function businessGet(ctx: HandlerContext): Promise<Response>;
+export declare function businessVideoList(ctx: HandlerContext): Promise<Response>;
+export declare function businessVideoPublish(ctx: HandlerContext): Promise<Response>;
+export declare function businessPhotoPublish(ctx: HandlerContext): Promise<Response>;
+export declare function businessPublishStatus(ctx: HandlerContext): Promise<Response>;
+export declare function businessPublishLocation(ctx: HandlerContext): Promise<Response>;
+export declare function discoveryCmlTrendingList(ctx: HandlerContext): Promise<Response>;

package/dist/business/src/semantics/open_api.js

@@ -0,0 +1,162 @@
+import { CODE, DEFAULT, NO_PERMISSION, PARAM, PERSON, PUBLISH, REFRESH, VIDEO, appOf, authorized, bodyOf, bySha, issue, jsonArray, mediaUrl, ok, postsFields, privacyOptions, profileFields, publish, publishObj, refuse, seconds, videoPage } from "./shared.js";
+// 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) {
+    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) {
+    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) {
+    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 = {
+        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) {
+    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) => {
+        const all = {
+            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) {
+    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) {
+    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.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) {
+    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) {
+    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) {
+    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/dist/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 },
+    })),
+  });
+}