@internetarchive/ia-book-actions 1.4.4-alpha9 → 1.4.6-alpha1

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-alpha9",
+  "version": "1.4.6-alpha1",
   "main": "index.js",
   "module": "index.js",
   "publishConfig": {

package/src/assets/data/info-icon.js

@@ -0,0 +1,17 @@
+import { html } from 'lit';
+
+export const infoIcon = html`<svg
+  height="20"
+  width="20"
+  viewBox="0 0 100 100"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <g fill="none" fill-rule="evenodd">
+    <path d="m0 0h100v100h-100z" fill="#fff" />
+    <path
+      d="m49.8315487 0h.1702245c6.7356878 0 13.1853038 1.31117332 19.3488483 3.93351997 6.1635444 2.62234664 11.4854233 6.15778963 15.9656369 10.60632903 4.4802135 4.4485394 8.0478347 9.7522946 10.7028636 15.9112655 2.655029 6.1589709 3.980878 12.6038012 3.9789971 19.3344909.0567419 6.6716279-1.1702933 13.0585776-3.6811042 19.1608491-2.510811 6.1022715-6.106803 11.5206067-10.7879759 16.2550055-9.7027949 9.7522946-21.4884754 14.6851412-35.3570414 14.79854h-.1702244c-6.7333236 0-13.1829397-1.3111733-19.3488483-3.93352-6.1659087-2.6223466-11.4877876-6.1577896-15.9656369-10.606329s-8.04547055-9.7522946-10.7028637-15.9112655c-2.65739314-6.1589709-3.9844243-12.6038012-3.98254337-19.3344909-.05674149-6.6716279 1.17029325-13.0585776 3.68110421-19.1608491 2.51081095-6.1022715 6.10680292-11.5206067 10.78797586-16.2550055 9.7027949-9.75229456 21.4884754-14.68514123 35.3570414-14.79854zm12.6566146 26.4757998c1.6745578-1.6828001 2.5118367-3.6747334 2.5118367-5.9757998 0-2.4126333-.8095238-4.4324583-2.4285714-6.059475s-3.6289796-2.440525-6.0297959-2.440525c-2.4008164 0-4.4107483.8135083-6.029796 2.440525-1.6745578 1.6270167-2.5118367 3.6468417-2.5118367 6.059475 0 2.1871753.8372789 4.1791086 2.5118367 5.9757998 1.6745579 1.6828001 3.6844898 2.5242002 6.029796 2.5242002 2.3453061 0 4.3274829-.8414001 5.9465306-2.5242002zm-12.1370589 52.7776981-1.2815282-.9486968c0-.4588935.398855-1.8938272 1.196565-4.3048011l12.7338588-39-23.0745876 3.6164609.2548896 3.873251c0-.1141289.4554971-.1997256 1.3664914-.2567901.9109942 0 1.623741.1723823 2.1382404.5171468.5121392.2306356.7965299.6039323.8531721 1.1198902 0 .8607225-.6549247 3.2134431-1.9647739 7.0581619l-8.1175252 24.1061729c-1.0242785 3.2716963-1.5080967 5.5388203-1.4514546 6.8013717.0566421 1.6643804.8826732 2.9839963 2.4780932 3.9588477 1.2532071.803658 2.8769482 1.205487 4.8712231 1.205487h.5982825c1.7653464-.0570645 3.8445846-.3875629 6.2377146-.9914952 2.3931299-.6039323 4.3590839-1.3933242 5.8978617-2.3681756 1.3098493-.803658 2.3919499-1.5359853 3.2463021-2.1969821.8543521-.6609968 1.3959925-1.1341564 1.6249211-1.4194788l.3433929-.3459533-2.8214861-3.3596708-2.9914125 2.0650205c-.79771.4588935-1.5104568.7454047-2.1382404.8595337z"
+      fill="#000"
+      fill-rule="nonzero"
+    />
+  </g>
+</svg> `;

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

@@ -1,7 +1,22 @@
 /* eslint-disable */
 import { sentryLogs } from '../../config/sentry-events.js';
+import {
+  sentryCaptureMessage,
+  sentryCaptureException,
+} from '../sentry-report.js';
 import log from '../log.js';
 
+/**
+ * Patron-facing messages for failures that never reached the lending
+ * service's own JSON error handling.
+ */
+export const unexpectedResponseError = status =>
+  `Unexpected response from the lending service (HTTP ${status}). Please try again.`;
+export const networkError =
+  'Could not reach the lending service. Please check your connection and try again.';
+export const unexpectedError =
+  'Something went wrong handling the lending service response. Please try again.';
+
 /**
  * Helper to call loan service
  * @param {Object} options
@@ -18,7 +33,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 +43,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;
@@ -44,14 +67,21 @@ export default async function ActionsHandlerService(options) {
   formData.append('action', option.action);
   formData.append('identifier', option.identifier);
 
+  // Set once a response arrives, so the catch below can tell a failed fetch
+  // (a real network problem) from anything thrown afterwards — including by
+  // the caller's own success/error callback, which run inside this try.
+  let reachedResponse = false;
+
   try {
     await fetch(baseHost, {
       method: 'POST',
       body: formData,
     })
       .then(async response => {
+        reachedResponse = true;
+
         // intentional error on localhost
-        if (shouldReturnError && erroneousActions.includes(option?.action)) {
+        if (shouldReturnError) {
           return {
             success: false,
             error: option?.action === 'create_token' ? tokenError : borrowError,
@@ -77,9 +107,7 @@ export default async function ActionsHandlerService(options) {
           };
         }
 
-        // The response is a Response instance.
-        // You parse the data into a useable format using `.json()`
-        return response.json();
+        return parseServiceResponse(response, option);
       })
       .then(data => {
         // `data` is the parsed version of the JSON returned from the above endpoint.
@@ -92,8 +120,100 @@ export default async function ActionsHandlerService(options) {
         }
       });
   } catch (error) {
-    window?.Sentry?.captureException(
-      `${sentryLogs.actionsHandlerService} - Error: ${error}`
+    sentryCaptureException(error, {
+      identifier: option.identifier,
+      action: option.action,
+      extra: {
+        message: `${sentryLogs.actionsHandlerService} - ${option.action} ${
+          reachedResponse ? 'threw' : 'fetch failed'
+        }`,
+      },
+    });
+
+    /**
+     * Report it, don't just swallow it. A rejected fetch (offline, dropped
+     * connection) lands here — a non-JSON body no longer does, see
+     * parseServiceResponse() — as does anything thrown after the response
+     * arrived; calling neither `success` nor `error` leaves every caller
+     * waiting on a callback that never comes. Only the former is a network
+     * problem, so only that one says so.
+     *
+     * For renew_loan that's not merely a missing modal: IABookActions
+     * clears its loanRenewInProgress guard from these callbacks, so a
+     * silent failure latched it on for good and every later renewal
+     * attempt became a no-op. Backgrounding a tab on a flaky mobile
+     * connection is exactly when this fires.
+     */
+    log(`[IABookActions] ✗ ${option.action} threw`, error);
+    option?.error?.({
+      error: reachedResponse ? unexpectedError : networkError,
+      detail: String(error),
+    });
+  }
+}
+
+/**
+ * Parse a lending service response without ever surfacing a raw
+ * `SyntaxError` to the patron. Anything in front of PHP (the WAF, or nginx
+ * swapping in /about/400.html or a 5xx page) can answer with HTML instead
+ * of the service's JSON; that becomes a readable error carrying the HTTP
+ * status, and is reported to Sentry with the identifier/action.
+ *
+ * @param {Response} response
+ * @param {Object} option - the ActionsHandlerService options
+ * @returns {Promise<Object>}
+ */
+export async function parseServiceResponse(response, option) {
+  const { status } = response;
+  const contentType = response.headers?.get('content-type') || '';
+
+  // The service always answers with JSON (application/json, or
+  // application/problem+json for OPDS) — anything else never came from it.
+  const body = await response.text();
+  let data;
+  if (contentType.includes('json')) {
+    try {
+      data = JSON.parse(body);
+    } catch (parseError) {
+      data = undefined;
+    }
+  }
+
+  if (data === undefined) {
+    sentryCaptureMessage(
+      `${sentryLogs.actionsHandlerService} - ${option.action}: non-JSON response (HTTP ${status})`,
+      {
+        identifier: option.identifier,
+        action: option.action,
+        extra: {
+          status,
+          contentType,
+          bodySnippet: body.slice(0, 300),
+        },
+      }
     );
+    // nonJsonResponse lets callers tell "something in front of PHP answered"
+    // apart from the service's own error — see
+    // IABookActions.handleLendingActionError.
+    return {
+      success: false,
+      error: unexpectedResponseError(status),
+      status,
+      nonJsonResponse: true,
+    };
+  }
+
+  // Carry the HTTP status on the service's own JSON errors too, so it
+  // reaches Sentry. A JSON error status without the service's usual `error`
+  // field would otherwise be treated as a success.
+  if (!response.ok) {
+    return {
+      ...(data && typeof data === 'object' ? data : {}),
+      success: false,
+      error: data?.error || unexpectedResponseError(status),
+      status,
+    };
   }
+
+  return data;
 }

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

@@ -2,11 +2,19 @@ import { LitElement } from 'lit';
 
 import { URLHelper } from '../../config/url-helper.js';
 import { sentryLogs } from '../../config/sentry-events.js';
+import {
+  sentryCaptureMessage,
+  sentryCaptureException,
+} from '../sentry-report.js';
 import log from '../log.js';
 
 import ActionsHandlerService from './actions-handler-service.js';
 import LoanAnanlytics from '../loan-analytics.js';
-import { analyticsCategories, analyticsActions, analyticsLabels } from '../../config/analytics-event-and-category.js';
+import {
+  analyticsCategories,
+  analyticsActions,
+  analyticsLabels,
+} from '../../config/analytics-event-and-category.js';
 import * as Cookies from '../doc-cookies.js';
 
 /**
@@ -172,32 +180,51 @@ export default class ActionsHandler extends LitElement {
       action,
       identifier: this.identifier,
       success: async data => {
-        log('RENEW_LOAN --- ', data, this.identifier);
-        const activeLoan = data.loan ? data.loan : undefined;
-        const isRenewal = activeLoan.renewal;
-
-        if (activeLoan && isRenewal) {
-          // Await — loanAutoRenewed listeners read this same cache key
-          // immediately; dispatching before the write lands was a race.
-          await this.setBrowseTimeSession();
-
-          // Only record the renew analytics event once the renewal has
-          // actually succeeded — not merely attempted.
-          await this.loanAnanlytics?.storeLoanStatsCount(
-            this.identifier,
-            'autorenew'
-          );
-          const analyticsLabel =
-            renewType === 'auto'
-              ? analyticsLabels.browseAutoRenew
-              : analyticsLabels.browseManualRenew;
-          this.loanAnanlytics?.sendEvent(
-            analyticsCategories.browse,
-            analyticsActions.browseRenew,
-            analyticsLabel,
-            this.identifier
-          );
-        } else {
+        // Anything thrown in here is an unhandled rejection that dispatches
+        // NOTHING — and IABookActions only clears loanRenewInProgress when
+        // one of these two events arrives, so a throw here latches it on
+        // permanently (dead countdown, loan stuck "active"). Always exit
+        // through exactly one of the two dispatches below.
+        try {
+          log('RENEW_LOAN --- ', data, this.identifier);
+          const activeLoan = data.loan ? data.loan : undefined;
+          // Optional chaining: `data.loan` is genuinely absent on some
+          // failures, and `activeLoan` can be undefined here.
+          const isRenewal = activeLoan?.renewal;
+
+          if (activeLoan && isRenewal) {
+            // Await — loanAutoRenewed listeners read this same cache key
+            // immediately; dispatching before the write lands was a race.
+            await this.setBrowseTimeSession();
+
+            // Only record the renew analytics event once the renewal has
+            // actually succeeded — not merely attempted.
+            await this.loanAnanlytics?.storeLoanStatsCount(
+              this.identifier,
+              'autorenew'
+            );
+            const analyticsLabel =
+              renewType === 'auto'
+                ? analyticsLabels.browseAutoRenew
+                : analyticsLabels.browseManualRenew;
+            this.loanAnanlytics?.sendEvent(
+              analyticsCategories.browse,
+              analyticsActions.browseRenew,
+              analyticsLabel,
+              this.identifier
+            );
+
+            // Dispatch the success outcome ONLY for a confirmed renewal —
+            // a `{loan: {renewal: false}}` response goes through
+            // dispatchActionError below instead, never both.
+            this.dispatchEvent(
+              new CustomEvent('loanAutoRenewed', {
+                detail: { action, data: { ...data, loan: activeLoan } },
+              })
+            );
+            return;
+          }
+
           log('RENEW_LOAN ERROR --- ', {
             action,
             isRenewal,
@@ -205,22 +232,32 @@ export default class ActionsHandler extends LitElement {
             data,
             id: this.identifier,
           });
-          window?.Sentry?.captureMessage(
-            `${sentryLogs.bookRenewFailed} - Error: ${JSON.stringify(data)}`
+          sentryCaptureMessage(
+            `${sentryLogs.bookRenewFailed} - no loan active`,
+            {
+              identifier: this.identifier,
+              action,
+              extra: { response: JSON.stringify(data) },
+            }
           );
           this.dispatchActionError(action, {
             data,
             error: true,
             message: 'Loan renewal failed: no loan active.',
           });
+        } catch (error) {
+          log('RENEW_LOAN THREW --- ', error);
+          sentryCaptureException(error, {
+            identifier: this.identifier,
+            action,
+            extra: { message: `${sentryLogs.bookRenewFailed} - threw` },
+          });
+          this.dispatchActionError(action, {
+            data,
+            error: true,
+            message: `Loan renewal failed: ${error}`,
+          });
         }
-
-        // dispatch outcome of loan renewal
-        this.dispatchEvent(
-          new CustomEvent('loanAutoRenewed', {
-            detail: { action, data: { ...data, loan: activeLoan } },
-          })
-        );
       },
       error: data => {
         this.dispatchActionError(action, data);
@@ -372,6 +409,12 @@ export default class ActionsHandler extends LitElement {
         new Date().getTime() + this.loanTotalTime * 1000
       );
 
+      log('[ActionsHandler] setBrowseTimeSession: resetting loanTime', {
+        identifier: this.identifier,
+        expireDate,
+        loanTotalTime: this.loanTotalTime,
+      });
+
       // set a value
       await this.localCache.set({
         key: `${this.identifier}-loanTime`,
@@ -381,12 +424,20 @@ export default class ActionsHandler extends LitElement {
 
       // delete pageChangedTime when book is auto renew at nth minute
       await this.localCache.delete(`${this.identifier}-pageChangedTime`);
+
+      log('[ActionsHandler] setBrowseTimeSession: loanTime reset complete', {
+        identifier: this.identifier,
+      });
     } catch (error) {
-      log(error);
+      log('[ActionsHandler] setBrowseTimeSession failed', error);
     }
   }
 
   deleteLoanCookies() {
+    log('[ActionsHandler] deleteLoanCookies: expiring loan cookies', {
+      identifier: this.identifier,
+    });
+
     const date = new Date();
     date.setTime(date.getTime() - 24 * 60 * 60 * 1000); // one day ago
 
@@ -414,7 +465,8 @@ export default class ActionsHandler extends LitElement {
    * @returns {void}
    */
   setStickyAdminAccess(value) {
-    const domain = window.location.hostname === 'localhost' ? 'localhost' : '.archive.org';
+    const domain =
+      window.location.hostname === 'localhost' ? 'localhost' : '.archive.org';
     const expires = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days from now
     Cookies.setItem('sticky-admin-access', value, expires, '/', domain);
   }

package/src/core/services/loan-analytics.js

@@ -159,17 +159,6 @@ export default class LoanAnanlytics {
    * @memberof LoanAnanlytics
    */
   sendEvent(eventCategory, eventAction, label, extraParams) {
-    log(
-      'eventCategory:-',
-      eventCategory,
-      '||\teventAction:-',
-      eventAction,
-      '||\tlabel:-',
-      label,
-      '||\textraParams:-',
-      extraParams,
-    );
-
     window?.archive_analytics?.send_event_no_sampling(
       eventCategory,
       eventAction,

package/src/core/services/loan-renew-helper.js

@@ -26,7 +26,7 @@ export class LoanRenewHelper {
     };
   }
 
-  async handleLoanRenew() {
+  handleLoanRenew() {
     try {
       if (this.hasPageChanged) {
         return this.pageChanged(); // user clicked on page
@@ -99,7 +99,7 @@ export class LoanRenewHelper {
     } else if (pageChangedTime >= pageChangeTimeFrame) {
       this.result = {
         texts: '',
-        renewNow: true,  // viewed in last time frame
+        renewNow: true, // viewed in last time frame
         renewType: 'auto',
       };
     }

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

@@ -2,6 +2,8 @@
 import ActionsHandlerService from './actions-handler/actions-handler-service.js';
 import LoanAnanlytics from './loan-analytics.js';
 import { sentryLogs } from '../config/sentry-events.js';
+import { sentryCaptureMessage } from './sentry-report.js';
+import log from './log.js';
 
 /**
  * This class is used to create loan token for borrowed books
@@ -9,12 +11,39 @@ import { sentryLogs } from '../config/sentry-events.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;
 
@@ -33,8 +62,17 @@ export class LoanTokenPoller {
 
   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
@@ -49,38 +87,86 @@ export class LoanTokenPoller {
         }, this.pollerDelay * 1000);
       }
     } else {
-      window?.Sentry?.captureMessage(
-        `${sentryLogs.bookAccessed} - not borrowed`
-      );
+      sentryCaptureMessage(`${sentryLogs.bookAccessed} - not borrowed`, {
+        identifier: this.identifier,
+        action: 'create_token',
+      });
 
       // if book is not browsed, just clear token polling interval
       this.disconnectedCallback();
     }
   }
 
+  /**
+   * @param {boolean} isInitial - the first create_token call right after
+   *   bookAccessed()/a renewal, as opposed to a routine interval tick.
+   */
   async handleLoanTokenPoller(isInitial = false) {
     const action = 'create_token';
+    log('[LoanTokenPoller] create_token requested', {
+      identifier: this.identifier,
+      isInitial,
+    });
     ActionsHandlerService({
       identifier: this.identifier,
       action,
-      error: data => {
-        this.errorCallback({ detail: { action, data } });
-
-        // send error to Sentry
-        window?.Sentry?.captureMessage(
-          `${sentryLogs.handleLoanTokenPoller} - Error: ${JSON.stringify(data)}`
-        );
-
-        // send LendingServiceError to GA
-        this.loanAnalytics?.sendEvent(
-          'LendingServiceLoanError',
-          action,
-          this.identifier
-        );
-      },
+      error: data => this.handleTokenError(data, isInitial),
       success: () => {
+        log('[LoanTokenPoller] create_token succeeded', {
+          identifier: this.identifier,
+          isInitial,
+        });
         if (isInitial) this.successCallback();
       },
     });
   }
+
+  /**
+   * Reports every create_token failure via errorCallback — the poller never
+   * retries, and the consumer decides whether a failure is terminal (see
+   * IABookActions.handleLendingActionError). 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
+   */
+  handleTokenError(data, isInitial) {
+    const action = 'create_token';
+
+    log('[LoanTokenPoller] create_token failed', {
+      identifier: this.identifier,
+      isInitial,
+      error: data?.error,
+    });
+
+    // isInitial rides along so the consumer can distinguish "the book won't
+    // open at all" from "a mid-read refresh blipped" — see
+    // IABookActions.handleLendingActionError.
+    this.errorCallback({ detail: { action, data, isInitial } });
+
+    // send error to Sentry
+    sentryCaptureMessage(
+      `${sentryLogs.handleLoanTokenPoller} - create_token failed`,
+      {
+        identifier: this.identifier,
+        action,
+        extra: {
+          borrowType: this.borrowType,
+          isInitial,
+          error: data?.error,
+          status: data?.status,
+          nonJsonResponse: data?.nonJsonResponse === true,
+          response: JSON.stringify(data),
+        },
+      }
+    );
+
+    // send LendingServiceError to GA
+    this.loanAnalytics?.sendEvent(
+      'LendingServiceLoanError',
+      action,
+      this.identifier
+    );
+  }
 }