mumin-api-monorepo 1.0.0

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/README.md

@@ -0,0 +1,206 @@
+# 🕌 Mumin API SDK
+
+The official, production-ready TypeScript SDK for the **Mumin Hadith API**.  
+Build Islamic applications with confidence using our fully typed, cached, and robust client libraries.
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![TypeScript](https://img.shields.io/badge/language-TypeScript-3178C6.svg)
+![Version](https://img.shields.io/badge/version-1.0.0-green)
+
+---
+
+## ✨ Features
+
+- **🛡️ Type Safety**: Full TypeScript support. No more guessing properties — getting `hadith.translation.text` is fully typed.
+- **🧠 Intelligent Caching**: Built-in `MemoryCache` stores responses to reduce API calls and latency.
+- **🔁 Auto-Retry**: Network glitches? The SDK automatically retries failed requests with exponential backoff.
+- **📦 Monorepo Architecture**: Modular packages for **Core** (Node.js/JS), **React** hooks, and **Vue** composables.
+- **⚡ Lightweight**: Zero-dependency core (uses native `fetch`).
+
+---
+
+## 📦 Installation
+
+We provide separate packages depending on your framework:
+
+### Core (Node.js / Vanilla JS / Next.js API)
+
+```bash
+npm install @mumin/core
+```
+
+### React
+
+```bash
+npm install @mumin/react @mumin/core
+```
+
+### Vue 3
+
+```bash
+npm install @mumin/vue @mumin/core
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Vanilla JS / Node.js
+
+Perfect for server-side code or simple scripts.
+
+```typescript
+import { MuminClient } from "@mumin/core";
+
+const client = new MuminClient("YOUR_API_KEY");
+
+async function main() {
+  // Get a random hadith from Sahih al-Bukhari
+  const random = await client.hadiths.random({ collection: "sahih-bukhari" });
+
+  console.log("Hadith #", random.hadithNumber);
+  console.log("Text:", random.translation?.text || random.arabicText);
+
+  // Search for hadiths
+  const results = await client.search.query("prayer", { limit: 5 });
+  console.log("Found:", results.data.length);
+}
+
+main();
+```
+
+### 2. React
+
+Use our dedicated hooks for easy data fetching.
+
+**App.tsx**
+
+```tsx
+import { MuminProvider } from "@mumin/react";
+
+function App() {
+  return (
+    <MuminProvider apiKey="YOUR_API_KEY">
+      <HadithCard />
+    </MuminProvider>
+  );
+}
+```
+
+**HadithCard.tsx**
+
+```tsx
+import { useHadith } from "@mumin/react";
+
+export function HadithCard() {
+  // Fetch Hadith #1 from Sahih Muslim
+  const { data, loading, error } = useHadith(1, { lang: "en" });
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div className="card">
+      <h3>
+        {data?.collection?.name} - #{data?.hadithNumber}
+      </h3>
+      <p>{data?.translation?.text}</p>
+    </div>
+  );
+}
+```
+
+### 3. Vue 3
+
+Reactive composables for your Vue apps.
+
+**main.ts**
+
+```typescript
+import { createApp } from "vue";
+import { MuminPlugin } from "@mumin/vue";
+import App from "./App.vue";
+
+const app = createApp(App);
+app.use(MuminPlugin, { apiKey: "YOUR_API_KEY" });
+app.mount("#app");
+```
+
+**HadithView.vue**
+
+```vue
+<script setup>
+import { useHadith } from "@mumin/vue";
+
+const { data, loading } = useHadith(1);
+</script>
+
+<template>
+  <div v-if="loading">Loading...</div>
+  <div v-else>
+    {{ data?.translation?.text }}
+  </div>
+</template>
+```
+
+---
+
+## 🛠️ Configuration
+
+The `MuminClient` is highly configurable:
+
+```typescript
+const client = new MuminClient("API_KEY", {
+  baseURL: "https://api.hadith.mumin.ink/v1", // Custom API URL
+  timeout: 5000, // 5s timeout
+  retries: 3, // Retry 3 times on fail
+  retryDelay: 1000, // Wait 1s between retries
+  cache: new RedisCache(), // Implement your own cache if needed!
+});
+```
+
+---
+
+## 📚 Resources API
+
+### `client.hadiths`
+
+- `.get(id)` - Get a single hadith by global ID.
+- `.random(filters)` - Get a random hadith (filter by book, collection, grade).
+- `.daily()` - Get the "Hadith of the Day".
+- `.list(filters)` - Paginated list of hadiths.
+
+### `client.collections`
+
+- `.list()` - Get all available collections.
+- `.get(slug)` - Get details about a collection (e.g., `sahih-bukhari`).
+
+### `client.search`
+
+- `.query(q, filters)` - Full-text search across translations and Arabic text.
+
+---
+
+## 🚨 Error Handling
+
+The SDK throws typed error classes for better handling:
+
+```typescript
+import { AuthenticationError, RateLimitError } from "@mumin/core";
+
+try {
+  await client.hadiths.get(1);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // Redirect to login or refresh token
+  } else if (error instanceof RateLimitError) {
+    // Wait a bit!
+  }
+}
+```
+
+---
+
+## ⚖️ License
+
+MIT © Mumin Team

package/examples/basic/index.ts

@@ -0,0 +1,35 @@
+import { MuminClient } from '@mumin/core'
+
+async function main() {
+  console.log('🚀 Initializing MuminClient...')
+  
+  // NOTE: This demo key is just for testing structure, obviously for real requests we need a real key
+  // But likely the user will replace it or we use a dummy one if we just want to test compilation
+  const client = new MuminClient('sk_mumin_test_key_1234567890abcdef12345678')
+
+  try {
+    console.log('📚 Fetching Collections...')
+    const collections = await client.collections.list()
+    console.log('RAW COLLECTIONS:', JSON.stringify(collections, null, 2))
+    
+    // Check if it's wrapped in 'data'
+    const list = Array.isArray(collections) ? collections : (collections as any).data || []
+    console.log(`✅ Found ${list?.length} collections`)
+
+    console.log('\n🎲 Fetching Random Hadith...')
+    const random = await client.hadiths.random()
+    console.log('✅ Random Hadith:', random.hadithNumber)
+    
+    // Handle text structure
+    const text = random.translation?.text || random.arabicText || 'No text found'
+    console.log('Text:', text.substring(0, 50) + '...')
+    
+  } catch (error: any) {
+    console.error('❌ Error full details:', JSON.stringify(error, null, 2))
+    if (error.response) {
+         console.error('Response data:', await error.response.json())
+    }
+  }
+}
+
+main()

package/examples/basic/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "example-basic",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "ts-node index.ts"
+  },
+  "dependencies": {
+    "@mumin/core": "*",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "mumin-api-monorepo",
+  "version": "1.0.0",
+  "private": false,
+  "workspaces": [
+    "packages/*",
+    "examples/*"
+  ],
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev --parallel",
+    "test": "turbo run test",
+    "lint": "turbo run lint",
+    "type-check": "turbo run type-check",
+    "publish": "turbo run build && changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.1",
+    "turbo": "^1.11.3",
+    "typescript": "^5.3.3"
+  }
+}

package/packages/core/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @mumin/core
+
+## 2.0.0
+
+### Major Changes
+
+- initial release

package/packages/core/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@mumin-api/core",
+  "version": "2.0.0",
+  "description": "Official SDK for Mumin Hadith API",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
+  },
+  "keywords": [
+    "hadith",
+    "islamic",
+    "api",
+    "sdk",
+    "mumin"
+  ],
+  "author": "Mumin Development Team",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.11.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0",
+    "eslint": "^8.56.0"
+  }
+}

package/packages/core/src/cache/memory.ts

@@ -0,0 +1,63 @@
+import { CacheAdapter } from '../types'
+
+interface CacheEntry<T> {
+  value: T
+  expiresAt: number
+}
+
+export class MemoryCache implements CacheAdapter {
+  private store = new Map<string, CacheEntry<any>>()
+  private cleanupInterval: NodeJS.Timeout | null = null
+
+  constructor(cleanupIntervalMs: number = 60000) {
+    // Start cleanup logic to avoid memory leaks
+    if (typeof setInterval !== 'undefined') {
+        this.cleanupInterval = setInterval(() => {
+          this.cleanup()
+        }, cleanupIntervalMs)
+    }
+  }
+
+  async get<T>(key: string): Promise<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 as T
+  }
+
+  async set<T>(key: string, value: T, ttl: number): Promise<void> {
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + ttl * 1000,
+    })
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key)
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear()
+  }
+
+  private cleanup(): void {
+    const now = Date.now()
+    for (const [key, entry] of this.store.entries()) {
+      if (now > entry.expiresAt) {
+        this.store.delete(key)
+      }
+    }
+  }
+
+  // Helper to stop interval if needed (e.g. tests)
+  dispose() {
+    if (this.cleanupInterval) {
+        clearInterval(this.cleanupInterval)
+    }
+  }
+}

package/packages/core/src/client.ts

@@ -0,0 +1,48 @@
+import { MuminConfig, CacheAdapter } from './types'
+import { HadithsResource } from './resources/hadiths'
+import { CollectionsResource } from './resources/collections'
+import { SearchResource } from './resources/search'
+import { HTTPClient } from './utils/http'
+import { MemoryCache } from './cache/memory'
+
+export class MuminClient {
+  private http: HTTPClient
+  private cache: CacheAdapter
+
+  // Resources
+  public readonly hadiths: HadithsResource
+  public readonly collections: CollectionsResource
+  public readonly search: SearchResource
+
+  constructor(apiKey: string, config?: Partial<MuminConfig>) {
+    if (!apiKey) {
+      throw new Error('API key is required. Get one at https://dashboard.mumin.ink')
+    }
+
+    const finalConfig: MuminConfig = {
+      apiKey,
+      baseURL: config?.baseURL || 'https://api.hadith.mumin.ink/v1',
+      timeout: config?.timeout || 10000,
+      retries: config?.retries || 2,
+      retryDelay: config?.retryDelay || 1000,
+      cache: config?.cache || new MemoryCache(),
+      ...config,
+    }
+
+    this.http = new HTTPClient(finalConfig)
+    this.cache = finalConfig.cache
+
+    this.hadiths = new HadithsResource(this.http, this.cache)
+    this.collections = new CollectionsResource(this.http, this.cache)
+    this.search = new SearchResource(this.http, this.cache)
+  }
+
+  /**
+   * Clear all internal caches
+   */
+  clearCache(): void {
+      this.cache.clear()
+  }
+}
+
+export default MuminClient

package/packages/core/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types'
+export * from './client'
+export * from './utils/errors'
+export { MemoryCache } from './cache/memory'

package/packages/core/src/resources/collections.ts

@@ -0,0 +1,29 @@
+import { HTTPClient } from '../utils/http'
+import { CacheAdapter, Collection } from '../types'
+
+export class CollectionsResource {
+  constructor(
+    private http: HTTPClient,
+    private cache: CacheAdapter
+  ) {}
+
+  async list(): Promise<Collection[]> {
+    const cacheKey = 'collections:all'
+    const cached = await this.cache.get<Collection[]>(cacheKey)
+    if (cached) return cached
+
+    const response = await this.http.get<Collection[]>('/collections')
+    await this.cache.set(cacheKey, response, 86400) // 24 hours
+    return response
+  }
+
+  async get(slug: string): Promise<Collection> {
+    const cacheKey = `collection:${slug}`
+    const cached = await this.cache.get<Collection>(cacheKey)
+    if (cached) return cached
+
+    const response = await this.http.get<Collection>(`/collections/${slug}`)
+    await this.cache.set(cacheKey, response, 86400)
+    return response
+  }
+}

package/packages/core/src/resources/hadiths.ts

@@ -0,0 +1,71 @@
+import { HTTPClient } from '../utils/http'
+import { CacheAdapter, Hadith, HadithQuery, PaginatedResponse } from '../types'
+
+export class HadithsResource {
+  constructor(
+    private http: HTTPClient,
+    private cache: CacheAdapter
+  ) {}
+
+  /**
+   * Get a single hadith by ID
+   */
+  async get(id: number, options?: { lang?: string }): Promise<Hadith> {
+    const cacheKey = `hadith:${id}:${options?.lang || 'default'}`
+    const cached = await this.cache.get<Hadith>(cacheKey)
+    if (cached) return cached
+
+    const response = await this.http.get<Hadith>(`/hadiths/${id}`, {
+      params: options as Record<string, string>
+    })
+
+    await this.cache.set(cacheKey, response, 3600) // 1 hour
+    return response
+  }
+
+  /**
+   * Get a random hadith
+   */
+  async random(options?: HadithQuery): Promise<Hadith> {
+    return this.http.get<Hadith>('/hadiths/random', {
+      params: options as Record<string, string | number | boolean | undefined>
+    })
+  }
+
+  /**
+   * Get the daily hadith
+   */
+  async daily(options?: { lang?: string }): Promise<Hadith> {
+     const cacheKey = `daily:${options?.lang || 'default'}`
+     const cached = await this.cache.get<Hadith>(cacheKey)
+     if (cached) return cached
+
+    const response = await this.http.get<Hadith>('/hadiths/daily', {
+      params: options as Record<string, string>
+    })
+    
+    // Cache until next day roughly, or just 1 hour
+    await this.cache.set(cacheKey, response, 3600) 
+    return response
+  }
+
+  /**
+   * List/Search hadiths
+   */
+  async list(options?: HadithQuery): Promise<PaginatedResponse<Hadith>> {
+    // If it's a search query, route to /search logic or handle here if supported
+    // The spec says 'list' hits /hadiths
+    return this.http.get<PaginatedResponse<Hadith>>('/hadiths', {
+      params: options as Record<string, string | number | boolean | undefined>
+    })
+  }
+
+  /**
+   * Search hadiths (Facade for search endpoint if separate)
+   */
+  async search(query: string, options?: HadithQuery): Promise<PaginatedResponse<Hadith>> {
+     return this.http.get<PaginatedResponse<Hadith>>('/hadiths/search', {
+        params: { q: query, ...options } as Record<string, string | number | boolean | undefined>
+     })
+  }
+}

package/packages/core/src/resources/search.ts

@@ -0,0 +1,22 @@
+import { HTTPClient } from '../utils/http'
+import { CacheAdapter, Hadith, PaginatedResponse, HadithQuery } from '../types'
+
+export class SearchResource {
+  constructor(
+    private http: HTTPClient,
+    private cache: CacheAdapter
+  ) {}
+
+  async query(q: string, options?: HadithQuery): Promise<PaginatedResponse<Hadith>> {
+    const cacheKey = `search:${q}:${JSON.stringify(options)}`
+    const cached = await this.cache.get<PaginatedResponse<Hadith>>(cacheKey)
+    if (cached) return cached
+
+    const response = await this.http.get<PaginatedResponse<Hadith>>('/hadiths/search', {
+      params: { q, ...options } as Record<string, string | number | boolean | undefined>
+    })
+    
+    await this.cache.set(cacheKey, response, 300) // 5 minutes
+    return response
+  }
+}

package/packages/core/src/types/index.ts

@@ -0,0 +1,110 @@
+
+// ============================================
+// CONFIGURATION
+// ============================================
+
+export interface MuminConfig {
+  apiKey: string
+  baseURL: string
+  timeout: number
+  retries: number
+  retryDelay: number
+  cache: CacheAdapter
+}
+
+// ============================================
+// CACHE
+// ============================================
+
+export interface CacheAdapter {
+  get<T>(key: string): Promise<T | null>
+  set<T>(key: string, value: T, ttl: number): Promise<void>
+  delete(key: string): Promise<void>
+  clear(): Promise<void>
+}
+
+// ============================================
+// HADITH
+// ============================================
+
+export interface Hadith {
+  id: number
+  collectionId: string
+  bookNumber: string | number
+  chapterId: string | number
+  hadithNumber: string
+  hadithNumberInt?: number
+  label?: string
+  
+  // Content variants
+  arabicText?: string
+  english?: string
+  russian?: string
+
+  // Translation object found in API response
+  translation?: {
+    id: number
+    text: string
+    languageCode: string
+    narrator?: string
+  }
+  
+  // Computed/Standardized fields (Removed flat 'text' as it is not in API)
+  // text: string // Removing this to avoid confusion as it's not in raw response
+}
+
+export interface HadithQuery {
+  lang?: string
+  collection?: string
+  book?: number
+  grade?: string
+  page?: number
+  limit?: number
+  q?: string // for search
+}
+
+// ============================================
+// COLLECTION
+// ============================================
+
+export interface Collection {
+  slug: string // 'sahih-bukhari'
+  name: string
+  totalHadiths: number
+  description?: string
+}
+
+export interface Book {
+  id: number | string
+  collectionSlug: string
+  bookNumber: string
+  title: string
+  hadithCount?: number
+}
+
+export interface Chapter {
+  id: number | string
+  bookId: number | string
+  chapterNumber: string
+  title: string
+}
+
+// ============================================
+// RESPONSE WRAPPERS
+// ============================================
+
+export interface PaginatedResponse<T> {
+  data: T[]
+  meta: {
+    total: number
+    page: number
+    limit: number
+    totalPages: number
+  }
+}
+
+// ============================================
+// ERROR CLASSES
+// ============================================
+
+export { MuminAPIError, AuthenticationError, RateLimitError } from '../utils/errors'

package/packages/core/src/utils/errors.ts

@@ -0,0 +1,41 @@
+export class MuminAPIError extends Error {
+  constructor(
+    message: string,
+    public statusCode: number,
+    public details?: any
+  ) {
+    super(message)
+    this.name = 'MuminAPIError'
+  }
+}
+
+export class AuthenticationError extends MuminAPIError {
+  constructor(message: string) {
+    super(message, 401)
+    this.name = 'AuthenticationError'
+  }
+}
+
+export class RateLimitError extends MuminAPIError {
+  constructor(
+    message: string,
+    public resetTime?: string | null
+  ) {
+    super(message, 429)
+    this.name = 'RateLimitError'
+  }
+}
+
+export class ValidationError extends MuminAPIError {
+  constructor(message: string, public errors: Record<string, string[]>) {
+    super(message, 400, errors)
+    this.name = 'ValidationError'
+  }
+}
+
+export class NotFoundError extends MuminAPIError {
+  constructor(message: string) {
+    super(message, 404)
+    this.name = 'NotFoundError'
+  }
+}

package/packages/core/src/utils/http.ts

@@ -0,0 +1,141 @@
+import { MuminConfig } from '../types'
+import { MuminAPIError, RateLimitError, AuthenticationError, NotFoundError } from './errors'
+
+interface RequestOptions {
+  params?: Record<string, string | number | boolean | undefined>
+  body?: any
+  headers?: HeadersInit
+}
+
+export class HTTPClient {
+  private baseURL: string
+  private apiKey: string
+  private timeout: number
+  private retries: number
+  private retryDelay: number
+
+  constructor(config: MuminConfig) {
+    this.baseURL = config.baseURL
+    this.apiKey = config.apiKey
+    this.timeout = config.timeout
+    this.retries = config.retries
+    this.retryDelay = config.retryDelay
+  }
+
+  async get<T>(path: string, options?: RequestOptions): Promise<T> {
+    return this.request<T>('GET', path, options)
+  }
+
+  async post<T>(path: string, body?: any, options?: RequestOptions): Promise<T> {
+    return this.request<T>('POST', path, { ...options, body })
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    options?: RequestOptions
+  ): Promise<T> {
+    // Ensure no double slashes if path starts with /
+    const cleanPath = path.startsWith('/') ? path : `/${path}`
+    const url = `${this.baseURL}${cleanPath}`
+    
+    // Filter out undefined params
+    const cleanParams: Record<string, string> = {}
+    if (options?.params) {
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          cleanParams[key] = String(value)
+        }
+      })
+    }
+
+    const queryString = Object.keys(cleanParams).length > 0
+      ? '?' + new URLSearchParams(cleanParams).toString()
+      : ''
+
+    const headers: HeadersInit = {
+      'Authorization': `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json',
+      'User-Agent': `mumin-api-sdk/1.0.0`,
+      'X-Mumin-SDK': '1.0.0', // Custom header to track usage
+      ...options?.headers,
+    }
+
+    let lastError: Error | null = null
+
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const controller = new AbortController()
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout)
+
+        const response = await fetch(url + queryString, {
+          method,
+          headers,
+          body: options?.body ? JSON.stringify(options.body) : undefined,
+          signal: controller.signal,
+        })
+
+        clearTimeout(timeoutId)
+
+        if (!response.ok) {
+          await this.handleErrorResponse(response)
+        }
+
+        // Handle 204 No Content
+        if (response.status === 204) {
+          return {} as T
+        }
+
+        const validResponse = await response.json()
+        // Automatically unwrap { success: true, data: ..., meta: ... } response wrapper
+        if (validResponse && typeof validResponse === 'object' && 'data' in validResponse) {
+            return (validResponse as any).data as T
+        }
+        return validResponse as T
+      } catch (error) {
+        lastError = error as Error
+
+        // Don't retry on 4xx errors (except 429)
+        if (error instanceof AuthenticationError || error instanceof NotFoundError) {
+          throw error
+        }
+        
+        // If it's a 429, we might want to respect retry-after, but for now we just treat it as non-retriable or use standard backoff
+        // (Implementation choice: usually we stop on 429 unless we have smart waiting logic)
+
+        // Wait before retry (exponential backoff)
+        if (attempt < this.retries) {
+          const delay = this.retryDelay * Math.pow(2, attempt)
+          await this.sleep(delay)
+        }
+      }
+    }
+
+    throw new MuminAPIError(
+      `Request failed after ${this.retries + 1} attempts: ${lastError?.message}`,
+      500
+    )
+  }
+
+  private async handleErrorResponse(response: Response): Promise<never> {
+    let errorData: any
+    try {
+      errorData = await response.json()
+    } catch {
+      errorData = { message: response.statusText }
+    }
+
+    const message = errorData.message || errorData.error || 'Unknown error'
+    const statusCode = response.status
+
+    if (statusCode === 401) throw new AuthenticationError(message)
+    if (statusCode === 404) throw new NotFoundError(message)
+    if (statusCode === 429) throw new RateLimitError(message)
+
+    throw new MuminAPIError(message, statusCode, errorData)
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}

package/packages/react/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @mumin/react
+
+## 2.0.0
+
+### Major Changes
+
+- initial release
+
+### Patch Changes
+
+- Updated dependencies
+  - @mumin/core@2.0.0

package/packages/react/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mumin-api/react",
+  "version": "2.0.0",
+  "description": "React hooks for Mumin Hadith API",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --external react",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --external react --watch",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0"
+  },
+  "dependencies": {
+    "@mumin-api/core": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.48",
+    "react": "^18.2.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3"
+  }
+}

package/packages/react/src/hooks/useHadith.ts

@@ -0,0 +1,43 @@
+import { useState, useEffect } from 'react'
+import { useMuminClient } from '../provider'
+import { Hadith, HadithQuery } from '@mumin/core'
+
+export interface UseHadithResult {
+  data: Hadith | null
+  loading: boolean
+  error: Error | null
+  refetch: () => Promise<void>
+}
+
+export function useHadith(
+  id: number | null, // null allowed to defer fetching
+  options?: { lang?: string, enabled?: boolean }
+): UseHadithResult {
+  const client = useMuminClient()
+  const [data, setData] = useState<Hadith | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+
+  const fetchHadith = async () => {
+    if (id === null) return
+    
+    setLoading(true)
+    setError(null)
+    try {
+      const result = await client.hadiths.get(id, { lang: options?.lang })
+      setData(result)
+    } catch (err: any) {
+      setError(err)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    if (options?.enabled !== false && id !== null) {
+      fetchHadith()
+    }
+  }, [id, options?.lang, options?.enabled])
+
+  return { data, loading, error, refetch: fetchHadith }
+}

package/packages/react/src/index.ts

@@ -0,0 +1,2 @@
+export * from './provider'
+export * from './hooks/useHadith'

package/packages/react/src/provider.tsx

@@ -0,0 +1,34 @@
+import React, { createContext, useContext, useMemo } from 'react'
+import { MuminClient, MuminConfig } from '@mumin/core'
+
+interface MuminContextValue {
+  client: MuminClient
+}
+
+const MuminContext = createContext<MuminContextValue | null>(null)
+
+export interface MuminProviderProps {
+  apiKey: string
+  config?: Partial<MuminConfig>
+  children: React.ReactNode
+}
+
+export function MuminProvider({ apiKey, config, children }: MuminProviderProps) {
+  const client = useMemo(() => {
+    return new MuminClient(apiKey, config)
+  }, [apiKey, config])
+
+  return (
+    <MuminContext.Provider value={{ client }}>
+      {children}
+    </MuminContext.Provider>
+  )
+}
+
+export function useMuminClient(): MuminClient {
+  const context = useContext(MuminContext)
+  if (!context) {
+    throw new Error('useMuminClient must be used within MuminProvider')
+  }
+  return context.client
+}

package/packages/react/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "jsx": "react-jsx",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}

package/packages/vue/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @mumin/vue
+
+## 2.0.0
+
+### Major Changes
+
+- initial release
+
+### Patch Changes
+
+- Updated dependencies
+  - @mumin/core@2.0.0

package/packages/vue/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mumin-api/vue",
+  "version": "2.0.0",
+  "description": "Vue 3 composables for Mumin Hadith API",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --external vue",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --external vue --watch",
+    "test": "vitest run",
+    "type-check": "vue-tsc --noEmit"
+  },
+  "peerDependencies": {
+    "vue": "^3.0.0"
+  },
+  "dependencies": {
+    "@mumin-api/core": "*"
+  },
+  "devDependencies": {
+    "vue": "^3.4.0",
+    "typescript": "^5.3.3",
+    "tsup": "^8.0.1",
+    "vue-tsc": "^1.8.27"
+  }
+}

package/packages/vue/src/composables/useHadith.ts

@@ -0,0 +1,46 @@
+import { ref, watchEffect, Ref, unref } from 'vue'
+import { useMuminClient } from '../plugin'
+import { Hadith } from '@mumin/core'
+
+export interface UseHadithOptions {
+  lang?: string
+  enabled?: Ref<boolean> | boolean
+}
+
+export function useHadith(
+  id: Ref<number | null> | number | null,
+  options?: UseHadithOptions
+) {
+  const client = useMuminClient()
+  const data = ref<Hadith | null>(null)
+  const loading = ref(false)
+  const error = ref<Error | null>(null)
+
+  const fetchHadith = async () => {
+    const hadithId = unref(id)
+    if (hadithId === null) return
+
+    loading.value = true
+    error.value = null
+    
+    try {
+      const result = await client.hadiths.get(hadithId, { lang: options?.lang })
+      data.value = result
+    } catch (err: any) {
+      error.value = err
+    } finally {
+      loading.value = false
+    }
+  }
+
+  watchEffect(() => {
+    const isEnabled = unref(options?.enabled) ?? true
+    const hadithId = unref(id)
+    
+    if (isEnabled && hadithId !== null) {
+      fetchHadith()
+    }
+  })
+
+  return { data, loading, error, refetch: fetchHadith }
+}

package/packages/vue/src/index.ts

@@ -0,0 +1,2 @@
+export * from './plugin'
+export * from './composables/useHadith'

package/packages/vue/src/plugin.ts

@@ -0,0 +1,24 @@
+import { inject, App, InjectionKey } from 'vue'
+import { MuminClient, MuminConfig } from '@mumin/core'
+
+export const MuminClientKey: InjectionKey<MuminClient> = Symbol('MuminClient')
+
+export interface MuminPluginOptions {
+  apiKey: string
+  config?: Partial<MuminConfig>
+}
+
+export const MuminPlugin = {
+  install(app: App, options: MuminPluginOptions) {
+    const client = new MuminClient(options.apiKey, options.config)
+    app.provide(MuminClientKey, client)
+  }
+}
+
+export function useMuminClient(): MuminClient {
+  const client = inject(MuminClientKey)
+  if (!client) {
+    throw new Error('MuminPlugin not installed')
+  }
+  return client
+}

package/packages/vue/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}

package/turbo.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "pipeline": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "test": {
+      "dependsOn": ["build"],
+      "outputs": [],
+      "inputs": ["src/**/*.ts", "test/**/*.ts"]
+    },
+    "lint": {
+      "outputs": []
+    },
+    "type-check": {
+      "outputs": []
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}