Read posts and analytics

X

Reads: posts list, get, and iterate. Metrics: account and post, plus native likes lists. Access: user scopes and your X API tier.

Use a user OAuth token. appBearerToken is for app-only operations such as full-archive search, not user timelines.

import { x } from "@opencoredev/social-sdk/x";

const adapter = x({ auth: { userId: "123", accessToken: process.env.X_ACCESS_TOKEN! } });

posts.list and posts.get return id, text, author_id, created_at, and conversation_id. They do not include public_metrics or referenced posts; read counts with analytics.getPostMetrics. User timeline, home timeline, mentions, liked posts, and liking users are native operations: userPosts, homeTimeline, mentions, likedPosts, and likingUsers. They need the matching X read capability, user scopes, and an eligible API tier. Missing access raises missing_permission; throttling raises rate_limited.

Bluesky

Reads: author feed through posts.list, plus native getPost and getPostThread. Metrics: account and post, plus native likes lists. Access: repo. Feed page size is 1 to 100.

Use a PDS service and DID with an access JWT, or an OAuth session.

import { bluesky } from "@opencoredev/social-sdk/bluesky";

const adapter = bluesky({
  auth: {
    service: "https://bsky.social",
    did: "did:plc:example",
    accessJwt: process.env.BSKY_JWT!,
  },
});

posts.list reads the account’s author feed. Each item is { post, reason? }, where post has uri, cid, the like, repost, reply, and quote counts, indexedAt, and public author fields (did, handle, displayName, avatar). Validated nested fields include record text, timestamps, facets, reply references, and embeds; AppView embeds; labels; and repost reasons. Image, video, external-link, and quoted-post embeds are retained, including quotes with attached media. Fields outside the public allowlist are omitted. Use native getPost({ uri }) or getPostThread({ uri }) for additional record or thread data; neither returns a cursor. The normalized post ref can carry the native uri and cid. Native getLikes lists users who liked a post; getActorLikes lists posts an actor liked. An invalid page size raises invalid_input.

Threads

Reads: list and get. Metrics: account and post. Access: user token. Feed page size is 1 to 100.

Use the Threads user ID and a long-lived user access token.

import { threads } from "@opencoredev/social-sdk/threads";

const adapter = threads({ auth: { userId: "th_123", accessToken: process.env.THREADS_TOKEN! } });

List items contain id, text, username, media_type, permalink, and timestamp. The after cursor is opaque. posts.get and search.posts are normalized; posts.get returns the post fields the native getPost reads. Threads has post and selected account insights but no normalized likes list. Mentions and keyword search options beyond the normalized input are native.

Instagram

Reads: media list and get. Metrics: account and post insights. Access: a professional account.

Use a professional account ID and access token, and pick Instagram Login or Facebook Login. Business discovery and hashtag features need Facebook Login.

import { instagram } from "@opencoredev/social-sdk/instagram";

const adapter = instagram({
  auth: {
    accountId: "17840000000000000",
    accessToken: process.env.IG_TOKEN!,
    flavor: "instagram-login",
  },
});

Media includes Graph API fields such as ID, caption, media type, permalink, timestamp, and URLs. Insights can include likes, comments, saves, shares, and reach. Mentions, tagged media, and business discovery are native. The tags mentions edge works with both login flavors. Missing permissions raise missing_permission.

YouTube

Reads: uploads and get. Metrics: channel and video statistics. Access: an OAuth token and the channel ID.

Normalized posts are videos from the channel uploads feed.

import { youtube } from "@opencoredev/social-sdk/youtube";

const adapter = youtube({
  auth: { accessToken: process.env.YOUTUBE_TOKEN!, channelId: "UC_example" },
});

posts.get returns id, snippet (title, description, channelId, publishedAt), and status (privacyStatus, uploadStatus, selfDeclaredMadeForKids). It does not include statistics; read view, like, and comment counts with analytics.getPostMetrics. Playlists and playlist items are native. Reports need the separate https://www.googleapis.com/auth/yt-analytics.readonly scope and a bounded query. An inaccessible video raises an error instead of returning an empty item.

LinkedIn

Reads: author feed and get. Metrics: post, and account for organizations only. Access: r_member_social or r_organization_social.

Use a person or organization author URN and a monthly API version.

import { linkedin } from "@opencoredev/social-sdk/linkedin";

const adapter = linkedin({
  auth: { accessToken: process.env.LINKEDIN_TOKEN!, author: "urn:li:person:abc" },
  apiVersion: "202609",
});

Person authors need r_member_social; organization authors need r_organization_social. The author feed uses an opaque offset cursor. Organization account metrics need an administrator grant such as rw_organization_admin. Member-profile account analytics are not supported. Invalid URNs or API versions raise invalid_config.

TikTok

Reads: video list and get. Metrics: account stats and per-video counts. Access: Display API with user.info.stats and video.list.

TikTok reads use an access token, the creator’s Open ID, and verified media origins.

import { tiktok } from "@opencoredev/social-sdk/tiktok";

const adapter = tiktok({
  auth: { accessToken: process.env.TIKTOK_TOKEN!, openId: "open-id" },
  verifiedMediaOrigins: ["https://media.example.com"],
});

Video items include ID, creation time, title, description, dimensions, share URL, and like, comment, share, and view counts. getPostMetrics reads the same four counts through the video query endpoint and needs video.list. Account counts need user.info.stats. TikTok has no normalized likes list.