@volter/twin-tiktok 0.1.0

package/src/tiktok-blobs.ts

@@ -0,0 +1,217 @@
+// Content-addressed BYTE storage for the TikTok twin — a posted video's real media.
+//
+// Transcribed from the YouTube pack's byte annex (youtube-blobs.ts), which took it from Slack's: bytes
+// ride the KERNEL'S BLOB SEAM (`getActiveBlobStore()`, runtime contract R11) — the filesystem locally,
+// object storage inside a served namespace — under this service's own `resources` dir, which
+// `scrubService('tiktok')` already owns. Keys (relative to that dir): blobs/sha256/<ab>/<hex>. The
+// kernel projection references a blob by digest only (`_content_sha256` on a video or a draft), so the
+// event log stays small however large the media is.
+//
+// READS GO THROUGH THE KERNEL'S RESOURCE-BLOB HELPERS (`readResourceBlobRange`, `resourceBlobSize`): a
+// branch inherits its ancestors' videos in the projection, so it must inherit their bytes too, and
+// those helpers look at the branch and then its retained ancestors. They read a RANGE natively, so
+// serving a seek, or sending one upload chunk, never loads the whole video.
+//
+// AN UPLOAD IS STAGING, and staging is NOT a kernel action: the upload_url the init hands back is a
+// place to put bytes, not an event in the creator's history. An upload is a pointer record plus its
+// chunks, each chunk its own key, joined ONCE when the final chunk lands; only that finalize is a
+// kernel write. An upload that is abandoned leaves no pending action to wedge a later deploy, and its
+// upload_url stops answering after TikTok's own hour.
+import { join } from 'node:path';
+import { blobDigest, getActiveBlobStore, readResourceBlobRange, resourceBlobSize, worldPaths } from '@volter/world-core';
+
+const SERVICE = 'tiktok';
+
+export interface TikTokBlobRef {
+  sha256: string;
+  size: number;
+}
+
+const DIGEST = /^[0-9a-f]{64}$/;
+const UPLOAD_ID = /^[0-9]{1,24}$/;
+
+function resources(root?: string): string {
+  return worldPaths(SERVICE, root).resources;
+}
+
+function blobKey(sha256: string): string {
+  return join('blobs', 'sha256', sha256.slice(0, 2), sha256);
+}
+
+/** Store bytes content-addressed in this branch's annex; identical content is a no-op write. */
+export async function putTikTokBlob(bytes: Uint8Array, root?: string): Promise<TikTokBlobRef> {
+  const sha256 = blobDigest(bytes);
+  const key = join(resources(root), blobKey(sha256));
+  if (!(await getActiveBlobStore().exists(key))) await getActiveBlobStore().put(key, bytes);
+  return { sha256, size: bytes.length };
+}
+
+/** A stored blob's size, here or at an ancestor; null when absent or the digest is malformed. */
+export async function tikTokBlobSize(sha256: unknown, root?: string): Promise<number | null> {
+  if (typeof sha256 !== 'string' || !DIGEST.test(sha256)) return null;
+  return resourceBlobSize(SERVICE, blobKey(sha256), root);
+}
+
+/** Bytes start..endInclusive of a stored blob, here or at an ancestor, read as a range. */
+export async function readTikTokBlobRange(sha256: unknown, start: number, endInclusive: number, root?: string): Promise<Uint8Array | null> {
+  if (typeof sha256 !== 'string' || !DIGEST.test(sha256)) return null;
+  return readResourceBlobRange(SERVICE, blobKey(sha256), start, endInclusive, root);
+}
+
+// ── uploads in flight (staging: pointer record + one key per chunk) ────────────────────────────
+
+/** What an upload remembers between its init and its final chunk. */
+export type TikTokUpload = {
+  /** The upload_id in the upload_url's query. */
+  uploadId: string;
+  /** The publish_id the init answered; status/fetch reads the upload by it until it finalizes. */
+  publishId: string;
+  /** `direct` (video.publish: Direct Post) or `inbox` (video.upload: the creator's drafts). */
+  mode: 'direct' | 'inbox';
+  /** The account and app the posting token belongs to (status/fetch answers
+   *  token_not_authorized_for_specified_publish_id to any other), and the token's SHA-256 — never the
+   *  token. */
+  accountId: string;
+  clientKey: string;
+  tokenSha256: string;
+  /** This upload's own signing secret (hex), drawn from entropy at init: the upload_token is an HMAC
+   *  under it, so no other upload's URL, and no credential, is ever the key (LinkedIn's per-asset
+   *  secret). */
+  uploadSecret: string;
+  /** The Direct Post `post_info` as the init validated it (empty for an inbox upload). */
+  postInfo: Record<string, unknown>;
+  videoSize: number;
+  chunkSize: number;
+  totalChunkCount: number;
+  /** World time (ms) the upload_url was issued and stops being valid. */
+  issuedAt: number;
+  expiresAt: number;
+  /** Set once the final chunk has landed: the digest the bytes were stored under. */
+  sha256?: string;
+};
+
+function uploadDir(root?: string): string {
+  return join(resources(root), 'uploads');
+}
+
+function assertUploadId(id: string): string {
+  if (!UPLOAD_ID.test(id)) throw new Error(`invalid TikTok upload id: ${JSON.stringify(id)}`);
+  return id;
+}
+
+function uploadKey(id: string, root?: string): string {
+  return join(uploadDir(root), `${assertUploadId(id)}.json`);
+}
+
+function publishKey(publishId: string, root?: string): string {
+  return join(uploadDir(root), 'by-publish', `${blobDigest(new TextEncoder().encode(publishId))}.json`);
+}
+
+function chunkDir(id: string, root?: string): string {
+  return join(uploadDir(root), assertUploadId(id));
+}
+
+/** A chunk's key carries its first byte, zero-padded so the seam's sorted listing is byte order. */
+function chunkKey(id: string, offset: number, root?: string): string {
+  return join(chunkDir(id, root), `${String(offset).padStart(16, '0')}.part`);
+}
+
+async function readJson<T>(key: string): Promise<T | null> {
+  try {
+    const stored = await getActiveBlobStore().get(key);
+    return stored === null ? null : (JSON.parse(new TextDecoder().decode(stored)) as T);
+  } catch {
+    return null;
+  }
+}
+
+export async function writeUpload(upload: TikTokUpload, root?: string): Promise<void> {
+  const bytes = new TextEncoder().encode(JSON.stringify(upload));
+  await getActiveBlobStore().put(uploadKey(upload.uploadId, root), bytes);
+  await getActiveBlobStore().put(publishKey(upload.publishId, root), new TextEncoder().encode(JSON.stringify({ uploadId: upload.uploadId })));
+}
+
+export async function readUpload(id: string, root?: string): Promise<TikTokUpload | null> {
+  if (!UPLOAD_ID.test(id)) return null;
+  const upload = await readJson<TikTokUpload>(uploadKey(id, root));
+  return upload && typeof upload.uploadId === 'string' ? upload : null;
+}
+
+/** The upload a publish_id names, while it is staging (before its final chunk lands). */
+export async function readUploadByPublishId(publishId: string, root?: string): Promise<TikTokUpload | null> {
+  const pointer = await readJson<{ uploadId: string }>(publishKey(publishId, root));
+  return pointer ? readUpload(pointer.uploadId, root) : null;
+}
+
+/** The upload's chunks in byte order, with their offsets and sizes. */
+async function chunks(id: string, root?: string): Promise<Array<{ key: string; offset: number; size: number }>> {
+  const prefix = `${chunkDir(id, root)}/`;
+  const out: Array<{ key: string; offset: number; size: number }> = [];
+  for (const key of await getActiveBlobStore().list(prefix)) {
+    const m = /(\d{16})\.part$/.exec(key);
+    if (!m) continue;
+    out.push({ key, offset: Number(m[1]), size: (await getActiveBlobStore().size(key)) ?? 0 });
+  }
+  return out.sort((a, b) => a.offset - b.offset);
+}
+
+/** Bytes an upload holds so far: the contiguous run from 0. */
+export async function stagedSize(id: string, root?: string): Promise<number> {
+  let held = 0;
+  for (const c of await chunks(id, root)) {
+    if (c.offset !== held) break;
+    held += c.size;
+  }
+  return held;
+}
+
+/** Stage one chunk at its first byte — its own key; nothing already staged is read or rewritten. */
+export async function stageChunk(id: string, offset: number, bytes: Uint8Array, root?: string): Promise<void> {
+  if (bytes.length > 0) await getActiveBlobStore().put(chunkKey(id, offset, root), bytes);
+}
+
+/** Join an upload's chunks, once, into the video's bytes. */
+export async function joinStaged(id: string, root?: string): Promise<Uint8Array> {
+  const parts = await chunks(id, root);
+  const total = parts.reduce((n, c) => n + c.size, 0);
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const c of parts) {
+    const bytes = await getActiveBlobStore().get(c.key);
+    if (bytes === null) continue;
+    out.set(bytes, at);
+    at += bytes.length;
+  }
+  return out.subarray(0, at);
+}
+
+/** Drop a finalized upload's chunks (the bytes now live content-addressed); the record stays, so a
+ *  final PUT whose answer was lost can be asked again and status/fetch still finds the publish. */
+export async function clearStaged(id: string, root?: string): Promise<void> {
+  try { await getActiveBlobStore().remove(`${chunkDir(id, root)}/`); } catch { /* never staged */ }
+}
+
+// ── a perform's own progress (not a kernel action; the byte annex, as staging is) ──────────────
+// A Direct Post publishes by itself once its last chunk lands, so a perform that died after its init
+// must never init again while TikTok still knows it: that could post the video twice. The publish it
+// opened is kept here, keyed by the entry and written only by the World performing it, so the next
+// perform of the same entry asks that publish where it stands before it opens another.
+
+/** The publish an entry's perform opened, and the upload_url TikTok gave it: kept only in this World's
+ *  byte annex (never an entry, never a changeset), so the next perform can resume the SAME publish's
+ *  chunks rather than open a second one. */
+export type PerformPublish = { publishId: string; uploadUrl: string; sha256: string; size: number; chunkSize: number; totalChunkCount: number };
+
+function performKey(actionId: string, root?: string): string {
+  return join(resources(root), 'perform-publishes', `${blobDigest(new TextEncoder().encode(actionId))}.json`);
+}
+
+export async function readPerformPublish(actionId: string, root?: string): Promise<PerformPublish | null> {
+  return readJson<PerformPublish>(performKey(actionId, root));
+}
+export async function writePerformPublish(actionId: string, record: PerformPublish, root?: string): Promise<void> {
+  await getActiveBlobStore().put(performKey(actionId, root), new TextEncoder().encode(JSON.stringify(record)));
+}
+export async function clearPerformPublish(actionId: string, root?: string): Promise<void> {
+  try { await getActiveBlobStore().remove(performKey(actionId, root)); } catch { /* none */ }
+}

package/src/tiktok-budget.ts

@@ -0,0 +1,163 @@
+// TikTok's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveTikTokExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` -> `rateBudget.ts`).
+//
+// ── HOW THE CEILING WAS CHOSEN (live-fetched first-party figures) ───────────────────────────────
+// TikTok PUBLISHES per-endpoint rate limits. From https://developers.tiktok.com/doc/tiktok-api-v2-rate-limit
+// (fetched 2026-09-13): "Request rate calculation is based on a one minute sliding window", the
+// table gives `/v2/user/info/`, `/v2/video/list/` and `/v2/video/query/` a limit of **600** each,
+// and "If the number of requests exceeds the threshold, new requests will be throttled and a
+// response will be returned with HTTP status 429 and error code rate_limit_exceeded."
+//
+// So the window is the vendor's own ONE MINUTE and the ceiling is the vendor's own 600, with each
+// Display API read at weight 1 — the declaration REPRODUCES the published scheme for the endpoints
+// the connector reads (the github-budget precedent: when the vendor's scheme is already a windowed
+// budget, transcribe it). Two deliberate tightenings on top, both stated rather than hidden:
+//
+//   • The vendor's 600 is PER ENDPOINT; this ledger is ONE budget across all of them, so 600
+//     shared is strictly tighter than the vendor's 1800 across the three.
+//   • The OAuth endpoints (`/v2/oauth/token/`, `/v2/oauth/revoke/`) publish NO scalar limit on
+//     that page. That absence is stated here rather than dressed up, and those calls are priced
+//     ABOVE the documented read so the undocumented surface is the conservative one.
+//
+// The window is already the kernel's 60s burst sub-window, so the ceiling IS the burst and the
+// kernel refuses a `burstCeiling` here. 600 units/minute out-bursts the kernel fallback's 30
+// calls/minute, which is licensed by the hand-written `burstAnchor` in this pack's gate.ts —
+// the vendor's own documented per-minute allowance, with its source.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'tiktok';
+
+/** Rolling window, in ms — TikTok's own one-minute sliding window. */
+export const TIKTOK_BUDGET_WINDOW_MS = 60_000;
+
+/** Weighted units allowed inside one window — TikTok's own published per-endpoint figure, applied
+ *  across ALL endpoints at once (strictly tighter than the vendor's own per-endpoint allowance). */
+export const TIKTOK_BUDGET_CEILING = 600;
+
+/** The window IS the kernel's burst sub-window, so this is also the per-minute burst bound. */
+export const TIKTOK_BUDGET_BURST_CEILING = TIKTOK_BUDGET_CEILING;
+
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export const TIKTOK_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is documented vs judged. */
+export const TIKTOK_CALL_WEIGHTS = {
+  /** The three Display API reads — 600/min is the PUBLISHED limit; weight 1 transcribes it. */
+  displayRead: 1,
+  /** `POST /v2/oauth/revoke/` — disconnects an app from a REAL human's TikTok account. Priced as a
+   *  human blast radius, not a throttle (a judgement call, stated as one). */
+  revoke: 60,
+  /** Everything else (the token endpoint): no published scalar limit -> priced conservatively. */
+  other: 5,
+  // The Content Posting calls publish their OWN per-token minute allowance on each reference page
+  // (fetched 2026-09-27), and each is priced so that the endpoint alone can never exceed it inside
+  // this 600-unit minute: weight = 600 / the published per-minute figure.
+  /** `POST /v2/post/publish/creator_info/query/` — "limited to 20 requests per minute". */
+  creatorInfo: 30,
+  /** `POST /v2/post/publish/video/init/` and `/inbox/video/init/` — "limited to 6 requests per minute". */
+  postInit: 100,
+  /** `POST /v2/post/publish/status/fetch/` — "limited to 30 requests per minute". */
+  postStatus: 20,
+} as const;
+
+/** THE PACK'S DECLARATION — pure data, the only TikTok-specific thing in the whole budget. */
+export const TIKTOK_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: TIKTOK_BUDGET_WINDOW_MS,
+  ceiling: TIKTOK_BUDGET_CEILING,
+  defaultWeight: TIKTOK_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: TIKTOK_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^GET /v2/user/info$', weight: TIKTOK_CALL_WEIGHTS.displayRead },
+    { match: '^POST /v2/video/list$', weight: TIKTOK_CALL_WEIGHTS.displayRead },
+    { match: '^POST /v2/video/query$', weight: TIKTOK_CALL_WEIGHTS.displayRead },
+    { match: '^POST /v2/oauth/revoke$', weight: TIKTOK_CALL_WEIGHTS.revoke },
+    { match: '^POST /v2/post/publish/creator_info/query$', weight: TIKTOK_CALL_WEIGHTS.creatorInfo },
+    { match: '^POST /v2/post/publish/video/init$', weight: TIKTOK_CALL_WEIGHTS.postInit },
+    { match: '^POST /v2/post/publish/inbox/video/init$', weight: TIKTOK_CALL_WEIGHTS.postInit },
+    { match: '^POST /v2/post/publish/status/fetch$', weight: TIKTOK_CALL_WEIGHTS.postStatus },
+  ],
+  reason:
+    'TikTok publishes per-endpoint rate limits (https://developers.tiktok.com/doc/tiktok-api-v2-rate-limit, '
+    + 'fetched 2026-09-13): "Request rate calculation is based on a one minute sliding window", the '
+    + 'table lists /v2/user/info/, /v2/video/list/ and /v2/video/query/ at 600 each, and exceeding a '
+    + 'limit answers "HTTP status 429 and error code rate_limit_exceeded". This declaration '
+    + "transcribes that scheme: the window is the vendor's own one minute, the ceiling is the "
+    + "vendor's own 600, and each Display API read costs 1. It is tighter than the vendor in one "
+    + 'respect, deliberately: the published 600 is PER ENDPOINT while this is ONE ledger shared '
+    + 'across all three, so the twin spends at a third of the vendor allowance in the worst case. '
+    + 'The OAuth token and revoke endpoints publish NO scalar limit on that page; they are priced '
+    + 'ABOVE the documented read (defaultWeight 5) so the undocumented surface is the conservative '
+    + 'one. POST /v2/oauth/revoke/ costs 60 because it is the one destructive call here — it '
+    + "disconnects an app from a real human's TikTok account — which is a human blast radius, not a "
+    + 'throttle; that price is a judgement call, stated as one. The Content Posting references each '
+    + 'publish a per-token minute allowance (fetched 2026-09-27): creator_info 20, the Direct Post and '
+    + 'inbox inits 6, status/fetch 30; each is priced 600 divided by its figure (30, 100, 20), so no '
+    + 'one of them can exceed its own allowance inside this minute. The chunk PUTs to the upload URL '
+    + 'are not charged: they go to the upload host on a presigned URL, and once a publish has started '
+    + 'the budget cannot stop it. The vendor publishes no rate-limit response headers, so the 429 / '
+    + 'Retry-After cooldown is the only backstop and is armed from whatever the vendor does send.',
+};
+
+// Declared at module load, so merely importing this module (which `tiktok-connector.ts` does) is
+// enough to arm the real ceiling.
+declareRateBudget(VENDOR, TIKTOK_RATE_BUDGET);
+
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation — and on THIS vendor the trailing slash is not hypothetical: every
+ * documented TikTok path carries one (`/v2/oauth/revoke/`), so a rule anchored on the bare form
+ * would price the vendor's OWN spelling of the destructive call at the default weight.
+ */
+export function tiktokCallWeight(method: string, path: string): number {
+  const { bare, query } = splitQuery(path);
+  return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+
+function splitQuery(path: string): { bare: string; query: Record<string, string> } {
+  const at = path.indexOf('?');
+  const query: Record<string, string> = {};
+  if (at !== -1) for (const [k, v] of new URLSearchParams(path.slice(at + 1))) query[k] = v;
+  const raw = at === -1 ? path : path.slice(0, at);
+  const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+  return { bare, query };
+}
+
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to
+ *  opt into world-scoped accounting. */
+export function tiktokBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through must not
+  // redirect this pack's ledger.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options. The vendor is fixed; everything else may only TIGHTEN. */
+export type TikTokBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not
+ * an alias, so `budget instanceof TikTokBudget` means "a budget that accounts against TIKTOK's
+ * ledger under TIKTOK's ceiling".
+ */
+export class TikTokBudget extends RateBudget {
+  constructor(opts: TikTokBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+export { RateBudgetError as TikTokBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as TikTokBudgetErrorKind } from '@volter/world-core';
+export type TikTokBudgetReservation = RateBudgetReservation;
+export type TikTokBudgetSnapshot = RateBudgetSnapshot;