npm package: @lemonhub/sdk
Description: A modern, modular SDK for building application hub platforms with Vue 3
Author: LemonHub Team
Latest version: 0.1.0

# LemonHub SDK

[![npm version](https://img.shields.io/npm/v/@lemonhub/sdk.svg)](https://www.npmjs.com/package/@lemonhub/sdk)
[![license](https://img.shields.io/npm/l/@lemonhub/sdk.svg)](https://github.com/lemonhub/lemon-hub/blob/main/LICENSE)
[![typescript](https://img.shields.io/npm/types/@lemonhub/sdk.svg)](https://www.typescriptlang.org)

A modern, modular SDK for building application hub platforms with Vue 3. Provides unified APIs for app registration, theming, navigation, events, notifications, and storage.

## Features

- **App Registry** - Register, query, and manage applications with lifecycle callbacks
- **Theme System** - Light/dark/auto mode with custom color support and system theme watching
- **Navigation** - Vue Router wrapper with typed route management
- **Event System** - Type-safe pub/sub with built-in SDK events
- **Notifications** - Toast notification system with multiple types and auto-dismiss
- **Storage** - Namespaced, typed localStorage with TTL/expiration support
- **TypeScript First** - Full type coverage, zero `any` in public APIs
- **Tree-shakeable** - All modules are side-effect free
- **SSR Safe** - Browser-only APIs are guarded for server-side rendering

## Installation

```bash
npm install @lemonhub/sdk
```

### Peer Dependencies

```bash
npm install vue@^3.3.0
# Optional - for navigation support
npm install vue-router@^4.0.0
```

## Quick Start

```typescript
import { LemonHub } from '@lemonhub/sdk'

// Create the SDK
const sdk = LemonHub.create({
  debug: true,
  defaultTheme: 'auto',
})

// Initialize (optionally pass vue-router)
import router from './router'
await sdk.init(router)
```

### In Vue Components

```vue
<script setup lang="ts">
import { inject } from 'vue'
import type { LemonHub } from '@lemonhub/sdk'

const sdk = inject<LemonHub>('sdk')!

// Register an app
sdk.apps.register({
  id: 'my-app',
  name: 'My App',
  description: 'A great application',
  icon: 'my-icon',
  category: 'productivity',
  status: 'available',
  version: '1.0.0',
  author: 'Me',
  rating: 4.5,
  downloads: 0,
  tags: ['demo'],
  lastUpdated: '2026-04-06',
})

// Toggle theme
sdk.theme.toggle()

// Navigate
sdk.navigation.navigate('/library')

// Notify
sdk.notify.success('Hello from LemonHub!')
</script>
```

## API Overview

### App Registry

```typescript
sdk.apps.register(app, options?)
sdk.apps.unregister(id)
sdk.apps.get(id)
sdk.apps.getAll()
sdk.apps.search(query)
sdk.apps.filterAndSearch(query, category)
sdk.apps.launch(id)

// Lifecycle callbacks
sdk.apps.register(app, {
  onInstall: (app) => sdk.notify.success(`${app.name} installed`),
  onLaunch: (app) => sdk.navigation.navigate(`/apps/${app.id}`),
})
```

### Theme

```typescript
sdk.theme.setMode('dark')
sdk.theme.toggle()
sdk.theme.isDark()
sdk.theme.getColors()
sdk.theme.setColors({ primary: '#ff6b6b' })
sdk.theme.watchSystemTheme()
```

### Events

```typescript
sdk.onAppInstalled((app) => console.log(app.name))
sdk.onThemeChanged(({ mode, isDark }) => console.log(mode))
sdk.onNavigated(({ path }) => console.log(path))

// Custom events
sdk.emit('my-event', { data: 'value' })
sdk.on('my-event', handler)
```

### Notifications

```typescript
sdk.notify.info('Info message')
sdk.notify.success('Success!', 'Title')
sdk.notify.warning('Warning message')
sdk.notify.error('Error message')

sdk.notify.show({
  title: 'Update',
  message: 'New version available',
  options: { duration: 0, actionLabel: 'Update', onAction: () => {} }
})
```

### Storage

```typescript
sdk.storage.set('token', 'abc123', { namespace: 'user', expiresIn: 3600000 })
const token = sdk.storage.get<string>('token', { namespace: 'user' })
sdk.storage.has('token')
sdk.storage.remove('token')
sdk.storage.clear()
```

## Full Documentation

See [docs/SDK.md](https://github.com/lemonhub/lemon-hub/blob/main/docs/SDK.md) for the complete API reference with examples.

## Architecture

```
LemonHub
├── events      → EventBus (pub/sub)
├── apps        → AppRegistry (lifecycle)
├── theme       → ThemeManager (colors, mode)
├── navigation  → NavigationManager (vue-router wrapper)
├── notify      → NotificationManager (toasts)
└── storage     → StorageManager (namespaced localStorage)
```

## Browser Support

LemonHub SDK supports all modern browsers that support ES2020+. For SSR environments (Nuxt, etc.), browser-only APIs are safely guarded.

## License

[MIT](https://github.com/lemonhub/lemon-hub/blob/main/LICENSE)