@volter/twin-tiktok 0.1.0

package/dist/src/tiktok-connector.js

@@ -0,0 +1,600 @@
+// TikTok CONNECTOR — the live-vendor pull path.
+//
+// PULL (real -> twin): the twin's persona registry is only as useful as the identities in it, and
+// Login Kit exposes exactly two authenticated reads a user token can perform: `GET /v2/user/info/`
+// and the Display API's video reads. A pull observes the real account behind the operator's own
+// user access token and, on request, that account's public videos, and folds them into the
+// observed log.
+//
+// SCOPES DECIDE WHAT A PULL CAN SEE, and that is a fact about this vendor rather than a bug to
+// paper over:
+//   • `/v2/user/info/` fields are gated per scope (basic / profile / stats), so a token that holds
+//     only `user.info.basic` cannot observe `username` or `follower_count`. The default pull asks
+//     for EVERY modelled field — a default-field pull would silently observe a bald persona — and
+//     a token with fewer scopes must NARROW `userFields` explicitly. A `scope_not_authorized`
+//     refusal THROWS; it is never read as "the account has no username".
+//   • the video reads need `video.list`, which the common Login Kit integration (Dub's included)
+//     does not request. So `videos` is OPT-IN: a refused read must never fold an empty video list
+//     over observed state, and silently skipping it would make "no videos" ambiguous.
+//
+// WHAT A PULL CANNOT OBSERVE, recorded as reasoned gaps rather than faked:
+//   • the DEVELOPER APP registry — TikTok apps are created in the developer portal; no API reads
+//     them (`tiktok.connector.pull_clients`, todo);
+//   • the GRANT (which scopes this token holds) — TikTok publishes no token-introspection
+//     endpoint, so the granted set cannot be enumerated; a successful user/info read evidences the
+//     scopes of the fields it returned and nothing more (`tiktok.connector.pull_grants`, todo).
+//
+// PUSH of the identity surface is an honest gap, not an omission: TikTok exposes NO write API for apps,
+// users or grants — apps live in the developer portal, and a user's app permissions are managed in
+// TikTok's own settings. `pushPendingTikTokActions` reports that; filed as `tiktok.connector.push`
+// (todo). A World's POSTS are the exception, and they cross through the kernel's perform: the
+// Content Posting API is TikTok's own write door for a new video (PERFORM, below).
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold NO
+// TikTok credential and import NO network client. Offline/tests pass a fake executor; live runs
+// pass `liveTikTokExecute(accessToken)`. Same code path either way.
+import { assertBudgetGuardIntact, deployableEntries, observeResources } from '@volter/world-core';
+import { TikTokBudget, TikTokBudgetError, tiktokBudgetPath, tiktokCallWeight } from "./tiktok-budget.js";
+import { clearPerformPublish, readPerformPublish, readTikTokBlobRange, tikTokBlobSize, writePerformPublish } from "./tiktok-blobs.js";
+import { USER_FIELDS, VIDEO_FIELDS } from "./tiktok-user.js";
+const SERVICE = 'tiktok';
+/** TikTok's real API host — the live executor's routing table. ONLY mapped paths may be called
+ *  live. The token/revoke paths are mapped so a live rehearsal can refresh or revoke the
+ *  operator's OWN token through the guarded path; nothing else on open.tiktokapis.com is
+ *  reachable, which is what keeps an unmodelled surface from being poked by accident (D8). */
+const HOSTS = {
+    '/v2/user/info': 'https://open.tiktokapis.com',
+    '/v2/video/list': 'https://open.tiktokapis.com',
+    '/v2/video/query': 'https://open.tiktokapis.com',
+    '/v2/oauth/token': 'https://open.tiktokapis.com',
+    '/v2/oauth/revoke': 'https://open.tiktokapis.com',
+};
+/** Every modelled user field a pull requests by default — narrow it for a narrower token. */
+export const PULL_USER_FIELDS = USER_FIELDS;
+/** Every modelled video field a pull requests when `videos` is enabled. */
+export const PULL_VIDEO_FIELDS = VIDEO_FIELDS;
+/**
+ * A live executor against the real TikTok open API, holding the operator's OWN user access token.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live TikTok request, and therefore the one place the
+ * rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the request
+ * goes out (`checkBudget`, which THROWS instead of returning when the ceiling or a cooldown says
+ * stop) and the response is fed back (`recordCall`) so a 429 / `Retry-After` becomes a PERSISTED
+ * cooldown that makes every later call fail fast WITHOUT touching TikTok. There is deliberately no
+ * option to disable the guard and no value of `budget` that yields an unguarded client
+ * (`assertBudgetGuardIntact`).
+ */
+export function liveTikTokExecute(accessToken, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, TikTokBudget, 'liveTikTokExecute')
+        : new TikTokBudget({ ...(opts.budgetOptions ?? {}), token: accessToken });
+    const explicitLedger = opts.budgetOptions?.path !== undefined || opts.budgetOptions?.root !== undefined;
+    if (opts.budget && !explicitLedger && budget.path !== tiktokBudgetPath({ token: accessToken })) {
+        throw new Error('liveTikTokExecute: injected budget is not keyed to the credential this client will send');
+    }
+    return async (method, path, init) => {
+        // TikTok writes every documented path WITH a trailing slash; the routing table and the price
+        // rules are keyed on the bare form, so both spellings resolve to one entry.
+        const bare = (path.split('?')[0] ?? path).replace(/\/+$/, '');
+        const host = HOSTS[bare];
+        if (!host)
+            throw new Error(`liveTikTokExecute: refusing to call an unmapped TikTok path: ${bare}`);
+        const weight = tiktokCallWeight(method, path);
+        if (Object.keys(init?.headers ?? {}).some((name) => name.toLowerCase() === 'authorization')) {
+            throw new Error('liveTikTokExecute: refusing an injected Authorization header; the guarded credential is fixed at construction');
+        }
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(`${host}${path}`, {
+            method,
+            headers: { ...(init?.headers ?? {}), Authorization: `Bearer ${accessToken}` },
+            ...(init?.body !== undefined ? { body: init.body } : {}),
+        });
+        const resHeaders = {};
+        res.headers.forEach((v, k) => {
+            resHeaders[k.toLowerCase()] = v;
+        });
+        // Settles the reservation and, on a back-off signal, arms the cooldown. The cooldown is
+        // persisted before body parsing or any throw, so even an HTML/plain-text 429 survives it.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer TikTok ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof TikTokBudgetError) || !res.ok)
+                throw error;
+        }
+        const raw = await res.text();
+        let parsed;
+        try {
+            parsed = raw === '' ? {} : JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`tiktok returned non-JSON for ${method} ${bare}: HTTP ${res.status}`);
+        }
+        // A REFUSED pull is NOT an empty account. TikTok answers a Display API failure with a NESTED
+        // error object whose `code` is something other than `ok` — and it carries that object on
+        // SUCCESS too, so a status check alone cannot tell refusal from genuine emptiness. Both
+        // shapes throw.
+        if (res.status >= 400)
+            throw new Error(`tiktok refused ${method} ${bare}: HTTP ${res.status} ${JSON.stringify(parsed)}`);
+        const code = parsed?.['error']?.['code'];
+        if (typeof code === 'string' && code !== 'ok') {
+            throw new Error(`tiktok refused ${method} ${bare}: ${JSON.stringify(parsed['error'])}`);
+        }
+        // The OAuth endpoints use the FLAT envelope instead — a string `error` field is a refusal.
+        if (typeof parsed?.['error'] === 'string') {
+            throw new Error(`tiktok refused ${method} ${bare}: ${JSON.stringify(parsed)}`);
+        }
+        return parsed;
+    };
+}
+/**
+ * Map a real `GET /v2/user/info/` response -> the account (persona) SyncResource.
+ *
+ * NOTHING IS INVENTED: a field the response omits records NOTHING rather than a placeholder —
+ * including username and display_name, because a scope-narrowed token legitimately omits them and
+ * a `?? null` there would fold null over a previously pulled persona's real values.
+ *
+ * The subject id is `union_id`, the vendor's own cross-app user key — NOT `open_id`, which is
+ * per-app and would give one human as many twin accounts as they have authorized apps.
+ */
+export function mapUserInfoAccount(body) {
+    const user = (body?.data?.user ?? {});
+    const str = (key, field) => (typeof user[key] === 'string' ? { [field]: user[key] } : {});
+    const num = (key, field) => (typeof user[key] === 'number' ? { [field]: user[key] } : {});
+    return {
+        type: 'account',
+        id: String(user['union_id'] ?? ''),
+        fields: {
+            ...str('username', 'username'),
+            ...str('display_name', 'displayName'),
+            ...str('avatar_url', 'avatarUrl'),
+            ...str('avatar_url_100', 'avatarUrl100'),
+            ...str('avatar_large_url', 'avatarLargeUrl'),
+            ...str('bio_description', 'bioDescription'),
+            ...str('profile_deep_link', 'profileDeepLink'),
+            ...(typeof user['is_verified'] === 'boolean' ? { isVerified: user['is_verified'] } : {}),
+            ...num('follower_count', 'followerCount'),
+            ...num('following_count', 'followingCount'),
+            ...num('likes_count', 'likesCount'),
+            ...num('video_count', 'videoCount'),
+            pulled: true,
+        },
+    };
+}
+/** Map one real Video object -> the video SyncResource, owned by the pulled account. */
+export function mapVideo(video, ownerUnionId) {
+    const num = (key, field) => (typeof video[key] === 'number' ? { [field]: video[key] } : {});
+    return {
+        type: 'video',
+        id: String(video['id'] ?? ''),
+        fields: {
+            ownerUnionId,
+            ...(typeof video['title'] === 'string' ? { title: video['title'] } : {}),
+            ...(typeof video['video_description'] === 'string' ? { videoDescription: video['video_description'] } : {}),
+            ...num('create_time', 'createTime'),
+            ...num('duration', 'duration'),
+            ...num('height', 'height'),
+            ...num('width', 'width'),
+            ...num('like_count', 'likeCount'),
+            ...num('comment_count', 'commentCount'),
+            ...num('share_count', 'shareCount'),
+            ...num('view_count', 'viewCount'),
+            ...(typeof video['is_aigc'] === 'boolean' ? { isAigc: video['is_aigc'] } : {}),
+            pulled: true,
+        },
+    };
+}
+/**
+ * A MOVING pull timestamp, forced strictly increasing within the process — never a pinned constant
+ * (ADDING_A_TWIN.md §6: under a fixed poll time a vendor value that REVERTS across polls collides
+ * with its own earlier observation and the delta silently vanishes).
+ */
+let lastPollMs = 0;
+function pollTimestamp() {
+    const now = Date.now();
+    lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+    return new Date(lastPollMs).toISOString();
+}
+async function collectTikTok(execute, opts) {
+    const fields = (opts.userFields ?? PULL_USER_FIELDS).join(',');
+    const body = await execute('GET', `/v2/user/info/?fields=${fields}`);
+    // The refusal check lives HERE, not only in the live executor: an injected executor (or a vendor
+    // 200 carrying a non-ok error object) must never fold an empty account over observed state. A
+    // reply with no `data.user.union_id` is a refusal or a malformed body, and either one THROWS.
+    const unionId = body?.['data']?.['user']?.['union_id'];
+    if (!body || typeof body !== 'object' || typeof unionId !== 'string' || unionId === '') {
+        throw new Error(`tiktok pull refused or malformed: ${JSON.stringify(body).slice(0, 200)}`);
+    }
+    const out = [mapUserInfoAccount(body)];
+    if (opts.videos === true) {
+        const count = opts.videoCount ?? 20;
+        const listed = await execute('POST', `/v2/video/list/?fields=${PULL_VIDEO_FIELDS.join(',')}`, { headers: { 'content-type': 'application/json' }, body: JSON.stringify({ max_count: count }) });
+        const videos = listed?.['data']?.['videos'];
+        if (!Array.isArray(videos)) {
+            throw new Error(`tiktok video pull refused or malformed: ${JSON.stringify(listed).slice(0, 200)}`);
+        }
+        for (const video of videos) {
+            if (typeof video?.['id'] === 'string' && video['id'] !== '')
+                out.push(mapVideo(video, unionId));
+        }
+    }
+    return out;
+}
+/** PULL the operator's own identity (and optionally their videos) into the observed log. */
+export async function pullTikTok(execute, opts = {}) {
+    const resources = await collectTikTok(execute, opts);
+    const at = opts.occurredAt ?? pollTimestamp();
+    observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:${SERVICE}:${at}` });
+    return resources.length;
+}
+/**
+ * D7 consumer-facing pull entry point: pull everything readable from the real TikTok surface and
+ * fold it into the twin in ONE observation, returning the standard `{ observed, deltasAppended }`.
+ * Idempotent — a re-pull of identical state appends nothing.
+ */
+export async function syncTikTokFromReal(execute, opts = {}) {
+    const at = opts.occurredAt ?? pollTimestamp();
+    const resources = await collectTikTok(execute, opts);
+    const result = observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:${SERVICE}:${at}` });
+    return { observed: resources.length, deltasAppended: result.appended };
+}
+/**
+ * PUSH without a kernel executor — reported, never faked. TikTok has no API that creates a
+ * developer app, seeds a user, grants a scope, or edits a published video: those are developer-portal
+ * and in-app actions. A World's new posts DO have a door (the Content Posting API), and they cross
+ * through the kernel's deploy (`performTikTokAction`), which holds the sealed credential this
+ * function never does. This never confirms an action and never pretends to have pushed one; it
+ * returns the pending count so a caller can see exactly how much local state is waiting.
+ */
+export function pushPendingTikTokActions(root) {
+    return { pushed: 0, unpushable: deployableEntries(SERVICE, root).length };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** A `TikTokExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export function tiktokExecuteOver(execute) {
+    return async (method, path, init) => {
+        const res = await execute({
+            method,
+            path,
+            headers: { accept: 'application/json', authorization: 'Bearer twin', ...(init?.headers ?? {}) },
+            ...(init?.body === undefined ? {} : { body: init.body }),
+        });
+        try {
+            return JSON.parse(res.body || '{}');
+        }
+        catch {
+            return {};
+        }
+    };
+}
+/**
+ * The refresh adapter (protocol 2): `GET /v2/user/info/` is a real read of the real account, so the
+ * operator's own identity comes back from TikTok itself. It is also nearly the only thing this
+ * vendor lets a client read about its own identity surface — apps, grants and scopes are portal
+ * state.
+ *
+ * ── WHY THIS ONE DOES NOT THROW, AND THE PULL ABOVE STILL DOES ──────────────────────────────────
+ * Two entry points, two callers, two correct behaviours — and the difference is deliberate rather
+ * than a softened refusal:
+ *
+ *   • `pullTikTok` / `syncTikTokFromReal` are the OPERATOR's pull over an executor they built. The
+ *     credential is theirs and it is meant to work, so any refusal is a fault they must see: those
+ *     THROW on every refusal shape, and `tiktok.connector.refused_pull_throws` holds that.
+ *   • THIS adapter is driven by the kernel against whatever credential the root holds — including
+ *     none. A reply that discloses no account is then not "the vendor failed", it is "this wire
+ *     has nothing to tell us", and the honest answer is ZERO OBSERVATIONS. It is the googleoauth
+ *     remote adapter's own shape (`collectGoogleOAuthIdentity` pushes a resource only when the
+ *     reply carries one), transcribed.
+ *
+ * WHAT IS NOT WEAKENED, because this is the line the doctrine actually draws: nothing empty is ever
+ * FOLDED. `observeResources` is not called at all on this path, so no prior observation is
+ * overwritten, no subject is tombstoned, and a previously pulled persona survives byte for byte —
+ * which is the whole content of "a refused pull is not an empty account". The count comes back 0,
+ * and a caller that reads the count sees exactly that nothing was observed.
+ * `tiktok.connector.remote_refresh_folds_nothing_when_unreadable` pins both halves at once.
+ */
+export async function syncTikTokFromRemote(execute, opts = {}) {
+    const at = opts.occurredAt ?? new Date().toISOString();
+    const body = await tiktokExecuteOver(execute)('GET', `/v2/user/info/?fields=${PULL_USER_FIELDS.join(',')}`);
+    const unionId = body?.['data']?.['user']?.['union_id'];
+    if (typeof unionId !== 'string' || unionId === '')
+        return { observed: 0, deltasAppended: 0 };
+    const resources = [mapUserInfoAccount(body)];
+    const result = observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at, batch: `obs:${SERVICE}:${at}` });
+    return { observed: resources.length, deltasAppended: result.appended };
+}
+// ── PERFORM: a World's post crosses to TikTok through the Content Posting API ──────────────────
+//
+// A `video.publish` entry (a Direct Post the World made) crosses as the vendor's own flow, the one
+// its Direct Post guide walks: (1) creator_info — the creator the credential names, and whether the
+// entry's privacy_level is one of their options (a mismatch is refused here, before anything is
+// sent); (2) video/init with FILE_UPLOAD and the chunk plan TikTok's rules require for the stored
+// size; (3) each chunk PUT to the upload_url the vendor returned, PRESIGNED — the URL's upload_token
+// is its authorization, so the sealed credential never goes with it, and the host is the vendor's
+// upload host, not the API's; (4) status/fetch until PUBLISH_COMPLETE. A `video.inbox_upload` entry
+// crosses the same way through inbox/video/init and ends at SEND_TO_USER_INBOX. The bytes are read
+// off the blob seam by the entry's digest, a chunk at a time, across the branch's ancestors.
+//
+// THE BUDGET wraps the executor the perform receives (`budgetedTikTokExecute`, the X pack's shape),
+// with ONE LEDGER PER CREDENTIAL — keyed by `ctx.credential`, the sealed credential's keyed
+// fingerprint, so every World and branch performing with one TikTok account spends one allowance (the
+// vendor meters the token, not the World), and by `ctx.root` only when no credential is sealed (the
+// X / YouTube / LinkedIn keying): creator_info, the init and every status read
+// are charged before they go and refused without calling TikTok when the ledger says stop; an answer
+// that has arrived is never dropped. The chunk PUTs are NOT charged: once a publish has started, the
+// budget cannot stop it — a half-sent video would be worse than a spent minute.
+//
+// THE BOUND. TikTok publishes no processing time and no polling interval, only status/fetch's 30 reads
+// a minute per token; the wait reads every STATUS_POLL_MS (3 s: twenty a minute, which leaves the
+// ledger room for the creator_info and init beside them) and stops at MAX_PUBLISH_WAIT_MS (120 s).
+// Past that the perform fails RETRYABLY, and the publish it opened is KEPT (tiktok-blobs.ts
+// perform-publishes): a Direct Post publishes itself once its bytes are in, so the next deploy asks
+// that publish where it stands rather than initializing a second post, and resumes its missing chunks
+// on the upload_url it kept. Only a publish TikTok says is gone — `invalid_publish_id`, or FAILED —
+// is cleared, so the next perform opens a fresh one. A chunk TikTok does not take fails the perform
+// retryably with the publish still kept. A 429 or a 5xx
+// from status/fetch is TikTok saying "later", so the wait keeps reading inside its bound and ends
+// RETRYABLY, never as a permanent failure.
+/** How often the perform reads status/fetch while TikTok processes (see THE BOUND above). */
+export const STATUS_POLL_MS = 3_000;
+/** How long, in total, a perform waits on TikTok's processing before it fails the entry retryably. */
+export const MAX_PUBLISH_WAIT_MS = 120_000;
+/** The chunk the perform sends: TikTok's 5 MB minimum (read as MiB), so a 4 GB video is 800 chunks. */
+export const PERFORM_CHUNK_BYTES = 5 * 1024 * 1024;
+/** TikTok answered "later" (429, a 5xx) — the entry stays deployable and the next deploy tries again. */
+export class TikTokRetryableError extends Error {
+    retryable = true;
+    constructor(message) {
+        super(message);
+        this.name = 'TikTokRetryableError';
+    }
+}
+/** TikTok has the video but has not finished processing it inside the bound: retry later. */
+export class TikTokStillProcessingError extends TikTokRetryableError {
+    publishId;
+    constructor(publishId, waitedMs, reads) {
+        super(`video still processing at TikTok (publish ${publishId}) after ${Math.round(waitedMs / 1000)}s and ${reads} status reads — the entry stays pending; the next deploy asks this publish where it stands`);
+        this.publishId = publishId;
+        this.name = 'TikTokStillProcessingError';
+    }
+}
+/**
+ * The kernel executor, charged to this pack's TikTokBudget: the check RESERVES before the call and
+ * throws (TikTokBudgetError) instead of calling when the ceiling or a cooldown says stop; the answer
+ * settles the reservation and arms a cooldown on 429 / Retry-After. The vendor has ANSWERED by then:
+ * if recording throws (a back-off past the cap, persisted first), the answer still goes back and the
+ * next call meets the cooldown — dropping it would record a post TikTok accepted as failed.
+ */
+export function budgetedTikTokExecute(execute, budget = new TikTokBudget()) {
+    const guard = assertBudgetGuardIntact(budget, TikTokBudget, 'budgetedTikTokExecute');
+    return async (request) => {
+        const weight = tiktokCallWeight(request.method, request.path);
+        const reservation = guard.checkBudget(weight);
+        const res = await execute(request);
+        try {
+            guard.recordCall(weight, Object.fromEntries(Object.entries(res.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v])), { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof TikTokBudgetError))
+                throw error;
+        }
+        return res;
+    };
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** One Content Posting call: its `data`, or a throw carrying the vendor's refusal. */
+async function postingCall(execute, label, path, body) {
+    const res = await execute({ method: 'POST', path, headers: { accept: 'application/json', 'content-type': 'application/json; charset=UTF-8' }, body: JSON.stringify(body) });
+    let parsed = {};
+    try {
+        parsed = res.body ? JSON.parse(res.body) : {};
+    }
+    catch {
+        throw new Error(`tiktok answered ${label} with a body that is not JSON: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+    }
+    const code = parsed?.error?.code;
+    // TikTok saying "later" is not a refusal of the post
+    if (res.status === 429 || res.status >= 500)
+        throw new TikTokRetryableError(`tiktok answered ${label} with HTTP ${res.status} (${String(code ?? 'no code')}) — retry later`);
+    if (res.status < 200 || res.status >= 300 || (typeof code === 'string' && code !== 'ok')) {
+        throw new TikTokRefusal(label, res.status, typeof code === 'string' ? code : '', JSON.stringify(parsed?.error ?? parsed).slice(0, 300));
+    }
+    return { data: (parsed.data ?? {}), raw: res.body };
+}
+/** TikTok refused a call, with its own `error.code`. */
+class TikTokRefusal extends Error {
+    status;
+    code;
+    constructor(label, status, code, detail) {
+        super(`tiktok refused ${label}: HTTP ${status} ${detail}`);
+        this.status = status;
+        this.code = code;
+        this.name = 'TikTokRefusal';
+    }
+}
+/** A budget refusal is a wait while the bound has room; past it, the caller's verdict. */
+async function withinBudget(deadline, call) {
+    for (;;) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            // only a window that will open again is a wait: ceiling, burst, a cooldown the vendor asked for
+            if (!(error instanceof TikTokBudgetError) || !['ceiling', 'burst', 'cooldown'].includes(error.kind))
+                throw error;
+            if (Date.now() + error.retryAfterMs > deadline)
+                throw error;
+            await sleep(error.retryAfterMs);
+        }
+    }
+}
+/** The chunk plan TikTok's rules require for `size` bytes at the perform's chunk size. */
+export function performChunkPlan(size) {
+    if (size < PERFORM_CHUNK_BYTES)
+        return { chunkSize: size, totalChunkCount: 1 };
+    return { chunkSize: PERFORM_CHUNK_BYTES, totalChunkCount: Math.floor(size / PERFORM_CHUNK_BYTES) };
+}
+/** status/fetch, with `publicaly_available_post_id` read off the RAW body: it is a list of int64 JSON
+ *  numbers, and JSON.parse would round a 19-digit id to the nearest double. */
+async function readStatus(execute, publishId) {
+    const { data, raw } = await postingCall(execute, 'status/fetch', '/v2/post/publish/status/fetch/', { publish_id: publishId });
+    const ids = /"publicaly_available_post_id"\s*:\s*\[\s*"?(\d+)/.exec(raw);
+    return {
+        status: String(data.status ?? ''),
+        ...(typeof data.fail_reason === 'string' && data.fail_reason ? { failReason: data.fail_reason } : {}),
+        ...(ids ? { postId: ids[1] } : {}),
+        uploadedBytes: Number(data.uploaded_bytes ?? 0),
+    };
+}
+async function publishOver(budgeted, raw, action, mode, root) {
+    const f = (action.fields ?? {});
+    const sha = f._content_sha256;
+    const size = await tikTokBlobSize(sha, root);
+    if (size === null)
+        throw new Error(`tiktok: ${action.operation} ${action.subject.id} has no stored media to post (_content_sha256 ${String(sha ?? 'absent')})`);
+    const contentType = typeof f._content_type === 'string' ? f._content_type : 'video/mp4';
+    const started = Date.now();
+    const deadline = started + MAX_PUBLISH_WAIT_MS;
+    const done = mode === 'direct' ? 'PUBLISH_COMPLETE' : 'SEND_TO_USER_INBOX';
+    // (0) a publish an earlier perform of this entry opened: where does it stand? It is re-opened ONLY
+    // when TikTok says it is gone — `invalid_publish_id`, or status FAILED ("an error has occurred and
+    // the entire process has failed"). Anything else is the same publish, still alive: PROCESSING_UPLOAD
+    // is "the upload is in process", and `uploaded_bytes` is "the number of bytes uploaded (1-indexed)
+    // for FILE_UPLOAD" (Get Post Status reference) — a count of what arrived, which says nothing about
+    // whether TikTok will still post it. So a partial count is where this perform resumes the SAME
+    // publish's chunks, on the upload_url it kept; a second init could put the video up twice.
+    let kept = await readPerformPublish(action.id, root);
+    if (kept && (kept.sha256 !== sha || kept.size !== size))
+        kept = null;
+    let offset = 0;
+    if (kept) {
+        let state = null;
+        try {
+            state = await withinBudget(deadline, () => readStatus(budgeted, kept.publishId));
+        }
+        catch (error) {
+            if (!(error instanceof TikTokRefusal) || error.code !== 'invalid_publish_id')
+                throw error;
+        }
+        if (state === null || state.status === 'FAILED') {
+            await clearPerformPublish(action.id, root);
+            kept = null;
+        }
+        else
+            offset = state.status === 'PROCESSING_UPLOAD' ? state.uploadedBytes : size;
+    }
+    // (1) + (2) the creator and the init — the only calls charged before a publish exists
+    if (!kept) {
+        if (mode === 'direct') {
+            const creator = await withinBudget(deadline, () => postingCall(budgeted, 'creator_info', '/v2/post/publish/creator_info/query/', {}));
+            const options = Array.isArray(creator.data.privacy_level_options) ? creator.data.privacy_level_options : [];
+            if (!options.includes(f.privacyLevel)) {
+                throw new Error(`tiktok: the creator @${String(creator.data.creator_username ?? '?')} cannot post as ${String(f.privacyLevel)} (their options: ${options.join(', ')})`);
+            }
+        }
+        const plan = performChunkPlan(size);
+        const postInfo = {
+            title: String(f.videoDescription ?? f.title ?? ''),
+            privacy_level: f.privacyLevel,
+            disable_duet: f.disableDuet === true,
+            disable_comment: f.disableComment === true,
+            disable_stitch: f.disableStitch === true,
+            ...(typeof f.videoCoverTimestampMs === 'number' ? { video_cover_timestamp_ms: f.videoCoverTimestampMs } : {}),
+            ...(f.brandContentToggle === true ? { brand_content_toggle: true } : {}),
+            ...(f.brandOrganicToggle === true ? { brand_organic_toggle: true } : {}),
+            ...(f.isAigc === true ? { is_aigc: true } : {}),
+        };
+        const init = await withinBudget(deadline, () => postingCall(budgeted, mode === 'direct' ? 'video/init' : 'inbox/video/init', mode === 'direct' ? '/v2/post/publish/video/init/' : '/v2/post/publish/inbox/video/init/', {
+            ...(mode === 'direct' ? { post_info: postInfo } : {}),
+            source_info: { source: 'FILE_UPLOAD', video_size: size, chunk_size: plan.chunkSize, total_chunk_count: plan.totalChunkCount },
+        }));
+        const publishId = init.data.publish_id;
+        if (typeof publishId !== 'string' || typeof init.data.upload_url !== 'string')
+            throw new Error(`tiktok init answered no publish_id/upload_url: ${init.raw.slice(0, 200)}`);
+        kept = { publishId, uploadUrl: init.data.upload_url, sha256: String(sha), size, ...plan };
+        await writePerformPublish(action.id, kept, root);
+        offset = 0;
+    }
+    const publish = kept;
+    // (3) the chunks still missing, in order, presigned, unbudgeted. A PUT TikTok does not take leaves
+    // the publish kept and fails RETRYABLY: the next perform asks status/fetch where it stands.
+    for (let index = Math.floor(offset / publish.chunkSize); offset < size && index < publish.totalChunkCount; index += 1) {
+        const first = index * publish.chunkSize;
+        const last = index === publish.totalChunkCount - 1 ? size - 1 : first + publish.chunkSize - 1;
+        const chunk = (await readTikTokBlobRange(sha, first, last, root)) ?? new Uint8Array(0);
+        const answer = await raw({
+            method: 'PUT',
+            path: publish.uploadUrl,
+            presigned: true,
+            headers: { 'content-type': contentType, 'content-length': String(chunk.length), 'content-range': `bytes ${first}-${last}/${size}` },
+            body: chunk,
+        });
+        if (answer.status === 206 || answer.status === 201)
+            continue;
+        throw new TikTokRetryableError(`tiktok: chunk ${index + 1}/${publish.totalChunkCount} of publish ${publish.publishId} answered HTTP ${answer.status} — the publish is kept; the next deploy asks it where it stands: ${answer.body.slice(0, 200)}`);
+    }
+    // (4) the wait, bounded; "later" answers keep it waiting
+    let reads = 0;
+    for (;;) {
+        let state = null;
+        try {
+            state = await withinBudget(deadline, () => readStatus(budgeted, publish.publishId));
+            reads += 1;
+        }
+        catch (error) {
+            if (error instanceof TikTokBudgetError)
+                throw new TikTokStillProcessingError(publish.publishId, Date.now() - started, reads);
+            if (!(error instanceof TikTokRetryableError))
+                throw error;
+        }
+        if (state?.status === done) {
+            await clearPerformPublish(action.id, root);
+            const postId = state.postId;
+            return {
+                externalId: postId ?? publish.publishId,
+                ...(postId ? { url: `https://www.tiktok.com/video/${postId}` } : {}),
+                data: { publish_id: publish.publishId, status: state.status, ...(postId ? { post_id: postId } : {}) },
+            };
+        }
+        if (state?.status === 'FAILED') {
+            await clearPerformPublish(action.id, root);
+            throw new Error(`tiktok failed publish ${publish.publishId}: ${state.failReason ?? 'no fail_reason'}`);
+        }
+        if (Date.now() + STATUS_POLL_MS > deadline)
+            throw new TikTokStillProcessingError(publish.publishId, Date.now() - started, reads);
+        await sleep(STATUS_POLL_MS);
+    }
+}
+/**
+ * The perform adapter (protocol 2).
+ *
+ * A World's post crosses (`video.publish`, `video.inbox_upload`: see PERFORM above). Everything else a
+ * World writes here has no upstream home, and saying so is the point: TikTok publishes NO API that
+ * creates a developer app, seeds a user, grants a scope or issues a token — those are developer-portal
+ * and in-app settings actions a person takes in a browser — and an upload whose file failed TikTok's
+ * checks here (`publish.fail`) has nothing to send.
+ */
+export async function performTikTokAction(execute, action, ctx, budget) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    if (op === 'video.publish' || op === 'video.inbox_upload') {
+        // ONE LEDGER PER CREDENTIAL (its keyed fingerprint), else per World root when none is sealed;
+        // `budget` is injectable so a verify charges a temporary ledger of its own
+        const budgeted = budgetedTikTokExecute(execute, budget ?? new TikTokBudget(ctx.credential !== undefined ? { token: ctx.credential } : ctx.root !== undefined ? { root: ctx.root } : {}));
+        return publishOver(budgeted, execute, action, op === 'video.publish' ? 'direct' : 'inbox', ctx.root);
+    }
+    return {
+        externalId: action.subject.id,
+        data: {
+            performed: false,
+            reason: op === 'publish.fail'
+                ? `${op}: the upload failed TikTok's checks on this twin (${String((action.fields ?? {}).failReason ?? 'unknown')}), so there is no post to send`
+                : `${op} has nowhere to go: TikTok creates developer apps, users, tokens and scope grants in the developer portal and in TikTok's own account settings, and publishes no API for any of them`,
+        },
+    };
+}

package/dist/src/tiktok-consent-ui.d.ts

@@ -0,0 +1,19 @@
+import { type ConsentView, type ErrorPageProps } from '../client/tiktok-consent.js';
+export type { ConsentAccount, ConsentScopeRow, ConsentView, ErrorPageProps } from '../client/tiktok-consent.js';
+/**
+ * THE STATE BUILDER — the authorization page's entire view model, folded out of the kernel
+ * projection. Returns `null` when the authorize request is unknown or already settled, or when the
+ * app or the signed-in account no longer exists (the caller renders the error page); it never
+ * invents an app name, an account or a scope row.
+ */
+export declare function tiktokConsentState(opts: {
+    root?: string;
+    requestId: string;
+    origin: string;
+}): ConsentView | null;
+/** The authorization page's stylesheet, served inline. Static text: no clock, no state, no build. */
+export declare const CONSENT_CSS: string;
+/** Render the authorization page from a view model. */
+export declare function consentPageHtml(view: ConsentView): string;
+/** Render the authorize-endpoint error page (an un-redirectable failure). */
+export declare function errorPageHtml(props: ErrorPageProps): string;