npm package: @spatio/platform-sdk
Description: Spatio Platform SDK - Runtime SDK for building custom platforms
Author: Spatio Labs
Latest version: 0.1.0

# @spatio/platform-sdk

Runtime SDK for building custom platforms that run inside Spatio.

## Installation

```bash
npm install @spatio/platform-sdk
# or
pnpm add @spatio/platform-sdk
# or
yarn add @spatio/platform-sdk
```

## Quick Start

```typescript
import { useWorkspace, useSpatioAPI, useNavigation } from '@spatio/platform-sdk'

export default function MyPlatform() {
  // Access workspace data
  const { workspace, user, organization } = useWorkspace()

  // Call Spatio APIs
  const api = useSpatioAPI()

  // Navigate between platforms
  const { goToPlatform, goBack } = useNavigation()

  return (
    <div>
      <h1>Welcome to {workspace.name}</h1>
      <p>User: {user.email}</p>

      <button onClick={() => goToPlatform('tasks')}>
        Go to Tasks
      </button>
    </div>
  )
}
```

## Hooks

### `useWorkspace()`

Access current workspace, organization, and user data.

```typescript
const { workspace, organization, user, hasPermission } = useWorkspace()
```

### `useSpatioAPI()`

Make authenticated API calls to Spatio backend.

```typescript
const api = useSpatioAPI()

// GET request
const data = await api.get('/api/endpoint')

// POST request
await api.post('/api/endpoint', { data })
```

### `useProviders()`

Access connected providers (Gmail, Salesforce, etc.)

```typescript
const providers = useProviders()

// List all providers
const allProviders = await providers.list()

// Execute provider action
await providers.execute('gmail', 'send_email', {
  to: 'user@example.com',
  subject: 'Hello',
  body: 'World'
})
```

### `useNavigation()`

Navigate between platforms and pages.

```typescript
const { goToPlatform, goBack, currentPath } = useNavigation()

// Navigate to another platform
goToPlatform('calendar')

// Navigate with path
goToPlatform('tasks', '/list/urgent')

// Go back
goBack()
```

### `useShellState()`

Control shell UI state (sidebar, fullscreen, etc.)

```typescript
const { sidebarOpen, toggleSidebar, setFullScreenMode } = useShellState()

// Toggle sidebar
toggleSidebar()

// Enable fullscreen
setFullScreenMode(true)
```

### `useSidebar()`

Convenient sidebar control.

```typescript
const { isOpen, toggle, open, close } = useSidebar()
```

### `useFullScreen()`

Convenient fullscreen control.

```typescript
const { isFullScreen, enable, disable, toggle } = useFullScreen()
```

### `useEvents()`

Inter-platform event communication.

```typescript
const events = useEvents()

// Listen for events
events.on('task:created', (task) => {
  console.log('New task:', task)
})

// Emit events
events.emit('task:completed', { id: '123' })
```

### `useEventListener()`

Subscribe to events with automatic cleanup.

```typescript
useEventListener('task:created', (task) => {
  // Handle event
})
```

### `useStorage()`

Persistent storage for platform data.

```typescript
const { value, setValue, remove, loading } = useStorage('myKey', {
  defaultValue: { count: 0 }
})

// Update value
await setValue({ count: value.count + 1 })

// Remove value
await remove()
```

## TypeScript

The SDK is fully typed. Import types directly:

```typescript
import type {
  PlatformManifest,
  User,
  Workspace,
  Organization,
  Provider
} from '@spatio/platform-sdk'
```

## Platform Manifest

Every platform needs a `platform.config.json` manifest:

```json
{
  "id": "my-platform",
  "name": "My Platform",
  "version": "1.0.0",
  "description": "My custom platform",
  "icon": "🚀",
  "bundleUrl": "https://cdn.spatio.app/platforms/my-platform/1.0.0/bundle.js",
  "permissions": [
    "read:workspace",
    "read:user",
    "write:storage"
  ],
  "dependencies": {
    "providers": [
      {
        "id": "gmail",
        "required": true
      }
    ]
  }
}
```

## Development

The shell app provides the `PlatformProvider` context. Platforms consume it via hooks.

```typescript
// Shell app wraps platform with provider
<PlatformProvider value={platformContext}>
  <YourPlatform />
</PlatformProvider>
```

## API Reference

For full API documentation, visit: https://docs.spatio.app/platform-sdk

## Examples

See example platforms at: https://github.com/spatiolabs/platform-examples

## Support

- Documentation: https://docs.spatio.app
- Discord: https://discord.gg/spatio
- Issues: https://github.com/spatiolabs/spatio/issues

## License

MIT