@xhub-short/sdk

> Glue Layer - Kết nối Core Domain với React UI

📖 SDK là gì?

SDK (Software Development Kit) là package chính mà Host App cài đặt để tích hợp Short Video Feed. Nó đóng vai trò "Glue Layer" - kết nối tất cả các thành phần bên trong SDK thành một API thống nhất, dễ sử dụng.

``
┌─────────────────────────────────────────────────────────────────────┐
│ HOST APP (Your App) │
│ │
│ import { ShortVideoProvider, useFeed, usePlayer } from '@xhub-short/sdk';
│ import { VideoFeed, VideoPlayer } from '@xhub-short/ui'; │
│ │
└──────────────────────────────┬──────────────────────────────────────┘
│ uses
▼
┌─────────────────────────────────────────────────────────────────────┐
│ @xhub-short/ui │
│ (Lego Components - Phase 4) │
│ │
│ VideoFeed, VideoPlayer, InteractionBar, CommentSheet... │
│ │
└──────────────────────────────┬──────────────────────────────────────┘
│ imports hooks from
▼
┌─────────────────────────────────────────────────────────────────────┐
│ @xhub-short/sdk │
│ (Glue Layer - Current) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Provider │ │ Hooks │ │ Factory (createSDK) │ │
│ │ (Context) │ │ (React) │ │ (Dependency Inject) │ │
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
│ │
└──────────────────────────────┬──────────────────────────────────────┘
│ orchestrates
┌────────────────────┴────────────────────┐
▼ ▼
┌─────────────┐ ┌─────────────┐
│ @core │ │ @adapters │
│ (Domain) │ │ (Infra) │
└─────────────┘ └─────────────┘
`

> Lưu ý: @sdk KHÔNG import từ @ui. Mũi tên chỉ hướng dependency (ai import ai).

---

🎯 Tại sao cần SDK?

| Vấn đề | Giải pháp của SDK |
|--------|-------------------|
| Host App phải hiểu kiến trúc phức tạp bên trong | SDK expose API đơn giản: hooks + provider |
| Khó setup dependency injection cho adapters | createSDK() tự động wire tất cả |
| State management phức tạp (Feed, Player, Resource...) | Hooks abstract hết complexity |
| SSR compatibility | useSyncExternalStore built-in |
| Memory leaks khi unmount | sdk.destroy() cleanup tự động |

---

📋 Nhiệm vụ chi tiết của SDK

SDK thực hiện 7 nhiệm vụ chính để Host App có thể tích hợp dễ dàng:

$3

SDK là nơi duy nhất thực hiện dependency injection - kết nối các adapters với core managers:

`
┌─────────────────────────────────────────────────────────────────────┐
│ DEPENDENCY INJECTION MAP │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Adapter Interface ───► Core Component │
│ ───────────────── ────────────── │
│ IDataSource ───► FeedManager │
│ IInteraction ───► OptimisticManager │
│ ISessionStorage ───► LifecycleManager │
│ INetworkAdapter ───► ResourceGovernor │
│ IVideoLoader + IPosterLoader ───► ResourceGovernor │
│ IAnalytics ───► PlayerEngine (events) │
│ ILogger ───► All managers (debug) │
│ │
└─────────────────────────────────────────────────────────────────────┘
`

$3

SDK tự động resolve adapters theo thứ tự ưu tiên:

`
Config Priority:
┌──────────────────────────────────────────────────────────────┐
│ │
│ 1. config.adapters.dataSource ◄── Highest (User-defined)│
│ │ │
│ ▼ fallback │
│ 2. config.preset → createBrowserAdapters() │
│ │ │
│ ▼ fallback │
│ 3. MockAdapter ◄── Lowest (Development) │
│ │
└──────────────────────────────────────────────────────────────┘
`

Điều này cho phép:
- Development: Không cần config → Mock adapters tự động
- Production với Preset: Chỉ cần baseUrl + auth + endpoints
- Full Custom: Override bất kỳ adapter nào

$3

Core Domain sử dụng vanilla stores (không React). SDK bridge chúng sang React:

`
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Core Store │ │ SDK Hook │ │ React UI │
│ (Vanilla) │ ───► │ (useSyncExternal│ ───► │ (Re-render) │
│ │ │ Store) │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ store.subscribe() │ getSnapshot()
│ store.setState() │
▼ ▼
Framework-agnostic SSR-safe subscription
`

Tại sao không dùng Zustand trực tiếp trong Core?
- Core phải framework-agnostic (có thể dùng với Vue, Svelte...)
- Giảm bundle size cho Core package
- Tách biệt concerns rõ ràng

$3

SDK wire các events giữa managers để chúng phối hợp:

`
┌──────────────────────────────────────────────────────────────────────┐
│ EVENT WIRING │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ PlayerEngine │
│ │ │
│ ├── on('videoChange') ──────► Analytics.flush() │
│ │ (Flush trước khi đổi video) │
│ │ │
│ └── on('timeUpdate') ───────► LifecycleManager.setPendingSave()│
│ (Auto-save playback position) │
│ │
│ LifecycleManager │
│ │ │
│ └── on('visibilityChange') ─► Analytics.flush() │
│ (state === 'hidden') (Flush khi app background) │
│ │
│ ResourceGovernor │
│ │ │
│ └── on('focusChange') ──────► PlayerEngine.load(video) │
│ (Load video khi swipe) │
│ │
└──────────────────────────────────────────────────────────────────────┘
`

$3

SDK quản lý toàn bộ vòng đời của các managers:

| Phase | SDK Actions |
|-------|-------------|
| Init | Tạo managers, inject adapters, wire events, restore session |
| Active | Managers hoạt động độc lập, SDK chỉ expose hooks |
| Background | Auto-save session, flush analytics |
| Destroy | Cleanup timers, unsubscribe events, clear cache |

`typescript
// Tự động trong Provider:
useEffect(() => {
const sdk = createSDK(config);
return () => sdk.destroy(); // Cleanup khi unmount
}, []);
`

$3

SDK expose API đơn giản, ẩn đi complexity bên trong:

| Exposed to Host App | Hidden from Host App |
|---------------------|----------------------|
| useFeed() - videos, loadMore | FeedManager internals |
| usePlayer() - play, pause, seek | PlayerEngine state machine |
| useOptimistic() - like, follow | Rollback queue, pending states |
| useSwipeGesture() - onSwipe | DOM allocation logic |
| Config với preset | Adapter creation |

$3

SDK đảm bảo hoạt động với Server-Side Rendering:

`
┌──────────────────────────────────────────────────────────────┐
│ SSR STRATEGY │
├──────────────────────────────────────────────────────────────┤
│ │
│ Server: │
│ ├─ ShortVideoProvider renders với empty state │
│ ├─ Hooks return initial/fallback values │
│ └─ Không tạo SDK instance │
│ │
│ Client (Hydration): │
│ ├─ useEffect tạo SDK instance │
│ ├─ Restore session từ localStorage │
│ └─ useSyncExternalStore subscribe to stores │
│ │
└──────────────────────────────────────────────────────────────┘
`

---

🏗️ Kiến trúc

$3

`
┌─────────────────────────────────────────────────────────────────────┐
│ HEXAGONAL ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ @xhub-short/sdk │ │
│ │ ════════════════ │ │
│ │ │ │
│ │ ShortVideoProvider ──────┬──────── createSDK() │ │
│ │ │ │ │ │ │
│ │ │ Dependency Injection │ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Hooks │ │ Core │ │ Adapters │ │ │
│ │ │ (React) │◀────▶│ Managers │◀──│ (Inject) │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ @contracts │ │ @core │ │ @adapters │ │
│ │ (Interfaces) │ │ (Domain) │ │ (Infrastructure) │ │
│ └──────────────┘ └──────────────┘ └──────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
`

$3

`
@xhub-short/sdk
├── @xhub-short/contracts (types, interfaces)
├── @xhub-short/core (domain logic)
├── @xhub-short/adapters (mock + preset adapters)
├── @xhub-short/ui (headless components)
├── react (peer dependency)
└── zustand (peer dependency)
`

$3

`bash
npm install @xhub-short/sdk
`

That's it! No other dependencies needed.

Bundled internally:
- zustand - state management (bundled in @xhub-short/core)
- clsx - class names utility (bundled in @xhub-short/ui)
- Custom useTouchDrag hook - gesture handling (bundled in @xhub-short/sdk)

---

✨ Chức năng chính

$3

`tsx



`

$3

| Hook | Mục đích |
|------|----------|
| useFeed() | Video list, pagination, loading states |
| usePlayer() | Playback control, time, volume, handlers |
| useResource() | DOM allocations, prefetch queue |
| useOptimistic() | Like/Follow với instant UI + rollback |
| useSwipeGesture() | Vertical swipe navigation |

$3

SDK exports pre-wired versions of UI components with SDK hooks already injected:

| Component | Description |
|-----------|-------------|
| VideoFeed | Wired VideoFeedHeadless with useFeed + useSwipeGesture |
| VideoSlot | Wired VideoSlotHeadless with useResourceAllocation + usePlayer |
| VideoPlayer | Wired VideoPlayerHeadless with usePlayer (auto-load, sync) |
| ProgressBar | Wired progress bar with Direct DOM Update (60fps smooth) |

#### VideoPlayer (Wired)

Pre-wired video player that auto-connects to SDK PlayerEngine.

`tsx
import { VideoSlot, VideoPlayer } from '@xhub-short/sdk';
import { VideoSlotPoster, VideoSlotOverlay } from '@xhub-short/ui';

function FeedItem({ video }) {
return (

resetOnInactive={true} // TikTok-like: restart from beginning
/>

...

);
}
`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| video | VideoItem | from context | Video to play (optional if inside VideoSlot) |
| autoLoad | boolean | true | Auto-load video into PlayerEngine |
| autoPlay | boolean | true | Auto-play when slot becomes active |
| resetOnInactive | boolean | true | Reset video to 0:00 when slot becomes inactive |
| loop | boolean | true | Loop video playback |
| muted | boolean | true | Start muted (required for autoplay) |

resetOnInactive behavior:
- true (default): TikTok-like - swiping back restarts video from beginning
- false: YouTube-like - video continues from where user left off

#### ProgressBar (Wired) - P11 Re-render Optimization

Pre-wired progress bar that uses Direct DOM Update for 60fps smooth animation.

`tsx
import { VideoSlot, VideoPlayer, ProgressBar } from '@xhub-short/sdk';
import { VideoSlotOverlay } from '@xhub-short/ui';

function FeedItem({ video }) {
return (



{/ 60fps smooth! /}


);
}
`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| seekable | boolean | true | Enable click/drag to seek |
| showTime | boolean | false | Show current/duration text |
| showTooltip | boolean | true | Show tooltip on hover |
| minimal | boolean | false | Thin bar without handle |

Performance Architecture:

`
PlayerEngine.store ───── subscribe() ───── fillRef.style.transform
(scaleX, GPU accelerated)
NOT React re-render!
`

This component demonstrates ADR 005: Direct DOM Manipulation for high-frequency updates.
See docs/issues/RE_RENDER_ANALYSIS.md for detailed optimization rationale.

$3

`typescript
const sdk = createSDK({
preset: { baseUrl, auth, endpoints }, // Auto-generate adapters
adapters: { dataSource, interaction }, // Or custom adapters
feed: { pageSize: 20 },
player: { autoplay: true },
});
`

---

🔄 Cách hoạt động

$3

`
┌──────────────────────────────────────────────────────────────────────┐
│ INITIALIZATION │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Host App mount │
│ │ │
│ ▼ │
│ 2. createSDK(config) │
│ ├─ Resolve adapters (preset → browser adapters) │
│ ├─ Create Core managers: │
│ │ ├─ FeedManager (video list, deduplication, GC) │
│ │ ├─ PlayerEngine (playback state machine) │
│ │ ├─ ResourceGovernor (DOM allocation, prefetch) │
│ │ ├─ OptimisticManager (like/follow with rollback) │
│ │ └─ LifecycleManager (session persistence) │
│ └─ Wire analytics flush events │
│ │ │
│ ▼ │
│ 3. SDKContext.Provider value={sdk} │
│ │ │
│ ▼ │
│ 4. Hooks subscribe to managers via useSyncExternalStore │
│ │
└──────────────────────────────────────────────────────────────────────┘
`

$3

`
User swipes down
│
▼
useSwipeGesture() ─────────► ResourceGovernor.setFocusedIndex(n+1)
│
┌────────────────┼────────────────┐
▼ ▼ ▼
Deallocate Allocate Preload
video[n-1] video[n+1] video[n+2]
│
▼
PlayerEngine.load(video)
│
▼
Analytics.track('video_view')
`

---

📦 Exports

$3

`typescript
export { ShortVideoProvider } from './provider';
export type { ShortVideoProviderProps, SDKConfig } from './provider';
`

$3

`typescript
// Feed management
export { useFeed, useFeedSelector } from './hooks';

// Player control
export { usePlayer, usePlayerSelector, usePlayerForVideo } from './hooks';

// Resource management (DOM allocation)
export { useResource, useResourceSelector, useResourceAllocation } from './hooks';

// Optimistic UI (like/follow)
export { useOptimistic, useOptimisticSelector } from './hooks';

// Swipe navigation
export { useSwipeGesture } from './hooks';

// SDK context access
export { useSDK } from './hooks';
`

$3

`typescript
export { createSDK } from './store';
export type { SDKInstance } from './store';
`

$3

`typescript
// From @xhub-short/contracts
export type { VideoItem, FeedResponse, IDataSource, ... } from '@xhub-short/contracts';

// From @xhub-short/core
export type { FeedState, PlayerState, ResourceState, ... } from '@xhub-short/core';
`

---

🚀 Quick Start

$3

`tsx
import { ShortVideoRoot, VideoFeed, DefaultSlot } from '@xhub-short/sdk';

function App() {
return (
config={{
preset: {
baseUrl: 'https://api.example.com/v1',
auth: { getAccessToken: () => localStorage.getItem('token') },
endpoints: {
feed: { list: '/videos', detail: '/videos/:id' },
interaction: { like: '/videos/:id/like' },
},
},
}}
errorMode="auto-skip-with-toast"
>
(
video={video}
index={index}
showBookmark={true}
onOpenComments={(videoId) => openSheet(videoId)}
onShare={(video) => shareVideo(video)}
/>
)} />

);
}
`

That's it! The SDK handles everything: video loading, HLS playback, swipe navigation, like/follow actions, error handling, and more.

$3

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| video | VideoItem | required | Video data |
| index | number | required | Index in feed |
| showPoster | boolean | true | Show poster |
| showLikeAnimation | boolean | true | Double-tap hearts |
| showAuthorInfo | boolean | true | Avatar + follow |
| showActionBar | boolean | true | Like, comment, share |
| showVideoInfo | boolean | true | Caption, hashtags |
| showProgressBar | boolean | true | Progress bar |
| showBookmark | boolean | false | Bookmark button |
| onOpenComments | (videoId) => void | - | Comment click |
| onShare | (video) => void | - | Share click |
| onOpenProfile | (author) => void | - | Author click |
| onHashtagClick | (tag) => void | - | Hashtag click |

$3

For full control, use individual components:

`tsx
import {
ShortVideoRoot, VideoFeed, VideoSlot, VideoPlayer,
ActionBar, AuthorInfo, VideoInfo, ProgressBar
} from '@xhub-short/sdk';
import { VideoSlotOverlay, VideoSlotPoster } from '@xhub-short/ui';

(














)} />

$3

`tsx
config={{
adapters: {
dataSource: new MyGraphQLAdapter(),
interaction: new MyFlutterBridgeAdapter(),
},
}}
>


`

---

👤 Guest Mode (Chế độ khách)

SDK hỗ trợ chế độ khách cho phép người dùng chưa đăng nhập xem video và bình luận (read-only). Các tương tác (Like, Comment, Follow) sẽ bị chặn và trigger callback để Host App xử lý (ví dụ: hiện modal đăng nhập).

$3

`tsx
config={{
// ...
guest: {
/**
* 'auto': Tự động detect dựa trên auth token (default)
* true: Force guest mode
* false: Disable guest mode
*/
mode: 'auto',

/**
* Callback khi guest thực hiện hành động cần auth (Like, Comment, Follow...)
*/
onAction: (action, context) => {
console.log('Guest Action:', action, context);
// VD: showLoginModal();
}
}
}}
>


`

$3


- Like / Bookmark: Trigger onAction
- Follow: Trigger onAction
- Comment Input: Hiển thị nút "Login to comment". Khi click triggers onAction (action='comment').

---

⚡ Prefetch Data (Tải trước dữ liệu)

Cho phép Host App tải trước dữ liệu Feed (Reels) để trải nghiệm hiển thị tức thì (instant loading).

$3

Gọi hàm prefetchFeed trước khi mount SDK components (ví dụ: khi hover vào menu Reels hoặc trong route loader).

`tsx
import { prefetchFeed } from '@xhub-short/sdk';

// 1. Prefetch data (lưu vào bộ nhớ tạm)
// Có thể gọi ở bất kỳ đâu trong Host App
await prefetchFeed(sdkConfig, { ttl: 5 60 1000 });

// ... Sau đó ...

// 2. Khi User vào trang Reels, SDK sẽ tự động dùng data đã fetch



`

$3


- In-Memory Cache: Dữ liệu chỉ lưu tạm trong RAM, mất khi refresh trang (đảm bảo fresh data).
- Auto-Consume: ShortVideoRoot tự động tiêu thụ cache và xóa sau khi dùng.
- Performance: Giúp giảm thời gian chờ đợi (LCP) xuống gần bằng 0 khi user chuyển trang.

---

🔗 Liên kết với các Packages

| Package | Quan hệ với SDK |
|---------|-----------------|
| @xhub-short/contracts | SDK re-export types/interfaces |
| @xhub-short/core | SDK wraps core managers với React hooks |
| @xhub-short/adapters | SDK inject adapters vào core managers |
| @xhub-short/ui | UI components sử dụng SDK hooks (Phase 4) |
| @xhub-short/bridge | Optional Flutter integration |

$3

`
contracts ◀─────────────────────────────────────────┐
▲ │
│ │
core ◀──────────────────────────┐ │
▲ │ │
│ │ │
adapters ◀──────────┐ │ │
▲ │ │ │
│ │ │ │
└───────────────┴──────────┴────────── sdk ───┘
│
▼
Host App
`

---

⚠️ Lưu ý quan trọng

$3


- Tất cả hooks sử dụng useSyncExternalStore
- Provider render fallback trên server
- SDK instance chỉ tạo trên client

$3

- sdk.destroy() được gọi tự động khi Provider unmount
- Max 3 video DOM nodes (via ResourceGovernor)
- LRU cache eviction trong FeedManager

$3

`typescript
// ❌ DEPRECATED - Singleton gây issues với SSR/testing
const sdk = getSDK(config);

// ✅ RECOMMENDED - Sử dụng Provider



``

---

📚 Tài liệu liên quan

- ADD.md - System Architecture
- TECH_STACK.md - Technology Stack
- packages/core/README.md - Core Domain
- packages/adapters/README.md - Adapters