Shared CloudKit models and utilities for the Celestra RSS reader ecosystem
CelestraKit is a Swift package that provides shared CloudKit data models for the Celestra RSS reader ecosystem. It defines the public database schema used by both the iOS application and server-side feed processing tools, enabling seamless data synchronization and sharing across the Celestra platform.
- 📱 CloudKit Public Database Models: Shared data structures for feeds and articles
- 🔄 Cross-Platform Compatibility: Works on all Apple platforms with CloudKit support
- 🔐 Server-Side Metrics: Track feed health, success rates, and fetch statistics
- 🔍 Content Deduplication: Composite key hashing for intelligent article deduplication
- ⏱️ TTL-Based Caching: Automatic expiration tracking for article freshness
- 📊 Quality Indicators: Feed quality scoring and health monitoring
- 🧮 Reading Time Estimation: Automatic word count and reading time calculation
- ⚡ Modern Swift: Built with Swift 6.2, strict concurrency, and modern language features
- 🧪 Comprehensive Testing: 67+ test cases covering all models and edge cases
Add CelestraKit to your Package.swift:
dependencies: [
.package(url: "https://github.com/brightdigit/CelestraKit.git", from: "0.0.1")
]Or add it through Xcode:
- File → Add Package Dependencies
- Enter:
https://github.com/brightdigit/CelestraKit.git - Select version and add to your target
- Swift: 6.2+
- Xcode: 16.3+ (for iOS/macOS development)
- CloudKit: All models designed for CloudKit public database
| Platform | Minimum Version |
|---|---|
| iOS | 26.0+ |
| macOS | 26.0+ |
| watchOS | 26.0+ |
| tvOS | 26.0+ |
| visionOS | 26.0+ |
| macCatalyst | 26.0+ |
Note: Platform versions are set to 26.0+ to ensure full CloudKit compatibility and modern platform features.
import CelestraKit
// Create a feed in the public database
let feed = Feed(
recordName: "feed-example",
feedURL: "https://example.com/feed.xml",
title: "Example RSS Feed",
description: "A sample RSS feed",
category: "Technology",
language: "en"
)
// Access computed properties
print("Feed health: \(feed.isHealthy ? "✓" : "✗")")
print("Success rate: \(feed.successRate * 100)%")
// Create an article linked to the feed
let article = Article(
feedRecordName: feed.recordName ?? feed.feedURL,
guid: "article-123",
title: "Example Article",
excerpt: "This is a sample article",
content: "<p>Full article content here</p>",
author: "John Doe",
url: "https://example.com/article",
publishedDate: Date()
)
// Check article status
if article.isExpired {
print("Article has expired and should be refreshed")
}
print("Reading time: \(article.estimatedReadingTime ?? 0) minutes")The Feed model represents RSS feeds in CloudKit's public database:
let feed = Feed(
recordName: "unique-feed-id",
feedURL: "https://example.com/feed.xml",
title: "Tech Blog",
description: "Latest technology news",
category: "Technology",
imageURL: "https://example.com/image.png",
language: "en",
tags: ["tech", "programming"],
qualityScore: 85,
isVerified: true,
isFeatured: false
)
// Server-side metrics (updated by feed processor)
feed.lastFetchedAt = Date()
feed.fetchAttempts = 100
feed.successfulFetches = 95
feed.failureCount = 5
// Check feed health
if feed.isHealthy {
print("✓ Feed is healthy (quality: \(feed.qualityScore), success rate: \(feed.successRate))")
}Key Properties:
feedURL: Unique feed identifierqualityScore: 0-100 quality indicatorsuccessRate: Computed from fetch statisticsisHealthy: Health status based on quality and reliability
The Article model represents cached RSS articles:
let article = Article(
feedRecordName: "feed-id",
guid: "article-guid",
title: "Article Title",
excerpt: "Brief summary",
content: "<p>Full HTML content</p>",
author: "Author Name",
url: "https://example.com/article",
publishedDate: Date(),
imageURL: "https://example.com/image.jpg",
language: "en",
tags: ["swift", "ios"],
ttlDays: 30 // Cache for 30 days
)
// Automatic content processing
print("Word count: \(article.wordCount ?? 0)")
print("Plain text: \(article.contentText ?? "")")
print("Content hash: \(article.contentHash)") // Composite key for deduplication
// Check if article needs refresh
if article.isExpired {
// Re-fetch article from source
}Key Features:
- Content Hash: Composite key of title|url|guid for deduplication
- Plain Text Extraction: Automatic HTML → plain text conversion
- Reading Time: Estimated based on 200 words per minute
- TTL Management: Automatic expiration tracking
- Duplicate Detection: Compare
contentHashacross articles
CelestraKit uses CloudKit's public database for content sharing:
┌─────────────────────┐
│ CloudKit Public │
│ Database │
└─────────────────────┘
│
┌─────┴─────┐
│ │
┌───▼────┐ ┌──▼──────┐
│ Feed │ │ Article │
└────────┘ └─────────┘
Feed → Article Relationship:
- Articles reference feeds via
feedRecordName - One feed can have multiple articles
- Articles use
guidfor uniqueness within a feed
All models are Sendable and designed for Swift 6 strict concurrency:
// Safe to use across actor boundaries
actor FeedProcessor {
func process(_ feed: Feed) async {
// Feed is Sendable - safe to pass to actors
}
}Articles use TTL-based expiration:
// Default: 30 days
let article = Article(..., ttlDays: 30)
// Expiration calculated from fetchedAt + TTL
if article.isExpired {
// Time to refresh
}- API Documentation: View on Swift Package Index
- PRD: See .claude/PRD.md for development roadmap
- Development Guide: See CLAUDE.md for AI-assisted development
CelestraKit is available under the MIT license. See LICENSE for details.
Part of the Celestra Ecosystem:
- CelestraKit (this package): Shared CloudKit models
- CelestraApp: iOS RSS reader application
- CelestraCloud: Server-side feed processing
Built with ❤️ by BrightDigit