philiprehberger-jwt_kit 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cd6d9f8d91d59046e8427bb209a93e9220a3ff0398ef1c84758a9396fae2eb7
-  data.tar.gz: 9fc834f733af1020130928f51ee99ff24d94f468c64ab86a638d7859dbba658e
+  metadata.gz: '09b9eb684b43c1e022244bc53c710d7ac590f454dde228d2bc2cf7ba6217810e'
+  data.tar.gz: 78e35b5e7712bde020b168ea4ba9077b2fc12c0735a967042339aab148b24254
 SHA512:
-  metadata.gz: 2751b52e541a834214dee62b4eaa136798d7f244900c206e063738dae3fd2ae90a2c350916ca82dcf714558028eeecb96ea4ac269a02ede7d6bb7c7c5116b7f2
-  data.tar.gz: 44de4708a12b6bf7b0317a98db9a05d3375a5083791cd126458b9f63f716942a054a4de5327a6a13c918fe1421936a72f5e19451c402f9dbb75070d234169b47
+  metadata.gz: 41bbac9795276d4770337b6b71d660a53fc7ddee64460acb262fa302c40845e798af3db2889ada71ff1149e957283671d2fabf1ef98fcc1ceb98cf1b9ba8f2bd
+  data.tar.gz: 3d74d20e81228260558cb80a2cb69b2986f9c276798a1cec102fbe41abc41311b123e204683354b2bbf8810d917fb79dfce24ab2c3d90cc88f4743180f8d85f3

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-31
+
+### Added
+- `JwtKit.time_to_expiry(token)` returns the seconds remaining until the token's `exp` claim. Negative for already-expired tokens; `nil` for malformed tokens or tokens without a numeric `exp`. Pairs with `expired?` for pre-emptive refresh scheduling.
+- README now includes the standard package card image after the badges.
+
 ## [0.5.0] - 2026-04-26
 
 ### Added

data/README.md

@@ -4,6 +4,8 @@
 [![Gem Version](https://badge.fury.io/rb/philiprehberger-jwt_kit.svg)](https://rubygems.org/gems/philiprehberger-jwt_kit)
 [![Last updated](https://img.shields.io/github/last-commit/philiprehberger/rb-jwt-kit)](https://github.com/philiprehberger/rb-jwt-kit/commits/main)
 
+![philiprehberger-jwt_kit](https://raw.githubusercontent.com/philiprehberger/rb-jwt-kit/main/package-card.webp)
+
 Opinionated JWT toolkit for Ruby — secure by default, with support for encoding, validation, refresh tokens, revocation, and key rotation
 
 ## Requirements
@@ -117,6 +119,16 @@ Philiprehberger::JwtKit.expired?(token)  # => false
 # Use to decide whether to refresh before the authoritative decode
 ```
 
+### Time to Expiry
+
+Get the seconds remaining until the token's `exp` claim. Negative when expired, `nil` when the token is malformed or has no numeric `exp`. Useful for scheduling pre-emptive refreshes rather than reacting after the fact:
+
+```ruby
+Philiprehberger::JwtKit.time_to_expiry(token)  # => 3599
+# refresh when fewer than 60 seconds remain
+Philiprehberger::JwtKit.refresh(refresh_token) if Philiprehberger::JwtKit.time_to_expiry(token).to_i < 60
+```
+
 ### Audience Validation
 
 ```ruby
@@ -224,6 +236,7 @@ Callbacks fire only after a successful operation. Exceptions raised inside a cal
 | `JwtKit.revoked?(token)` | Checks if a token has been revoked |
 | `JwtKit.peek(token)` | Decode header and payload without signature verification |
 | `JwtKit.expired?(token)` | Check `exp` claim without verifying the signature |
+| `JwtKit.time_to_expiry(token)` | Seconds remaining until `exp`; negative when expired, nil when unknown |
 | `JwtKit.revocation_store=` | Set a custom revocation store |
 | `MemoryStore#cleanup!(max_age:)` | Remove revocation entries older than max_age seconds |
 | `Configuration#on_encode { \|token, payload\| ... }` | Register a callback fired after a successful encode |

data/lib/philiprehberger/jwt_kit/version.rb

@@ -2,6 +2,6 @@
 
 module Philiprehberger
   module JwtKit
-    VERSION = '0.5.0'
+    VERSION = '0.6.0'
   end
 end

data/lib/philiprehberger/jwt_kit.rb

@@ -73,6 +73,23 @@ module Philiprehberger
         true
       end
 
+      # Seconds remaining until a token's `exp` claim. Does not verify the
+      # signature. Returns a negative integer for already-expired tokens and
+      # `nil` for malformed tokens or tokens without a numeric `exp` claim.
+      # Useful for scheduling a refresh before expiration rather than after.
+      #
+      # @param token [String] JWT token
+      # @return [Integer, nil] seconds remaining, or nil when undeterminable
+      def time_to_expiry(token)
+        payload = peek(token)[:payload]
+        exp = payload['exp']
+        return nil unless exp.is_a?(Numeric)
+
+        exp.to_i - Time.now.to_i
+      rescue DecodeError
+        nil
+      end
+
       # Encodes a payload into a signed JWT token.
       #
       # @param payload [Hash] custom claims

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: philiprehberger-jwt_kit
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Philip Rehberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-06-01 00:00:00.000000000 Z
 dependencies: []
 description: A complete JWT toolkit for Ruby. Encode and decode tokens with automatic
   claim management (exp, iat, iss, jti), generate access/refresh token pairs, validate