@dracoonghost/trndup-sdk 1.0.0

package/README.md

@@ -0,0 +1,224 @@
+# TrndUp TypeScript SDK
+
+Official TypeScript SDK for the TrndUp API with Firebase authentication support.
+
+## Installation
+
+```bash
+# In your mobile app
+npm install file:../trndup-service/src/sdk
+# or when published
+npm install @trndup/sdk
+```
+
+## Quick Start
+
+```typescript
+import { TrndUpSDK } from '@trndup/sdk';
+import auth from '@react-native-firebase/auth';
+
+// Initialize SDK
+const sdk = new TrndUpSDK({
+  baseUrl: 'https://api.trndup.app', // or 'http://localhost:3000' for dev
+  getToken: async () => {
+    const user = auth().currentUser;
+    return user ? await user.getIdToken() : null;
+  },
+  onAuthFailure: () => {
+    // Handle auth failure - navigate to login
+    console.log('Authentication failed - please log in again');
+  },
+  debug: __DEV__, // Enable debug logging in development
+});
+
+export default sdk;
+```
+
+## Usage
+
+### Authentication
+
+```typescript
+// Login with Firebase ID token
+const result = await sdk.auth.login(firebaseIdToken);
+console.log('User:', result.user);
+
+// Get current user
+const { user, socialAccounts } = await sdk.auth.getCurrentUser();
+
+// Update profile
+await sdk.auth.updateProfile({
+  username: 'New Name',
+  picture: 'https://...',
+});
+
+// Logout
+await sdk.auth.logout();
+```
+
+### YouTube Analytics
+
+```typescript
+// Check initialization status
+const status = await sdk.youtube.getInitStatus();
+console.log('Needs init:', status.needsInit);
+
+// Initialize YouTube data
+if (status.needsInit) {
+  await sdk.youtube.initialize();
+}
+
+// Get videos
+const { videos, total } = await sdk.youtube.getVideos({
+  limit: 20,
+  sortBy: 'views',
+});
+
+// Get channel metrics
+const metrics = await sdk.youtube.getChannelMetrics();
+console.log('Subscribers:', metrics.subscriberCount);
+
+// Get health score
+const health = await sdk.youtube.getHealthScore({ range: '30d' });
+console.log('Score:', health.score, 'Grade:', health.grade);
+```
+
+### Instagram Analytics
+
+```typescript
+// Check initialization status
+const status = await sdk.instagram.getInitStatus();
+
+// Get posts
+const { posts } = await sdk.instagram.getPosts({ limit: 20 });
+
+// Get account metrics
+const metrics = await sdk.instagram.getAccountMetrics();
+console.log('Followers:', metrics.followersCount);
+```
+
+### Social Account Linking
+
+```typescript
+// Link YouTube account
+await sdk.social.linkYouTube({
+  accessToken: 'ya29.a0...',
+  refreshToken: '1//0g...',
+});
+
+// Link Instagram account
+await sdk.social.linkInstagram({
+  accessToken: 'IGQVJ...',
+});
+
+// Get connected accounts
+const accounts = await sdk.social.getConnectedAccounts();
+
+// Unlink account
+await sdk.social.unlinkAccount('youtube');
+```
+
+### Cross-Platform Insights
+
+```typescript
+// Get overview
+const overview = await sdk.insights.getOverview();
+console.log('Total followers:', overview.totalFollowers);
+
+// Get trending content
+const trending = await sdk.insights.getTrending();
+```
+
+## Error Handling
+
+```typescript
+import { TrndUpApiError, TrndUpNetworkError } from '@trndup/sdk';
+
+try {
+  await sdk.youtube.getVideos();
+} catch (error) {
+  if (error instanceof TrndUpApiError) {
+    console.error('API Error:', error.message);
+    console.error('Status:', error.status);
+    console.error('Code:', error.code);
+    
+    if (error.isAuthError()) {
+      // Handle authentication error
+      console.log('Please log in again');
+    }
+    
+    if (error.isRateLimitError()) {
+      // Handle rate limiting
+      console.log('Too many requests, please wait');
+    }
+  } else if (error instanceof TrndUpNetworkError) {
+    console.error('Network Error:', error.message);
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+```
+
+## Configuration Options
+
+```typescript
+interface TrndUpClientConfig {
+  /** Base URL for the API */
+  baseUrl: string;
+  
+  /** Function to get the current Firebase ID token */
+  getToken: () => string | null | Promise<string | null>;
+  
+  /** Called when auth completely fails */
+  onAuthFailure?: () => void | Promise<void>;
+  
+  /** Called on any API error */
+  onError?: (error: ApiErrorResponse, endpoint: string) => void;
+  
+  /** Custom headers to include in all requests */
+  defaultHeaders?: Record<string, string>;
+  
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+```
+
+## Type Safety
+
+The SDK is fully typed with TypeScript. All request/response types are available:
+
+```typescript
+import type { Auth, YouTube, Instagram, Social, Insights } from '@trndup/sdk';
+
+// Use types in your code
+const user: Auth.User = await sdk.auth.getCurrentUser();
+const videos: YouTube.Video[] = await sdk.youtube.getVideos();
+```
+
+## Development
+
+```bash
+# Build SDK
+cd src/sdk
+npm install
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Type check
+npm run type-check
+
+# Link for local development
+npm link
+
+# In your mobile app
+npm link @trndup/sdk
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,478 @@
+interface ApiErrorResponse {
+    success: false;
+    error: string;
+    code?: string;
+    metadata?: Record<string, unknown>;
+}
+declare namespace Auth {
+    interface User {
+        id: string;
+        firebaseUid: string;
+        email: string;
+        username: string;
+        picture?: string;
+        emailVerified: boolean;
+        createdAt: string;
+        updatedAt: string;
+    }
+    interface SocialAccount {
+        provider: string;
+        accountName?: string;
+        username?: string;
+        profilePictureUrl?: string;
+        connectedAt: string;
+    }
+    interface LoginRequest {
+        idToken: string;
+    }
+    interface LoginResponse {
+        user: User;
+        idToken: string;
+    }
+    interface CurrentUserResponse {
+        user: User;
+        socialAccounts: SocialAccount[];
+    }
+    interface UpdateProfileRequest {
+        username?: string;
+        picture?: string;
+    }
+    interface UpdateProfileResponse {
+        user: User;
+    }
+}
+declare namespace Social {
+    interface LinkYouTubeRequest {
+        accessToken: string;
+        refreshToken?: string;
+    }
+    interface LinkInstagramRequest {
+        accessToken: string;
+    }
+    interface LinkAccountResponse {
+        message: string;
+        provider: string;
+        accountName?: string;
+    }
+    interface ConnectedAccount {
+        provider: string;
+        accountName?: string;
+        username?: string;
+        profilePictureUrl?: string;
+        connectedAt: string;
+        lastSyncAt?: string;
+    }
+}
+declare namespace YouTube {
+    interface InitStatusResponse {
+        needsInit: boolean;
+        message: string;
+        videoCount?: number;
+        channelId?: string;
+        channelTitle?: string;
+    }
+    interface Video {
+        id: string;
+        title: string;
+        description?: string;
+        thumbnailUrl?: string;
+        publishedAt: string;
+        duration?: string;
+        viewCount?: number;
+        likeCount?: number;
+        commentCount?: number;
+        engagementRate?: number;
+    }
+    interface GetVideosParams {
+        limit?: number;
+        offset?: number;
+        sortBy?: 'recent' | 'views' | 'engagement';
+    }
+    interface GetVideosResponse {
+        videos: Video[];
+        total: number;
+        hasMore: boolean;
+    }
+    interface ChannelMetrics {
+        subscriberCount: number;
+        totalViews: number;
+        totalVideos: number;
+        averageViews: number;
+        engagementRate: number;
+    }
+    interface HealthScore {
+        score: number;
+        grade: 'A' | 'B' | 'C' | 'D' | 'F';
+        metrics: {
+            consistency: number;
+            engagement: number;
+            growth: number;
+            quality: number;
+        };
+    }
+    interface GetHealthScoreParams {
+        range?: string;
+    }
+}
+declare namespace Instagram {
+    interface InitStatusResponse {
+        needsInit: boolean;
+        message: string;
+        postCount?: number;
+        accountId?: string;
+        username?: string;
+    }
+    interface Post {
+        id: string;
+        caption?: string;
+        mediaType: 'IMAGE' | 'VIDEO' | 'CAROUSEL_ALBUM';
+        mediaUrl: string;
+        permalink: string;
+        timestamp: string;
+        likeCount?: number;
+        commentsCount?: number;
+        engagementRate?: number;
+    }
+    interface GetPostsParams {
+        limit?: number;
+        offset?: number;
+    }
+    interface GetPostsResponse {
+        posts: Post[];
+        total: number;
+        hasMore: boolean;
+    }
+    interface AccountMetrics {
+        followersCount: number;
+        followsCount: number;
+        mediaCount: number;
+        averageLikes: number;
+        engagementRate: number;
+    }
+}
+declare namespace Insights {
+    interface CrossPlatformMetrics {
+        totalFollowers: number;
+        totalEngagement: number;
+        platforms: {
+            youtube?: {
+                subscribers: number;
+                views: number;
+                videos: number;
+            };
+            instagram?: {
+                followers: number;
+                posts: number;
+                avgEngagement: number;
+            };
+        };
+    }
+    interface TrendingContent {
+        youtube?: YouTube.Video[];
+        instagram?: Instagram.Post[];
+    }
+}
+
+/**
+ * TrndUp SDK - Base Client
+ *
+ * Core HTTP client with Firebase authentication support,
+ * error handling, and automatic retries.
+ */
+
+interface TrndUpClientConfig {
+    /** Base URL for the API (e.g., 'https://api.trndup.app' or 'http://localhost:3000') */
+    baseUrl: string;
+    /** Function to get the current Firebase ID token */
+    getToken: () => string | null | Promise<string | null>;
+    /** Called when auth completely fails (user needs to re-login) */
+    onAuthFailure?: () => void | Promise<void>;
+    /** Called on any API error */
+    onError?: (error: ApiErrorResponse, endpoint: string) => void;
+    /** Custom headers to include in all requests */
+    defaultHeaders?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface RequestOptions {
+    /** Skip authentication for this request */
+    skipAuth?: boolean;
+    /** Additional headers for this request */
+    headers?: Record<string, string>;
+    /** AbortController signal for cancellation */
+    signal?: AbortSignal;
+    /** Custom timeout for this request */
+    timeout?: number;
+}
+declare class TrndUpApiError extends Error {
+    readonly response: ApiErrorResponse;
+    readonly status: number;
+    readonly endpoint: string;
+    constructor(response: ApiErrorResponse, status: number, endpoint: string);
+    get code(): string | undefined;
+    get metadata(): Record<string, unknown> | undefined;
+    /** Check if error is due to authentication failure */
+    isAuthError(): boolean;
+    /** Check if error is due to rate limiting */
+    isRateLimitError(): boolean;
+}
+declare class TrndUpNetworkError extends Error {
+    readonly originalError: Error;
+    readonly endpoint: string;
+    constructor(originalError: Error, endpoint: string);
+}
+declare class TrndUpClient {
+    private config;
+    auth: any;
+    youtube: any;
+    instagram: any;
+    social: any;
+    insights: any;
+    constructor(config: TrndUpClientConfig);
+    get<T = unknown>(path: string, params?: Record<string, string | number | boolean | undefined>, options?: RequestOptions): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    private request;
+    private buildUrl;
+    private buildHeaders;
+    private handleResponse;
+}
+
+/**
+ * TrndUp SDK - Auth Module
+ *
+ * Firebase authentication methods
+ */
+
+declare class AuthModule {
+    private client;
+    constructor(client: TrndUpClient);
+    /**
+     * Login with Firebase ID token
+     * POST /auth/login
+     */
+    login(idToken: string): Promise<Auth.LoginResponse>;
+    /**
+     * Get current authenticated user's profile
+     * GET /auth/me
+     */
+    getCurrentUser(): Promise<Auth.CurrentUserResponse>;
+    /**
+     * Update user profile
+     * PATCH /auth/me
+     */
+    updateProfile(data: Auth.UpdateProfileRequest): Promise<Auth.UpdateProfileResponse>;
+    /**
+     * Logout (acknowledge logout on backend)
+     * POST /auth/logout
+     */
+    logout(): Promise<{
+        message: string;
+    }>;
+    /**
+     * Check auth service status
+     * GET /auth/status
+     */
+    getStatus(): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+}
+
+/**
+ * TrndUp SDK - YouTube Module
+ *
+ * YouTube analytics and data methods
+ */
+
+declare class YouTubeModule {
+    private client;
+    constructor(client: TrndUpClient);
+    /**
+     * Get YouTube initialization status
+     * GET /v1/platforms/youtube/init/status
+     */
+    getInitStatus(): Promise<YouTube.InitStatusResponse>;
+    /**
+     * Initialize YouTube data sync
+     * POST /v1/platforms/youtube/init
+     */
+    initialize(): Promise<{
+        message: string;
+        jobId?: string;
+    }>;
+    /**
+     * Get YouTube videos
+     * GET /v1/platforms/youtube/videos
+     */
+    getVideos(params?: YouTube.GetVideosParams): Promise<YouTube.GetVideosResponse>;
+    /**
+     * Get specific video by ID
+     * GET /v1/platforms/youtube/videos/:videoId
+     */
+    getVideo(videoId: string): Promise<YouTube.Video>;
+    /**
+     * Get channel metrics
+     * GET /v1/platforms/youtube/channel/metrics
+     */
+    getChannelMetrics(): Promise<YouTube.ChannelMetrics>;
+    /**
+     * Get channel health score
+     * GET /v1/platforms/youtube/health
+     */
+    getHealthScore(params?: YouTube.GetHealthScoreParams): Promise<YouTube.HealthScore>;
+    /**
+     * Refresh YouTube data
+     * POST /v1/platforms/youtube/refresh
+     */
+    refresh(): Promise<{
+        message: string;
+        jobId?: string;
+    }>;
+}
+
+/**
+ * TrndUp SDK - Instagram Module
+ *
+ * Instagram analytics and data methods
+ */
+
+declare class InstagramModule {
+    private client;
+    constructor(client: TrndUpClient);
+    /**
+     * Get Instagram initialization status
+     * GET /v1/platforms/instagram/init/status
+     */
+    getInitStatus(): Promise<Instagram.InitStatusResponse>;
+    /**
+     * Initialize Instagram data sync
+     * POST /v1/platforms/instagram/init
+     */
+    initialize(): Promise<{
+        message: string;
+    }>;
+    /**
+     * Get Instagram posts
+     * GET /v1/platforms/instagram/posts
+     */
+    getPosts(params?: Instagram.GetPostsParams): Promise<Instagram.GetPostsResponse>;
+    /**
+     * Get specific post by ID
+     * GET /v1/platforms/instagram/posts/:postId
+     */
+    getPost(postId: string): Promise<Instagram.Post>;
+    /**
+     * Get account metrics
+     * GET /v1/platforms/instagram/account/metrics
+     */
+    getAccountMetrics(): Promise<Instagram.AccountMetrics>;
+    /**
+     * Refresh Instagram data
+     * POST /v1/platforms/instagram/refresh
+     */
+    refresh(): Promise<{
+        message: string;
+    }>;
+}
+
+/**
+ * TrndUp SDK - Social Module
+ *
+ * Social account linking methods
+ */
+
+declare class SocialModule {
+    private client;
+    constructor(client: TrndUpClient);
+    /**
+     * Link YouTube account
+     * POST /social/link/youtube
+     */
+    linkYouTube(data: Social.LinkYouTubeRequest): Promise<Social.LinkAccountResponse>;
+    /**
+     * Link Instagram account
+     * POST /social/link/instagram
+     */
+    linkInstagram(data: Social.LinkInstagramRequest): Promise<Social.LinkAccountResponse>;
+    /**
+     * Get all connected social accounts
+     * GET /social/accounts
+     */
+    getConnectedAccounts(): Promise<Social.ConnectedAccount[]>;
+    /**
+     * Unlink a social account
+     * DELETE /social/unlink/:provider
+     */
+    unlinkAccount(provider: string): Promise<{
+        message: string;
+    }>;
+}
+
+/**
+ * TrndUp SDK - Insights Module
+ *
+ * Cross-platform insights and analytics
+ */
+
+declare class InsightsModule {
+    private client;
+    constructor(client: TrndUpClient);
+    /**
+     * Get cross-platform metrics
+     * GET /v1/insights/overview
+     */
+    getOverview(): Promise<Insights.CrossPlatformMetrics>;
+    /**
+     * Get trending content across all platforms
+     * GET /v1/insights/trending
+     */
+    getTrending(): Promise<Insights.TrendingContent>;
+}
+
+/**
+ * TrndUp API SDK
+ *
+ * Official TypeScript SDK for the TrndUp API.
+ * Provides type-safe methods for all API endpoints with Firebase authentication.
+ *
+ * @example
+ * ```typescript
+ * import { TrndUpSDK } from '@trndup/sdk';
+ * import auth from '@react-native-firebase/auth';
+ *
+ * const sdk = new TrndUpSDK({
+ *   baseUrl: 'https://api.trndup.app',
+ *   getToken: async () => {
+ *     const user = auth().currentUser;
+ *     return user ? await user.getIdToken() : null;
+ *   },
+ *   onAuthFailure: () => {
+ *     // Handle auth failure - navigate to login
+ *     navigation.navigate('Login');
+ *   },
+ * });
+ *
+ * // Type-safe API calls
+ * const user = await sdk.auth.getCurrentUser();
+ * const videos = await sdk.youtube.getVideos({ limit: 10 });
+ * const healthScore = await sdk.youtube.getHealthScore({ range: '30d' });
+ * ```
+ */
+
+declare class TrndUpSDK extends TrndUpClient {
+    auth: AuthModule;
+    youtube: YouTubeModule;
+    instagram: InstagramModule;
+    social: SocialModule;
+    insights: InsightsModule;
+    constructor(config: TrndUpClientConfig);
+}
+
+declare const SDK_VERSION = "1.0.0";
+
+export { Auth, Insights, Instagram, type RequestOptions, SDK_VERSION, Social, TrndUpApiError, type TrndUpClientConfig, TrndUpNetworkError, TrndUpSDK, YouTube };