@telemetryos/cli 1.7.4 → 1.8.0

package/templates/vite-react-typescript/_claude/skills/tos-media-api/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: tos-media-api
+description: Access TelemetryOS Media Library for images, videos, and files. Use when building apps that display user-uploaded media content.
+---
+
+# TelemetryOS Media API
+
+The Media API provides access to content uploaded to the TelemetryOS Media Library. Users manage their media through Studio and your app can display it.
+
+## Quick Reference
+
+```typescript
+import { media } from '@telemetryos/sdk'
+
+// Get all folders
+const folders = await media().getAllFolders()
+
+// Get content in a folder
+const content = await media().getAllByFolderId('folder-id')
+
+// Get content by tag
+const tagged = await media().getAllByTag('banner')
+
+// Get single item by ID
+const item = await media().getById('content-id')
+```
+
+## Response Types
+
+### MediaFolder
+
+```typescript
+interface MediaFolder {
+  id: string
+  parentId: string        // Parent folder ID (empty for root)
+  name: string            // Folder name
+  size: number            // Number of items
+  default: boolean        // Is this the default folder?
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+### MediaContent
+
+```typescript
+interface MediaContent {
+  id: string
+  contentFolderId: string // Parent folder
+  contentType: string     // MIME type (image/jpeg, video/mp4, etc.)
+  name: string            // File name
+  description: string     // User description
+  thumbnailUrl: string    // Thumbnail for preview
+  keys: string[]          // Storage keys
+  publicUrls: string[]    // CDN URLs for display
+  hidden: boolean         // Hidden from listings
+  validFrom?: Date        // Content scheduling
+  validTo?: Date          // Content scheduling
+  createdAt: Date
+  updatedAt: Date
+}
+```
+
+## Common Patterns
+
+### Folder Picker in Settings
+
+Let users select a folder, then display its contents in Render.
+
+```typescript
+// hooks/store.ts
+import { createUseInstanceStoreState } from '@telemetryos/sdk/react'
+
+export const useFolderIdState = createUseInstanceStoreState<string>('folderId', '')
+```
+
+```typescript
+// views/Settings.tsx
+import { useEffect, useState } from 'react'
+import { media } from '@telemetryos/sdk'
+import {
+  SettingsContainer,
+  SettingsField,
+  SettingsLabel,
+  SettingsSelectFrame,
+} from '@telemetryos/sdk/react'
+import { useFolderIdState } from '../hooks/store'
+
+interface Folder {
+  id: string
+  name: string
+}
+
+export default function Settings() {
+  const [isLoading, folderId, setFolderId] = useFolderIdState()
+  const [folders, setFolders] = useState<Folder[]>([])
+
+  useEffect(() => {
+    media().getAllFolders().then(setFolders)
+  }, [])
+
+  return (
+    <SettingsContainer>
+      <SettingsField>
+        <SettingsLabel>Media Folder</SettingsLabel>
+        <SettingsSelectFrame>
+          <select
+            disabled={isLoading || folders.length === 0}
+            value={folderId}
+            onChange={(e) => setFolderId(e.target.value)}
+          >
+            <option value="">Select a folder...</option>
+            {folders.map(folder => (
+              <option key={folder.id} value={folder.id}>
+                {folder.name}
+              </option>
+            ))}
+          </select>
+        </SettingsSelectFrame>
+      </SettingsField>
+    </SettingsContainer>
+  )
+}
+```
+
+### Image Gallery in Render
+
+```typescript
+// views/Render.tsx
+import { useEffect, useState } from 'react'
+import { media } from '@telemetryos/sdk'
+import { useFolderIdState } from '../hooks/store'
+
+interface MediaItem {
+  id: string
+  name: string
+  url: string
+  thumbnailUrl: string
+}
+
+export default function Render() {
+  const [isLoading, folderId] = useFolderIdState()
+  const [items, setItems] = useState<MediaItem[]>([])
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    if (isLoading || !folderId) return
+
+    const fetchMedia = async () => {
+      setLoading(true)
+      try {
+        const content = await media().getAllByFolderId(folderId)
+
+        // Filter to images only
+        const images = content
+          .filter(item => item.contentType.startsWith('image/'))
+          .map(item => ({
+            id: item.id,
+            name: item.name,
+            url: item.publicUrls[0],
+            thumbnailUrl: item.thumbnailUrl,
+          }))
+
+        setItems(images)
+      } catch (err) {
+        console.error('Failed to load media:', err)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    fetchMedia()
+  }, [folderId, isLoading])
+
+  if (isLoading) return <div>Loading config...</div>
+  if (!folderId) return <div>Select a folder in Settings</div>
+  if (loading) return <div>Loading images...</div>
+  if (items.length === 0) return <div>No images in folder</div>
+
+  return (
+    <div className="gallery">
+      {items.map(item => (
+        <img
+          key={item.id}
+          src={item.url}
+          alt={item.name}
+          loading="lazy"
+        />
+      ))}
+    </div>
+  )
+}
+```
+
+### Video Player
+
+```typescript
+// views/Render.tsx
+import { useEffect, useState } from 'react'
+import { media } from '@telemetryos/sdk'
+import { useVideoIdState } from '../hooks/store'
+
+export default function Render() {
+  const [isLoading, videoId] = useVideoIdState()
+  const [videoUrl, setVideoUrl] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (isLoading || !videoId) return
+
+    media().getById(videoId).then(item => {
+      if (item.contentType.startsWith('video/')) {
+        setVideoUrl(item.publicUrls[0])
+      }
+    })
+  }, [videoId, isLoading])
+
+  if (isLoading) return <div>Loading...</div>
+  if (!videoUrl) return <div>No video selected</div>
+
+  return (
+    <video
+      src={videoUrl}
+      autoPlay
+      loop
+      muted
+      playsInline
+      style={{ width: '100%', height: '100%', objectFit: 'cover' }}
+    />
+  )
+}
+```
+
+### Content Picker by Tag
+
+```typescript
+// Settings - let user select from tagged content
+const [items, setItems] = useState<MediaContent[]>([])
+
+useEffect(() => {
+  media().getAllByTag('logo').then(setItems)
+}, [])
+```
+
+### Slideshow with Auto-Advance
+
+```typescript
+import { useEffect, useState } from 'react'
+import { media } from '@telemetryos/sdk'
+import { useFolderIdState, useIntervalState } from '../hooks/store'
+
+export default function Render() {
+  const [, folderId] = useFolderIdState()
+  const [, interval] = useIntervalState() // seconds
+
+  const [images, setImages] = useState<string[]>([])
+  const [currentIndex, setCurrentIndex] = useState(0)
+
+  // Load images
+  useEffect(() => {
+    if (!folderId) return
+
+    media().getAllByFolderId(folderId).then(content => {
+      const urls = content
+        .filter(item => item.contentType.startsWith('image/'))
+        .map(item => item.publicUrls[0])
+      setImages(urls)
+    })
+  }, [folderId])
+
+  // Auto-advance
+  useEffect(() => {
+    if (images.length <= 1) return
+
+    const timer = setInterval(() => {
+      setCurrentIndex(i => (i + 1) % images.length)
+    }, interval * 1000)
+
+    return () => clearInterval(timer)
+  }, [images.length, interval])
+
+  if (images.length === 0) return <div>No images</div>
+
+  return (
+    <img
+      src={images[currentIndex]}
+      alt={`Slide ${currentIndex + 1}`}
+      style={{ width: '100%', height: '100%', objectFit: 'contain' }}
+    />
+  )
+}
+```
+
+## Content Type Filtering
+
+```typescript
+const content = await media().getAllByFolderId(folderId)
+
+// Images only
+const images = content.filter(item => item.contentType.startsWith('image/'))
+
+// Videos only
+const videos = content.filter(item => item.contentType.startsWith('video/'))
+
+// PDFs only
+const pdfs = content.filter(item => item.contentType === 'application/pdf')
+
+// Specific formats
+const jpegs = content.filter(item => item.contentType === 'image/jpeg')
+const mp4s = content.filter(item => item.contentType === 'video/mp4')
+```
+
+## Scheduling Support
+
+Media items can have valid date ranges:
+
+```typescript
+const content = await media().getAllByFolderId(folderId)
+
+const now = new Date()
+const activeContent = content.filter(item => {
+  // Check if within valid date range
+  if (item.validFrom && new Date(item.validFrom) > now) return false
+  if (item.validTo && new Date(item.validTo) < now) return false
+  return true
+})
+```
+
+## Tips
+
+1. **Use publicUrls[0]** - First URL is the primary CDN URL
+2. **Use thumbnailUrl for previews** - Smaller, faster loading
+3. **Filter by contentType** - Ensure you're displaying compatible content
+4. **Handle empty folders** - Show appropriate message when no content
+5. **Lazy load images** - Use `loading="lazy"` for galleries
+6. **Respect hidden flag** - Filter out hidden items unless intentional

package/templates/vite-react-typescript/_claude/skills/tos-proxy-fetch/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: tos-proxy-fetch
+description: REQUIRED for external API calls in TelemetryOS. MUST invoke BEFORE using proxy().fetch() or adding any third-party API integration. Contains CORS workaround patterns, useEffect dependencies, refresh intervals, and error handling.
+---
+
+# TelemetryOS Proxy Fetch
+
+When external APIs don't include CORS headers, browsers block requests from your app. The TelemetryOS proxy solves this by routing requests through the platform.
+
+## When to Use
+
+### Use proxy().fetch() when:
+- API returns CORS error in browser console
+- API doesn't include `Access-Control-Allow-Origin` header
+- You need to call APIs that weren't designed for browser use
+
+### Use regular fetch() when:
+- API includes CORS headers
+- API is designed for browser/client-side use
+- You want to use the player's advanced caching (regular fetch has better caching on devices)
+
+## Quick Reference
+
+```typescript
+import { proxy } from '@telemetryos/sdk'
+
+// Simple GET
+const response = await proxy().fetch('https://api.example.com/data')
+const data = await response.json()
+
+// With headers
+const response = await proxy().fetch('https://api.example.com/data', {
+  headers: {
+    'Authorization': 'Bearer YOUR_API_KEY',
+    'Content-Type': 'application/json',
+  }
+})
+
+// POST request
+const response = await proxy().fetch('https://api.example.com/data', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({ key: 'value' })
+})
+```
+
+## Complete Example
+
+### Settings (API Key + Endpoint Config)
+
+```typescript
+// hooks/store.ts
+import { createUseInstanceStoreState } from '@telemetryos/sdk/react'
+
+export const useApiKeyState = createUseInstanceStoreState<string>('apiKey', '')
+export const useEndpointState = createUseInstanceStoreState<string>('endpoint', '')
+```
+
+```typescript
+// views/Settings.tsx
+import {
+  SettingsContainer,
+  SettingsField,
+  SettingsLabel,
+  SettingsInputFrame,
+} from '@telemetryos/sdk/react'
+import { useApiKeyState, useEndpointState } from '../hooks/store'
+
+export default function Settings() {
+  const [isLoadingKey, apiKey, setApiKey] = useApiKeyState()
+  const [isLoadingEndpoint, endpoint, setEndpoint] = useEndpointState()
+
+  return (
+    <SettingsContainer>
+      <SettingsField>
+        <SettingsLabel>API Key</SettingsLabel>
+        <SettingsInputFrame>
+          <input
+            type="password"
+            placeholder="Enter API key..."
+            disabled={isLoadingKey}
+            value={apiKey}
+            onChange={(e) => setApiKey(e.target.value)}
+          />
+        </SettingsInputFrame>
+      </SettingsField>
+
+      <SettingsField>
+        <SettingsLabel>API Endpoint</SettingsLabel>
+        <SettingsInputFrame>
+          <input
+            type="url"
+            placeholder="https://api.example.com/data"
+            disabled={isLoadingEndpoint}
+            value={endpoint}
+            onChange={(e) => setEndpoint(e.target.value)}
+          />
+        </SettingsInputFrame>
+      </SettingsField>
+    </SettingsContainer>
+  )
+}
+```
+
+### Render (Data Display)
+
+```typescript
+// views/Render.tsx
+import { useEffect, useState } from 'react'
+import { proxy } from '@telemetryos/sdk'
+import { useApiKeyState, useEndpointState } from '../hooks/store'
+
+interface ApiData {
+  // Define your API response type
+  items: Array<{
+    id: string
+    name: string
+    value: number
+  }>
+}
+
+export default function Render() {
+  const [isLoadingKey, apiKey] = useApiKeyState()
+  const [isLoadingEndpoint, endpoint] = useEndpointState()
+
+  const [data, setData] = useState<ApiData | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (isLoadingKey || isLoadingEndpoint || !apiKey || !endpoint) return
+
+    const fetchData = async () => {
+      setLoading(true)
+      setError(null)
+
+      try {
+        const response = await proxy().fetch(endpoint, {
+          headers: {
+            'Authorization': `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+          }
+        })
+
+        if (!response.ok) {
+          throw new Error(`API error: ${response.status} ${response.statusText}`)
+        }
+
+        const json = await response.json()
+        setData(json)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Unknown error')
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    fetchData()
+
+    // Refresh every 5 minutes
+    const interval = setInterval(fetchData, 5 * 60 * 1000)
+    return () => clearInterval(interval)
+  }, [apiKey, endpoint, isLoadingKey, isLoadingEndpoint])
+
+  // Loading states
+  if (isLoadingKey || isLoadingEndpoint) return <div>Loading config...</div>
+  if (!apiKey || !endpoint) return <div>Configure API in Settings</div>
+  if (loading && !data) return <div>Loading data...</div>
+  if (error && !data) return <div>Error: {error}</div>
+
+  return (
+    <div>
+      {data?.items.map(item => (
+        <div key={item.id}>
+          {item.name}: {item.value}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+## Common API Patterns
+
+### RSS Feed
+
+```typescript
+const response = await proxy().fetch('https://example.com/feed.xml')
+const xml = await response.text()
+
+// Parse XML (use DOMParser or a library)
+const parser = new DOMParser()
+const doc = parser.parseFromString(xml, 'text/xml')
+const items = doc.querySelectorAll('item')
+```
+
+### JSON API with Query Params
+
+```typescript
+const params = new URLSearchParams({
+  apiKey: apiKey,
+  city: city,
+  format: 'json',
+})
+
+const response = await proxy().fetch(`https://api.example.com/data?${params}`)
+const data = await response.json()
+```
+
+### Sports Data API
+
+```typescript
+const response = await proxy().fetch(
+  `https://api.sportsdata.io/v3/nfl/scores/json/Games/${season}`,
+  {
+    headers: {
+      'Ocp-Apim-Subscription-Key': apiKey,
+    }
+  }
+)
+
+const games = await response.json()
+```
+
+### News/Headlines API
+
+```typescript
+const response = await proxy().fetch(
+  `https://newsapi.org/v2/top-headlines?country=us&apiKey=${apiKey}`
+)
+
+const news = await response.json()
+```
+
+## Error Handling
+
+```typescript
+try {
+  const response = await proxy().fetch(endpoint)
+
+  // Check HTTP status
+  if (!response.ok) {
+    if (response.status === 401) {
+      throw new Error('Invalid API key')
+    } else if (response.status === 404) {
+      throw new Error('Endpoint not found')
+    } else if (response.status === 429) {
+      throw new Error('Rate limit exceeded')
+    } else {
+      throw new Error(`API error: ${response.status}`)
+    }
+  }
+
+  const data = await response.json()
+} catch (err) {
+  if (err instanceof Error) {
+    if (err.message.includes('timeout')) {
+      // SDK timeout (30 seconds)
+      console.error('Request timed out')
+    } else if (err.message.includes('network')) {
+      // Network error
+      console.error('Network error')
+    } else {
+      console.error(err.message)
+    }
+  }
+}
+```
+
+## Request Options
+
+The proxy supports all standard fetch options:
+
+```typescript
+await proxy().fetch(url, {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer token',
+    // Any custom headers
+  },
+  body: JSON.stringify(data), // For POST/PUT/PATCH
+})
+```
+
+## Response Handling
+
+```typescript
+const response = await proxy().fetch(url)
+
+// JSON
+const json = await response.json()
+
+// Text
+const text = await response.text()
+
+// Blob (for binary data)
+const blob = await response.blob()
+
+// Check content type
+const contentType = response.headers.get('Content-Type')
+if (contentType?.includes('application/json')) {
+  return response.json()
+} else {
+  return response.text()
+}
+```
+
+## Tips
+
+1. **Check CORS first** - Try regular `fetch()` first; only use proxy if CORS fails
+2. **Handle errors** - Always check `response.ok` before parsing
+3. **Add refresh interval** - External data goes stale; refresh periodically
+4. **Store API keys securely** - Use instance or application store hooks
+5. **Show stale data** - Display last known data while refreshing
+6. **Log errors** - Help users troubleshoot configuration issues
+7. **Timeout awareness** - SDK times out after 30 seconds