@thewhateverapp/tile-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 The Whatever App
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,582 @@
+# @thewhateverapp/tile-sdk
+
+> ⚠️ **Beta Release (v0.0.1)**: This package is in early preview. Requires integration with The Whatever App parent window (thewhatever.app). Use for development and testing.
+
+SDK for building interactive tiles on The Whatever App platform. Provides secure parent-tile communication, authentication, storage, and more.
+
+## Features
+
+- **🔐 Authentication**: OAuth-like permission system for accessing user data
+- **💾 Storage**: Parent-managed persistent storage (100KB per tile)
+- **📋 Clipboard**: Secure clipboard access with user permission
+- **🔄 Navigation**: Navigate to full page or open external URLs
+- **📊 Analytics**: Track events and user interactions
+- **🎨 React Hooks**: Easy-to-use React hooks and components
+- **🔒 Security**: Sandboxed iframe with validated message bridge
+
+## Installation
+
+```bash
+npm install @thewhateverapp/tile-sdk
+```
+
+## Quick Start
+
+### React Component
+
+```tsx
+import { TileProvider, useTile } from '@thewhateverapp/tile-sdk/react';
+
+function MyTileApp() {
+  return (
+    <TileProvider fallback={<div>Loading...</div>}>
+      <TileContent />
+    </TileProvider>
+  );
+}
+
+function TileContent() {
+  const tile = useTile();
+
+  const handleClick = async () => {
+    // Navigate to full page
+    tile.navigateToPage();
+
+    // Track event
+    tile.trackEvent('button_click', { action: 'open_page' });
+  };
+
+  return (
+    <div className="w-full h-full">
+      <h1>My Tile</h1>
+      <button onClick={handleClick}>Open Full App</button>
+    </div>
+  );
+}
+```
+
+### Vanilla JavaScript
+
+```javascript
+import { getTileBridge } from '@thewhateverapp/tile-sdk';
+
+const bridge = getTileBridge();
+
+// Wait for bridge to be ready
+await bridge.waitForReady();
+
+// Use bridge APIs
+bridge.navigateToPage();
+bridge.trackEvent('page_view', { page: 'home' });
+```
+
+## Authentication
+
+The tile SDK implements an OAuth-like permission system where apps start with minimal access (user ID only) and must request additional permissions.
+
+### Permission Scopes
+
+- **`id`** - User's internal ID (always granted)
+- **`profile`** - Username, avatar, display name
+- **`email`** - Email address
+- **`wallet`** - Connected wallet addresses
+- **`analytics:read`** - View user's analytics
+- **`analytics:write`** - Track analytics (auto-granted)
+- **`storage:read`** - Read user's storage (auto-granted)
+- **`storage:write`** - Write to storage (auto-granted)
+
+### Request User Authentication
+
+```tsx
+const tile = useTile();
+
+// Request user with specific scopes
+const handleLogin = async () => {
+  const user = await tile.auth.getUser({
+    scopes: ['profile', 'email'],
+    reason: 'We need your email to send you updates'
+  });
+
+  if (user) {
+    console.log('User granted access:', user);
+    // { id, username, email, scopes }
+  } else {
+    console.log('User denied permission');
+  }
+};
+```
+
+### Get Current User
+
+```tsx
+const tile = useTile();
+
+// Get current user (if already authenticated)
+const user = await tile.auth.getCurrentUser();
+
+if (user) {
+  console.log(`Hello, ${user.username || 'User'}!`);
+}
+```
+
+### Request Additional Scopes
+
+```tsx
+const tile = useTile();
+
+// Later in the app, request wallet access
+const handleConnectWallet = async () => {
+  const granted = await tile.auth.requestScopes(['wallet']);
+
+  if (granted) {
+    const user = await tile.auth.getCurrentUser();
+    console.log('Wallet addresses:', user.walletAddresses);
+  }
+};
+```
+
+## Storage
+
+Tiles get 100KB of persistent storage managed by the parent window.
+
+```tsx
+const tile = useTile();
+
+// Store data
+await tile.storage.set('user_preferences', {
+  theme: 'dark',
+  notifications: true
+});
+
+// Retrieve data
+const prefs = await tile.storage.get('user_preferences');
+console.log('Theme:', prefs.theme);
+```
+
+## Clipboard
+
+Clipboard access requires user permission (one-time prompt).
+
+```tsx
+const tile = useTile();
+
+const handleCopy = async () => {
+  try {
+    await tile.clipboard.write('Hello from my tile!');
+    console.log('Copied to clipboard!');
+  } catch (error) {
+    console.error('User denied clipboard access');
+  }
+};
+```
+
+## Navigation
+
+### Navigate to Full Page
+
+```tsx
+const tile = useTile();
+
+// Opens the full page view of your app
+tile.navigateToPage();
+```
+
+### Open External URL
+
+```tsx
+const tile = useTile();
+
+// Opens URL with user confirmation
+tile.openUrl('https://example.com', '_blank');
+```
+
+## Analytics
+
+Track user events and interactions.
+
+```tsx
+const tile = useTile();
+
+// Track custom event
+tile.trackEvent('button_click', {
+  button: 'subscribe',
+  location: 'header'
+});
+
+// Track page view
+tile.trackEvent('page_view', { page: 'home' });
+```
+
+## Configuration
+
+Access tile configuration from parent.
+
+```tsx
+const tile = useTile();
+
+if (tile.config) {
+  console.log('App ID:', tile.config.appId);
+  console.log('Position:', tile.config.position);
+  console.log('Theme:', tile.config.theme);
+}
+```
+
+## Advanced: Using TileBridge Directly
+
+For non-React apps or advanced use cases:
+
+```typescript
+import { getTileBridge } from '@thewhateverapp/tile-sdk';
+
+const bridge = getTileBridge();
+
+// Wait for ready
+const config = await bridge.waitForReady();
+
+// Listen for events
+bridge.on('theme:change', (theme) => {
+  console.log('Theme changed:', theme);
+});
+
+// Request resize (max 512x512)
+bridge.requestResize(400, 300);
+
+// Get user with auth
+const user = await bridge.getUser({
+  scopes: ['profile'],
+  reason: 'Show your name'
+});
+
+// Storage operations
+await bridge.setStorage('key', { data: 'value' });
+const data = await bridge.getStorage('key');
+
+// Navigate
+bridge.navigateToPage();
+bridge.openUrl('https://example.com');
+
+// Track events
+bridge.trackEvent('custom_event', { foo: 'bar' });
+
+// Clipboard
+await bridge.writeToClipboard('text to copy');
+```
+
+## Security Model
+
+### Sandboxed Iframe
+
+All tiles run in sandboxed iframes with strict policies:
+
+```html
+<iframe
+  sandbox="allow-scripts allow-pointer-lock"
+  referrerpolicy="no-referrer"
+  allow="clipboard-read; clipboard-write"
+/>
+```
+
+### Origin Validation
+
+All messages are validated against the parent origin:
+- Production: `https://thewhatever.app`
+- Development: `http://localhost:3000`
+
+### Permission System
+
+- Apps start with **minimal access** (user ID only)
+- Additional permissions require **explicit user consent**
+- Users can **revoke permissions** anytime in settings
+- Permission grants are **audited** for security
+
+## Best Practices
+
+### 1. Request Minimal Scopes
+
+❌ Bad:
+```typescript
+await tile.auth.getUser({
+  scopes: ['profile', 'email', 'wallet']
+});
+```
+
+✅ Good:
+```typescript
+// Start minimal
+await tile.auth.getUser({
+  scopes: ['profile']
+});
+
+// Request more later when needed
+await tile.auth.requestScopes(['email']);
+```
+
+### 2. Explain Why
+
+```typescript
+await tile.auth.getUser({
+  scopes: ['email'],
+  reason: 'Send you order confirmation'
+});
+```
+
+### 3. Handle Denials Gracefully
+
+```typescript
+const user = await tile.auth.getUser({ scopes: ['email'] });
+
+if (!user || !user.email) {
+  // Provide alternative flow
+  return <ManualEmailInput />;
+}
+```
+
+### 4. Check Scopes Before Using
+
+```typescript
+const user = await tile.auth.getCurrentUser();
+
+if (user?.scopes.includes('email')) {
+  sendEmail(user.email);
+} else {
+  console.log('Email permission not granted');
+}
+```
+
+## API Reference
+
+### `useTile()` Hook
+
+Returns the tile context with all available methods.
+
+**Returns**: `TileContextValue`
+
+### `TileContextValue`
+
+```typescript
+interface TileContextValue {
+  config: TileConfig | null;
+  bridge: TileBridge;
+  isReady: boolean;
+
+  // Navigation
+  navigateToPage: () => void;
+  openUrl: (url: string, target?: '_blank' | '_self') => void;
+
+  // Analytics
+  trackEvent: (eventName: string, data?: any) => void;
+
+  // Storage
+  storage: {
+    get: (key: string) => Promise<any>;
+    set: (key: string, value: any) => Promise<void>;
+  };
+
+  // Clipboard
+  clipboard: {
+    write: (text: string) => Promise<void>;
+  };
+
+  // Authentication
+  auth: {
+    getUser: (options?: {
+      scopes?: string[];
+      reason?: string;
+    }) => Promise<UserContext | null>;
+    requestScopes: (scopes: string[]) => Promise<boolean>;
+    getCurrentUser: () => Promise<UserContext | null>;
+  };
+}
+```
+
+### `TileConfig`
+
+```typescript
+interface TileConfig {
+  appId: string;
+  position: { row: number; col: number };
+  tileUrl: string;
+  apiEndpoint?: string;
+  theme?: 'light' | 'dark';
+  debug?: boolean;
+}
+```
+
+### `UserContext`
+
+```typescript
+interface UserContext {
+  authenticated: boolean;
+  userId: string;
+  scopes: string[];
+
+  // Only if 'profile' scope granted
+  username?: string;
+  avatar?: string;
+  displayName?: string;
+
+  // Only if 'email' scope granted
+  email?: string;
+
+  // Only if 'wallet' scope granted
+  walletAddresses?: string[];
+}
+```
+
+## Examples
+
+### Example: Simple Counter Tile
+
+```tsx
+import { TileProvider, useTile } from '@thewhateverapp/tile-sdk/react';
+import { useState, useEffect } from 'react';
+
+function CounterTile() {
+  return (
+    <TileProvider>
+      <Counter />
+    </TileProvider>
+  );
+}
+
+function Counter() {
+  const tile = useTile();
+  const [count, setCount] = useState(0);
+
+  // Load count from storage on mount
+  useEffect(() => {
+    tile.storage.get('count').then(savedCount => {
+      if (savedCount !== undefined) setCount(savedCount);
+    });
+  }, []);
+
+  // Save count to storage when it changes
+  useEffect(() => {
+    tile.storage.set('count', count);
+  }, [count]);
+
+  const increment = () => {
+    setCount(c => c + 1);
+    tile.trackEvent('counter_increment', { value: count + 1 });
+  };
+
+  return (
+    <div className="flex flex-col items-center justify-center h-full">
+      <h1 className="text-4xl font-bold">{count}</h1>
+      <button onClick={increment} className="mt-4 px-6 py-2 bg-blue-500">
+        Increment
+      </button>
+      <button onClick={() => tile.navigateToPage()} className="mt-2">
+        View Full App
+      </button>
+    </div>
+  );
+}
+```
+
+### Example: User Profile Tile
+
+```tsx
+import { TileProvider, useTile } from '@thewhateverapp/tile-sdk/react';
+import { useState, useEffect } from 'react';
+
+function ProfileTile() {
+  return (
+    <TileProvider>
+      <Profile />
+    </TileProvider>
+  );
+}
+
+function Profile() {
+  const tile = useTile();
+  const [user, setUser] = useState(null);
+
+  const handleLogin = async () => {
+    const userData = await tile.auth.getUser({
+      scopes: ['profile', 'email'],
+      reason: 'Display your profile information'
+    });
+
+    if (userData) {
+      setUser(userData);
+      tile.trackEvent('user_logged_in');
+    }
+  };
+
+  if (!user) {
+    return (
+      <div className="flex items-center justify-center h-full">
+        <button onClick={handleLogin} className="px-6 py-3 bg-purple-500">
+          Sign In
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-4">
+      <img src={user.avatar} className="w-16 h-16 rounded-full" />
+      <h2 className="text-xl font-bold mt-2">{user.username}</h2>
+      {user.email && <p className="text-gray-600">{user.email}</p>}
+      <button onClick={() => tile.navigateToPage()} className="mt-4">
+        View Full Profile
+      </button>
+    </div>
+  );
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with type definitions included.
+
+```typescript
+import type {
+  TileContextValue,
+  TileConfig,
+  UserContext,
+  TileBridge
+} from '@thewhateverapp/tile-sdk';
+```
+
+## Development
+
+### Local Testing
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run type checking
+npm run typecheck
+
+# Lint
+npm run lint
+```
+
+### Testing with Parent
+
+To test your tile locally, you'll need the parent window running:
+
+```bash
+# In parent project
+npm run dev
+
+# Your tile will be loaded at:
+# http://localhost:3000/tile/[your-app-id]
+```
+
+## Resources
+
+- [Platform Documentation](https://thewhatever.app/docs)
+- [Authentication Guide](https://thewhatever.app/docs/auth)
+- [Security Best Practices](https://thewhatever.app/docs/security)
+- [Example Apps](https://github.com/thewhateverapp/examples)
+
+## License
+
+Proprietary - All rights reserved

package/dist/bridge/TileBridge.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Secure message bridge for tile-parent communication
+ * This runs inside the iframe (tile side)
+ */
+export interface TileMessage {
+    type: string;
+    payload?: any;
+    id?: string;
+    timestamp?: number;
+}
+export interface TileConfig {
+    appId: string;
+    position: {
+        row: number;
+        col: number;
+    };
+    tileUrl: string;
+    apiEndpoint?: string;
+    theme?: 'light' | 'dark';
+    debug?: boolean;
+}
+export declare class TileBridge {
+    private config;
+    private messageQueue;
+    private responseHandlers;
+    private eventHandlers;
+    private ready;
+    private parentOrigin;
+    constructor(expectedOrigin?: string);
+    private initialize;
+    private handleMessage;
+    private handleConfig;
+    private handleResponse;
+    private handleEvent;
+    private sendToParent;
+    /**
+     * Request to navigate to full page view
+     */
+    navigateToPage(): void;
+    /**
+     * Request to open a URL (with user confirmation)
+     */
+    openUrl(url: string, target?: '_blank' | '_self'): void;
+    /**
+     * Send analytics event
+     */
+    trackEvent(eventName: string, data?: any): void;
+    /**
+     * Request clipboard write (requires user permission)
+     */
+    writeToClipboard(text: string): Promise<void>;
+    /**
+     * Store data in parent's storage (limited to 100KB per tile)
+     */
+    setStorage(key: string, value: any): Promise<void>;
+    /**
+     * Get data from parent's storage
+     */
+    getStorage(key: string): Promise<any>;
+    /**
+     * Request resize (within limits)
+     */
+    requestResize(width: number, height: number): void;
+    /**
+     * Request user authentication with specific scopes
+     */
+    getUser(options?: {
+        scopes?: string[];
+        reason?: string;
+    }): Promise<any>;
+    /**
+     * Request additional permission scopes
+     */
+    requestScopes(scopes: string[]): Promise<boolean>;
+    /**
+     * Get current authenticated user (if available)
+     */
+    getCurrentUser(): Promise<any>;
+    /**
+     * Subscribe to events from parent
+     */
+    on(event: string, handler: (data: any) => void): () => void;
+    /**
+     * Get tile configuration
+     */
+    getConfig(): TileConfig | null;
+    /**
+     * Check if ready
+     */
+    isReady(): boolean;
+    /**
+     * Wait for ready state
+     */
+    waitForReady(): Promise<TileConfig>;
+    private emitEvent;
+    private generateId;
+    private isDevelopment;
+}
+export declare function getTileBridge(): TileBridge;
+//# sourceMappingURL=TileBridge.d.ts.map

package/dist/bridge/TileBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TileBridge.d.ts","sourceRoot":"","sources":["../../src/bridge/TileBridge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,gBAAgB,CAAmD;IAC3E,OAAO,CAAC,aAAa,CAAoD;IACzE,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAAS;gBAEjB,cAAc,GAAE,MAAkC;IAW9D,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,aAAa;IA6BrB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,YAAY;IAsBpB;;OAEG;IACI,cAAc,IAAI,IAAI;IAO7B;;OAEG;IACI,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,QAAQ,GAAG,OAAkB,GAAG,IAAI;IAOxE;;OAEG;IACI,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IAOtD;;OAEG;IACU,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA4B1D;;OAEG;IACU,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B/D;;OAEG;IACU,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAoBlD;;OAEG;IACI,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAWzD;;OAEG;IACU,OAAO,CAAC,OAAO,CAAC,EAAE;QAC7B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,GAAG,CAAC;IAiChB;;OAEG;IACU,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IA8B9D;;OAEG;IACU,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC;IAuB3C;;OAEG;IACI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI;IAgBlE;;OAEG;IACI,SAAS,IAAI,UAAU,GAAG,IAAI;IAIrC;;OAEG;IACI,OAAO,IAAI,OAAO;IAIzB;;OAEG;IACU,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC;IAehD,OAAO,CAAC,SAAS;IAOjB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,aAAa;CAKtB;AAKD,wBAAgB,aAAa,IAAI,UAAU,CAK1C"}