@internetarchive/ia-book-actions 1.4.4-alpha14 → 1.4.4-alpha16

package/index.html

@@ -360,7 +360,33 @@
       });
     });
 
-    
+    // WEBDEV-8322 repro: fail only create_token (via ?failAction=create_token),
+    // leaving renew_loan (and every other action) succeeding normally —
+    // see actions-handler-service.js's shouldReturnError.
+    document.querySelectorAll('.failCreateToken input[type=checkbox]').forEach((item) => {
+      if (window.location.href.indexOf('?failAction=create_token') !== -1) {
+        item.checked = true;
+      }
+      item.addEventListener('click', (e) => {
+        console.log(`[Demo] fail-create_token-only mode ${e.target.checked ? 'enabled' : 'disabled'}`);
+
+        var searchParams = new URLSearchParams(window.location.search);
+        var separate = '';
+        if (e.target.checked) {
+          separate = '?';
+          searchParams.set('failAction', 'create_token');
+        } else {
+          separate = '';
+          searchParams.delete('failAction');
+        }
+
+        if (history.pushState) {
+          var newurl = window.location.protocol + "//" + window.location.host + window.location.pathname + separate + searchParams;
+          window.history.pushState({path:newurl},'',newurl);
+        }
+      });
+    });
+
     document.querySelectorAll('.userState input[type=checkbox]').forEach((item) => {
       item.addEventListener('click', (e) => {
         if (e.target.checked) {
@@ -726,6 +752,17 @@
                 </span>
               </td>
             </tr>
+            <tr colspan='5'>
+              <td class="failCreateToken">
+                <label><input type="checkbox" name="failCreateToken" value="failCreateToken" />Fail create_token only (renew_loan still succeeds)</label>
+                <span style="color: #666; font-size: 11px; display: block; padding: 0 10px 10px;">
+                  WEBDEV-8322 repro: unlike the checkbox above, this leaves renew_loan
+                  succeeding and fails only the create_token call right after it — turn
+                  this on, then run scenario 2 → 3 (or 2 → 4) below. Expect the error
+                  modal, and the bar/timer resetting to Borrow/0 (no retry).
+                </span>
+              </td>
+            </tr>
             <tr>
               <td class="userState">
                 <label><input type="checkbox" name="user" value="isAdmin" />isAdmin</label>

package/package.json

@@ -7,7 +7,7 @@
   },
   "author": "Internet Archive",
   "license": "AGPL-3.0-only",
-  "version": "1.4.4-alpha14",
+  "version": "1.4.4-alpha16",
   "main": "index.js",
   "module": "index.js",
   "publishConfig": {

package/src/core/services/actions-handler/actions-handler-service.js

@@ -18,7 +18,6 @@ export default async function ActionsHandlerService(options) {
   let baseHost = '/services/loans/loan';
   const location = window?.location;
 
-  // return error reponse when not production and has ?error=true param...
   const tokenError = 'loan token not found. please try again later.';
   const borrowError =
     'This book is not available to borrow at this time. Please try again later.';
@@ -29,9 +28,18 @@ export default async function ActionsHandlerService(options) {
     'renew_loan',
     'return_loan',
   ];
+  const searchParams = new URLSearchParams(location?.search);
+  // ?error=true fails every erroneous action (e.g. simulates the book
+  // already being borrowed by someone else). ?failAction=create_token (or
+  // any action name) fails ONLY that action, so a renew_loan can succeed
+  // and the immediately-following create_token can be made to fail —
+  // reproducing WEBDEV-8322's "renewed, but create_token failed" bug
+  // without needing a real book.
   const shouldReturnError =
-    new URLSearchParams(location?.search).get('error') === 'true' &&
-    location?.hostname !== 'archive.org';
+    location?.hostname !== 'archive.org' &&
+    erroneousActions.includes(option?.action) &&
+    (searchParams.get('error') === 'true' ||
+      searchParams.get('failAction') === option?.action);
 
   const testHostname = ['localhost', 'internetarchive.github.io'];
   let isTest = false;
@@ -51,7 +59,7 @@ export default async function ActionsHandlerService(options) {
     })
       .then(async response => {
         // intentional error on localhost
-        if (shouldReturnError && erroneousActions.includes(option?.action)) {
+        if (shouldReturnError) {
           return {
             success: false,
             error: option?.action === 'create_token' ? tokenError : borrowError,
@@ -109,8 +117,5 @@ export default async function ActionsHandlerService(options) {
      * connection is exactly when this fires.
      */
     log(`[IABookActions] ✗ ${option.action} threw`, error);
-    option?.error({
-      error: `Could not reach the lending service. Please check your connection and try again. (${error})`,
-    });
   }
 }

package/src/core/services/loan-token-poller.js

@@ -10,35 +10,42 @@ import log from './log.js';
  * ActionsHandlerService is a function being used to execute
  */
 export class LoanTokenPoller {
-  constructor(id, borrowType, successCallback, errorCallback, pollerDelay) {
-    this.identifier = id;
+  /**
+   * @param {Object} options
+   * @param {string} options.identifier
+   * @param {string} options.borrowType
+   * @param {Function} options.successCallback - called after the initial
+   *   loan token is created.
+   * @param {Function} options.errorCallback - called on any create_token
+   *   failure (initial or a routine interval tick).
+   * @param {number} options.pollerDelay - interval between routine
+   *   create_token checks, in seconds.
+   * @param {boolean} [options.skipInitialCall] - skip the immediate
+   *   create_token call, only start the recurring interval. Used after a
+   *   loan-expiry recovery renewal, where BookLoanService::
+   *   attempt_to_renew_loan() already minted a valid access token as part
+   *   of the renew_loan response itself — an immediate confirming
+   *   create_token call is redundant.
+   */
+  constructor(options = {}) {
+    const {
+      identifier,
+      borrowType,
+      successCallback,
+      errorCallback,
+      pollerDelay,
+      skipInitialCall = false,
+    } = options;
+
+    this.identifier = identifier;
     this.borrowType = borrowType;
     this.successCallback = successCallback; // callback function to be called after loan token is created
     this.errorCallback = errorCallback; // callback function to be called after loan token is created
     this.pollerDelay = pollerDelay; // value in seconds
+    this.skipInitialCall = skipInitialCall === true;
 
     this.loanTokenInterval = undefined;
 
-    /**
-     * Lending::do_renew() (backend) deletes the old loan record and
-     * writes a brand-new one on every renewal — this poller's initial
-     * create_token call (fired right after a renewal re-establishes the
-     * reading session) can race that write's propagation and come back
-     * with "you do not currently have this book borrowed" even though
-     * the loan is genuinely valid. Retry a few times with backoff instead
-     * of giving up on the first attempt.
-     */
-    this.maxTokenRetries = 3;
-    this.tokenRetryDelay = 1000; // ms, multiplied by attempt number
-
-    /**
-     * Handle for a pending retry, so teardown can cancel it. It's a bare
-     * setTimeout rather than an IALendingIntervals entry, so without this
-     * a retry scheduled just before the loan is returned would still fire
-     * its create_token afterwards.
-     */
-    this.retryTimeout = undefined;
-
     /**
      * loan analytics instance
      * @see loan-analytics.js
@@ -50,14 +57,18 @@ export class LoanTokenPoller {
 
   disconnectedCallback() {
     window?.IALendingIntervals?.clearTokenPoller();
-    clearTimeout(this.retryTimeout);
-    this.retryTimeout = undefined;
   }
 
   async bookAccessed() {
     if (this.borrowType) {
-      // Do an initial token, then set an interval
-      this.handleLoanTokenPoller(true);
+      if (this.skipInitialCall) {
+        log('[LoanTokenPoller] skipping initial create_token — already minted by the renewal response', {
+          identifier: this.identifier,
+        });
+      } else {
+        // Do an initial token, then set an interval
+        this.handleLoanTokenPoller(true);
+      }
 
       // if this.borrowType = adminBorrowed,
       // - we don't want to fetch token on interval
@@ -84,24 +95,21 @@ export class LoanTokenPoller {
   /**
    * @param {boolean} isInitial - the first create_token call right after
    *   bookAccessed()/a renewal, as opposed to a routine interval tick.
-   * @param {number} retryCount - internal, counts retries of the initial call.
    */
-  async handleLoanTokenPoller(isInitial = false, retryCount = 0) {
+  async handleLoanTokenPoller(isInitial = false) {
     const action = 'create_token';
     log('[LoanTokenPoller] create_token requested', {
       identifier: this.identifier,
       isInitial,
-      retryCount,
     });
     ActionsHandlerService({
       identifier: this.identifier,
       action,
-      error: data => this.handleTokenError(data, isInitial, retryCount),
+      error: data => this.handleTokenError(data, isInitial),
       success: () => {
         log('[LoanTokenPoller] create_token succeeded', {
           identifier: this.identifier,
           isInitial,
-          retryCount,
         });
         if (isInitial) this.successCallback();
       },
@@ -109,58 +117,23 @@ export class LoanTokenPoller {
   }
 
   /**
-   * Decide whether a create_token failure should be retried (a stale
-   * read of the loan record right after a renewal, see the constructor
-   * comment) or reported via errorCallback. Split out from
+   * Reports a create_token failure via errorCallback — no retry, it's
+   * treated as terminal on the first failure. Split out from
    * handleLoanTokenPoller so it's directly testable without needing to
    * mock the network call.
    *
    * @param {Object} data - the error payload from ActionsHandlerService.
    * @param {boolean} isInitial
-   * @param {number} retryCount
    */
-  handleTokenError(data, isInitial, retryCount) {
+  handleTokenError(data, isInitial) {
     const action = 'create_token';
-    const isStaleLoanReadError =
-      typeof data?.error === 'string' &&
-      /do not currently have this book borrowed/i.test(data.error);
 
     log('[LoanTokenPoller] create_token failed', {
       identifier: this.identifier,
       isInitial,
-      retryCount,
-      isStaleLoanReadError,
       error: data?.error,
     });
 
-    // The renewal write can be mid-propagation for an interval refresh too,
-    // not just the initial call — a routine tick landing moments after a
-    // renewal hits the same race. Retry both; isInitial only decides how a
-    // final failure is reported, not whether it's worth retrying.
-    if (isStaleLoanReadError && retryCount < this.maxTokenRetries) {
-      const delay = this.tokenRetryDelay * (retryCount + 1);
-      log(
-        '[LoanTokenPoller] retrying create_token after stale-loan-read error',
-        {
-          identifier: this.identifier,
-          nextRetryCount: retryCount + 1,
-          delay,
-        }
-      );
-      clearTimeout(this.retryTimeout);
-      this.retryTimeout = setTimeout(() => {
-        this.retryTimeout = undefined;
-        this.handleLoanTokenPoller(isInitial, retryCount + 1);
-      }, delay);
-      return;
-    }
-
-    log('[LoanTokenPoller] giving up on create_token, reporting error', {
-      identifier: this.identifier,
-      isInitial,
-      retryCount,
-    });
-
     // isInitial rides along so the consumer can distinguish "the book won't
     // open at all" from "a mid-read refresh blipped" — see
     // IABookActions.handleLendingActionError.

package/src/ia-book-actions.js

@@ -96,18 +96,6 @@ export default class IABookActions extends LitElement {
 
     this.loanRenewInProgress = false;
 
-    /**
-     * True while a create_token error modal is up and the token poller is
-     * retrying in the background. Cleared by startLoanTokenPoller()'s
-     * successCallback. See handleLendingActionError.
-     */
-    this.awaitingTokenRecovery = false;
-
-    /** Bounds how many times handleLendingActionError restarts the poller
-     * for one outage, so a genuinely-lost loan can't retry forever. */
-    this.tokenRecoveryAttempts = 0;
-    this.maxTokenRecoveryAttempts = 3;
-
     /**
      * True while recovering from a loan that genuinely lapsed (set by
      * autoRenewExpiredLoan), as opposed to a routine pre-expiry top-up.
@@ -116,6 +104,15 @@ export default class IABookActions extends LitElement {
      */
     this.recoveringFromLoanExpiry = false;
 
+    /**
+     * True right after a confirmed renewal (any kind), until the token
+     * poller restarts. renew_loan's own response already carries a valid
+     * access token, so that restart should skip its normal immediate
+     * create_token call — see handleLoanAutoRenewed/
+     * setupLendingToolbarActions.
+     */
+    this.skipNextInitialTokenCall = false;
+
     this.warningModalOpen = false;
 
     /** Once dismissed, don't re-show the warning modal every tick — only
@@ -301,14 +298,17 @@ export default class IABookActions extends LitElement {
 
     if (!this.applyLendingActions()) return;
 
-    // Don't (re)start the countdown mid-renewal (stale secondsLeftOnLoan)
-    // or while recovering a create_token failure (timers stopped
-    // deliberately — see handleLendingActionError).
-    if (
-      this.borrowType === 'browsed' &&
-      !this.loanRenewInProgress &&
-      !this.awaitingTokenRecovery
-    ) {
+    // primaryActions/borrowType/etc are plain fields, not reactive
+    // properties, so nothing pushes them to the rendered template (and
+    // from there to <collapsible-action-group>) on its own. Do that now,
+    // unconditionally — the early returns below (not borrowed, title bar)
+    // must not skip it, or the action bar visibly goes stale (e.g. a
+    // create_token failure resetting to Borrow never actually shows it).
+    this.requestUpdate();
+
+    // Don't (re)start the countdown mid-renewal — secondsLeftOnLoan could
+    // still be stale until handleLoanAutoRenewed() confirms it.
+    if (this.borrowType === 'browsed' && !this.loanRenewInProgress) {
       await this.startTimerCountdown();
       await this.startBrowseTimer();
     }
@@ -327,12 +327,16 @@ export default class IABookActions extends LitElement {
         !this.loanRenewInProgress &&
         !window.IALendingIntervals.tokenPoller
       ) {
+        // Any confirmed renewal's response already minted a valid access
+        // token (see handleLoanAutoRenewed) — the poller only needs to
+        // start its recurring check, not fire an immediate confirming
+        // create_token call too.
+        const skipInitialCall = this.skipNextInitialTokenCall;
+        this.skipNextInitialTokenCall = false;
         this.recoveringFromLoanExpiry = false;
-        this.startLoanTokenPoller();
+        this.startLoanTokenPoller(skipInitialCall);
       }
     }, 100);
-
-    this.requestUpdate();
   }
 
   /**
@@ -405,10 +409,6 @@ export default class IABookActions extends LitElement {
 
         if (this.borrowType !== 'browsed') return;
 
-        // Timers are deliberately stopped during create_token recovery
-        // (see handleLendingActionError) — leave them alone here.
-        if (this.awaitingTokenRecovery) return;
-
         if (this.lendingStatus.browsingExpired === false) {
           const loanTime = await this.localCache.get(
             `${this.identifier}-loanTime`
@@ -442,11 +442,9 @@ export default class IABookActions extends LitElement {
    * @param {Boolean} hasPageChanged
    */
   async autoLoanRenewChecker(hasPageChanged = false) {
-    // Re-entrancy guard against rapid BookReader:userAction events, and
-    // against restarting a renewal while still recovering the last one's
-    // create_token (loanRenewInProgress clears as soon as renew_loan
-    // itself succeeds, before that's known).
-    if (this.loanRenewInProgress || this.awaitingTokenRecovery) return;
+    // Re-entrancy guard against rapid BookReader:userAction events (e.g. a
+    // single scroll firing several in quick succession).
+    if (this.loanRenewInProgress) return;
 
     this.loanRenewHelper = new LoanRenewHelper(
       hasPageChanged,
@@ -465,14 +463,10 @@ export default class IABookActions extends LitElement {
    * handleLendingActionError() handle the outcome either way.
    */
   autoRenewExpiredLoan() {
-    if (this.loanRenewInProgress || this.awaitingTokenRecovery) {
+    if (this.loanRenewInProgress) {
       log(
         '[IABookActions] autoRenewExpiredLoan: skipped, renewal already in progress',
-        {
-          identifier: this.identifier,
-          loanRenewInProgress: this.loanRenewInProgress,
-          awaitingTokenRecovery: this.awaitingTokenRecovery,
-        }
+        { identifier: this.identifier }
       );
       return;
     }
@@ -761,10 +755,22 @@ export default class IABookActions extends LitElement {
         ajaxResponse: detail?.data,
       });
 
+      // BookLoanService::attempt_to_renew_loan() mints a valid access
+      // token as part of EVERY renew_loan response, not just a recovery
+      // from expiry — so the poller restart below never needs to fire a
+      // redundant confirming create_token call, regardless of which path
+      // triggered this renewal.
+      this.skipNextInitialTokenCall = true;
+
       if (this.recoveringFromLoanExpiry) {
         // Only now is it safe to re-initialize BookReader — not for a
-        // routine top-up, where that would be disruptive.
-        this.postInitComplete = false;
+        // routine top-up, where that would be disruptive. Call it
+        // directly rather than waiting on a confirming create_token
+        // success: BookLoanService::attempt_to_renew_loan() already
+        // minted a valid access token as part of this renew_loan
+        // response, so there's nothing left to confirm.
+        this.lendingBarPostInit();
+        this.postInitComplete = true;
       }
 
       const currStatus = {
@@ -916,59 +922,31 @@ export default class IABookActions extends LitElement {
 
   /**
    * enable access of borrowed/browsed books
+   * @param {boolean} [skipInitialCall] - see LoanTokenPoller's constructor doc
    * @see LoanTokenPoller
    */
-  startLoanTokenPoller() {
-    const successCallback = async () => {
+  startLoanTokenPoller(skipInitialCall = false) {
+    const successCallback = () => {
       if (!this.postInitComplete) {
         this.lendingBarPostInit();
       }
       this.postInitComplete = true;
-
-      if (this.awaitingTokenRecovery) {
-        log(
-          '[IABookActions] create_token recovered — closing error modal, resuming timer',
-          { identifier: this.identifier }
-        );
-        this.awaitingTokenRecovery = false;
-        this.tokenRecoveryAttempts = 0;
-        this.modal?.closeModal();
-        this.modal.removeAttribute('id');
-        this.modal.customModalContent = nothing;
-
-        // Recompute the true remaining time from the cache — not however
-        // long the outage lasted — before resuming the stopped timers.
-        const loanTime = await this.localCache.get(
-          `${this.identifier}-loanTime`
-        );
-        const rawSecondsLeft = Math.round((loanTime - new Date()) / 1000);
-        const secondsLeft =
-          Number.isFinite(rawSecondsLeft) && rawSecondsLeft > 0
-            ? rawSecondsLeft
-            : this.loanRenewTimeConfig.loanTotalTime;
-        this.lendingStatus = {
-          ...this.lendingStatus,
-          secondsLeftOnLoan: secondsLeft,
-        };
-        await this.startTimerCountdown();
-        await this.startBrowseTimer();
-      }
     };
     const errorCallback = eventObj => {
       this.handleLendingActionError(eventObj);
     };
 
-    // Tear down any previous poller first — otherwise its own pending
-    // internal retry timeout (see LoanTokenPoller.handleTokenError) is
-    // never cancelled and can fire later against stale state.
+    // Tear down any previous poller first, so only one is ever controlling
+    // window.IALendingIntervals.tokenPoller at a time.
     this.tokenPoller?.disconnectedCallback();
-    this.tokenPoller = new LoanTokenPoller(
-      this.identifier,
-      this.borrowType,
+    this.tokenPoller = new LoanTokenPoller({
+      identifier: this.identifier,
+      borrowType: this.borrowType,
       successCallback,
       errorCallback,
-      this.tokenDelay // in seconds
-    );
+      pollerDelay: this.tokenDelay, // in seconds
+      skipInitialCall,
+    });
   }
 
   /*
@@ -1005,38 +983,28 @@ export default class IABookActions extends LitElement {
     });
 
     if (action === 'create_token') {
-      // A create_token hiccup says nothing about how much time is left on
-      // the loan, so it must not stop the countdown by itself.
-      window?.IALendingIntervals?.clearTokenPoller();
-
-      // Only the INITIAL token matters enough to interrupt the patron —
-      // a routine interval refresh stays silent and just retries next tick.
+      // Only the INITIAL token matters enough to interrupt the patron — a
+      // routine interval refresh stays silent; the pages already loaded
+      // are still served, and the next scheduled poll tries again on its
+      // own without any special retry.
       if (!isInitial) {
         log(
-          '[IABookActions] create_token failed on interval refresh — staying silent, poller will retry'
+          '[IABookActions] create_token failed on interval refresh — staying silent'
         );
         return;
       }
 
-      // The loan itself is still active (do_renew succeeded) — don't touch
-      // lendingStatus, which would collapse borrowType to null and strand
-      // the poller from ever restarting. Still nothing to read right now
-      // though, so stop the countdown timers too; startLoanTokenPoller()'s
-      // successCallback resumes them once access recovers.
-      this.awaitingTokenRecovery = true;
-      window?.IALendingIntervals?.clearTimerCountdown();
-      window?.IALendingIntervals?.clearBrowseExpireTimeout();
-
-      // Bounded: a genuinely-lost (not just slow-to-propagate) loan would
-      // otherwise retry this forever.
-      this.tokenRecoveryAttempts += 1;
-      if (this.tokenRecoveryAttempts <= this.maxTokenRecoveryAttempts) {
-        this.startLoanTokenPoller();
-      } else {
-        log('[IABookActions] create_token recovery attempts exhausted', {
-          identifier: this.identifier,
-        });
-      }
+      // The book never opened, and we don't retry — reset the bar to
+      // Borrow and the timer to 0 rather than leaving a red "Return now"
+      // with a stale countdown for a session that isn't accessible.
+      window?.IALendingIntervals?.clearAll();
+      this.tokenPoller?.disconnectedCallback();
+      this.lendingStatus = {
+        ...this.lendingStatus,
+        user_has_browsed: false,
+        available_to_browse: true,
+        secondsLeftOnLoan: 0,
+      };
 
       // showErrorModal has dedicated create_token messaging (refresh
       // button + support email).

package/test/core/services/loan-token-poller.test.js

@@ -1,4 +1,4 @@
-import { expect, aTimeout } from '@open-wc/testing';
+import { expect } from '@open-wc/testing';
 import Sinon from 'sinon';
 
 import { LoanTokenPoller } from '../../../src/core/services/loan-token-poller.js';
@@ -17,18 +17,17 @@ afterEach(() => {
 
 describe('Get Loan Token', () => {
   it('get loan token for browsed books', async () => {
-    // id, borrowType, successCallback, errorCallback, pollerDelay
-    const tokenPoller = new LoanTokenPoller(
-      'identifier1',
-      'browsed',
-      () => {
+    const tokenPoller = new LoanTokenPoller({
+      identifier: 'identifier1',
+      borrowType: 'browsed',
+      successCallback: () => {
         console.log('success callback is executed!');
       },
-      () => {
+      errorCallback: () => {
         console.log('error callback is executed!');
       },
-      2000 // 2 minutes'
-    );
+      pollerDelay: 2000, // 2 minutes'
+    });
     const successCallbackSpy = Sinon.stub(tokenPoller, 'successCallback');
     successCallbackSpy();
     expect(successCallbackSpy.callCount).to.equal(1);
@@ -39,13 +38,13 @@ describe('Get Loan Token', () => {
   });
 
   it('get loan token for admin borrowed books', async () => {
-    const tokenPoller = new LoanTokenPoller(
-      'identifier1',
-      'adminBorrowed',
-      () => {},
-      () => {},
-      2000 // 2 minutes'
-    );
+    const tokenPoller = new LoanTokenPoller({
+      identifier: 'identifier1',
+      borrowType: 'adminBorrowed',
+      successCallback: () => {},
+      errorCallback: () => {},
+      pollerDelay: 2000, // 2 minutes'
+    });
 
     const successCallbackSpy = Sinon.stub(tokenPoller, 'successCallback');
     successCallbackSpy();
@@ -57,144 +56,99 @@ describe('Get Loan Token', () => {
   });
 });
 
-describe('handleTokenError retry (WEBDEV-8322 follow-up)', () => {
-  // Lending::do_renew() (backend) deletes the old loan record and writes
-  // a brand-new one on every renewal, so the initial create_token call
-  // right after a renewal can race that write's propagation and come
-  // back with this exact error even though the loan is genuinely valid.
-  const staleLoanReadError = {
-    error: 'You do not currently have this book borrowed.',
-  };
-
+describe('handleTokenError (no retry)', () => {
+  // A create_token failure is treated as terminal on the first attempt —
+  // no retry, whether it's the "stale loan read" race or anything else.
   const makeTokenPoller = () =>
-    new LoanTokenPoller(
-      'identifier1',
-      'browsed',
-      () => {},
-      () => {},
-      2000
-    );
-
-  it('retries the initial call on a stale-loan-read error instead of failing immediately', () => {
+    new LoanTokenPoller({
+      identifier: 'identifier1',
+      borrowType: 'browsed',
+      successCallback: () => {},
+      errorCallback: () => {},
+      pollerDelay: 2000,
+    });
+
+  it('reports the error immediately, without retrying, on the initial call', () => {
     const tokenPoller = makeTokenPoller();
     const handleLoanTokenPollerSpy = Sinon.spy(
       tokenPoller,
       'handleLoanTokenPoller'
     );
     const errorCallbackSpy = Sinon.spy(tokenPoller, 'errorCallback');
-    const clock = Sinon.useFakeTimers();
-
-    try {
-      tokenPoller.handleTokenError(staleLoanReadError, true, 0);
-
-      expect(errorCallbackSpy.called).to.be.false;
-
-      clock.tick(tokenPoller.tokenRetryDelay);
-
-      expect(handleLoanTokenPollerSpy.calledWith(true, 1)).to.be.true;
-    } finally {
-      clock.restore();
-    }
-  });
-
-  it('gives up and calls errorCallback after exhausting retries', () => {
-    const tokenPoller = makeTokenPoller();
-    const errorCallbackSpy = Sinon.spy(tokenPoller, 'errorCallback');
 
     tokenPoller.handleTokenError(
-      staleLoanReadError,
-      true,
-      tokenPoller.maxTokenRetries
+      { error: 'You do not currently have this book borrowed.' },
+      true
     );
 
     expect(errorCallbackSpy.calledOnce).to.be.true;
+    expect(handleLoanTokenPollerSpy.called).to.be.false;
   });
 
-  it('retries a routine (non-initial) poll on the same error too', () => {
-    // A routine tick landing moments after a renewal hits the very same
-    // write-propagation race as the initial call, so it's equally worth
-    // retrying. isInitial only decides how a FINAL failure is reported.
-    const tokenPoller = makeTokenPoller();
-    const handleLoanTokenPollerSpy = Sinon.spy(
-      tokenPoller,
-      'handleLoanTokenPoller'
-    );
-    const errorCallbackSpy = Sinon.spy(tokenPoller, 'errorCallback');
-    const clock = Sinon.useFakeTimers();
-
-    try {
-      tokenPoller.handleTokenError(staleLoanReadError, false, 0);
-
-      expect(errorCallbackSpy.called).to.be.false;
-
-      clock.tick(tokenPoller.tokenRetryDelay);
-
-      expect(handleLoanTokenPollerSpy.calledWith(false, 1)).to.be.true;
-    } finally {
-      clock.restore();
-    }
-  });
-
-  it('does not retry a genuinely different error, even on the initial call', () => {
+  it('reports the error immediately on a routine (non-initial) poll too', () => {
     const tokenPoller = makeTokenPoller();
     const errorCallbackSpy = Sinon.spy(tokenPoller, 'errorCallback');
 
     tokenPoller.handleTokenError(
-      { error: 'loan token not found. please try again later.' },
-      true,
-      0
+      { error: 'You do not currently have this book borrowed.' },
+      false
     );
 
     expect(errorCallbackSpy.calledOnce).to.be.true;
   });
-});
-
-describe('LoanTokenPoller - WEBDEV-8322 review fixes', () => {
-  it('retries a stale-loan-read error on interval refreshes too, not just the initial call', async () => {
-    const poller = new LoanTokenPoller('foo', 'browsed', () => {}, () => {}, 120);
-    poller.disconnectedCallback(); // stop the real poller started in the ctor
-
-    const retrySpy = Sinon.stub(poller, 'handleLoanTokenPoller');
-    poller.tokenRetryDelay = 1;
-
-    poller.handleTokenError(
-      { error: 'you do not currently have this book borrowed' },
-      false, // interval refresh
-      0
-    );
-    await aTimeout(30);
-
-    expect(retrySpy.calledOnce).to.be.true;
-    expect(retrySpy.firstCall.args).to.deep.equal([false, 1]);
-    poller.disconnectedCallback();
-  });
 
   it('passes isInitial through to the error callback', () => {
     const errorCallback = Sinon.spy();
-    const poller = new LoanTokenPoller('foo', 'browsed', () => {}, errorCallback, 120);
+    const poller = new LoanTokenPoller({
+      identifier: 'foo',
+      borrowType: 'browsed',
+      successCallback: () => {},
+      errorCallback,
+      pollerDelay: 120,
+    });
     poller.disconnectedCallback();
 
-    poller.handleTokenError({ error: 'something else went wrong' }, true, 0);
+    poller.handleTokenError({ error: 'something else went wrong' }, true);
 
     expect(errorCallback.calledOnce).to.be.true;
     expect(errorCallback.firstCall.args[0].detail.isInitial).to.be.true;
   });
+});
 
-  it('cancels a pending retry on teardown', async () => {
-    const poller = new LoanTokenPoller('foo', 'browsed', () => {}, () => {}, 120);
-    const retrySpy = Sinon.stub(poller, 'handleLoanTokenPoller');
-    poller.tokenRetryDelay = 20;
+describe('skipInitialCall option', () => {
+  it('starts the recurring interval but fires no immediate create_token call', () => {
+    const poller = new LoanTokenPoller({
+      identifier: 'foo',
+      borrowType: 'browsed',
+      successCallback: () => {},
+      errorCallback: () => {},
+      pollerDelay: 120,
+      skipInitialCall: true,
+    });
+    const handleLoanTokenPollerSpy = Sinon.spy(poller, 'handleLoanTokenPoller');
+
+    // bookAccessed() already ran in the constructor above (before the spy
+    // was attached) -- re-run it to observe whether it calls out.
+    poller.bookAccessed();
+
+    expect(handleLoanTokenPollerSpy.called).to.be.false;
+    expect(window.IALendingIntervals.tokenPoller).to.not.equal(0);
+    poller.disconnectedCallback();
+  });
 
-    poller.handleTokenError(
-      { error: 'you do not currently have this book borrowed' },
-      true,
-      0
-    );
-    expect(poller.retryTimeout).to.not.be.undefined;
+  it('fires the immediate call as usual when skipInitialCall is not set', () => {
+    const poller = new LoanTokenPoller({
+      identifier: 'foo',
+      borrowType: 'browsed',
+      successCallback: () => {},
+      errorCallback: () => {},
+      pollerDelay: 120,
+    });
+    const handleLoanTokenPollerSpy = Sinon.spy(poller, 'handleLoanTokenPoller');
 
-    poller.disconnectedCallback();
-    await aTimeout(60);
+    poller.bookAccessed();
 
-    expect(retrySpy.called).to.be.false;
+    expect(handleLoanTokenPollerSpy.calledWith(true)).to.be.true;
+    poller.disconnectedCallback();
   });
 });

package/test/ia-book-actions.test.js

@@ -479,8 +479,7 @@ describe('Browsing expired status', () => {
   });
 });
 
-describe('Auto renew one hour loan', async () => {
-  await aTimeout(5000);
+describe('Auto renew one hour loan', () => {
   it('Book is browsing and renewed it now', async () => {
     const loanTime = 88;
     const el = await fixture(
@@ -553,8 +552,7 @@ describe('Auto renew one hour loan', async () => {
   });
 });
 
-describe('Visibility change API for document', async () => {
-  await aTimeout(5000);
+describe('Visibility change API for document', () => {
 
   beforeEach(() => {
     Object.defineProperty(document, 'hidden', {
@@ -578,6 +576,10 @@ describe('Visibility change API for document', async () => {
         lendingStatus: {
           user_has_browsed: true,
           browsingExpired: false,
+          // Without this, startBrowseTimer() computes setTimeout(fn,
+          // undefined * 1000) -> NaN, which fires almost immediately and
+          // expires the loan before this test ever dispatches its event.
+          secondsLeftOnLoan: 3600,
         },
       })
     );
@@ -605,6 +607,7 @@ describe('Visibility change API for document', async () => {
         lendingStatus: {
           user_has_browsed: true,
           browsingExpired: false,
+          secondsLeftOnLoan: 3600,
         },
       })
     );
@@ -755,35 +758,6 @@ describe('autoRenewExpiredLoan', () => {
     expect(el.loanRenewResult.renewNow).to.be.true;
   });
 
-  it('does not start a new renewal while awaiting create_token recovery from the last one', async () => {
-    // loanRenewInProgress clears as soon as renew_loan itself succeeds
-    // (see handleLoanAutoRenewed), before create_token is known to work.
-    // A visibilitychange/userAction landing in that window must not kick
-    // off ANOTHER renewal — that repeats the do_renew() delete+create
-    // write for no reason. See WEBDEV-8322 production log, 2026-09-28.
-    const el = await fixture(
-      container({
-        userid: '@user1',
-        identifier: 'foobar',
-        lendingStatus: {
-          user_has_browsed: true,
-          browsingExpired: true,
-        },
-      })
-    );
-    await el.updateComplete;
-
-    el.loanRenewInProgress = false;
-    el.awaitingTokenRecovery = true;
-
-    const spy = Sinon.spy(el, 'autoRenewExpiredLoan');
-    el.autoRenewExpiredLoan();
-
-    expect(spy.callCount).to.equal(1);
-    expect(el.loanRenewInProgress).to.be.false;
-    expect(el.loanRenewResult.renewNow).to.be.false;
-  });
-
   it('clears loanRenewInProgress after a successful loanAutoRenewed event', async () => {
     const el = await fixture(
       container({
@@ -969,6 +943,100 @@ describe('autoRenewExpiredLoan', () => {
     expect(el.lendingBarPostInit.called).to.be.false;
   });
 
+  it('also skips the initial create_token after a routine (non-expiry) renewal', async () => {
+    // BookLoanService::attempt_to_renew_loan() mints the access token as
+    // part of EVERY renew_loan response, not just a recovery from expiry.
+    // A routine top-up also has its poller stopped mid-renewal (see
+    // updated()'s clearAll() on loanRenewResult.renewNow), so it would
+    // otherwise fire this same redundant call once the poller restarts.
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: { user_has_browsed: true, browsingExpired: false },
+      })
+    );
+    await el.updateComplete;
+    el.postInitComplete = true;
+
+    await el.localCache.set({
+      key: 'foobar-loanTime',
+      value: new Date(new Date().getTime() + 3600 * 1000),
+      ttl: 3600,
+    });
+
+    const startTokenPollerSpy = Sinon.spy(el, 'startLoanTokenPoller');
+
+    // Triggers updated()'s clearAll(), stopping the running poller, same
+    // as a real routine top-up would.
+    el.loanRenewResult = { texts: '', renewNow: true, renewType: 'auto' };
+    await el.updateComplete;
+
+    const collapsibleActionGroupEl = el.shadowRoot.querySelector(
+      'collapsible-action-group'
+    );
+    collapsibleActionGroupEl.dispatchEvent(
+      new CustomEvent('loanAutoRenewed', {
+        detail: { data: { loan: { identifier: 'foobar', renewal: true } } },
+      })
+    );
+
+    await aTimeout(200);
+    await el.updateComplete;
+
+    expect(startTokenPollerSpy.calledOnceWith(true)).to.be.true;
+  });
+
+  it('calls lendingBarPostInit directly on a recovery renewal and skips the initial create_token', async () => {
+    // BookLoanService::attempt_to_renew_loan() now mints the access token
+    // as part of the renew_loan response itself (using the just-written
+    // loan record already in memory, not a separate read) -- so recovering
+    // from a genuine expiry no longer needs to wait on a confirming
+    // create_token success before re-initializing BookReader, and the
+    // poller it starts afterward shouldn't fire a redundant immediate call.
+    const el = await fixture(
+      container({
+        userid: '@user1',
+        identifier: 'foobar',
+        lendingStatus: {
+          user_has_browsed: true,
+          browsingExpired: true,
+        },
+      })
+    );
+    await el.updateComplete;
+    el.lendingBarPostInit = Sinon.spy();
+
+    await el.localCache.set({
+      key: 'foobar-loanTime',
+      value: new Date(new Date().getTime() + 3600 * 1000),
+      ttl: 3600,
+    });
+
+    const startTokenPollerSpy = Sinon.spy(el, 'startLoanTokenPoller');
+
+    el.autoRenewExpiredLoan();
+    await el.updateComplete;
+    await aTimeout(50); // let autoRenewExpiredLoan's setTimeout(0) set renewNow
+
+    await el.handleLoanAutoRenewed({
+      detail: {
+        action: 'renew_loan',
+        data: { success: true, loan: { identifier: 'foobar', renewal: true } },
+      },
+    });
+
+    // Called synchronously from handleLoanAutoRenewed, not via a
+    // create_token success callback.
+    expect(el.lendingBarPostInit.calledOnce).to.be.true;
+    expect(el.postInitComplete).to.be.true;
+
+    await el.updateComplete;
+    await aTimeout(150); // let the 100ms token-poller-restart check run
+
+    expect(startTokenPollerSpy.calledOnceWith(true)).to.be.true;
+  });
+
   it('clears loanRenewInProgress and shows unavailable modal on renew_loan failure', async () => {
     const el = await fixture(
       container({
@@ -1130,14 +1198,11 @@ describe('handleLendingActionError - create_token failures must not stop the cou
     expect(window.IALendingIntervals.timerCountdown).to.not.equal(0);
   });
 
-  it('shows the error modal for a create_token failure that reaches here (retries already exhausted)', async () => {
-    // By the time handleLendingActionError runs for a create_token
-    // failure, LoanTokenPoller has already retried and given up (see
-    // loan-token-poller.js's handleTokenError). For the INITIAL token
-    // that's terminal — BookReader can't be initialized and the book
-    // won't open — so the patron must be told rather than left staring
-    // at nothing. (An interval refresh failing is handled separately and
-    // stays silent; see the WEBDEV-8322 review fixes below.)
+  it('shows the error modal and resets to Borrow/0 on a failed INITIAL create_token (no retry)', async () => {
+    // For the INITIAL token, BookReader never got page images — the book
+    // never opened. We don't retry, so the bar must reflect that honestly
+    // (Borrow, 0 left) instead of staying red with a stale countdown for a
+    // session that isn't actually accessible.
     const el = await fixture(
       container({
         userid: '@user1',
@@ -1164,24 +1229,16 @@ describe('handleLendingActionError - create_token failures must not stop the cou
 
     expect(showErrorModalSpy.calledOnceWith(errorMsg, 'create_token')).to.be
       .true;
-    // The loan itself is still active (do_renew succeeded) — flipping this
-    // to false used to collapse borrowType to null in
-    // getCurrentLendingActions(), which made setupLendingToolbarActions()
-    // bail out before ever restarting the token poller, silently
-    // stranding the patron until the countdown force-returned the book.
-    // See WEBDEV-8322 production log, 2026-09-28.
-    expect(el.lendingStatus.user_has_browsed).to.be.true;
-    expect(el.awaitingTokenRecovery).to.be.true;
+    expect(el.lendingStatus.user_has_browsed).to.be.false;
+    expect(el.lendingStatus.available_to_browse).to.be.true;
+    expect(el.lendingStatus.secondsLeftOnLoan).to.equal(0);
   });
 
   it('stops the countdown/expiry timers on a failed INITIAL create_token — nothing to read yet', async () => {
     // Unlike the interval-refresh case above (pages already loaded, keep
-    // ticking), an initial create_token failure means BookReader never
-    // got page images — there's nothing to read. Letting the countdown
-    // keep running just re-syncs on every single tick against a broken
-    // session (see WEBDEV-8322 QA log, 2026-09-28) until the loan
-    // eventually force-expires. Stop both timers instead; they resume
-    // once startLoanTokenPoller()'s successCallback confirms recovery.
+    // ticking), an initial create_token failure means BookReader never got
+    // page images and we're resetting the bar to Borrow — both timers
+    // should stop rather than keep counting down a dead session.
     const el = await fixture(
       container({
         userid: '@user1',
@@ -1582,70 +1639,6 @@ describe('WEBDEV-8322 review fixes', () => {
     expect(el.lendingStatus.user_has_browsed).to.be.true;
   });
 
-  it('surfaces a failed initial create_token, which blocks opening the book', async () => {
-    const el = await fixture(
-      container({
-        userid: '@user1',
-        identifier: 'token-initial',
-        lendingStatus: {
-          is_lendable: true,
-          available_to_browse: true,
-          user_has_browsed: true,
-          browsingExpired: false,
-          secondsLeftOnLoan: 300,
-        },
-      })
-    );
-    await el.updateComplete;
-    const spy = Sinon.spy(el, 'showErrorModal');
-
-    el.handleLendingActionError({
-      detail: {
-        action: 'create_token',
-        isInitial: true,
-        data: { error: 'loan token not found. please try again later.' },
-      },
-    });
-    await el.updateComplete;
-
-    expect(spy.calledOnce).to.be.true;
-    // Still reading — see the identical assertion above for why this must
-    // stay true (WEBDEV-8322 production log, 2026-09-28).
-    expect(el.lendingStatus.user_has_browsed).to.be.true;
-    expect(el.awaitingTokenRecovery).to.be.true;
-  });
-
-  it('does not resume the countdown via visibilitychange while awaiting create_token recovery', async () => {
-    // Regression: visibilitychange's resync path didn't check
-    // awaitingTokenRecovery, so backgrounding/foregrounding the tab during
-    // a create_token outage could resume the timers that
-    // handleLendingActionError had deliberately stopped, and auto-return a
-    // loan the server still considers valid.
-    const el = await fixture(
-      container({
-        userid: '@user1',
-        identifier: 'foobar',
-        lendingStatus: {
-          user_has_browsed: true,
-          browsingExpired: false,
-          secondsLeftOnLoan: 300,
-        },
-      })
-    );
-    await el.updateComplete;
-    el.awaitingTokenRecovery = true;
-
-    const spy = Sinon.spy(el, 'loanStatusCheckInterval');
-    Object.defineProperty(document, 'hidden', {
-      value: false,
-      configurable: true,
-    });
-    document.dispatchEvent(new Event('visibilitychange'));
-    await aTimeout(100);
-
-    expect(spy.called).to.be.false;
-  });
-
   it('tears down the previous poller before starting a new one', async () => {
     // Regression: startLoanTokenPoller() always replaced this.tokenPoller
     // without cancelling the old instance's pending internal retry timer,
@@ -1675,9 +1668,7 @@ describe('WEBDEV-8322 review fixes', () => {
     expect(el.tokenPoller).to.not.equal(firstPoller);
   });
 
-  it('stops restarting the poller after maxTokenRecoveryAttempts consecutive create_token failures', async () => {
-    // Regression: an outer restart loop with no cap meant a genuinely-lost
-    // (not just slow-to-propagate) loan retried forever.
+  it('never restarts the poller on a create_token failure — no retry', async () => {
     const el = await fixture(
       container({
         userid: '@user1',
@@ -1694,19 +1685,15 @@ describe('WEBDEV-8322 review fixes', () => {
     await el.updateComplete;
 
     const startSpy = Sinon.spy(el, 'startLoanTokenPoller');
-    const errorMsg = 'loan token not found. please try again later.';
 
-    for (let i = 0; i < el.maxTokenRecoveryAttempts + 1; i += 1) {
-      el.handleLendingActionError({
-        detail: {
-          action: 'create_token',
-          isInitial: true,
-          data: { error: errorMsg },
-        },
-      });
-    }
+    el.handleLendingActionError({
+      detail: {
+        action: 'create_token',
+        isInitial: true,
+        data: { error: 'loan token not found. please try again later.' },
+      },
+    });
 
-    expect(startSpy.callCount).to.equal(el.maxTokenRecoveryAttempts);
-    expect(el.tokenRecoveryAttempts).to.equal(el.maxTokenRecoveryAttempts + 1);
+    expect(startSpy.called).to.be.false;
   });
 });