Release v1.0.0

[soulevilx]

Summary

• Prepare CHANGELOG.md for v1.0.0.
• Release PR from develop to master after PR Improve safe Flickr SDK performance #1 raised test coverage above the 95% target.

Validation

• composer validate --strict
• composer lint:all
• composer test
• composer test:coverage
• composer ci

Coverage: elements 1447/1512 (95.70%), statements 1077/1116 (96.51%).

Summary by CodeRabbit

Release Notes

• New Features

  • Added lazy pagination for photo search via new searchPages() method
  • Introduced optional response caching for public GET requests with configurable TTL

• Bug Fixes

  • Fixed upload and replace streams to ensure proper cleanup after requests
  • Improved cache key consistency for parameter handling

• Documentation

  • Enhanced guides covering caching behavior, pagination, upload workflows, and development setup

• Tests

  • Expanded test coverage for caching, pagination, uploads, and OAuth token management

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[coderabbitai]

Warning

Rate limit exceeded

@soulevilx has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 53 minutes and 32 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 17124287-d55e-4579-9c43-5d263f54d25e

📥 Commits

Reviewing files that changed from the base of the PR and between 5d1504b and c7d17a7.

📒 Files selected for processing (1)

• CHANGELOG.md

📝 Walkthrough

Walkthrough

This PR implements optional response caching with deterministic cache keys, lazy pagination for photo search, stream cleanup for upload requests, and extensive developer documentation. The feature is backward-compatible—caching defaults to disabled via NullCache—and includes comprehensive test coverage and guidance for contributors.

Changes

Caching, pagination, and upload cleanup

Layer / File(s)	Summary
Deterministic cache key resolution src/Cache/CacheKeyResolver.php	CacheKeyResolver sorts input parameters recursively before hashing to ensure stable cache keys regardless of parameter order, using sortParameters() and sortValue() helpers to normalize associative arrays and nested structures.
FlickrClient caching integration src/Client/FlickrClient.php	FlickrClient::call() now computes cache keys, reads/writes responses from/to cache, and refactors responsibilities into helpers: prepareParameters(), authenticate() (gating OAuth signing), transportOptions(), cacheKey(), and shouldUseCache() (eligibility checks for method cacheability, HTTP method, auth requirements).
Cache configuration and factory wiring src/Config/FlickrConfig.php, src/FlickrFactory.php	FlickrConfig adds validated publicCacheTtlSeconds property (default 300 seconds), and FlickrFactory::make() accepts optional FlickrCacheContract parameter, conditionally injecting cache into FlickrClient.
Lazy photo search pagination src/Contracts/Services/PhotoServiceContract.php, src/DTO/Common/PaginationOptionsData.php, src/Services/PhotoService.php	PaginationOptionsData DTO configures pagination (max pages, per-page, start page, empty-result stop behavior), PhotoServiceContract extends with searchPages() method returning iterable<ApiResponseData>, and PhotoService implements generator-based pagination with helper methods for parameter building and result extraction.
Multipart stream cleanup src/Client/MultipartRequestBuilder.php, src/Client/FlickrUploadClient.php	MultipartRequestBuilder::close() releases open file stream resources by closing handles when contents is a resource, and FlickrUploadClient::send() wraps multipart construction in try-finally to guarantee cleanup even on errors.
Method metadata cache marking src/Metadata/methods.php	Auth/OAuth token methods (flickr.auth.*, flickr.auth.oauth.*) and upload ticket-check (flickr.photos.upload.checkTickets) are marked non-cacheable by setting the cache flag to false.
Test fake doubles tests/Fakes/ArrayCache.php, tests/Fakes/SpySigner.php, tests/Fakes/SpyTokenStore.php	ArrayCache tracks in-memory cached items and call counters; SpySigner returns deterministic signed output and counts invocations; SpyTokenStore tracks token store access and stores/retrieves tokens.
Comprehensive test coverage tests/Unit/ClientAndParserTest.php, tests/Unit/ConfigAndDtoTest.php, tests/Unit/OAuthTest.php, tests/Unit/OfficialMethodCoverageTest.php, tests/Unit/ServiceTest.php, tests/Unit/SupportAndRegistryTest.php	Tests validate cacheable GET request behavior and TTL handling, cache bypass for authenticated/disabled scenarios, API/XML/upload response parsing with invalid case rejection, lazy pagination iteration and stop conditions, method metadata cacheability rules, wrapper dispatch to raw methods, and support utility behavior (QueryString, FileValidator, cache adapters).

Developer guidance and documentation

Layer / File(s)	Summary
Caching and security guidance README.md, docs/02-user-guide/13-cache-and-error-handling.md, docs/04-development/05-method-registry.md	Documentation clarifies runtime caching is disabled by default (NullCache), restricted to public cacheable GET REST calls when enabled, with explicit enumeration of cache bypass cases (auth, mutations, uploads, ticket polling, authenticated workflows, stat=fail responses), and per-request bypass via RequestOptionsData(cache: CachePolicy::Disabled).
Pagination and upload documentation README.md, docs/02-user-guide/02-photos.md, docs/00-architecture/05-upload-and-replace.md	User guide documents searchPages() lazy iteration, PaginationOptionsData configuration, and stop conditions; architecture docs clarify multipart photo stream is closed after transport request.
Contributor workflow and safety AGENTS.md, ai/skills/README.md, docs/04-development/08-ai-contributor-workflow.md, docs/04-development/09-secret-scanning.md, docs/04-development/01-code-style.md, docs/04-development/02-testing.md	New/updated docs define AI contributor scope (framework-agnostic, no Laravel specifics), DTO style alignment with jooservices/dto, Pint formatter precedence, testing with focused commands, secret-scanning procedures (environment variable loading, staged-change inspection, credential rotation), and performance/Git flow rules for caching and branching.
CI/CD and release process .github/workflows/ci.yml, docs/04-development/07-ci-cd.md, docs/04-development/04-release.md, docs/04-development/06-repository-metadata.md	CI workflow targets master/develop branches instead of main, runs composer check instead of separate lint/test steps, documentation clarifies PR validation with FLICKR_REAL_TESTS=false and lists gate steps, release flow adds git checkout master and git pull before tagging, and repository metadata updated with expanded topics ("jooservices", "framework-agnostic", "api-client").
DTO roadmap and change tracking docs/05-maintenance/01-risks-legacy-and-gaps.md, CHANGELOG.md, docs/05-maintenance/02-docs-changelog.md, docs/README.md	New "DTO-first roadmap" section outlines incremental typed expansion strategy (avoiding all-224-methods wrap) with priority candidates (flickr.photos.*, flickr.people.*, etc.) and raw fallback preservation; changelog and docs index updated to reflect v1.0.0 release and new documentation pages.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Poem

A rabbit hops through caches bright,
With lazy pages, streaming streams,
No need to fetch when keys align,
Just yield the photos, sorted dreams!
Configuration flows just right,
Tests ensure no auth creaks. 🐰✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title 'Release v1.0.0' directly and clearly summarizes the primary objective of the changeset, which is to prepare and release version 1.0.0 of the package.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release/v1.0.0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}