From 64da65f47a34f3724e511d26446e8dc16f9c886f Mon Sep 17 00:00:00 2001
From: Noah Zentzis <noahz@fal.ai>
Date: Mon, 17 Nov 2025 11:20:21 -0800
Subject: [PATCH 1/2] feat: add API to ensure CDN token validity

This commit adds a new `valid_for` parameter that allows callers to
assert that a CDN token should be valid for a specified time period.
---
 .../fal/src/fal/toolkit/file/providers/fal.py | 30 +++++++++++++++----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/projects/fal/src/fal/toolkit/file/providers/fal.py b/projects/fal/src/fal/toolkit/file/providers/fal.py
index e03b42f76..aa989eba6 100644
--- a/projects/fal/src/fal/toolkit/file/providers/fal.py
+++ b/projects/fal/src/fal/toolkit/file/providers/fal.py
@@ -7,7 +7,7 @@
 from base64 import b64encode
 from contextlib import contextmanager
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Dict, Generator, Generic, TypeVar
 from urllib.error import HTTPError, URLError
@@ -95,8 +95,21 @@ class FalV2Token:
     base_upload_url: str
     expires_at: datetime
 
-    def is_expired(self) -> bool:
-        return datetime.now(timezone.utc) >= self.expires_at
+    def is_expired(self, offset: timedelta | int | None = None) -> bool:
+        """
+        Return whether the token has expired.
+
+        If `offset` is provided, return whether the token *will have* expired as of
+        `now + offset`, rather than whether it is *currently* expired. Offsets can be
+        either a number of seconds or a `timedelta` object.
+        """
+        as_of = datetime.now(timezone.utc)
+        if offset is not None:
+            if isinstance(offset, timedelta):
+                as_of += offset
+            else:
+                as_of += timedelta(seconds=offset)
+        return as_of >= self.expires_at
 
 
 class FalV3Token(FalV2Token):
@@ -117,9 +130,16 @@ def __init__(self):
         )
         self._lock: threading.Lock = threading.Lock()
 
-    def get_token(self) -> FalV2Token:
+    def get_token(self, valid_for: timedelta | int | None = None) -> FalV2Token:
+        """
+        Get a valid authentication token.
+
+        If `valid_for` is specified, return a token that's guaranteed to remain valid
+        for the specified duration. Durations can be specified as an integer number of
+        seconds, or as a `timedelta` object.
+        """
         with self._lock:
-            if self._token.is_expired():
+            if self._token.is_expired(offset=valid_for):
                 self._refresh_token()
             return self._token
 

From 3c484efcc71a5ee59b5a1338154918221083b0bc Mon Sep 17 00:00:00 2001
From: Noah Zentzis <noahz@fal.ai>
Date: Mon, 17 Nov 2025 11:27:36 -0800
Subject: [PATCH 2/2] chore: change default token validity interval to 1h

---
 projects/fal/src/fal/toolkit/file/providers/fal.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/projects/fal/src/fal/toolkit/file/providers/fal.py b/projects/fal/src/fal/toolkit/file/providers/fal.py
index aa989eba6..97a76b7d1 100644
--- a/projects/fal/src/fal/toolkit/file/providers/fal.py
+++ b/projects/fal/src/fal/toolkit/file/providers/fal.py
@@ -130,7 +130,10 @@ def __init__(self):
         )
         self._lock: threading.Lock = threading.Lock()
 
-    def get_token(self, valid_for: timedelta | int | None = None) -> FalV2Token:
+    def get_token(
+        self,
+        valid_for: timedelta | int | None = timedelta(hours=1),
+    ) -> FalV2Token:
         """
         Get a valid authentication token.