@volter/twin-tiktok 0.1.36 → 1.0.0

package/dist/src/tiktok-blobs.js

@@ -1,161 +0,0 @@
-// 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';
-const DIGEST = /^[0-9a-f]{64}$/;
-const UPLOAD_ID = /^[0-9]{1,24}$/;
-function resources(root) {
-    return worldPaths(SERVICE, root).resources;
-}
-function blobKey(sha256) {
-    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, root) {
-    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, root) {
-    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, start, endInclusive, root) {
-    if (typeof sha256 !== 'string' || !DIGEST.test(sha256))
-        return null;
-    return readResourceBlobRange(SERVICE, blobKey(sha256), start, endInclusive, root);
-}
-function uploadDir(root) {
-    return join(resources(root), 'uploads');
-}
-function assertUploadId(id) {
-    if (!UPLOAD_ID.test(id))
-        throw new Error(`invalid TikTok upload id: ${JSON.stringify(id)}`);
-    return id;
-}
-function uploadKey(id, root) {
-    return join(uploadDir(root), `${assertUploadId(id)}.json`);
-}
-function publishKey(publishId, root) {
-    return join(uploadDir(root), 'by-publish', `${blobDigest(new TextEncoder().encode(publishId))}.json`);
-}
-function chunkDir(id, root) {
-    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, offset, root) {
-    return join(chunkDir(id, root), `${String(offset).padStart(16, '0')}.part`);
-}
-async function readJson(key) {
-    try {
-        const stored = await getActiveBlobStore().get(key);
-        return stored === null ? null : JSON.parse(new TextDecoder().decode(stored));
-    }
-    catch {
-        return null;
-    }
-}
-export async function writeUpload(upload, root) {
-    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, root) {
-    if (!UPLOAD_ID.test(id))
-        return null;
-    const upload = await readJson(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, root) {
-    const pointer = await readJson(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, root) {
-    const prefix = `${chunkDir(id, root)}/`;
-    const out = [];
-    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, root) {
-    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, offset, bytes, root) {
-    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, root) {
-    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, root) {
-    try {
-        await getActiveBlobStore().remove(`${chunkDir(id, root)}/`);
-    }
-    catch { /* never staged */ }
-}
-function performKey(actionId, root) {
-    return join(resources(root), 'perform-publishes', `${blobDigest(new TextEncoder().encode(actionId))}.json`);
-}
-export async function readPerformPublish(actionId, root) {
-    return readJson(performKey(actionId, root));
-}
-export async function writePerformPublish(actionId, record, root) {
-    await getActiveBlobStore().put(performKey(actionId, root), new TextEncoder().encode(JSON.stringify(record)));
-}
-export async function clearPerformPublish(actionId, root) {
-    try {
-        await getActiveBlobStore().remove(performKey(actionId, root));
-    }
-    catch { /* none */ }
-}

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

@@ -1,56 +0,0 @@
-import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
-/** Rolling window, in ms — TikTok's own one-minute sliding window. */
-export declare const TIKTOK_BUDGET_WINDOW_MS = 60000;
-/** 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 declare const TIKTOK_BUDGET_CEILING = 600;
-/** The window IS the kernel's burst sub-window, so this is also the per-minute burst bound. */
-export declare const TIKTOK_BUDGET_BURST_CEILING = 600;
-/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
-export declare 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 declare const TIKTOK_CALL_WEIGHTS: {
-    /** The three Display API reads — 600/min is the PUBLISHED limit; weight 1 transcribes it. */
-    readonly 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). */
-    readonly revoke: 60;
-    /** Everything else (the token endpoint): no published scalar limit -> priced conservatively. */
-    readonly other: 5;
-    /** `POST /v2/post/publish/creator_info/query/` — "limited to 20 requests per minute". */
-    readonly creatorInfo: 30;
-    /** `POST /v2/post/publish/video/init/` and `/inbox/video/init/` — "limited to 6 requests per minute". */
-    readonly postInit: 100;
-    /** `POST /v2/post/publish/status/fetch/` — "limited to 30 requests per minute". */
-    readonly postStatus: 20;
-};
-/** THE PACK'S DECLARATION — pure data, the only TikTok-specific thing in the whole budget. */
-export declare const TIKTOK_RATE_BUDGET: RateBudgetDeclaration;
-/**
- * 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 declare function tiktokCallWeight(method: string, path: string): number;
-/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to
- *  opt into world-scoped accounting. */
-export declare function tiktokBudgetPath(opts?: {
-    root?: string;
-    token?: string;
-} | string): string;
-/** 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 declare class TikTokBudget extends RateBudget {
-    constructor(opts?: TikTokBudgetOptions);
-}
-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;

package/dist/src/tiktok-budget.js

@@ -1,136 +0,0 @@
-// 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, } 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,
-};
-/** THE PACK'S DECLARATION — pure data, the only TikTok-specific thing in the whole budget. */
-export const TIKTOK_RATE_BUDGET = {
-    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, path) {
-    const { bare, query } = splitQuery(path);
-    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
-}
-function splitQuery(path) {
-    const at = path.indexOf('?');
-    const query = {};
-    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 = {}) {
-    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 });
-}
-/**
- * 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 = {}) {
-        super({ ...opts, vendor: VENDOR });
-    }
-}
-export { RateBudgetError as TikTokBudgetError } from '@volter/world-core';

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

@@ -1,7 +0,0 @@
-import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
-export declare const TIKTOK_CAPABILITIES: CapabilitySpec[];
-/** Committed area census (TWIN-87/F1) — enumerated TOP-DOWN from the vendor's own product nav
- *  (Login Kit, Display API, Content Posting, Research, Data Portability, Local Services, Business)
- *  plus this pack's structural areas, not derived from the manifest (which would be a tautology). */
-export declare const TIKTOK_AREAS: readonly ["authorize", "business", "client_credentials", "conformance", "connector", "consent", "content_posting", "errors", "local_services", "login_kit", "mini_apps", "oembed", "portability", "rate", "readonly", "refresh", "research", "revoke", "scopes", "share_kit", "token", "ui", "user_info", "video", "webhooks"];
-export declare function tiktokCapabilities(): Promise<CapabilityReport>;