@meeovi/social 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,79 @@
+
+---
+
+# 📦 `@meeovi/social` — README.md  
+*(This one is more advanced because of caching, SWR, retry, metrics, etc.)*
+
+```md
+# @meeovi/social
+
+A powerful, backend‑agnostic social integration layer for Meeovi.  
+Supports ATProto (Bluesky), Mastodon, WordPress/BuddyPress, and any custom social backend.
+
+## ✨ Features
+
+- Pluggable social providers  
+- Unified `useSocial()` composable  
+- Unified activity feed abstraction  
+- Caching (TTL‑based)  
+- Stale‑While‑Revalidate (SWR) background refresh  
+- Retry + exponential backoff  
+- Provider‑specific rate‑limit strategies  
+- Analytics hooks (per‑provider metrics)  
+- Unified error model  
+
+## 📦 Installation
+
+```sh
+npm install @meeovi/social
+
+🧩 Usage
+
+import { useSocial } from '@meeovi/social'
+
+const { getActivityFeed } = useSocial()
+
+const feed = await getActivityFeed('sebastian')
+🔌 Providers
+
+export interface SocialProvider {
+  getProfile(handle: string): Promise<SocialProfile>
+  listPosts(handle: string): Promise<SocialPost[]>
+  createPost?(content: string): Promise<SocialPost>
+}
+Register:
+
+
+registerSocialProvider('mastodon', MastodonProvider)
+🧠 Advanced Features
+Caching
+
+cacheKey: `atproto:posts:${handle}`,
+ttlMs: 30000
+SWR (Stale‑While‑Revalidate)
+
+swr: true
+Retry + Backoff
+
+retry: true
+Provider‑Specific Rate Limits
+
+setRateLimit('mastodon', { maxRequests: 10, windowMs: 60000 })
+Metrics
+
+import { getMetrics } from '@meeovi/social'
+
+console.log(getMetrics('atproto'))
+🧱 Folder Structure
+Code
+src/
+  providers/
+  config.
+  registry.
+  useSocial.
+  cache.
+  retry.
+  swr.
+  rateLimit.
+  metrics.
+  utils.

package/index.ts

@@ -0,0 +1,8 @@
+export * from './src/types'
+export * from './src/config'
+export * from './src/registry'
+export * from './src/useSocial'
+
+// providers auto‑register on import
+export * from './src/providers/atproto'
+export * from './src/providers/mastodon'

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@meeovi/social",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
   "main": "index.js",
+  "exports": { ".": "./index.ts" },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/src/cache.ts

@@ -0,0 +1,44 @@
+export interface CacheEntry<T> {
+  value: T
+  expiresAt: number
+}
+
+export interface SocialCache {
+  store: any
+  get<T>(key: string): T | null
+  set<T>(key: string, value: T, ttlMs: number): void
+  delete(key: string): void
+}
+
+let cache: SocialCache = {
+  store: new Map<string, CacheEntry<any>>(),
+
+  get<T>(key: string): T | null {
+    const entry = this.store.get(key)
+    if (!entry) return null
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key)
+      return null
+    }
+    return entry.value
+  },
+
+  set<T>(key: string, value: T, ttlMs: number) {
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + ttlMs
+    })
+  },
+
+  delete(key: string) {
+    this.store.delete(key)
+  }
+}
+
+export function setSocialCache(customCache: SocialCache) {
+  cache = customCache
+}
+
+export function getSocialCache() {
+  return cache
+}

package/src/config.ts

@@ -1,27 +1,18 @@
-
 export interface SocialConfig {
-  providers: {
-    google?: boolean
-    github?: boolean
-    facebook?: boolean
-    twitter?: boolean
-    apple?: boolean
-    [key: string]: any
-  }
-  redirectUrl?: string
+  provider: string
+  baseUrl?: string
+  apiKey?: string
+  [key: string]: any
 }
 
 let config: SocialConfig = {
-  providers: {},
-  redirectUrl: ''
+  provider: 'atproto',
+  baseUrl: '',
+  apiKey: ''
 }
 
 export function setSocialConfig(newConfig: Partial<SocialConfig>) {
-  config = {
-    ...config,
-    providers: { ...config.providers, ...(newConfig.providers || {}) },
-    redirectUrl: newConfig.redirectUrl ?? config.redirectUrl
-  }
+  config = { ...config, ...newConfig }
 }
 
 export function getSocialConfig(): SocialConfig {

package/src/errors.ts

@@ -0,0 +1,16 @@
+export class SocialError extends Error {
+  constructor(message: string, public provider?: string, public cause?: any) {
+    super(message)
+    this.name = 'SocialError'
+  }
+}
+
+export class RateLimitError extends SocialError {
+  retryAfter?: number
+
+  constructor(message: string, provider?: string, retryAfter?: number, cause?: any) {
+    super(message, provider, cause)
+    this.name = 'RateLimitError'
+    this.retryAfter = retryAfter
+  }
+}

package/src/metrics.ts

@@ -0,0 +1,52 @@
+export interface SocialMetrics {
+  requests: number
+  successes: number
+  failures: number
+  cacheHits: number
+  cacheMisses: number
+  backgroundRefreshes: number
+}
+
+const metrics = new Map<string, SocialMetrics>()
+
+function getProviderMetrics(provider: string): SocialMetrics {
+  if (!metrics.has(provider)) {
+    metrics.set(provider, {
+      requests: 0,
+      successes: 0,
+      failures: 0,
+      cacheHits: 0,
+      cacheMisses: 0,
+      backgroundRefreshes: 0
+    })
+  }
+  return metrics.get(provider)!
+}
+
+export function recordRequest(provider: string) {
+  getProviderMetrics(provider).requests++
+}
+
+export function recordSuccess(provider: string) {
+  getProviderMetrics(provider).successes++
+}
+
+export function recordFailure(provider: string) {
+  getProviderMetrics(provider).failures++
+}
+
+export function recordCacheHit(provider: string) {
+  getProviderMetrics(provider).cacheHits++
+}
+
+export function recordCacheMiss(provider: string) {
+  getProviderMetrics(provider).cacheMisses++
+}
+
+export function recordBackgroundRefresh(provider: string) {
+  getProviderMetrics(provider).backgroundRefreshes++
+}
+
+export function getMetrics(provider: string) {
+  return getProviderMetrics(provider)
+}

package/src/providers/atproto.ts

@@ -0,0 +1,75 @@
+import { wrapSocialRequest } from '../utils'
+import { getSocialConfig } from '../config'
+import { registerSocialProvider } from '../registry'
+
+async function atprotoFetch(path: string, options: RequestInit = {}) {
+  const { baseUrl, apiKey } = getSocialConfig()
+  const res = await fetch(`${baseUrl}${path}`, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+      ...(options.headers || {})
+    }
+  })
+
+  if (!res.ok) {
+    const error: any = new Error(`ATProto error: ${res.status}`)
+    error.status = res.status
+    error.response = res
+    throw error
+  }
+
+  return res.json()
+}
+
+const AtprotoProvider = {
+  async getProfile(handle: string) {
+    return wrapSocialRequest(
+      'atproto',
+      async () => {
+        const data = await atprotoFetch(`/xrpc/app.bsky.actor.getProfile?actor=${handle}`)
+        return {
+          id: data.did,
+          username: data.handle,
+          displayName: data.displayName,
+          avatarUrl: data.avatar,
+          url: `https://bsky.app/profile/${data.handle}`
+        }
+      },
+      {
+        cacheKey: `atproto:profile:${handle}`,
+        ttlMs: 1000 * 60 * 5, // 5 minutes
+        retry: true
+      }
+    )
+  },
+
+  async listPosts(handle: string) {
+    return wrapSocialRequest(
+      'atproto',
+      async () => {
+        const data = await atprotoFetch(`/xrpc/app.bsky.feed.getAuthorFeed?actor=${handle}`)
+        return (data.feed || []).map((item: any) => ({
+          id: item.post.uri,
+          content: item.post.record?.text,
+          createdAt: item.post.record?.createdAt,
+          author: {
+            id: item.post.author.did,
+            username: item.post.author.handle,
+            displayName: item.post.author.displayName,
+            avatarUrl: item.post.author.avatar
+          },
+          url: `https://bsky.app/profile/${item.post.author.handle}/post/${item.post.uri}`
+        }))
+      },
+      {
+        cacheKey: `atproto:posts:${handle}`,
+        ttlMs: 1000 * 30, // 30 seconds
+        retry: true
+      }
+    )
+  }
+}
+
+registerSocialProvider('atproto', AtprotoProvider)

package/src/providers/mastodon.ts

@@ -0,0 +1,45 @@
+// src/providers/mastodon.ts
+import type { SocialProvider, SocialProfile, SocialPost } from '../types'
+import { registerSocialProvider } from '../registry'
+import { getSocialConfig } from '../config'
+
+async function mastodonFetch(path: string, options: RequestInit = {}) {
+  const { baseUrl, apiKey } = getSocialConfig()
+  const res = await fetch(`${baseUrl}${path}`, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+      ...(options.headers || {})
+    }
+  })
+  if (!res.ok) throw new Error(`Mastodon error: ${res.status}`)
+  return res.json()
+}
+
+const MastodonProvider: SocialProvider = {
+  async getProfile(handle: string): Promise<SocialProfile> {
+    const data = await mastodonFetch(`/api/v1/accounts/lookup?acct=${handle}`)
+    return {
+      id: data.id,
+      username: data.acct,
+      displayName: data.display_name,
+      avatarUrl: data.avatar,
+      url: data.url
+    }
+  },
+
+  async listPosts(handle: string): Promise<SocialPost[]> {
+    const profile = await this.getProfile(handle)
+    const data = await mastodonFetch(`/api/v1/accounts/${profile.id}/statuses`)
+    return data.map((status: any) => ({
+      id: status.id,
+      content: status.content,
+      createdAt: status.created_at,
+      author: profile,
+      url: status.url
+    }))
+  }
+}
+
+registerSocialProvider('mastodon', MastodonProvider)

package/src/rateLimit.ts

@@ -0,0 +1,41 @@
+import { RateLimitError } from "./errors";
+
+export interface RateLimitConfig {
+  maxRequests: number
+  windowMs: number
+}
+
+const providerLimits = new Map<string, RateLimitConfig>()
+const providerUsage = new Map<string, { count: number; resetAt: number }>()
+
+export function setRateLimit(provider: string, config: RateLimitConfig) {
+  providerLimits.set(provider, config)
+}
+
+export function checkRateLimit(provider: string) {
+  const limit = providerLimits.get(provider)
+  if (!limit) return
+
+  const now = Date.now()
+  const usage = providerUsage.get(provider) || {
+    count: 0,
+    resetAt: now + limit.windowMs
+  }
+
+  if (now > usage.resetAt) {
+    usage.count = 0
+    usage.resetAt = now + limit.windowMs
+  }
+
+  usage.count++
+
+  providerUsage.set(provider, usage)
+
+  if (usage.count > limit.maxRequests) {
+    throw new RateLimitError(
+      `Meeovi internal rate limit exceeded for provider "${provider}"`,
+      provider,
+      Math.ceil((usage.resetAt - now) / 1000)
+    )
+  }
+}

package/src/registry.ts

@@ -0,0 +1,13 @@
+import type { SocialProvider } from './types'
+
+const providers: Record<string, SocialProvider> = {}
+
+export function registerSocialProvider(name: string, provider: SocialProvider) {
+  providers[name] = provider
+}
+
+export function getSocialProvider(name: string): SocialProvider {
+  const provider = providers[name]
+  if (!provider) throw new Error(`Social provider "${name}" not found`)
+  return provider
+}

package/src/retry.ts

@@ -0,0 +1,40 @@
+export interface RetryOptions {
+  retries: number
+  baseDelayMs: number
+  maxDelayMs: number
+}
+
+const defaultRetry: RetryOptions = {
+  retries: 3,
+  baseDelayMs: 300,
+  maxDelayMs: 5000
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  opts: Partial<RetryOptions> = {}
+): Promise<T> {
+  const { retries, baseDelayMs, maxDelayMs } = { ...defaultRetry, ...opts }
+
+  let attempt = 0
+
+  while (true) {
+    try {
+      return await fn()
+    } catch (err: any) {
+      attempt++
+      if (attempt > retries) throw err
+
+      const delay = Math.min(
+        baseDelayMs * Math.pow(2, attempt) + Math.random() * 100,
+        maxDelayMs
+      )
+
+      await sleep(delay)
+    }
+  }
+}

package/src/swr.ts

@@ -0,0 +1,22 @@
+import { getSocialCache } from './cache'
+
+const refreshQueue = new Map<string, Promise<any>>()
+
+export function scheduleBackgroundRefresh(
+  key: string,
+  fn: () => Promise<any>,
+  ttlMs: number
+) {
+  if (refreshQueue.has(key)) return
+
+  const promise = fn()
+    .then((fresh) => {
+      const cache = getSocialCache()
+      cache.set(key, fresh, ttlMs)
+    })
+    .finally(() => {
+      refreshQueue.delete(key)
+    })
+
+  refreshQueue.set(key, promise)
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+export interface SocialProfile {
+  id: string
+  username: string
+  displayName?: string
+  avatarUrl?: string
+  url?: string
+  [key: string]: any
+}
+
+export interface SocialPost {
+  id: string
+  content: string
+  createdAt: string
+  author: SocialProfile
+  url?: string
+  [key: string]: any
+}
+
+export interface SocialActivity extends SocialPost {
+  provider: string
+  source?: string
+}
+
+export interface SocialProvider {
+  getProfile(handle: string): Promise<SocialProfile>
+  listPosts(handle: string, options?: Record<string, any>): Promise<SocialPost[]>
+  createPost?(content: string, options?: Record<string, any>): Promise<SocialPost>
+}

package/src/useSocial.ts

@@ -0,0 +1,25 @@
+import { getSocialConfig } from './config'
+import { getSocialProvider } from './registry'
+import type { SocialActivity } from './types'
+
+export function useSocial() {
+  const { provider } = getSocialConfig()
+  const socialProvider = getSocialProvider(provider)
+
+  async function getActivityFeed(handle: string, options?: Record<string, any>): Promise<SocialActivity[]> {
+    const posts = await socialProvider.listPosts(handle, options)
+
+    return posts.map((post) => ({
+      ...post,
+      provider,
+      source: provider
+    }))
+  }
+
+  return {
+    getProfile: socialProvider.getProfile,
+    listPosts: socialProvider.listPosts,
+    createPost: socialProvider.createPost,
+    getActivityFeed
+  }
+}

package/src/utils.ts

@@ -0,0 +1,99 @@
+// utils.ts
+
+import { RateLimitError, SocialError } from './errors'
+import { getSocialCache } from './cache'
+import { withRetry } from './retry'
+import { scheduleBackgroundRefresh } from './swr'
+import { checkRateLimit } from './rateLimit'
+import {
+  recordRequest,
+  recordSuccess,
+  recordFailure,
+  recordCacheHit,
+  recordCacheMiss
+} from './metrics'
+
+export interface RequestOptions {
+  cacheKey?: string
+  ttlMs?: number
+  retry?: boolean
+  swr?: boolean
+}
+
+/**
+ * Core wrapper for all provider requests.
+ * Handles:
+ * - caching
+ * - SWR background refresh
+ * - retry/backoff
+ * - provider-specific rate limits
+ * - unified error handling
+ * - analytics hooks
+ */
+export async function wrapSocialRequest<T>(
+  provider: string,
+  fn: () => Promise<T>,
+  opts: RequestOptions = {}
+): Promise<T> {
+  const cache = getSocialCache()
+
+  // Track request attempt
+  recordRequest(provider)
+
+  // Provider-specific rate limit enforcement
+  checkRateLimit(provider)
+
+  // 1. Cache check
+  if (opts.cacheKey) {
+    const cached = cache.get<T>(opts.cacheKey)
+
+    if (cached) {
+      recordCacheHit(provider)
+
+      // SWR: return cached immediately, refresh in background
+      if (opts.swr && opts.ttlMs) {
+        scheduleBackgroundRefresh(opts.cacheKey, fn, opts.ttlMs)
+      }
+
+      return cached
+    }
+
+    recordCacheMiss(provider)
+  }
+
+  // 2. Execute request (with optional retry/backoff)
+  let result: T
+
+  try {
+    result = await (opts.retry ? withRetry(fn) : fn())
+    recordSuccess(provider)
+  } catch (err: any) {
+    recordFailure(provider)
+
+    const status = err?.status || err?.response?.status
+    const retryAfterHeader = err?.response?.headers?.['retry-after']
+    const retryAfter = retryAfterHeader ? Number(retryAfterHeader) : undefined
+
+    if (status === 429) {
+      throw new RateLimitError(
+        `Rate limit exceeded for provider "${provider}"`,
+        provider,
+        retryAfter,
+        err
+      )
+    }
+
+    throw new SocialError(
+      `Social provider "${provider}" request failed`,
+      provider,
+      err
+    )
+  }
+
+  // 3. Cache fresh result
+  if (opts.cacheKey && opts.ttlMs) {
+    cache.set(opts.cacheKey, result, opts.ttlMs)
+  }
+
+  return result
+}