@volter/twin-tiktok 0.1.0

package/dist/src/tiktok-consent-ui.js

@@ -0,0 +1,127 @@
+// TikTok twin — the SERVER HALF of the authorization page.
+//
+// Named `-consent-ui` rather than `-mirror-ui` on purpose (the googleoauth/xidentity class
+// doctrine): a dashboard mirror is a SECOND renderer this repo writes over a vendor's data,
+// whereas this is the vendor's OWN page, on the vendor's OWN path, in the middle of the vendor's
+// OWN protocol. The mirror DISCIPLINE still applies in full — one renderer, data-coupled to the
+// projection, driven by a real browser journey.
+//
+// The pieces:
+//   • `tiktokConsentState` — THE STATE BUILDER. Everything on screen is derived here, from the
+//     kernel projection, and nowhere else. It is the seam `scripts/mutation-test.ts` sabotages in
+//     the mirror phase (TWIN-20/B9): with it dead the screen has no app name, no account and no
+//     scopes, so every UI capability must go red while the write/handler path stays real.
+//   • `consentPageHtml` / `errorPageHtml` — server-render the REAL exported React components with
+//     `renderToStaticMarkup`. There is no template string of vendor markup anywhere.
+//   • `CONSENT_CSS` — the stylesheet, INLINE. This pack ships no browser bundle (the whole screen
+//     is a plain form; see client/tiktok-consent.tsx), so there is no build on the serve path
+//     (R12b) and no generated asset to drift — the page is one self-contained document.
+import { createElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { ConsentPage, ErrorPage, } from "../client/tiktok-consent.js";
+import { describeScopes, parseScopeParam, sortScopesForConsent } from "./tiktok-scopes.js";
+import { readOne } from "./tiktok-store.js";
+function toConsentAccount(row) {
+    return {
+        unionId: row.id,
+        username: String(row.username ?? ''),
+        displayName: String(row.displayName ?? ''),
+    };
+}
+/**
+ * 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 function tiktokConsentState(opts) {
+    const authRequest = readOne(opts.root, 'auth_request', opts.requestId);
+    if (!authRequest || authRequest.settled === true)
+        return null;
+    const client = readOne(opts.root, 'oauth_client', String(authRequest.clientKey));
+    if (!client)
+        return null;
+    const account = readOne(opts.root, 'account', String(authRequest.accountId ?? ''));
+    if (!account)
+        return null;
+    const requested = sortScopesForConsent(parseScopeParam(String(authRequest.scope ?? '')));
+    const scopes = describeScopes(requested).map((s) => ({
+        scope: s.scope,
+        label: s.label,
+        product: s.product,
+        known: s.known,
+    }));
+    let redirectHost = '';
+    try {
+        redirectHost = new URL(String(authRequest.redirectUri)).host;
+    }
+    catch {
+        redirectHost = String(authRequest.redirectUri);
+    }
+    return {
+        requestId: opts.requestId,
+        origin: opts.origin,
+        app: { clientKey: client.id, name: String(client.name ?? '') },
+        account: toConsentAccount(account),
+        scopes,
+        redirectHost,
+    };
+}
+/** The authorization page's stylesheet, served inline. Static text: no clock, no state, no build. */
+export const CONSENT_CSS = `
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body {
+  margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
+  background: #f1f1f2; color: #161823; padding: 24px;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+.card {
+  background: #fff; width: 100%; max-width: 440px; border-radius: 12px; padding: 28px 28px 22px;
+  box-shadow: 0 2px 12px rgba(0,0,0,.10); border: 1px solid rgba(22,24,35,.10);
+}
+.tt-header { display: flex; align-items: center; gap: 8px; margin-bottom: 20px; }
+.tt-mark { font-size: 26px; line-height: 1; color: #fe2c55; }
+.tt-wordmark { font-size: 18px; font-weight: 700; letter-spacing: -0.4px; }
+.signed-in { display: flex; align-items: center; gap: 8px; margin-bottom: 14px; }
+.account-text { display: flex; align-items: baseline; gap: 8px; font-size: 14px; }
+.account-name { font-weight: 600; }
+.account-username { color: rgba(22,24,35,.60); }
+.title { font-size: 20px; line-height: 1.35; font-weight: 600; margin: 0 0 18px; }
+.app-name { font-weight: 700; }
+.scope-lead { font-size: 14px; color: rgba(22,24,35,.72); margin: 0 0 10px; }
+.scope-list { list-style: none; margin: 0 0 22px; padding: 0; display: flex; flex-direction: column; gap: 12px; }
+.scope-row { display: flex; flex-direction: column; gap: 4px; }
+.scope-label { display: flex; align-items: flex-start; gap: 10px; font-size: 14px; line-height: 1.45; cursor: pointer; }
+.scope-check { margin-top: 3px; accent-color: #fe2c55; width: 16px; height: 16px; flex: none; }
+.scope-tag { align-self: flex-start; font-size: 11px; border-radius: 999px; padding: 2px 8px; margin-left: 26px; }
+.scope-tag-unknown { background: #fff1f3; color: #b3082f; border: 1px solid #ffd3db; }
+.actions { display: flex; gap: 10px; justify-content: flex-end; }
+.btn { font: inherit; font-weight: 600; border-radius: 6px; padding: 10px 20px; cursor: pointer; border: 1px solid transparent; }
+.btn-primary { background: #fe2c55; color: #fff; }
+.btn-secondary { background: #fff; color: #161823; border-color: rgba(22,24,35,.20); }
+.legal { font-size: 12px; line-height: 1.5; color: rgba(22,24,35,.55); margin: 18px 0 0; }
+.redirect-host { color: rgba(22,24,35,.80); }
+.card-error .title { margin-bottom: 12px; }
+.error-detail { font-size: 14px; line-height: 1.5; margin: 0 0 12px; }
+.error-code { font-size: 13px; font-weight: 600; color: #b3082f; margin: 0 0 6px; }
+.error-request { font-size: 12px; color: rgba(22,24,35,.55); word-break: break-all; margin: 0; }
+`.trim();
+function page(title, bodyMarkup) {
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)}</title><style>${CONSENT_CSS}</style></head>
+<body><div id="root">${bodyMarkup}</div></body></html>`;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** Render the authorization page from a view model. */
+export function consentPageHtml(view) {
+    const markup = renderToStaticMarkup(createElement(ConsentPage, { view }));
+    return page(`Authorize ${view.app.name} | TikTok`, markup);
+}
+/** Render the authorize-endpoint error page (an un-redirectable failure). */
+export function errorPageHtml(props) {
+    return page(`Error ${props.status}: ${props.code} | TikTok`, renderToStaticMarkup(createElement(ErrorPage, props)));
+}

package/dist/src/tiktok-errors.d.ts

@@ -0,0 +1,78 @@
+export type TikTokResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/** The ten `error` values the OAuth error-handling reference publishes, with its descriptions
+ *  verbatim. Exported so a verify can assert against the vendor's list rather than the twin's. */
+export declare const OAUTH_ERRORS: Record<string, string>;
+/**
+ * An OAuth-endpoint refusal. `status` defaults to RFC 6749 §5.2's 400 — see the EVIDENCE BOUNDARY
+ * in this file's header; the live status is unpinned.
+ */
+export declare function oauthError(error: string, description: string, occurredAt: string, status?: number): TikTokResponse;
+/** A refusal whose description is the vendor's OWN published one for that code. */
+export declare function oauthErrorCode(error: keyof typeof OAUTH_ERRORS & string, occurredAt: string, status?: number): TikTokResponse;
+/** The vendor's own wording for a malformed request — the literal string its refresh/revoke
+ *  examples show ("The request parameters are malformed."). */
+export declare function malformedRequest(occurredAt: string, detail?: string): TikTokResponse;
+/**
+ * The ONE answer an unusable authorization code or refresh token gets. Unknown, already redeemed,
+ * expired, minted for another client, wrong redirect_uri pairing or failed PKCE are deliberately
+ * indistinguishable — telling them apart would leak which codes exist — and `invalid_grant` is the
+ * code the vendor's own reference assigns to exactly that family ("The provided authorization
+ * grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in
+ * the authorization request, or was issued to another client").
+ */
+export declare function invalidGrant(occurredAt: string): TikTokResponse;
+/** Client authentication failed at the token/revoke endpoint (RFC 6749 §5.2: 401). */
+export declare function invalidClient(occurredAt: string): TikTokResponse;
+/**
+ * The seven codes the v2 error-handling reference publishes, with their documented HTTP status.
+ * `ok` is the success value the same envelope carries.
+ *
+ * EVIDENCE BOUNDARY ON THE MESSAGES, so a reader can tell a quotation from twin prose. VERBATIM
+ * from the vendor's table: `access_token_invalid`, `invalid_file_upload`, `rate_limit_exceeded`
+ * and `scope_not_authorized`. TWIN PROSE, because the reference describes those rows rather than
+ * quoting a message ("generic TikTok internal error; refer to message for details", "one or more
+ * request fields are invalid", "access token lacks required scopes"): `internal_error`,
+ * `invalid_params` and `scope_permission_missed`. The CODES and the STATUSES are the vendor's for
+ * all seven, which is what `tiktok.errors.api_codes_and_statuses_match_vendor_table` asserts.
+ */
+export declare const API_ERRORS: Record<string, {
+    status: number;
+    message: string;
+}>;
+/** The success envelope: the `data` the endpoint computed, plus `error: {code:"ok", message:"", log_id}`. */
+export declare function apiOk(data: unknown, occurredAt: string, seed: string): TikTokResponse;
+/**
+ * An API-endpoint refusal. The status comes from the vendor's own published table, so a caller
+ * that branches on the status and a caller that branches on `error.code` agree by construction.
+ * `message` may be overridden to carry the specific detail the vendor's message field carries
+ * ("consult the error message for specifics" is what its own reference says of `invalid_params`).
+ */
+export declare function apiError(code: keyof typeof API_ERRORS & string, occurredAt: string, message?: string): TikTokResponse;
+/**
+ * The Content Posting API's OWN codes, with the HTTP status each reference page gives them
+ * (developers.tiktok.com content-posting-api-reference-direct-post, -upload-video,
+ * -query-creator-info and -get-video-status, fetched 2026-09-27). Note the SINGULAR `invalid_param`:
+ * the posting references spell it that way while the v2 error table spells `invalid_params`, and a
+ * client that branches on the code must meet the spelling of the endpoint it called. Messages are
+ * the reference's descriptions, lightly completed into sentences (twin prose); codes and statuses are
+ * the vendor's.
+ */
+export declare const POSTING_ERRORS: Record<string, {
+    status: number;
+    message: string;
+}>;
+/** A Content Posting refusal, in the same nested envelope as the rest of the v2 API. */
+export declare function postingError(code: keyof typeof POSTING_ERRORS & string, occurredAt: string, message?: string): TikTokResponse;
+/**
+ * An UNMODELLED path on a twinned TikTok host fails like the vendor rather than faking a success.
+ * TikTok publishes no 404 body for an unknown v2 route, so the twin answers the API family's own
+ * `invalid_params` shape with a message that names the route — an honest refusal in the envelope
+ * the surrounding endpoints speak. `tiktok.errors.unknown_route_pin` (todo) pins the live answer.
+ */
+export declare function unknownRoute(method: string, path: string, occurredAt: string): TikTokResponse;
+/** A contained unexpected failure. Never exposes local exception text. */
+export declare function internalError(occurredAt: string): TikTokResponse;

package/dist/src/tiktok-errors.js

@@ -0,0 +1,175 @@
+// TikTok's TWO error envelopes, kept distinct because they really are two different contracts and
+// an integration branches on them (Dub's own code does: the OAuth leg reads `response.ok` plus
+// `access_token`, the Display leg parses `data.user` through a Zod schema).
+//
+//   1. THE OAUTH FAMILY — `/v2/oauth/token/` and `/v2/oauth/revoke/`. A FLAT body:
+//        { "error": "invalid_request",
+//          "error_description": "Redirect_uri is not matched with the uri when requesting code.",
+//          "log_id": "202206221854370101130062072500FFA2" }
+//      Verbatim from the User Access Token Management guide
+//      (developers.tiktok.com/doc/oauth-user-access-token-management, fetched 2026-09-13). The
+//      `error` values are the ten the OAuth error-handling reference publishes
+//      (developers.tiktok.com/docs/en/oauth-error-handling) — access_denied, invalid_client,
+//      invalid_grant, invalid_request, invalid_scope, unauthorized_client, unsupported_grant_type,
+//      unsupported_response_type, server_error, temporarily_unavailable — each with the
+//      description that page gives it.
+//
+//      EVIDENCE BOUNDARY — THE HTTP STATUS. That reference publishes the codes and descriptions
+//      and NO status column, and no fetched artefact shows the status line of a TikTok OAuth
+//      failure. The twin answers RFC 6749 §5.2's statuses (400, or 401 for invalid_client),
+//      which is the reading every OAuth client library assumes; `tiktok.token.error_http_status`
+//      (todo) pins the live one. Marked here rather than dressed up as a vendor fact.
+//
+//   2. THE API FAMILY — `/v2/user/info/`, `/v2/video/list/`, `/v2/video/query/`. A NESTED error
+//      object that is present on SUCCESS TOO:
+//        { "data": { ... }, "error": { "code": "ok", "message": "", "log_id": "…" } }
+//      Verbatim from the Get User Info reference. The codes are the seven the v2 error-handling
+//      reference publishes WITH their HTTP statuses: access_token_invalid (401), internal_error
+//      (500), invalid_file_upload (400), invalid_params (400), rate_limit_exceeded (429),
+//      scope_not_authorized (401), scope_permission_missed (400).
+//
+// `log_id` is deterministic here (see tiktok-ids.ts) because it is served content: runtime
+// contract R9 forbids a clock or entropy in a served byte, and a twin whose every response
+// carried a fresh random id would fail the two-fresh-roots replay on every single read.
+import { logId } from "./tiktok-ids.js";
+/** TikTok's own curl examples set `Cache-Control: no-cache` on the request; the twin refuses to
+ *  let a credential-bearing reply be cached on the way back. */
+const NOSTORE = { 'cache-control': 'no-cache, no-store, max-age=0' };
+const JSON_CT = { 'content-type': 'application/json; charset=utf-8' };
+// ── family 1: the OAuth endpoints (flat body) ───────────────────────────────────────────────────
+/** The ten `error` values the OAuth error-handling reference publishes, with its descriptions
+ *  verbatim. Exported so a verify can assert against the vendor's list rather than the twin's. */
+export const OAUTH_ERRORS = {
+    access_denied: 'The resource owner or authorization server denied the request.',
+    invalid_client: 'Client authentication failed (for example, unknown client, no client authentication included, or unsupported authentication method).',
+    invalid_grant: 'The provided authorization grant (for example, authorization code or resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.',
+    invalid_request: 'The request misses a required parameter or is otherwise malformed.',
+    invalid_scope: 'The requested scope is invalid, unknown, or malformed.',
+    unauthorized_client: 'The client is not authorized to request an authorization code using this method.',
+    unsupported_grant_type: 'The authorization grant type is not supported by the authorization server.',
+    unsupported_response_type: 'The authorization server does not support obtaining an authorization code using this method.',
+    server_error: 'Other internal server errors.',
+    temporarily_unavailable: 'Service is temporarily unavailable.',
+};
+/**
+ * An OAuth-endpoint refusal. `status` defaults to RFC 6749 §5.2's 400 — see the EVIDENCE BOUNDARY
+ * in this file's header; the live status is unpinned.
+ */
+export function oauthError(error, description, occurredAt, status = 400) {
+    return {
+        status,
+        body: { error, error_description: description, log_id: logId(occurredAt, `oauth:${error}:${description}`) },
+        headers: { ...NOSTORE, ...JSON_CT },
+    };
+}
+/** A refusal whose description is the vendor's OWN published one for that code. */
+export function oauthErrorCode(error, occurredAt, status = 400) {
+    return oauthError(error, OAUTH_ERRORS[error] ?? 'The request misses a required parameter or is otherwise malformed.', occurredAt, status);
+}
+/** The vendor's own wording for a malformed request — the literal string its refresh/revoke
+ *  examples show ("The request parameters are malformed."). */
+export function malformedRequest(occurredAt, detail) {
+    return oauthError('invalid_request', detail ?? 'The request parameters are malformed.', occurredAt);
+}
+/**
+ * The ONE answer an unusable authorization code or refresh token gets. Unknown, already redeemed,
+ * expired, minted for another client, wrong redirect_uri pairing or failed PKCE are deliberately
+ * indistinguishable — telling them apart would leak which codes exist — and `invalid_grant` is the
+ * code the vendor's own reference assigns to exactly that family ("The provided authorization
+ * grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in
+ * the authorization request, or was issued to another client").
+ */
+export function invalidGrant(occurredAt) {
+    return oauthErrorCode('invalid_grant', occurredAt);
+}
+/** Client authentication failed at the token/revoke endpoint (RFC 6749 §5.2: 401). */
+export function invalidClient(occurredAt) {
+    return oauthErrorCode('invalid_client', occurredAt, 401);
+}
+// ── family 2: the v2 API endpoints (nested error object, present on success too) ─────────────────
+/**
+ * The seven codes the v2 error-handling reference publishes, with their documented HTTP status.
+ * `ok` is the success value the same envelope carries.
+ *
+ * EVIDENCE BOUNDARY ON THE MESSAGES, so a reader can tell a quotation from twin prose. VERBATIM
+ * from the vendor's table: `access_token_invalid`, `invalid_file_upload`, `rate_limit_exceeded`
+ * and `scope_not_authorized`. TWIN PROSE, because the reference describes those rows rather than
+ * quoting a message ("generic TikTok internal error; refer to message for details", "one or more
+ * request fields are invalid", "access token lacks required scopes"): `internal_error`,
+ * `invalid_params` and `scope_permission_missed`. The CODES and the STATUSES are the vendor's for
+ * all seven, which is what `tiktok.errors.api_codes_and_statuses_match_vendor_table` asserts.
+ */
+export const API_ERRORS = {
+    access_token_invalid: { status: 401, message: 'The access token is invalid or not found in the request. Please refresh the token and retry.' },
+    internal_error: { status: 500, message: 'Server internal error. Please retry later.' },
+    invalid_file_upload: { status: 400, message: 'The uploaded file does not meet API specifications. Please correct the file and try again.' },
+    invalid_params: { status: 400, message: 'One or more request fields are invalid.' },
+    rate_limit_exceeded: { status: 429, message: 'The API rate limit was exceeded. Please try again later.' },
+    scope_not_authorized: { status: 401, message: 'The user did not authorize the scope required for completing this request. Please ask the user to authorize and then retry.' },
+    scope_permission_missed: { status: 400, message: 'The access token does not carry the scopes required by this request.' },
+};
+/** The success envelope: the `data` the endpoint computed, plus `error: {code:"ok", message:"", log_id}`. */
+export function apiOk(data, occurredAt, seed) {
+    return {
+        status: 200,
+        body: { data, error: { code: 'ok', message: '', log_id: logId(occurredAt, `api:ok:${seed}`) } },
+        headers: { ...NOSTORE, ...JSON_CT },
+    };
+}
+/**
+ * An API-endpoint refusal. The status comes from the vendor's own published table, so a caller
+ * that branches on the status and a caller that branches on `error.code` agree by construction.
+ * `message` may be overridden to carry the specific detail the vendor's message field carries
+ * ("consult the error message for specifics" is what its own reference says of `invalid_params`).
+ */
+export function apiError(code, occurredAt, message) {
+    const spec = API_ERRORS[code];
+    return {
+        status: spec.status,
+        body: { error: { code, message: message ?? spec.message, log_id: logId(occurredAt, `api:${code}:${message ?? ''}`) } },
+        headers: { ...NOSTORE, ...JSON_CT },
+    };
+}
+/**
+ * The Content Posting API's OWN codes, with the HTTP status each reference page gives them
+ * (developers.tiktok.com content-posting-api-reference-direct-post, -upload-video,
+ * -query-creator-info and -get-video-status, fetched 2026-09-27). Note the SINGULAR `invalid_param`:
+ * the posting references spell it that way while the v2 error table spells `invalid_params`, and a
+ * client that branches on the code must meet the spelling of the endpoint it called. Messages are
+ * the reference's descriptions, lightly completed into sentences (twin prose); codes and statuses are
+ * the vendor's.
+ */
+export const POSTING_ERRORS = {
+    invalid_param: { status: 400, message: 'The request contains an invalid parameter. Check the error message for details.' },
+    spam_risk_too_many_posts: { status: 403, message: 'The daily post cap for this user has been reached.' },
+    spam_risk_user_banned_from_posting: { status: 403, message: 'This user is banned from making new posts.' },
+    reached_active_user_cap: { status: 403, message: 'The daily quota for active publishing users from this client has been reached.' },
+    unaudited_client_can_only_post_to_private_accounts: { status: 403, message: 'Unaudited clients can only post to a private account.' },
+    url_ownership_unverified: { status: 403, message: 'To use PULL_FROM_URL, the developer must verify ownership of the URL prefix or domain.' },
+    privacy_level_option_mismatch: { status: 403, message: 'The privacy_level is not one of the privacy_level_options this creator has.' },
+    spam_risk_too_many_pending_share: { status: 403, message: 'This user has too many pending shares in the last 24 hours.' },
+    invalid_publish_id: { status: 400, message: 'The publish_id does not exist.' },
+    token_not_authorized_for_specified_publish_id: { status: 400, message: 'The access token is not authorized to read the status of this publish_id.' },
+};
+/** A Content Posting refusal, in the same nested envelope as the rest of the v2 API. */
+export function postingError(code, occurredAt, message) {
+    const spec = POSTING_ERRORS[code];
+    return {
+        status: spec.status,
+        body: { error: { code, message: message ?? spec.message, log_id: logId(occurredAt, `posting:${code}:${message ?? ''}`) } },
+        headers: { ...NOSTORE, ...JSON_CT },
+    };
+}
+/**
+ * An UNMODELLED path on a twinned TikTok host fails like the vendor rather than faking a success.
+ * TikTok publishes no 404 body for an unknown v2 route, so the twin answers the API family's own
+ * `invalid_params` shape with a message that names the route — an honest refusal in the envelope
+ * the surrounding endpoints speak. `tiktok.errors.unknown_route_pin` (todo) pins the live answer.
+ */
+export function unknownRoute(method, path, occurredAt) {
+    return apiError('invalid_params', occurredAt, `${method} ${path} is not a TikTok open API endpoint this twin serves`);
+}
+/** A contained unexpected failure. Never exposes local exception text. */
+export function internalError(occurredAt) {
+    return apiError('internal_error', occurredAt);
+}

package/dist/src/tiktok-ids.d.ts

@@ -0,0 +1,16 @@
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist
+ *  (the resend/xidentity exemplar's `stableHex`). Pure: no clock, no entropy, no host state. */
+export declare function stableHex(seed: string, n: number): string;
+/** `yyyyMMddHHmmss` in UTC — the leading 14 digits of TikTok's own `log_id` examples. */
+export declare function logTimestamp(occurredAt: string): string;
+/**
+ * A TikTok `log_id` — "the unique id associated with every request for debugging purposes"
+ * (developers.tiktok.com error-handling reference, fetched 2026-09-13).
+ *
+ * SHAPE, from the vendor's own two published examples
+ * (`20220829194722CBE87ED59D524E727021`, `202206221854370101130062072500FFA2`): 14 digits of UTC
+ * `yyyyMMddHHmmss` followed by 20 UPPERCASE hex characters — 34 characters total. The twin
+ * reproduces the shape (an integration's log scraper may key on it); the trailing bytes are a
+ * stable hash of the request coordinates, never entropy, because the value is served (R9).
+ */
+export declare function logId(occurredAt: string, seed: string): string;

package/dist/src/tiktok-ids.js

@@ -0,0 +1,48 @@
+// Deterministic id material for the TikTok twin — the ONE place a served identifier's bytes are
+// derived, shared by the credential minting in `tiktok-store.ts` and the `log_id` every TikTok
+// response carries (`tiktok-errors.ts`).
+//
+// WHY IT IS PURE (runtime contract R9): every value minted here is SERVED — the authorization
+// code rides the callback redirect, the `act.`/`rft.`/`clt.` tokens ride the token reply, and
+// `log_id` is in the envelope of literally every TikTok v2 response, success or failure. A served
+// response must be a pure function of (request, stored state), so there is no clock read and no
+// entropy in this module: callers pass the world instant and a state-derived seed.
+//
+// A twin's credentials are stand-ins, not secrets. Determinism is the contract and predictability
+// from public state is not a threat model a twin has; UNIQUENESS is, and the callers carry it by
+// seeding with the row COUNT of the type being minted (which advances on every mint) plus the
+// subject the credential is issued for.
+/** FNV-1a over the seed, widened by re-hashing with a round counter until `n` hex chars exist
+ *  (the resend/xidentity exemplar's `stableHex`). Pure: no clock, no entropy, no host state. */
+export function stableHex(seed, n) {
+    let out = '';
+    for (let round = 0; out.length < n; round += 1) {
+        let h = 0x811c9dc5;
+        const s = `${round}:${seed}`;
+        for (let i = 0; i < s.length; i += 1) {
+            h ^= s.charCodeAt(i);
+            h = Math.imul(h, 0x01000193) >>> 0;
+        }
+        out += h.toString(16).padStart(8, '0');
+    }
+    return out.slice(0, n);
+}
+/** `yyyyMMddHHmmss` in UTC — the leading 14 digits of TikTok's own `log_id` examples. */
+export function logTimestamp(occurredAt) {
+    const d = new Date(occurredAt);
+    const p = (n, w = 2) => String(n).padStart(w, '0');
+    return `${p(d.getUTCFullYear(), 4)}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`;
+}
+/**
+ * A TikTok `log_id` — "the unique id associated with every request for debugging purposes"
+ * (developers.tiktok.com error-handling reference, fetched 2026-09-13).
+ *
+ * SHAPE, from the vendor's own two published examples
+ * (`20220829194722CBE87ED59D524E727021`, `202206221854370101130062072500FFA2`): 14 digits of UTC
+ * `yyyyMMddHHmmss` followed by 20 UPPERCASE hex characters — 34 characters total. The twin
+ * reproduces the shape (an integration's log scraper may key on it); the trailing bytes are a
+ * stable hash of the request coordinates, never entropy, because the value is served (R9).
+ */
+export function logId(occurredAt, seed) {
+    return `${logTimestamp(occurredAt)}${stableHex(`log:${occurredAt}:${seed}`, 20).toUpperCase()}`;
+}

package/dist/src/tiktok-media.d.ts

@@ -0,0 +1,7 @@
+export type MediaProbe = {
+    durationSeconds?: number;
+    width?: number;
+    height?: number;
+    frameRate?: number;
+};
+export declare function probeMp4(bytes: Uint8Array): MediaProbe;

package/dist/src/tiktok-media.js

@@ -0,0 +1,86 @@
+function boxes(view, start, end) {
+    const out = [];
+    let at = start;
+    while (at + 8 <= end) {
+        let size = view.getUint32(at);
+        const type = String.fromCharCode(view.getUint8(at + 4), view.getUint8(at + 5), view.getUint8(at + 6), view.getUint8(at + 7));
+        let header = 8;
+        if (size === 1) {
+            if (at + 16 > end)
+                break;
+            size = Number(view.getBigUint64(at + 8));
+            header = 16;
+        }
+        else if (size === 0) {
+            size = end - at;
+        }
+        if (size < header || at + size > end)
+            break;
+        out.push({ type, start: at + header, end: at + size });
+        at += size;
+    }
+    return out;
+}
+/** A track's frame rate: its sample count over its media duration (mdhd timescale units). */
+function frameRateOf(view, trak) {
+    const mdia = boxes(view, trak.start, trak.end).find((b) => b.type === 'mdia');
+    if (!mdia)
+        return undefined;
+    const inMdia = boxes(view, mdia.start, mdia.end);
+    const mdhd = inMdia.find((b) => b.type === 'mdhd');
+    const stbl = (() => { const minf = inMdia.find((b) => b.type === 'minf'); return minf ? boxes(view, minf.start, minf.end).find((b) => b.type === 'stbl') : undefined; })();
+    const stts = stbl ? boxes(view, stbl.start, stbl.end).find((b) => b.type === 'stts') : undefined;
+    if (!mdhd || !stts)
+        return undefined;
+    const version = view.getUint8(mdhd.start);
+    const timescale = view.getUint32(mdhd.start + (version === 1 ? 20 : 12));
+    const duration = version === 1 ? Number(view.getBigUint64(mdhd.start + 24)) : view.getUint32(mdhd.start + 16);
+    const entries = view.getUint32(stts.start + 4);
+    let samples = 0;
+    for (let i = 0; i < entries && stts.start + 8 + i * 8 + 4 <= stts.end; i += 1)
+        samples += view.getUint32(stts.start + 8 + i * 8);
+    if (timescale <= 0 || duration <= 0 || samples <= 0)
+        return undefined;
+    return samples / (duration / timescale);
+}
+export function probeMp4(bytes) {
+    try {
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        const moov = boxes(view, 0, bytes.byteLength).find((b) => b.type === 'moov');
+        if (!moov)
+            return {};
+        const out = {};
+        const children = boxes(view, moov.start, moov.end);
+        const mvhd = children.find((b) => b.type === 'mvhd');
+        if (mvhd) {
+            const version = view.getUint8(mvhd.start);
+            const timescale = view.getUint32(mvhd.start + (version === 1 ? 20 : 12));
+            const duration = version === 1 ? Number(view.getBigUint64(mvhd.start + 24)) : view.getUint32(mvhd.start + 16);
+            if (timescale > 0)
+                out.durationSeconds = duration / timescale;
+        }
+        for (const trak of children.filter((b) => b.type === 'trak')) {
+            const tkhd = boxes(view, trak.start, trak.end).find((b) => b.type === 'tkhd');
+            if (!tkhd)
+                continue;
+            const version = view.getUint8(tkhd.start);
+            const sizeAt = tkhd.start + (version === 1 ? 88 : 76);
+            if (sizeAt + 8 > tkhd.end)
+                continue;
+            const width = view.getUint32(sizeAt) / 65536;
+            const height = view.getUint32(sizeAt + 4) / 65536;
+            if (width > 0 && height > 0) {
+                out.width = Math.round(width);
+                out.height = Math.round(height);
+                const rate = frameRateOf(view, trak);
+                if (rate !== undefined)
+                    out.frameRate = rate;
+                break;
+            }
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}

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

@@ -0,0 +1,49 @@
+export type TtRow = Record<string, any>;
+/** The user fields the profile reads — every one the Display API gates behind the three user scopes. */
+export declare const PROFILE_FIELDS = "open_id,union_id,avatar_url,display_name,username,bio_description,is_verified,follower_count,following_count,likes_count,video_count";
+/** The fields a token holding only user.info.basic may ask for (the header then carries no counts). */
+export declare const BASIC_FIELDS = "open_id,union_id,avatar_url,display_name";
+/** The Video Object fields the grid and the player read. */
+export declare const VIDEO_READ_FIELDS = "id,create_time,title,video_description,duration,width,height,like_count,comment_count,share_count,view_count";
+/** The Display API's own page maximum. */
+export declare const VIDEO_PAGE_SIZE = 20;
+/** tiktok.com's count: exact under 10,000 ("1280"), then one decimal of K or M ("45.1K", "1.4M"),
+ *  the trailing ".0" dropped ("12K"). */
+export declare function compactCount(raw: unknown): string;
+/** The profile header's three counts, each only when the twin returned it. */
+export declare function profileStats(user: TtRow | undefined): Array<{
+    label: 'Following' | 'Followers' | 'Likes';
+    value: string;
+}>;
+export type CaptionSegment = {
+    kind: 'text' | 'hashtag' | 'mention';
+    value: string;
+};
+/** A caption split the way tiktok.com bolds it: #hashtags and @mentions are links, the rest text. */
+export declare function captionSegments(text: unknown): CaptionSegment[];
+/** The caption a post shows: the Video Object's description, else its title. */
+export declare function captionOf(video: TtRow | undefined): string;
+/** "0:03", "1:02" — the player's time readout. */
+export declare function clock(seconds: unknown): string;
+/** A post's bytes on the twin's media route, relative to the wire base. The creator's token rides the
+ *  URL (a <video> element sends no header), which is what a post that is not public needs. */
+export declare function mediaSource(base: string, videoId: string, token: string): string;
+/** The avatar placeholder's letter and hue: pure functions of the account. */
+export declare function avatarInitial(user: TtRow | undefined): string;
+export declare function avatarHue(key: unknown): number;
+/** Build the React/TSX mirror client to browser JS; memoized, so a pack does exactly one Bun.build. */
+export declare function buildTiktokMirrorClient(): Promise<string>;
+/** Serve the TikTok mirror UI (React app) + its backing API, upload and media routes on one origin. */
+export declare function createTiktokMirrorServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    url: string;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure). The client itself is the React app. */
+export declare function tiktokMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function tiktokMirrorStyles(): Promise<string>;