Skip to content

CLAUDE.md

Latest commit

 

History

History
92 lines (68 loc) · 4.14 KB

CLAUDE.md

File metadata and controls

92 lines (68 loc) · 4.14 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

BloggerAPI is a Swift package that provides a client library for the Google Blogger API v3. The package is available as both a Swift Package Manager library and a CocoaPod.

  • Current branch: feature/async - Major refactoring to modernize the API with Swift Concurrency (async/await)
  • Main branch: Contains the legacy callback-based implementation
  • Platform: macOS 13+ (uses Swift 6.2 tools version)

Building and Testing

# Build the package
swift build

# Run all tests
swift test

# Run a specific test target
swift test --filter BloggerAPITests

# Build for release
swift build -c release

Code Architecture

Current State (feature/async branch)

The feature/async branch is undergoing a major refactoring. Most implementation files have been deleted and only the Blogger class skeleton remains. This represents a transition from the legacy callback-based architecture to a modern async/await implementation.

Legacy Architecture (main branch)

The main branch uses a dependency injection pattern with completion handlers:

Core Components:

  • Blogger: Main entry point for API interactions. Accepts a blog URL, API key, and NetworkFetch protocol implementation
  • Injector: Singleton-based dependency injection container that manages shared dependencies (API key, fetch handler, blog ID, date formatter)
  • NetworkRequest<T, Result>: Generic base class for all API requests. Handles URL construction, query parameters, and response parsing using Codable

Dependency Injection Pattern:

  • Protocols define injectable dependencies: FetchConsumer, KeyConsumer, BlogIdConsumer, DateFormatterConsumer
  • Request objects declare conformance to these protocols and receive dependencies through the Injector
  • The InjectionHandler protocol + extension pattern enables automatic dependency injection before request execution

Request Flow:

  1. Blogger class receives requests (e.g., fetchUpdates, fetchPost)
  2. Before executing, checks if blogId is available; if not, resolves it via ResolveBlogByURLRequest
  3. Creates appropriate request object (e.g., ListPostsRequest, RetrievePostRequest)
  4. Injects dependencies via Injector.sharedInstance.inject(into:)
  5. Request constructs URL with path variables (:blogId:, :postId:), query parameters, and API key
  6. Executes via injected NetworkFetch implementation
  7. Parses JSON response using Codable with custom date formatting
  8. Invokes completion callback with result

Data Models:

  • Post: Blog post with id, published date, title, content, images, URL
  • Blog: Blog metadata
  • Image: Post image with URL
  • PostsPage: Paginated response containing posts array and next page token
  • NextPageCursor: Pagination state tracking (page token, date filters)

API Requests:

  • ResolveBlogByURLRequest: Converts blog URL to blog ID (required for other operations)
  • ListPostsRequest: Fetches posts with pagination support (by date or cursor)
  • RetrievePostRequest: Fetches a single post by ID

Async/Await Migration Considerations

When implementing async/await:

  • Replace Injector singleton with actor-based dependency management or function parameters
  • Convert NetworkFetch protocol to async throws pattern
  • Replace completion callbacks with async functions returning values or throwing errors
  • Use structured concurrency for blog ID resolution flow
  • Ensure date formatter thread safety (DateFormatter is not thread-safe, consider using actor isolation)
  • Follow Swift Concurrency best practices per ~/.claude/docs/swift-concurrency.md

API Details

The package communicates with Google Blogger API v3 at https://www.googleapis.com/blogger/v3.

Authentication: API key-based (passed as key query parameter)

Key Endpoints:

  • /blogs/:blogId:/posts - List posts with pagination
  • POST paths follow similar pattern with blog/post ID variables

Distribution

This package is distributed via:

  • Swift Package Manager: Primary distribution method (see Package.swift)
  • CocoaPods: See BloggerAPI.podspec (iOS 9.0+)