flickarr 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dd50d5580622268a50b6050a2d74bb4cca723d0d0e66c6238e5d86b017b952d
-  data.tar.gz: a50e621f678f3f8a3479ecef24dca5d448269adb7a714a803225e5ced9d9e1aa
+  metadata.gz: c94bc7b1f3ffc434e88faf5a632728406d6c297e2256354d5053af345be8d649
+  data.tar.gz: d2ed214497de643eab92773755bd4b33a655532266736fd4d964d0a3cf1a07a4
 SHA512:
-  metadata.gz: a1673833cb8cdd13da7166d9bb26576793cf19acfda964e0d94f068d565c73e66b59971921c13dcca0262999c1426860b2cc1e59ee9daa9b1bd15a0af3c34210
-  data.tar.gz: 0b0efcf5314432863584a1fb640b5353510df81fea003a0794c779c1e53e11dd3e5e1a79f938151319c4091a54017e156f7564b3018942fba4b5a78817bc4420
+  metadata.gz: 0060a46d0cb77a92dfaae7a5cc9a21f2979dfa4b7d36d67a3c3bfb2930702e00751f8f9a204455ceb74a55199f7f23f7b93f87e1955889d406326a0a673babb0
+  data.tar.gz: 439ae3fbb665d42b07302b34b7d9070ca06e5064d227f998fcf7c8cb5d0a74dd08adf2b9adceec22f7eecb8e7c1cfe274b4baaa431ee0900dcdd1b7efffd7af1

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [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

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

@@ -510,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
@@ -600,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
@@ -618,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)

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/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

@@ -3,7 +3,7 @@ require 'net/http'
 require 'uri'
 
 module Flickarr
-  VERSION = '0.1.5'.freeze
+  VERSION = '0.1.6'.freeze
 
   class Version
     RUBYGEMS_URL = 'https://rubygems.org/api/v1/gems/flickarr.json'.freeze

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flickarr
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Shane Becker
@@ -91,10 +91,16 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - HELP.txt
-- HOWTO.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- 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