@thewhateverapp/shared

Shared types, schemas, and utilities for The Whatever App platform. Provides Zod schemas for validation and TypeScript types for type safety across all packages.

Features

- 🔍 Type Safety: Comprehensive TypeScript definitions
- ✅ Validation: Zod schemas for runtime validation
- 📦 Zero Dependencies: Only depends on Zod
- 🎯 Domain Models: Tiles, apps, bidding, points, users
- ⚙️ Configuration: Platform config and feature flags

Installation

``bash
npm install @thewhateverapp/shared
`

Usage

$3

`typescript
import type {
AppManifest,
TilePosition,
TileBid,
UserPoints,
FeatureFlags
} from '@thewhateverapp/shared';
`

$3

`typescript
import {
AppManifest,
TilePosition,
AppGenerationRequest
} from '@thewhateverapp/shared';

// Validate data
const result = AppManifest.safeParse(data);

if (result.success) {
console.log('Valid manifest:', result.data);
} else {
console.error('Validation errors:', result.error);
}
`

Core Types

$3

`typescript
import type { AppManifest, AppComponent, AppVersion } from '@thewhateverapp/shared';

const manifest: AppManifest = {
id: 'uuid-here',
name: 'My App',
description: 'A cool app',
version: '1.0.0',
owner: 'user_123',
createdAt: '2025-01-01T00:00:00Z',
updatedAt: '2025-01-01T00:00:00Z',
components: {
tile: {
entrypoint: '/tile/page.tsx',
assets: ['tile.css', 'tile.js']
},
page: {
entrypoint: '/page/page.tsx',
assets: ['page.css', 'page.js']
},
worker: {
entrypoint: '/worker/index.ts',
routes: ['/api/*']
}
},
metadata: {
icon: 'https://cdn.example.com/icon.png',
color: '#FF6B6B',
tags: ['game', 'fun']
}
};
`

$3

`typescript
import type { Tile, TilePosition, TileStatus } from '@thewhateverapp/shared';

const position: TilePosition = {
row: 0,
col: 5
};

const tile: Tile = {
id: 'tile-uuid',
position: { row: 0, col: 5 },
ownerId: 'user_123',
tileId: 'app-uuid',
status: 'owned',
isElite: true,
metadata: {
name: 'My Tile',
description: 'Elite tile',
color: '#FF6B6B',
tags: ['featured']
},
visibility: 'public',
createdAt: '2025-01-01T00:00:00Z',
updatedAt: '2025-01-01T00:00:00Z'
};
`

$3

`typescript
import type { TileBid, TileBidExtended, BiddingRound } from '@thewhateverapp/shared';

const bid: TileBid = {
tileId: 'tile-123',
position: { row: 0, col: 0 },
bidder: 'user_456',
amount: 10.5,
tileId: 'app-uuid',
timestamp: '2025-01-01T10:00:00Z',
status: 'pending'
};

const extendedBid: TileBidExtended = {
...bid,
pointsAmount: 1000,
currentHighBid: 950,
rotationWeek: '2025-W01',
expiresAt: '2025-01-07T23:59:59Z'
};
`

$3

`typescript
import type {
UserPoints,
PointsTransaction,
PointsPackage
} from '@thewhateverapp/shared';

const userPoints: UserPoints = {
userId: 'user_123',
balance: 1500,
totalEarned: 2000,
totalSpent: 500,
lastUpdated: '2025-01-01T00:00:00Z'
};

const transaction: PointsTransaction = {
id: 'txn-uuid',
userId: 'user_123',
amount: 100,
type: 'purchase',
description: 'Bought 100 points',
stripePaymentIntentId: 'pi_xxx',
createdAt: '2025-01-01T00:00:00Z'
};

const package: PointsPackage = {
id: 'pkg_starter',
name: 'Starter Pack',
points: 100,
priceUsd: 9.99,
stripePriceId: 'price_xxx',
bonusPoints: 10,
popular: false,
enabled: true
};
`

$3

`typescript
import type {
AppGenerationRequest,
FileOperation,
AgentAction,
DomainTool
} from '@thewhateverapp/shared';

const request: AppGenerationRequest = {
prompt: 'Create a counter app',
userId: 'user_123',
preferences: {
style: 'modern',
primaryColor: '#FF6B6B',
features: ['animations', 'dark-mode']
}
};

const fileOp: FileOperation = {
type: 'create',
path: 'src/components/Counter.tsx',
content: 'export const Counter = () => { ... }',
encoding: 'utf8'
};

const action: AgentAction = {
id: 'action-123',
timestamp: '2025-01-01T00:00:00Z',
type: 'file_operation',
details: fileOp,
result: {
success: true,
message: 'File created successfully'
}
};
`

$3

`typescript
import type { PlatformConfig, FeatureFlags } from '@thewhateverapp/shared';

const config: PlatformConfig = {
maxTilesPerRow: 10,
maxRows: 100,
tileSize: 512,
minimumBid: 1,
bidIncrement: 0.1,
maxAppsPerUser: 10,
allowedDomains: ['thewhatever.app']
};

const features: FeatureFlags = {
eliteTileBidding: true,
whateverPoints: true,
tileMarketplace: false,
userDashboard: true,
stripePayments: true,
weeklyRotation: true
};
`

Validation with Zod

$3

`typescript
import { AppGenerationRequest, TilePosition } from '@thewhateverapp/shared';

// Validate generation request
const requestResult = AppGenerationRequest.safeParse({
prompt: 'Create a game',
userId: 'user_123',
preferences: {
style: 'playful'
}
});

if (requestResult.success) {
// Type-safe data
const { prompt, userId, preferences } = requestResult.data;
} else {
// Handle validation errors
console.error(requestResult.error.format());
}

// Validate position
const positionResult = TilePosition.safeParse({ row: 0, col: 5 });
`

$3

`typescript
import { AppManifest } from '@thewhateverapp/shared';

async function fetchManifest(tileId: string) {
const response = await fetch(/api/apps/${tileId});
const data = await response.json();

// Validate response matches schema
const result = AppManifest.safeParse(data);

if (!result.success) {
throw new Error('Invalid manifest data');
}

return result.data; // Type-safe manifest
}
`

$3

`typescript
import { PlatformConfig } from '@thewhateverapp/shared';

// Parse with default values
const config = PlatformConfig.parse({
tileSize: 512
// Other fields will use defaults
});

console.log(config.maxTilesPerRow); // 10 (default)
console.log(config.minimumBid); // 1 (default)
`

All Available Types

$3


- TilePosition - Row and column position
- TileDimensions - Fixed 256×554 dimensions
- TileStatus - empty, owned, elite, bidding
- Tile - Complete tile object
- TileUpdateRequest - Update tile metadata
- EliteTilePosition - Elite tile position (row 0)

$3

- AppComponent - tile, page, worker
- AppManifest - Complete app manifest
- AppVersion - Versioned app snapshot
- AppGenerationRequest - AI generation request

$3

- TileBid - Basic bid
- TileBidExtended - Bid with points and rotation
- BiddingRound - Weekly bidding round

$3

- UserPoints - User's point balance
- PointsTransaction - Point transaction record
- PointsPackage - Points purchase package
- StripePaymentIntent - Stripe payment record

$3

- FileOperation - File CRUD operations
- AgentAction - Agent action log
- DomainTool - Domain-specific tool definition

$3

- PlatformConfig - Platform configuration
- FeatureFlags - Feature toggle flags

Constants

`typescript
import { TILE_SIZE, MAX_TILES_PER_ROW } from '@thewhateverapp/shared';

console.log(TILE_SIZE); // 512
console.log(MAX_TILES_PER_ROW); // 10
`

Utilities

`typescript
import { generateId, formatDate, validateEmail } from '@thewhateverapp/shared';

const id = generateId(); // Generate UUID
const formatted = formatDate(new Date()); // ISO datetime string
const isValid = validateEmail('user@example.com'); // true
`

TypeScript Support

All types are fully typed with TypeScript. Import types using the type keyword:

`typescript
import type {
AppManifest,
Tile,
TileBid,
UserPoints
} from '@thewhateverapp/shared';
`

Import Zod schemas for validation:

`typescript
import {
AppManifest,
Tile,
TileBid,
UserPoints
} from '@thewhateverapp/shared';
`

Best Practices

$3

`typescript
import { AppManifest } from '@thewhateverapp/shared';

// ❌ Don't trust external data
const manifest = await response.json();

// ✅ Always validate
const result = AppManifest.safeParse(await response.json());
if (result.success) {
// Now type-safe
const manifest = result.data;
}
`

$3

`typescript
import type { TileStatus } from '@thewhateverapp/shared';

function handleTile(status: TileStatus) {
switch (status) {
case 'empty':
// Handle empty tile
break;
case 'owned':
// Handle owned tile
break;
case 'elite':
// Handle elite tile
break;
case 'bidding':
// Handle bidding
break;
}
}
`

$3

`typescript
import { z } from 'zod';
import { AppManifest } from '@thewhateverapp/shared';

// Extend schemas with transformations
const AppManifestWithDefaults = AppManifest.transform(data => ({
...data,
metadata: {
...data.metadata,
color: data.metadata?.color || '#000000'
}
}));
`

Development

`bash


Install dependencies

npm install

Run type checking

npm run typecheck

Lint code

npm run lint
`

Related Packages

- @thewhateverapp/platform - Platform services SDK
- @thewhateverapp/tile-sdk - Tile development SDK
- @thewhateverapp/app-templates` - App templates

License

Proprietary - All rights reserved