flickarr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1a4f5663fb2b4656993bc7d505a4351f0eb6462be9c7be9c93e1a3f8bea1b50
+  data.tar.gz: 984db8707cff6d63685b8e137722a092feeeb453da838750c796c0d17c0564b1
+SHA512:
+  metadata.gz: f5b54f40b7baf2e8fba73a1113ff85756721684e45194e5f86ee6af51131b7d89d3ec089d4d01be212546f37ac4d35d76a53f7dc2535fa522d35f1cb1c516543
+  data.tar.gz: 72a742302f25405933445a910e1f52d5dc21f47bcf6ecaade46b2f724b144f7d78e1e7e4d933bf6cc25b73118fe9e904864d214d4c648439c3fa37f495329803

data/.rubocop_todo.yml

@@ -0,0 +1,13 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2026-03-20 01:20:48 UTC using RuboCop version 1.85.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+RSpec/ExpectActual:
+  Exclude:
+    - "spec/flickarr_spec.rb"

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+## [Unreleased]
+
+### Commands
+- `flickarr init` — create config directory and stub config file
+- `flickarr auth` — authenticate with Flickr via OAuth
+- `flickarr config` / `flickarr config <key>` — show configuration
+- `flickarr config:set key=value` — set configuration values
+- `flickarr export` / `flickarr export:posts` — export all posts (photos + videos)
+- `flickarr export URL` — export a single post by Flickr URL
+- `flickarr export:photos` — export only photos
+- `flickarr export:videos` — export only videos
+- `flickarr export:sets` / `flickarr export:albums` — export photosets/albums
+- `flickarr export:collections` — export collections (groups of albums)
+- `flickarr export:profile` — export Flickr profile (avatar, metadata, social links)
+- `flickarr status` — show archive summary with local/upstream counts
+- `flickarr open` — open archive folder in Finder
+- `flickarr path` — print archive path (for scripting)
+- `flickarr errors` — print path to _errors.log
+- `flickarr help` / `-h` / `--help` — show help
+
+### Features
+- Post/Photo/Video model hierarchy with delegated media behavior
+- Full metadata sidecars (JSON + YAML) with EXIF, geo, tags, license, owner, sizes, URLs
+- License model mapping Flickr IDs to human-readable names and Creative Commons URLs
+- Profile data merged from people.getInfo and profile.getProfile
+- Video support with poster frame download
+- Fallback to smaller video sizes when original is unavailable on CDN
+- Rate limiter (1 req/sec) on all Flickr API calls
+- Resume state: saves last page per media type, resumes on next run
+- Fast skip: checks file existence from list data before per-post API calls
+- Graceful Ctrl+C: saves progress and exits cleanly
+- Failed exports logged to _errors.log with post URL and timestamp
+- `--limit N` counts actual downloads, not skips
+- `--overwrite` to re-download existing files; default skips them
+- `--overwrite` on `status` busts cached upstream totals
+- Smart URL routing: `export URL` auto-detects post, set/album, collection, or profile URLs
+- Single post/set/collection export by URL
+- Client with query object API: `client.photo(id:).info`, `client.profile(user_id:).info`
+
+## [0.1.0] - 2026-03-19
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"flickarr" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["veganstraightedge@gmail.com"](mailto:"veganstraightedge@gmail.com").

data/HELP.txt

@@ -0,0 +1,50 @@
+Export and archive your Flickr library
+
+USAGE
+  flickarr command [options]
+  flickarr command:subcommand [options]
+
+EXAMPLES
+  flickarr export
+  flickarr export https://flickr.com/veganstraightedge/3513998015
+  flickarr export https://flickr.com/veganstraightedge/3513998015 --overwrite
+
+  flickarr export --limit 5
+  flickarr export:photos --limit 7
+  flickarr export:videos --limit 3
+
+ARGUMENTS
+  URL                       URL of single item to download from Flickr
+
+FLAGS
+  --limit N                 Stop after N downloads
+  --overwrite               Re-download and overwrite existing files
+
+COMMANDS:
+  init                      Create config directory and stub config file
+  auth                      Authenticate with Flickr
+  config                    Show current configuration
+  config <key>              Show a single config value
+  config:set                Set configuration values (key=value)
+
+  open                      Open archive folder in Finder
+  path                      Print archive path (for scripting)
+  status                    Show archive summary
+  errors                    Print path to _errors.log
+
+  export                    Export all posts
+  export <URL>              Export a single post by URL
+  export:photo <URL>        Export a single post by URL
+  export:video <URL>        Export a single post by URL
+
+  export:posts              Export all posts (photos + videos)
+  export:photos             Export only photos
+  export:videos             Export only videos
+
+  export:sets               Export all photosets with references to posts
+  export:sets <URL>         Export a single photoset with references to posts
+  export:albums             Export all albums with references to posts
+  export:albums <URL>       Export a single album with references to posts
+  export:collections        Export all collections (groups of albums)
+  export:collections <URL>  Export a single collection (groups of albums) with references to albums
+  export:profile            Export Flickr profile to archive

data/HOWTO.md

@@ -0,0 +1,260 @@
+# How to use Flickarr
+
+A step-by-step guide to exporting your Flickr library.
+
+## 1. Check your Ruby version
+
+Flickarr requires Ruby 4.0 or newer.
+
+```sh
+ruby -v
+```
+
+If you need to install or update Ruby, see https://ruby-lang.org/en/downloads
+
+## 2. Install Flickarr
+
+```sh
+gem install flickarr
+```
+
+## 3. Create a Flickr API app
+
+You need your own Flickr API key and secret. Flickarr uses these to authenticate with the Flickr API on your behalf.
+
+1. Go to https://www.flickr.com/services/apps/create/
+2. Click "Apply for a Non-Commercial Key"
+3. Fill in the form:
+   - **Application Name**: anything you want (e.g. "Flickarr Export")
+   - **Description**: anything (e.g. "Personal archive export")
+4. Submit the form
+5. Copy your **Key** and **Secret** from the confirmation page
+
+<!-- TODO: screenshot of Flickr API key creation page -->
+<!-- TODO: screenshot of Flickr API key and secret confirmation page -->
+
+## 4. Initialize Flickarr
+
+This creates a config file at `~/.flickarr/config.yml`.
+
+```sh
+flickarr init
+```
+
+By default, your archive will be saved to `~/Pictures/Flickarr/`. After you authenticate, a subfolder with your Flickr username is created automatically (e.g. `~/Pictures/Flickarr/veganstraightedge/`).
+
+To use a different base location:
+
+```sh
+flickarr init /path/to/your/archive
+```
+
+## 5. Save your API credentials
+
+```sh
+flickarr config:set api_key=YOUR_KEY shared_secret=YOUR_SECRET
+```
+
+Verify they're saved:
+
+```sh
+flickarr config
+```
+
+## 6. Authenticate with Flickr
+
+```sh
+flickarr auth
+```
+
+This starts the OAuth flow:
+
+1. Flickarr prints a URL — open it in your browser
+2. Flickr asks you to authorize the app — click "OK, I'll Authorize It"
+3. Flickr shows you a verification code (9 digits, like `888-675-309`)
+4. Copy that code
+5. Paste the code back into your terminal
+
+<!-- TODO: screenshot of Flickr OAuth authorization page -->
+<!-- TODO: screenshot of Flickr verification code page -->
+
+After authenticating, your access tokens, username, and user ID are saved to the config file. You only need to do this once.
+
+## 7. Export your profile
+
+```sh
+flickarr export:profile
+```
+
+This downloads your profile metadata (JSON + YAML), avatar image, and account info to `~/Pictures/Flickarr/username/Profile/`.
+
+## 8. Export your photos and videos
+
+Export everything:
+
+```sh
+flickarr export
+```
+
+This paginates through your entire Flickr timeline (most recent first) and downloads each photo/video with full metadata sidecars. It respects Flickr's rate limit (1 request per second).
+
+For a large library, this will take a while. You can:
+
+- **Limit** how many to download in one run: `flickarr export --limit 100`
+- **Interrupt** with Ctrl+C — progress is saved and the next run picks up where you left off
+- **Resume** — just run `flickarr export` again; already-downloaded files are skipped instantly
+
+Export only photos or only videos:
+
+```sh
+flickarr export:photos
+flickarr export:videos
+```
+
+Export a single item by its Flickr URL — `export` auto-detects the URL type (post, album, collection, or profile):
+
+```sh
+flickarr export https://flickr.com/photos/USERNAME/3513998015
+flickarr export https://flickr.com/photos/USERNAME/sets/72157718538273371/
+flickarr export https://flickr.com/photos/USERNAME/albums/72157718538273371/
+flickarr export https://flickr.com/photos/USERNAME/collections/72157666222057746/
+flickarr export https://flickr.com/photos/USERNAME/
+```
+
+## 9. Export your albums and collections
+
+Albums (sets) are exported as folders of reference files that point to your downloaded photos/videos:
+
+```sh
+flickarr export:sets
+# or
+flickarr export:albums
+```
+
+Export a single album by URL:
+
+```sh
+flickarr export:sets https://www.flickr.com/photos/USERNAME/sets/72157718538273371/
+```
+
+Collections (groups of albums) work the same way:
+
+```sh
+flickarr export:collections
+```
+
+Export a single collection by URL:
+
+```sh
+flickarr export:collections https://www.flickr.com/photos/USERNAME/collections/72157666222057746/
+```
+
+## 10. Check your progress
+
+```sh
+flickarr status
+```
+
+Shows a summary of your archive: how many photos, videos, sets, and collections are downloaded vs. total available.
+
+The upstream totals are fetched from Flickr on first run and cached in your config file. To refresh them:
+
+```sh
+flickarr status --overwrite
+```
+
+## 11. Utility commands
+
+Open your archive folder in Finder:
+
+```sh
+flickarr open
+```
+
+Print the archive path (useful for scripting):
+
+```sh
+flickarr path
+```
+
+Check the error log for any failed downloads:
+
+```sh
+flickarr errors
+cat $(flickarr errors)
+```
+
+## Re-downloading
+
+By default, Flickarr skips files that already exist. To force a re-download:
+
+```sh
+flickarr export         --overwrite
+flickarr export URL     --overwrite
+flickarr export:profile --overwrite
+flickarr export:sets    --overwrite
+```
+
+## Archive structure
+
+```
+~/Pictures/Flickarr/username/
+  _errors.log                           # log of any failed downloads
+
+  Profile/
+    avatar.jpg
+    profile.json
+    profile.yaml
+
+  2016/
+    11/
+      12/
+        12345678901_oh-no-photo.jpg     # original size photo
+        12345678901_oh-no-photo.json    # full metadata (EXIF, geo, tags, license, etc.)
+        12345678901_oh-no-photo.yaml    # same metadata in YAML
+      13/
+        98765432101_cubs-win-video.mp4  # original video (or best available)
+        98765432101_cubs-win-video.jpg  # poster frame
+        98765432101_cubs-win-video.json
+        98765432101_cubs-win-video.yaml
+
+  Sets/
+    72157718538273371_vacation-photos/
+      set.json                          # set metadata (title, description, dates)
+      set.yaml
+      photos.json                       # ordered list of photo references with file paths
+      photos.yaml
+
+  Collections/
+    375727-72157666222057746_travel/
+      collection.json                   # collection metadata
+      collection.yaml
+      sets.json                         # references to sets in this collection
+      sets.yaml
+```
+
+## Metadata sidecar contents
+
+Each photo/video sidecar includes:
+
+- **Camera**:       make, model, and full EXIF data
+- **Dates**:        taken, uploaded, last updated
+- **Description**:  post description/caption
+- **Geo/Location**: latitude, longitude, locality, region, country
+- **License**:      ID, human-readable name, and Creative Commons URL
+- **Owner**:        username, real name, NSID
+- **Sizes**:        all available sizes with dimensions and URLs
+- **Tags**:         full tag list
+- **URLs**:         Flickr page URL
+- **Views**:        view count
+- **Visibility**:   public, friends, family
+
+## Troubleshooting
+
+**"Not authenticated" error**: Run `flickarr auth` to complete the OAuth flow.
+
+**Video download 404**: Some older videos may not have their original resolution available on Flickr's CDN. Flickarr automatically falls back to the next best available size. If all sizes fail, the error is logged to `_errors.log`.
+
+**Rate limiting**: Flickarr respects Flickr's 1 request/second rate limit. If you see rate limit errors, just wait and try again.
+
+**Resuming after interruption**: Flickarr saves your progress after each page. Just run the same export command again to resume.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Shane Becker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,109 @@
+# Flickarr
+
+Export an archive of your Flickr library — photos, videos, metadata, tags, albums, collections, and profile.
+
+## What you get
+
+```
+~/Pictures/Flickarr/username/
+  Profile/
+    avatar.jpg
+    profile.json
+    profile.yaml
+  2016/
+    11/
+      02/
+        12345678901_cubs-win-photo.jpg
+        12345678901_cubs-win-photo.json
+        12345678901_cubs-win-photo.yaml
+  Sets/
+    72157718538273371_vacation-photos/
+      set.json
+      set.yaml
+      photos.json
+      photos.yaml
+  Collections/
+    375727-72157666222057746_travel/
+      collection.json
+      collection.yaml
+      sets.json
+      sets.yaml
+```
+
+Photos and videos are organized by date taken (`YYYY/MM/DD`). Each media file has JSON and YAML sidecar files with full metadata: EXIF, geo/location, tags, license, owner, sizes, and more.
+
+Sets and collections are folders of reference files that point to the downloaded media.
+
+## Installation
+
+```sh
+gem install flickarr
+```
+
+## Quick start
+
+```sh
+flickarr init
+flickarr config:set api_key=YOUR_KEY shared_secret=YOUR_SECRET
+flickarr auth
+flickarr export
+```
+
+See [HOWTO.md](HOWTO.md) for detailed setup instructions.
+
+## Usage
+
+```sh
+# Export everything
+flickarr export
+
+# Export a single post by URL
+flickarr export https://www.flickr.com/photos/username/12345678901
+
+# Export only photos or only videos
+flickarr export:photos
+flickarr export:videos
+
+# Export with a limit
+flickarr export --limit 10
+
+# Re-download existing files
+flickarr export --overwrite
+
+# Export albums, sets, collections, profile
+flickarr export:sets
+flickarr export:albums
+flickarr export:collections
+flickarr export:profile
+
+# Utility commands
+flickarr status
+flickarr open
+flickarr path
+flickarr config
+flickarr errors
+```
+
+Run `flickarr help` for the full command reference.
+
+## Requirements
+
+- Ruby >= 4.0
+- A [Flickr API key](https://flickr.com/services/apps/create)
+
+## Development
+
+```sh
+git clone https://github.com/veganstraightedge/flickarr.git
+cd flickarr
+bin/setup
+bundle exec rake spec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/veganstraightedge/flickarr.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/TODO.md

@@ -0,0 +1,6 @@
+# Flickarr TODO
+
+## Features
+
+- [ ] Retry on transient network failures (5xx, timeouts)
+- [ ] Verify downloaded file integrity (checksum or size check)

data/exe/flickarr

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'flickarr'
+
+Flickarr::CLI.new(ARGV).run

data/lib/flickarr/auth.rb

@@ -0,0 +1,43 @@
+module Flickarr
+  class Auth
+    def initialize config, config_path: CLI::DEFAULT_CONFIG_PATH
+      @config = config
+      @config_path = config_path
+      @client = Client.new(config)
+    end
+
+    def authenticated?
+      !@config.access_token.nil? && !@config.access_secret.nil?
+    end
+
+    def authenticate
+      flickr = @client.flickr
+
+      request_token = flickr.get_request_token
+      auth_url      = flickr.get_authorize_url request_token['oauth_token'], perms: 'read'
+
+      puts 'Open this URL in your browser to authorize Flickarr:'
+      puts auth_url
+
+      verifier = prompt_for_verifier
+
+      flickr.get_access_token request_token['oauth_token'], request_token['oauth_token_secret'], verifier
+
+      login = flickr.test.login
+
+      @config.access_token  = flickr.access_token
+      @config.access_secret = flickr.access_secret
+      @config.user_nsid     = login.id
+      @config.username      = login.username
+
+      @config.save @config_path
+
+      puts "Authenticated as #{@config.username}"
+    end
+
+    def prompt_for_verifier
+      print 'Enter the verification code: '
+      $stdin.gets.strip
+    end
+  end
+end