@volter/twin-tiktok 0.1.0

package/src/tiktok-user.ts

@@ -0,0 +1,137 @@
+// The two FIELD CATALOGS the TikTok open API selects over, and the projections that render them.
+//
+// Both are `fields`-driven: a caller names the fields it wants in a query parameter and gets back
+// exactly those, which means the field list itself is vendor surface — a wrong name here is a
+// twin that accepts what TikTok refuses.
+//
+//   • USER_FIELDS — the Get User Info reference's own table
+//     (developers.tiktok.com/docs/en/tiktok-api-v2-get-user-info, fetched 2026-09-13), including
+//     the SCOPE each field is gated behind. That gating is the reason the table carries a scope
+//     column at all: asking for `username` with only `user.info.basic` granted is the documented
+//     `scope_not_authorized` case, and it is exactly the bug a Login Kit integration hits when the
+//     user unchecks a permission on the consent sheet.
+//
+//   • VIDEO_FIELDS — the Video Object reference's own table
+//     (developers.tiktok.com/doc/tiktok-api-v2-video-object), which `/v2/video/list/` and
+//     `/v2/video/query/` both select over. Every field there is gated behind the single
+//     `video.list` scope.
+import type { Row } from './tiktok-store.ts';
+
+export const USER_INFO_SCOPES = ['user.info.basic', 'user.info.profile', 'user.info.stats'] as const;
+
+/** Field -> the scope that gates it, in the reference table's own order. */
+export const USER_FIELD_SCOPES: Record<string, string> = {
+  open_id: 'user.info.basic',
+  union_id: 'user.info.basic',
+  avatar_url: 'user.info.basic',
+  avatar_url_100: 'user.info.basic',
+  avatar_large_url: 'user.info.basic',
+  display_name: 'user.info.basic',
+  bio_description: 'user.info.profile',
+  profile_deep_link: 'user.info.profile',
+  is_verified: 'user.info.profile',
+  username: 'user.info.profile',
+  follower_count: 'user.info.stats',
+  following_count: 'user.info.stats',
+  likes_count: 'user.info.stats',
+  video_count: 'user.info.stats',
+};
+
+export const USER_FIELDS: readonly string[] = Object.keys(USER_FIELD_SCOPES);
+
+/**
+ * Render an account row as the vendor's User object for a requested field set.
+ *
+ * `open_id` is APP-SCOPED and therefore comes from the grant, not from the account — that is the
+ * whole distinction TikTok draws between `open_id` and `union_id`. A modelled field whose value
+ * this persona genuinely lacks is OMITTED rather than served as a placeholder (the connector's
+ * "invent nothing" rule, applied at the read side too).
+ */
+export function renderUser(account: Row, openId: string, fields: readonly string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const put = (key: string, value: unknown) => {
+    if (value !== undefined && value !== null) out[key] = value;
+  };
+  for (const field of fields) {
+    switch (field) {
+      case 'open_id': put(field, openId); break;
+      case 'union_id': put(field, account.id); break;
+      case 'avatar_url': put(field, account.avatarUrl); break;
+      case 'avatar_url_100': put(field, account.avatarUrl100); break;
+      case 'avatar_large_url': put(field, account.avatarLargeUrl); break;
+      case 'display_name': put(field, account.displayName); break;
+      case 'bio_description': put(field, account.bioDescription); break;
+      case 'profile_deep_link': put(field, account.profileDeepLink); break;
+      case 'is_verified': put(field, typeof account.isVerified === 'boolean' ? account.isVerified : undefined); break;
+      case 'username': put(field, account.username); break;
+      case 'follower_count': put(field, account.followerCount); break;
+      case 'following_count': put(field, account.followingCount); break;
+      case 'likes_count': put(field, account.likesCount); break;
+      case 'video_count': put(field, account.videoCount); break;
+      default: break;
+    }
+  }
+  return out;
+}
+
+/** The Video Object's fields, verbatim from the vendor's own reference table. */
+export const VIDEO_FIELDS: readonly string[] = [
+  'id',
+  'create_time',
+  'cover_image_url',
+  'share_url',
+  'video_description',
+  'duration',
+  'height',
+  'width',
+  'title',
+  'embed_html',
+  'embed_link',
+  'like_count',
+  'comment_count',
+  'share_count',
+  'view_count',
+  'is_aigc',
+];
+
+/** The single scope every Display API video read is gated behind. */
+export const VIDEO_SCOPE = 'video.list';
+
+/**
+ * Render a video row for a requested field set.
+ *
+ * The four LINK fields are DERIVED, deterministically, from the stored row — TikTok composes them
+ * the same way (`share_url` is the canonical `/@handle/video/<id>` permalink and `embed_link` the
+ * `/embed/v2/<id>` player). Deriving keeps them consistent with the id and the owner's handle
+ * instead of storing four strings that could drift apart; the exact CDN host of `cover_image_url`
+ * is a twin host, not the vendor's, and `tiktok.video.link_shapes` (todo) pins the live forms.
+ */
+export function renderVideo(video: Row, ownerUsername: string, fields: readonly string[]): Record<string, unknown> {
+  const shareUrl = `https://www.tiktok.com/@${ownerUsername}/video/${video.id}`;
+  const out: Record<string, unknown> = {};
+  const put = (key: string, value: unknown) => {
+    if (value !== undefined && value !== null) out[key] = value;
+  };
+  for (const field of fields) {
+    switch (field) {
+      case 'id': put(field, video.id); break;
+      case 'create_time': put(field, video.createTime); break;
+      case 'cover_image_url': put(field, `https://p16-sign.tiktokcdn-us.com/twin/${video.id}~tplv-cover.jpeg`); break;
+      case 'share_url': put(field, shareUrl); break;
+      case 'video_description': put(field, video.videoDescription); break;
+      case 'duration': put(field, video.duration); break;
+      case 'height': put(field, video.height); break;
+      case 'width': put(field, video.width); break;
+      case 'title': put(field, video.title); break;
+      case 'embed_html': put(field, `<blockquote class="tiktok-embed" cite="${shareUrl}" data-video-id="${video.id}"></blockquote>`); break;
+      case 'embed_link': put(field, `https://www.tiktok.com/embed/v2/${video.id}`); break;
+      case 'like_count': put(field, video.likeCount); break;
+      case 'comment_count': put(field, video.commentCount); break;
+      case 'share_count': put(field, video.shareCount); break;
+      case 'view_count': put(field, video.viewCount); break;
+      case 'is_aigc': put(field, video.isAigc === true); break;
+      default: break;
+    }
+  }
+  return out;
+}