flickarr 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 047771d3b777387881e11c1bbe210a0ab9b6ff75a26a30fbff7e856a337fe3f7
-  data.tar.gz: 4b13d68b86693ec63c75fca5ca4116cf166b2a6c711368245d9a75afd5051eb3
+  metadata.gz: c94bc7b1f3ffc434e88faf5a632728406d6c297e2256354d5053af345be8d649
+  data.tar.gz: d2ed214497de643eab92773755bd4b33a655532266736fd4d964d0a3cf1a07a4
 SHA512:
-  metadata.gz: bd2b1b6a9c71c7fef881a49c58866ffa35948a1e76a96614c7f662c3a9b04c183294ab605edf3bfaf218a9d4eed2d8ab703caa813e1612ae9da20ae1f6e9a311
-  data.tar.gz: e0653f10a829f86efd3c4c7635d3054090c45339164a03d1e4dfce74a7edd47fc70bd6aab040f0f9f134e27f5a231d7fd26f81e5c8abf4812fb747e85ff1dfd9
+  metadata.gz: 0060a46d0cb77a92dfaae7a5cc9a21f2979dfa4b7d36d67a3c3bfb2930702e00751f8f9a204455ceb74a55199f7f23f7b93f87e1955889d406326a0a673babb0
+  data.tar.gz: 439ae3fbb665d42b07302b34b7d9070ca06e5064d227f998fcf7c8cb5d0a74dd08adf2b9adceec22f7eecb8e7c1cfe274b4baaa431ee0900dcdd1b7efffd7af1

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.1.6] - 2026-03-31
+
+- Add `version` and `help` commands to help output
+- Retry transient Flickr API errors ("service not currently available") with backoff, instead of crashing
+- Truncate very long slugs to prevent `Errno::ENAMETOOLONG` on filenames exceeding 255 bytes
+
+## [0.1.5] - 2026-03-23
+
+- Add `flickarr version` / `-v` / `--version` command
+- Show version header in help output
+- Check for gem updates: always on `version` and `status`, periodically (daily) after other commands
+
 ## [0.1.4] - 2026-03-22
 
 - Retry transient network errors (connection reset, timeouts, HTML-instead-of-JSON) up to 3 times with backoff

data/HELP.txt

@@ -48,3 +48,6 @@ COMMANDS:
   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
+
+  help, -h, --help          Show this help
+  version, -v, --version    Show version (checks for updates)

data/README.md

@@ -49,7 +49,7 @@ flickarr auth
 flickarr export
 ```
 
-See [HOWTO.md](HOWTO.md) for detailed setup instructions.
+See [doc/HOWTO.md](doc/HOWTO.md) for detailed setup instructions.
 
 ## Usage
 

data/{HOWTO.md → doc/HOWTO.md}

@@ -22,16 +22,24 @@ gem install flickarr
 
 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"
+1. Go to https://flickr.com/services/apps/create and click the [Request an API Key](https://flickr.com/services/apps/create/apply) link in the **Get your API Key** section.
+   ![Screenshot of Flickr App Gardn page](how-to-1.png)
+
+2. On the next page https://flickr.com/services/apps/create/apply click "[Apply for a Non-Commercial Key](https://flickr.com/services/apps/create/noncommercial)"
+
+   ![Screenshot of Flickr app application page](how-to-2.png)
+
 3. Fill in the form:
    - **Application Name**: anything you want (e.g. "Flickarr Export")
    - **Description**: anything (e.g. "Personal archive export")
+
+   ![Screenshot of Flickr API key creation page](how-to-3.png)
+
 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 -->
+![Screenshot of Flickr API key and secret confirmation page](how-to-4.png)
 
 ## 4. Initialize Flickarr
 
@@ -73,10 +81,12 @@ This starts the OAuth flow:
 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
+
+   ![Screenshot of Flickr verification page](how-to-5.png)
+
 5. Paste the code back into your terminal
 
-<!-- TODO: screenshot of Flickr OAuth authorization page -->
-<!-- TODO: screenshot of Flickr verification code page -->
+   ![Screenshot of Flickr auhorization code page](how-to-6.png)
 
 After authenticating, your access tokens, username, and user ID are saved to the config file. You only need to do this once.
 
@@ -134,7 +144,7 @@ flickarr export:albums
 Export a single album by URL:
 
 ```sh
-flickarr export:sets https://www.flickr.com/photos/USERNAME/sets/72157718538273371/
+flickarr export:sets https://flickr.com/photos/USERNAME/sets/72157718538273371/
 ```
 
 Collections (groups of albums) work the same way:
@@ -146,7 +156,7 @@ flickarr export:collections
 Export a single collection by URL:
 
 ```sh
-flickarr export:collections https://www.flickr.com/photos/USERNAME/collections/72157666222057746/
+flickarr export:collections https://flickr.com/photos/USERNAME/collections/72157666222057746/
 ```
 
 ## 10. Check your progress

data/lib/flickarr/cli.rb

@@ -4,7 +4,8 @@ module Flickarr
   class CLI
     DEFAULT_CONFIG_PATH = File.join(Dir.home, '.flickarr', 'config.yml').freeze
     VALID_CONFIG_KEYS = %i[access_secret access_token api_key last_page_photos last_page_posts last_page_videos
-                           library_path shared_secret total_collections total_photos total_sets total_videos
+                           latest_version latest_version_checked_at library_path shared_secret
+                           total_collections total_photos total_sets total_videos
                            user_nsid username].freeze
 
     def initialize args, config_path: DEFAULT_CONFIG_PATH
@@ -12,7 +13,7 @@ module Flickarr
       @limit       = nil
       @overwrite   = false
 
-      if args.empty? || %w[-h --help help].include?(args.first)
+      if args.empty? || %w[-h --help help -v --version version].include?(args.first)
         @args = args
       else
         @parser = build_parser
@@ -35,12 +36,15 @@ module Flickarr
       when 'export:photos'                                 then run_export_posts(media: 'photos')
       when 'export:profile'                                then run_export_profile
       when 'export:videos'                                 then run_export_posts(media: 'videos')
+      when '-v', '--version', 'version'                    then run_version
       when 'init'                                          then run_init
       when 'open'                                          then run_open
       when 'path'                                          then run_path
       when 'status'                                        then run_status
       else                                                      print_help
       end
+
+      check_for_update unless %w[-v --version version status -h --help help config config:set init].include?(command)
     end
 
     private
@@ -301,7 +305,13 @@ module Flickarr
       collection_count = count_subdirs(File.join(archive, 'Collections'))
       disk_usage       = human_size(dir_size(archive))
 
+      checker = Version.new(config)
+      checker.check
+      config.save(@config_path)
+      version_str = checker.update_message || "#{Flickarr::VERSION} (up to date)"
+
       rows = [
+        ['Version',     version_str],
         ['Archive',     archive],
         ['Profile',     profile_exists ? 'Downloaded' : 'Not downloaded'],
         ['Photos',      format_count(photo_count, config.total_photos)],
@@ -353,6 +363,35 @@ module Flickarr
       end
     end
 
+    def check_for_update
+      return unless File.exist?(@config_path)
+
+      config  = Config.load(@config_path)
+      checker = Version.new(config)
+      return unless checker.stale?
+
+      message = checker.update_message
+      config.save(@config_path)
+      return unless message
+
+      warn "\n#{message}"
+    rescue StandardError
+      nil
+    end
+
+    def run_version
+      config  = Config.load(@config_path)
+      checker = Version.new(config)
+      latest  = checker.check
+      config.save(@config_path)
+
+      if latest && Gem::Version.new(latest) > Gem::Version.new(Flickarr::VERSION)
+        puts "#{Flickarr::VERSION} (latest: #{latest} — run `gem update flickarr`)"
+      else
+        puts "#{Flickarr::VERSION} (up to date)"
+      end
+    end
+
     def count_subdirs path
       return 0 unless Dir.exist?(path)
 
@@ -471,6 +510,18 @@ module Flickarr
             end
             warn "Failed to fetch page #{page} after retries: #{e.message}"
             break
+          rescue Flickr::FailedResponse => e
+            if transient_flickr_error?(e)
+              page_retries -= 1
+              if page_retries.positive?
+                warn "Transient API error fetching page #{page}: #{e.message} — retrying in 5s (#{page_retries} left)"
+                sleep 5
+                retry
+              end
+              warn "Failed to fetch page #{page} after retries: #{e.message}"
+              break
+            end
+            raise
           end
           total       = response.total.to_i
           total_pages = response.pages.to_i
@@ -561,6 +612,17 @@ module Flickarr
         log_error archive: archive, post_id: post_id, username: config.username, error: e
         return
       rescue Flickr::FailedResponse => e
+        if transient_flickr_error?(e)
+          retries -= 1
+          if retries.positive?
+            warn "Transient API error on post #{post_id}: #{e.message} — retrying in 5s (#{retries} left)"
+            sleep 5
+            retry
+          end
+          warn "Failed post #{post_id} after retries: #{e.message}"
+          log_error archive: archive, post_id: post_id, username: config.username, error: e
+          return
+        end
         warn "Error on post #{post_id}: #{e.message}"
         log_error archive: archive, post_id: post_id, username: config.username, error: e
         return
@@ -579,6 +641,13 @@ module Flickarr
       end
     end
 
+    def transient_flickr_error? error
+      message = error.message.to_s.downcase
+      code    = error.respond_to?(:code) ? error.code.to_s : ''
+
+      code == '105' || message.include?('not currently available') || message.include?('service unavailable')
+    end
+
     def log_error archive:, post_id:, username:, error:
       log_path = File.join archive, '_errors.log'
       FileUtils.mkdir_p File.dirname(log_path)
@@ -707,6 +776,8 @@ module Flickarr
     end
 
     def print_help
+      puts "flickarr version #{Flickarr::VERSION}"
+      puts
       help_path = File.expand_path('../../HELP.txt', __dir__)
       puts File.read(help_path)
       puts

data/lib/flickarr/collection.rb

@@ -28,13 +28,15 @@ module Flickarr
     end
 
     def dirname
-      [id, slug].compact.join '_'
+      truncated = Post.truncate_slug(slug, id: id, ext: '')
+      [id, truncated].compact.join '_'
     end
 
     def sets_to_a
       @set_refs.map do |s|
         set_slug = s.title.to_s.slugify
-        set_dirname = [s.id, set_slug.empty? ? nil : set_slug].compact.join('_')
+        set_slug = Post.truncate_slug(set_slug, id: s.id, ext: '')
+        set_dirname = [s.id, set_slug].compact.join('_')
 
         {
           description: s.description.to_s,

data/lib/flickarr/config.rb

@@ -6,7 +6,8 @@ module Flickarr
     DEFAULT_LIBRARY_PATH = File.join(Dir.home, 'Pictures', 'Flickarr').freeze
 
     attr_accessor :access_secret, :access_token, :api_key, :last_page_photos, :last_page_posts, :last_page_videos,
-                  :library_path, :shared_secret, :total_collections, :total_photos, :total_sets, :total_videos,
+                  :latest_version, :latest_version_checked_at, :library_path, :shared_secret,
+                  :total_collections, :total_photos, :total_sets, :total_videos,
                   :user_nsid, :username
 
     def initialize
@@ -16,6 +17,8 @@ module Flickarr
       @last_page_photos = nil
       @last_page_posts = nil
       @last_page_videos = nil
+      @latest_version = nil
+      @latest_version_checked_at = nil
       @library_path = DEFAULT_LIBRARY_PATH
       @shared_secret = ENV.fetch('FLICKARR_SHARED_SECRET', nil)
       @total_collections = nil
@@ -43,20 +46,22 @@ module Flickarr
 
     def to_h
       {
-        access_secret:     access_secret,
-        access_token:      access_token,
-        api_key:           api_key,
-        last_page_photos:  last_page_photos,
-        last_page_posts:   last_page_posts,
-        last_page_videos:  last_page_videos,
-        library_path:      library_path,
-        shared_secret:     shared_secret,
-        total_collections: total_collections,
-        total_photos:      total_photos,
-        total_sets:        total_sets,
-        total_videos:      total_videos,
-        user_nsid:         user_nsid,
-        username:          username
+        access_secret:             access_secret,
+        access_token:              access_token,
+        api_key:                   api_key,
+        last_page_photos:          last_page_photos,
+        last_page_posts:           last_page_posts,
+        last_page_videos:          last_page_videos,
+        latest_version:            latest_version,
+        latest_version_checked_at: latest_version_checked_at,
+        library_path:              library_path,
+        shared_secret:             shared_secret,
+        total_collections:         total_collections,
+        total_photos:              total_photos,
+        total_sets:                total_sets,
+        total_videos:              total_videos,
+        user_nsid:                 user_nsid,
+        username:                  username
       }
     end
 
@@ -67,20 +72,22 @@ module Flickarr
       yaml = YAML.load_file(path, symbolize_names: true)
       return config unless yaml.is_a?(Hash)
 
-      config.access_secret     = yaml[:access_secret]     if yaml[:access_secret]
-      config.access_token      = yaml[:access_token]      if yaml[:access_token]
-      config.api_key           = yaml[:api_key]           if yaml[:api_key]
-      config.last_page_photos  = yaml[:last_page_photos]  if yaml[:last_page_photos]
-      config.last_page_posts   = yaml[:last_page_posts]   if yaml[:last_page_posts]
-      config.last_page_videos  = yaml[:last_page_videos]  if yaml[:last_page_videos]
-      config.library_path      = yaml[:library_path]      if yaml[:library_path]
-      config.shared_secret     = yaml[:shared_secret]     if yaml[:shared_secret]
-      config.total_collections = yaml[:total_collections] if yaml[:total_collections]
-      config.total_photos      = yaml[:total_photos]      if yaml[:total_photos]
-      config.total_sets        = yaml[:total_sets]        if yaml[:total_sets]
-      config.total_videos      = yaml[:total_videos]      if yaml[:total_videos]
-      config.user_nsid         = yaml[:user_nsid]         if yaml[:user_nsid]
-      config.username          = yaml[:username]          if yaml[:username]
+      config.access_secret              = yaml[:access_secret]              if yaml[:access_secret]
+      config.access_token               = yaml[:access_token]               if yaml[:access_token]
+      config.api_key                    = yaml[:api_key]                    if yaml[:api_key]
+      config.last_page_photos           = yaml[:last_page_photos]           if yaml[:last_page_photos]
+      config.last_page_posts            = yaml[:last_page_posts]            if yaml[:last_page_posts]
+      config.last_page_videos           = yaml[:last_page_videos]           if yaml[:last_page_videos]
+      config.latest_version             = yaml[:latest_version]             if yaml[:latest_version]
+      config.latest_version_checked_at  = yaml[:latest_version_checked_at]  if yaml[:latest_version_checked_at]
+      config.library_path               = yaml[:library_path]               if yaml[:library_path]
+      config.shared_secret              = yaml[:shared_secret]              if yaml[:shared_secret]
+      config.total_collections          = yaml[:total_collections]          if yaml[:total_collections]
+      config.total_photos               = yaml[:total_photos]               if yaml[:total_photos]
+      config.total_sets                 = yaml[:total_sets]                 if yaml[:total_sets]
+      config.total_videos               = yaml[:total_videos]               if yaml[:total_videos]
+      config.user_nsid                  = yaml[:user_nsid]                  if yaml[:user_nsid]
+      config.username                   = yaml[:username]                   if yaml[:username]
 
       config
     end

data/lib/flickarr/photo_set.rb

@@ -42,7 +42,8 @@ module Flickarr
     end
 
     def dirname
-      [id, slug].compact.join '_'
+      truncated = Post.truncate_slug(slug, id: id, ext: '')
+      [id, truncated].compact.join '_'
     end
 
     def photos_to_a
@@ -110,7 +111,8 @@ module Flickarr
     def relative_photo_path item
       ext  = item.media.to_s == 'video' ? 'mp4' : item.originalformat.to_s
       slug = item.title.to_s.slugify
-      base = [item.id, slug.empty? ? nil : slug].compact.join('_')
+      slug = Post.truncate_slug(slug, id: item.id, ext: ext)
+      base = [item.id, slug].compact.join('_')
       date = if item.datetakenunknown.to_i.zero?
                Date.parse item.datetaken
              else

data/lib/flickarr/post.rb

@@ -8,6 +8,7 @@ require 'yaml'
 module Flickarr
   class Post
     FLICKR_URL_PATTERN = %r{\Ahttps?://(?:www\.)?flickr\.com/photos/[^/]+/(\d+)}
+    MAX_FILENAME_BYTES = 255
 
     def self.build info:, sizes:, exif: nil
       case info.media.to_s
@@ -25,14 +26,25 @@ module Flickarr
       id       = item.id
       title    = item.title.to_s
       slug     = title.slugify
-      basename = [id, slug.empty? ? nil : slug].compact.join('_')
       ext      = item.media.to_s == 'video' ? 'mp4' : item.originalformat.to_s
+      slug     = truncate_slug(slug, id: id, ext: ext)
+      basename = [id, slug].compact.join('_')
       date     = compute_date_from_list_item(item)
       folder   = date.strftime '%Y/%m/%d'
 
       File.join archive_path, folder, "#{basename}.#{ext}"
     end
 
+    def self.truncate_slug slug, id:, ext:
+      return nil if slug.nil? || slug.empty?
+
+      # "id_slug.ext" must fit in MAX_FILENAME_BYTES
+      max_slug = MAX_FILENAME_BYTES - id.to_s.bytesize - ext.to_s.bytesize - 2 # underscore + dot
+      return slug if slug.bytesize <= max_slug
+
+      slug[0, max_slug].chomp('-')
+    end
+
     def self.compute_date_from_list_item item
       if item.datetakenunknown.to_i.zero?
         Date.parse item.datetaken
@@ -75,7 +87,9 @@ module Flickarr
     end
 
     def basename
-      [id, slug].compact.join '_'
+      longest_ext = [extension, 'yaml'].max_by(&:bytesize)
+      truncated = self.class.truncate_slug(slug, id: id, ext: longest_ext)
+      [id, truncated].compact.join '_'
     end
 
     def date_taken

data/lib/flickarr/version.rb

@@ -1,3 +1,67 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
 module Flickarr
-  VERSION = '0.1.4'.freeze
+  VERSION = '0.1.6'.freeze
+
+  class Version
+    RUBYGEMS_URL = 'https://rubygems.org/api/v1/gems/flickarr.json'.freeze
+    CACHE_TTL_SECONDS = 86_400 # 1 day
+
+    def initialize config
+      @config = config
+    end
+
+    def check
+      fetch_latest if stale?
+      @config.latest_version
+    end
+
+    def stale?
+      return true if @config.latest_version_checked_at.nil?
+
+      last_check = Time.parse(@config.latest_version_checked_at.to_s)
+      Time.now - last_check > CACHE_TTL_SECONDS
+    rescue ArgumentError
+      true
+    end
+
+    def update_available?
+      latest = check
+      return false unless latest
+
+      Gem::Version.new(latest) > Gem::Version.new(Flickarr::VERSION)
+    rescue ArgumentError
+      false
+    end
+
+    def update_message
+      latest = check
+      return nil unless latest
+
+      if Gem::Version.new(latest) > Gem::Version.new(Flickarr::VERSION)
+        "Update available: #{latest} (current: #{Flickarr::VERSION}) — run `gem update flickarr`"
+      end
+    rescue ArgumentError
+      nil
+    end
+
+    private
+
+    def fetch_latest
+      uri      = URI(RUBYGEMS_URL)
+      response = Net::HTTP.get_response(uri)
+      return unless response.is_a?(Net::HTTPSuccess)
+
+      data    = JSON.parse(response.body)
+      version = data['version']
+
+      @config.latest_version            = version
+      @config.latest_version_checked_at = Time.now.iso8601
+      version
+    rescue StandardError
+      nil
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flickarr
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Shane Becker
@@ -91,11 +91,16 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - HELP.txt
-- HOWTO.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- TODO.md
+- doc/HOWTO.md
+- doc/how-to-1.png
+- doc/how-to-2.png
+- doc/how-to-3.png
+- doc/how-to-4.png
+- doc/how-to-5.png
+- doc/how-to-6.png
 - exe/flickarr
 - lib/flickarr.rb
 - lib/flickarr/auth.rb

data/TODO.md

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