@volter/twin-tiktok 0.1.0

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

@@ -0,0 +1,158 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { TikTokBudget, type TikTokBudgetOptions } from './tiktok-budget.js';
+/** Every modelled user field a pull requests by default — narrow it for a narrower token. */
+export declare const PULL_USER_FIELDS: readonly string[];
+/** Every modelled video field a pull requests when `videos` is enabled. */
+export declare const PULL_VIDEO_FIELDS: readonly string[];
+/**
+ * The injected real-TikTok boundary. `execute` issues ONE request and returns the parsed JSON
+ * body. A real client (a raw fetch wrapper) is structurally assignable; tests pass a fake.
+ */
+export type TikTokExecute = (method: 'GET' | 'POST', path: string, init?: {
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<Record<string, any>>;
+export type LiveTikTokOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: TikTokBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: TikTokBudgetOptions;
+};
+/**
+ * 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 declare function liveTikTokExecute(accessToken: string, opts?: LiveTikTokOptions): TikTokExecute;
+/**
+ * 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 declare function mapUserInfoAccount(body: Record<string, any>): SyncResource;
+/** Map one real Video object -> the video SyncResource, owned by the pulled account. */
+export declare function mapVideo(video: Record<string, any>, ownerUnionId: string): SyncResource;
+export type PullOptions = {
+    root?: string;
+    occurredAt?: string;
+    /** Narrow the `user.fields` a pull asks for — required when the token holds fewer scopes than
+     *  the three `user.info.*` ones (an unauthorized field is a refusal, not an empty value). */
+    userFields?: readonly string[];
+    /** Also pull the account's videos. OFF by default: the Display API video reads need the separate
+     *  `video.list` scope, and a refused read must never fold an empty list over observed state. */
+    videos?: boolean;
+    /** How many videos to ask for in one page (TikTok's own maximum is 20). */
+    videoCount?: number;
+};
+/** PULL the operator's own identity (and optionally their videos) into the observed log. */
+export declare function pullTikTok(execute: TikTokExecute, opts?: PullOptions): Promise<number>;
+/**
+ * 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 declare function syncTikTokFromReal(execute: TikTokExecute, opts?: PullOptions): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * 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 declare function pushPendingTikTokActions(root?: string): {
+    pushed: 0;
+    unpushable: number;
+};
+/** 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 declare function tiktokExecuteOver(execute: RemoteExecute): TikTokExecute;
+/**
+ * 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 declare function syncTikTokFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/** How often the perform reads status/fetch while TikTok processes (see THE BOUND above). */
+export declare const STATUS_POLL_MS = 3000;
+/** How long, in total, a perform waits on TikTok's processing before it fails the entry retryably. */
+export declare const MAX_PUBLISH_WAIT_MS = 120000;
+/** The chunk the perform sends: TikTok's 5 MB minimum (read as MiB), so a 4 GB video is 800 chunks. */
+export declare const PERFORM_CHUNK_BYTES: number;
+/** TikTok answered "later" (429, a 5xx) — the entry stays deployable and the next deploy tries again. */
+export declare class TikTokRetryableError extends Error {
+    readonly retryable = true;
+    constructor(message: string);
+}
+/** TikTok has the video but has not finished processing it inside the bound: retry later. */
+export declare class TikTokStillProcessingError extends TikTokRetryableError {
+    readonly publishId: string;
+    constructor(publishId: string, waitedMs: number, reads: number);
+}
+/**
+ * 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 declare function budgetedTikTokExecute(execute: RemoteExecute, budget?: TikTokBudget): RemoteExecute;
+/** The chunk plan TikTok's rules require for `size` bytes at the perform's chunk size. */
+export declare function performChunkPlan(size: number): {
+    chunkSize: number;
+    totalChunkCount: number;
+};
+/**
+ * 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 declare function performTikTokAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext, budget?: TikTokBudget): Promise<PushOutcome>;