npm package: @michaelbhaines/photo-weather-shared
Description: Shared types and utilities for Photo-to-DB backend and frontend projects
Author: Michael Haines
Latest version: 1.0.0

# Photo-Weather Shared Package

Shared TypeScript types, constants, and utilities for the Photo-to-DB backend and Angular frontend projects.

## 📦 Installation

```bash
npm install @mhaines/photo-weather-shared
```

## 🚀 Usage

### **Import Types**
```typescript
import {
  WeatherData,
  TidalData,
  ImageMetadata,
  ExifData,
  ApiResponse
} from '@mhaines/photo-weather-shared';
```

### **Import Constants**
```typescript
import {
  ENDPOINTS,
  QUERY_PARAMS,
  DEFAULTS,
  WeatherProvider,
  DataQuality
} from '@mhaines/photo-weather-shared';
```

### **Import Utilities**
```typescript
import {
  validateCoordinates,
  calculateDistance,
  formatDateForAPI,
  getRelativeTime
} from '@mhaines/photo-weather-shared';
```

## 📋 What's Included

### **🌤️ Weather Types**
- `WeatherData` - Complete weather information structure
- `TidalData` - Tidal conditions and predictions
- `WeatherDataRequest` - Request parameters for weather APIs
- `WeatherProvider`, `DataQuality` enums

### **📷 Image Types**
- `ImageMetadata` - Complete image information
- `ExifData` - Camera and GPS metadata
- `ImageUploadRequest/Response` - Upload API contracts
- `ImageQueryParams` - Filtering and pagination

### **🌐 API Types**
- `ApiResponse<T>` - Standardized API response format
- `ApiError` - Error response structure
- `HealthCheckResponse` - System health information
- `HttpStatus` enum - Standard HTTP status codes

### **🔧 Utilities**
- **Coordinates**: Validation, distance calculation, formatting
- **Dates**: API formatting, validation, relative time
- **Constants**: API endpoints, query parameters, defaults

## 🎯 Frontend Usage (Angular)

### **Service Integration**
```typescript
import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import {
  ENDPOINTS,
  ImageUploadResponse,
  WeatherData,
  ApiResponse
} from '@mhaines/photo-weather-shared';

@Injectable()
export class PhotoService {
  constructor(private http: HttpClient) {}

  uploadImage(formData: FormData): Observable<ImageUploadResponse> {
    return this.http.post<ImageUploadResponse>(ENDPOINTS.IMAGES.UPLOAD, formData);
  }

  getWeatherData(lat: number, lon: number): Observable<ApiResponse<WeatherData>> {
    return this.http.get<ApiResponse<WeatherData>>(ENDPOINTS.WEATHER.BASE, {
      params: { latitude: lat.toString(), longitude: lon.toString() }
    });
  }
}
```

### **Component Usage**
```typescript
import { Component } from '@angular/core';
import {
  ImageMetadata,
  WeatherData,
  formatDisplayDateTime,
  getRelativeTime
} from '@mhaines/photo-weather-shared';

@Component({
  template: `
    <div *ngFor="let image of images">
      <h3>{{ image.originalName }}</h3>
      <p>Uploaded: {{ getRelativeTime(image.uploadDate) }}</p>
      <div *ngIf="image.weatherData">
        <p>Temperature: {{ image.weatherData.temperature.value }}°{{ image.weatherData.temperature.unit }}</p>
        <p *ngIf="image.weatherData.tidalData">
          Tide: {{ image.weatherData.tidalData.tidalPhase }}
        </p>
      </div>
    </div>
  `
})
export class ImageListComponent {
  images: ImageMetadata[] = [];
  
  getRelativeTime = getRelativeTime;
}
```

## 🔧 Backend Usage (Node.js)

### **API Response Formatting**
```typescript
import { ApiResponse, ImageUploadResponse } from '@mhaines/photo-weather-shared';

export function createSuccessResponse<T>(data: T, message: string): ApiResponse<T> {
  return {
    success: true,
    data,
    message
  };
}

export function createErrorResponse(error: string, message: string): ApiResponse {
  return {
    success: false,
    error,
    message
  };
}
```

### **Validation**
```typescript
import { validateCoordinates, isValidWeatherDate } from '@mhaines/photo-weather-shared';

export function validateWeatherRequest(lat: number, lon: number, date: Date) {
  const coordValidation = validateCoordinates(lat, lon);
  if (!coordValidation.isValid) {
    throw new Error(coordValidation.errors.join(', '));
  }
  
  if (!isValidWeatherDate(date)) {
    throw new Error('Invalid date for weather data');
  }
}
```

## 🔄 Development Workflow

### **Making Changes**
1. Update types/constants/utilities in this package
2. Build and publish new version
3. Update both backend and frontend projects
4. Ensures consistency across projects

### **Publishing**
```bash
npm run build
npm version patch  # or minor/major
npm publish
```

### **Updating Projects**
```bash
# In backend project
npm update @mhaines/photo-weather-shared

# In frontend project  
npm update @mhaines/photo-weather-shared
```

## 📝 Type Safety Benefits

- **Consistent APIs**: Same types across backend and frontend
- **Compile-time Validation**: Catch mismatches early
- **IntelliSense Support**: Better developer experience
- **Refactoring Safety**: Changes propagate across projects
- **Documentation**: Types serve as living documentation

## 🎯 Best Practices

1. **Version Carefully**: Breaking changes require major version bump
2. **Document Changes**: Update README for new features
3. **Test Thoroughly**: Validate in both backend and frontend
4. **Keep Focused**: Only shared code belongs here
5. **Semantic Versioning**: Follow semver for predictable updates

---

**Shared package ensures type safety and consistency across your Photo-to-DB ecosystem!** 🚀