@internetarchive/fetch-handler 1.0.1

package/README.md

@@ -0,0 +1,82 @@
+![Build Status](https://github.com/internetarchive/iaux-fetch-handler-service/actions/workflows/ci.yml/badge.svg) [![codecov](https://codecov.io/gh/internetarchive/iaux-fetch-handler-service/graph/badge.svg?token=ZOYRJ2BV9W)](https://codecov.io/gh/internetarchive/iaux-fetch-handler-service)
+
+
+# Internet Archive Fetch Handler Service
+
+
+A custom service for handling API requests.
+
+
+## Installation
+
+```bash
+npm install @internetarchive/fetch-handler-service
+```
+
+
+## Sample Usage
+
+```ts
+import { IaFetchHandler } from '../src/ia-fetch-handler';
+
+@property({ type: Object }) data: any = null;
+@property({ type: String }) error: string = '';
+@property({ type: Boolean }) loading: boolean = false;
+
+private fetchHandler: IaFetchHandler;
+
+this.fetchHandler = new IaFetchHandler({
+  iaApiBaseUrl: 'https://archive.org',
+});
+
+
+async fetchData() {
+  this.loading = true;
+  this.error = '';
+  try {
+    const result =
+      await this.fetchHandler.fetchIAApiResponse('/metadata/goody');
+    this.data = result;
+  } catch (error) {
+    this.error = `Error fetching data: ${error}`;
+  } finally {
+    this.loading = false;
+  }
+}
+```
+
+See the `demo` directory for a more detailed example.
+
+## Local Demo with `web-dev-server`
+Add `127.0.0.1 local.archive.org` to your `/etc/hosts` file
+
+```bash
+npm run start
+```
+
+**NOTE** The first time you visit the site, the browser will say the site is insecure because it's using a self-signed certificate. Accept the certificate and visit the site and the browser will then accept the certificate in the future. It may always say the site is insecure, but for the purposes of development, it's secure enough.
+
+To run a local development server that serves the basic demo located in `demo/index.html`
+
+## Testing with Web Test Runner
+To run the suite of Web Test Runner tests, run
+```bash
+npm run test
+```
+
+To run the tests in watch mode (for <abbr title="test driven development">TDD</abbr>, for example), run
+
+```bash
+npm run test:watch
+```
+
+## Linting with ESLint, Prettier, and Types
+To scan the project for linting errors, run
+```bash
+npm run lint
+```
+
+To automatically fix many linting errors, run
+```bash
+npm run format
+```

package/coverage/.gitignore

@@ -0,0 +1,3 @@
+*
+!.placeholder
+!.gitignore

package/demo/app-root.ts

@@ -0,0 +1,84 @@
+import { html, LitElement, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+
+import { IaFetchHandler } from '../src/ia-fetch-handler';
+
+@customElement('app-root')
+export class AppRoot extends LitElement {
+  @property({ type: Object }) data: any = null;
+  @property({ type: String }) error: string = '';
+  @property({ type: Boolean }) loading: boolean = false;
+
+  private fetchHandler: IaFetchHandler;
+
+  constructor() {
+    super();
+    this.fetchHandler = new IaFetchHandler({
+      iaApiBaseUrl: 'https://archive.org',
+    });
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.fetchData();
+  }
+
+  async fetchData() {
+    this.loading = true;
+    this.error = '';
+    try {
+      const result =
+        await this.fetchHandler.fetchIAApiResponse('/metadata/goody');
+      this.data = result;
+    } catch (error) {
+      this.error = `Error fetching data: ${error}`;
+    } finally {
+      this.loading = false;
+    }
+  }
+
+  render() {
+    return html`
+      <div class="container">
+        <h1>Fetch Data</h1>
+        ${this.loading
+          ? html`<p>Loading...</p>`
+          : this.error
+            ? html`<p class="error">${this.error}</p>`
+            : this.data
+              ? html`<pre>${JSON.stringify(this.data, null, 2)}</pre>`
+              : html`<p>No data available.</p>`}
+        <button @click="${this.fetchData}">Retry</button>
+      </div>
+    `;
+  }
+
+  static styles = css`
+    .container {
+      padding: 20px;
+      font-family: Arial, sans-serif;
+    }
+
+    h1 {
+      color: #333;
+    }
+
+    .error {
+      color: red;
+    }
+
+    button {
+      margin-top: 20px;
+      padding: 10px 20px;
+      background-color: #007bff;
+      color: white;
+      border: none;
+      cursor: pointer;
+      border-radius: 5px;
+    }
+
+    button:hover {
+      background-color: #0056b3;
+    }
+  `;
+}

package/demo/index.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en-GB">
+<head>
+  <meta charset="utf-8">
+  <style>
+    body {
+      background: #fff;
+      font-family: sans-serif;
+    }
+  </style>
+</head>
+<body>
+  <div id="demo"></div>
+
+  <script type="module">
+    import { html, render } from 'lit-html';
+    import '../dist/demo/app-root.js';
+
+    render(
+      html`
+        <app-root></app-root>
+      `,
+      document.querySelector('#demo')
+    );
+  </script>
+</body>
+</html>

package/dist/demo/app-root.d.ts

@@ -0,0 +1,12 @@
+import { LitElement } from 'lit';
+export declare class AppRoot extends LitElement {
+    data: any;
+    error: string;
+    loading: boolean;
+    private fetchHandler;
+    constructor();
+    connectedCallback(): void;
+    fetchData(): Promise<void>;
+    render(): import("lit").TemplateResult<1>;
+    static styles: import("lit").CSSResult;
+}

package/dist/demo/app-root.js

@@ -0,0 +1,90 @@
+import { __decorate } from "tslib";
+import { html, LitElement, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { IaFetchHandler } from '../src/ia-fetch-handler';
+let AppRoot = class AppRoot extends LitElement {
+    constructor() {
+        super();
+        this.data = null;
+        this.error = '';
+        this.loading = false;
+        this.fetchHandler = new IaFetchHandler({
+            iaApiBaseUrl: 'https://archive.org',
+        });
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.fetchData();
+    }
+    async fetchData() {
+        this.loading = true;
+        this.error = '';
+        try {
+            const result = await this.fetchHandler.fetchIAApiResponse('/metadata/goody');
+            this.data = result;
+        }
+        catch (error) {
+            this.error = `Error fetching data: ${error}`;
+        }
+        finally {
+            this.loading = false;
+        }
+    }
+    render() {
+        return html `
+      <div class="container">
+        <h1>Fetch Data</h1>
+        ${this.loading
+            ? html `<p>Loading...</p>`
+            : this.error
+                ? html `<p class="error">${this.error}</p>`
+                : this.data
+                    ? html `<pre>${JSON.stringify(this.data, null, 2)}</pre>`
+                    : html `<p>No data available.</p>`}
+        <button @click="${this.fetchData}">Retry</button>
+      </div>
+    `;
+    }
+};
+AppRoot.styles = css `
+    .container {
+      padding: 20px;
+      font-family: Arial, sans-serif;
+    }
+
+    h1 {
+      color: #333;
+    }
+
+    .error {
+      color: red;
+    }
+
+    button {
+      margin-top: 20px;
+      padding: 10px 20px;
+      background-color: #007bff;
+      color: white;
+      border: none;
+      cursor: pointer;
+      border-radius: 5px;
+    }
+
+    button:hover {
+      background-color: #0056b3;
+    }
+  `;
+__decorate([
+    property({ type: Object })
+], AppRoot.prototype, "data", void 0);
+__decorate([
+    property({ type: String })
+], AppRoot.prototype, "error", void 0);
+__decorate([
+    property({ type: Boolean })
+], AppRoot.prototype, "loading", void 0);
+AppRoot = __decorate([
+    customElement('app-root')
+], AppRoot);
+export { AppRoot };
+//# sourceMappingURL=app-root.js.map

package/dist/demo/app-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-root.js","sourceRoot":"","sources":["../../demo/app-root.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAGlD,IAAM,OAAO,GAAb,MAAM,OAAQ,SAAQ,UAAU;IAOrC;QACE,KAAK,EAAE,CAAC;QAPkB,SAAI,GAAQ,IAAI,CAAC;QACjB,UAAK,GAAW,EAAE,CAAC;QAClB,YAAO,GAAY,KAAK,CAAC;QAMpD,IAAI,CAAC,YAAY,GAAG,IAAI,cAAc,CAAC;YACrC,YAAY,EAAE,qBAAqB;SACpC,CAAC,CAAC;IACL,CAAC;IAED,iBAAiB;QACf,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC1B,IAAI,CAAC,SAAS,EAAE,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,SAAS;QACb,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,MAAM,MAAM,GACV,MAAM,IAAI,CAAC,YAAY,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,CAAC;YAChE,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;QACrB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,GAAG,wBAAwB,KAAK,EAAE,CAAC;QAC/C,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAA;;;UAGL,IAAI,CAAC,OAAO;YACZ,CAAC,CAAC,IAAI,CAAA,mBAAmB;YACzB,CAAC,CAAC,IAAI,CAAC,KAAK;gBACV,CAAC,CAAC,IAAI,CAAA,oBAAoB,IAAI,CAAC,KAAK,MAAM;gBAC1C,CAAC,CAAC,IAAI,CAAC,IAAI;oBACT,CAAC,CAAC,IAAI,CAAA,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ;oBACxD,CAAC,CAAC,IAAI,CAAA,2BAA2B;0BACrB,IAAI,CAAC,SAAS;;KAEnC,CAAC;IACJ,CAAC;;AAEM,cAAM,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BlB,AA3BY,CA2BX;AA3E0B;IAA3B,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;qCAAkB;AACjB;IAA3B,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;sCAAoB;AAClB;IAA5B,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;wCAA0B;AAH3C,OAAO;IADnB,aAAa,CAAC,UAAU,CAAC;GACb,OAAO,CA6EnB","sourcesContent":["import { html, LitElement, css } from 'lit';\nimport { customElement, property } from 'lit/decorators.js';\n\nimport { IaFetchHandler } from '../src/ia-fetch-handler';\n\n@customElement('app-root')\nexport class AppRoot extends LitElement {\n  @property({ type: Object }) data: any = null;\n  @property({ type: String }) error: string = '';\n  @property({ type: Boolean }) loading: boolean = false;\n\n  private fetchHandler: IaFetchHandler;\n\n  constructor() {\n    super();\n    this.fetchHandler = new IaFetchHandler({\n      iaApiBaseUrl: 'https://archive.org',\n    });\n  }\n\n  connectedCallback() {\n    super.connectedCallback();\n    this.fetchData();\n  }\n\n  async fetchData() {\n    this.loading = true;\n    this.error = '';\n    try {\n      const result =\n        await this.fetchHandler.fetchIAApiResponse('/metadata/goody');\n      this.data = result;\n    } catch (error) {\n      this.error = `Error fetching data: ${error}`;\n    } finally {\n      this.loading = false;\n    }\n  }\n\n  render() {\n    return html`\n      <div class=\"container\">\n        <h1>Fetch Data</h1>\n        ${this.loading\n          ? html`<p>Loading...</p>`\n          : this.error\n            ? html`<p class=\"error\">${this.error}</p>`\n            : this.data\n              ? html`<pre>${JSON.stringify(this.data, null, 2)}</pre>`\n              : html`<p>No data available.</p>`}\n        <button @click=\"${this.fetchData}\">Retry</button>\n      </div>\n    `;\n  }\n\n  static styles = css`\n    .container {\n      padding: 20px;\n      font-family: Arial, sans-serif;\n    }\n\n    h1 {\n      color: #333;\n    }\n\n    .error {\n      color: red;\n    }\n\n    button {\n      margin-top: 20px;\n      padding: 10px 20px;\n      background-color: #007bff;\n      color: white;\n      border: none;\n      cursor: pointer;\n      border-radius: 5px;\n    }\n\n    button:hover {\n      background-color: #0056b3;\n    }\n  `;\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { IaFetchHandler } from './src/ia-fetch-handler';
+export { FetchHandlerInterface } from './src/fetch-handler-interface';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { IaFetchHandler } from './src/ia-fetch-handler';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC","sourcesContent":["export { IaFetchHandler } from './src/ia-fetch-handler';\nexport { FetchHandlerInterface } from './src/fetch-handler-interface';\n"]}

package/dist/src/fetch-handler-interface.d.ts

@@ -0,0 +1,33 @@
+export interface FetchHandlerInterface {
+    /**
+     * Generic fetch function that handles retries and common IA parameters like `reCache=1`
+     *
+     * @param input RequestInfo
+     * @param init RequestInit
+     */
+    fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;
+    /**
+     * A helper function to fetch a response from an API and get a JSON object
+     *
+     * @param path string
+     * @param options?: { includeCredentials?: boolean }
+     */
+    fetchApiResponse<T>(url: string, options?: {
+        includeCredentials?: boolean;
+        method?: string;
+        body?: BodyInit;
+        headers?: HeadersInit;
+    }): Promise<T>;
+    /**
+     * A helper function to fetch a response from the IA API and get a JSON object
+     *
+     * This allows you to just pass the path to the API and get the response instead
+     * of the full URL. If you need a full URL, use `fetchApiResponse` instead.
+     *
+     * @param path string
+     * @param options?: { includeCredentials?: boolean }
+     */
+    fetchIAApiResponse<T>(path: string, options?: {
+        includeCredentials?: boolean;
+    }): Promise<T>;
+}

package/dist/src/fetch-handler-interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fetch-handler-interface.js.map

package/dist/src/fetch-handler-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-handler-interface.js","sourceRoot":"","sources":["../../src/fetch-handler-interface.ts"],"names":[],"mappings":"","sourcesContent":["export interface FetchHandlerInterface {\n  /**\n   * Generic fetch function that handles retries and common IA parameters like `reCache=1`\n   *\n   * @param input RequestInfo\n   * @param init RequestInit\n   */\n  fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;\n\n  /**\n   * A helper function to fetch a response from an API and get a JSON object\n   *\n   * @param path string\n   * @param options?: { includeCredentials?: boolean }\n   */\n  fetchApiResponse<T>(\n    url: string,\n    options?: {\n      includeCredentials?: boolean;\n      method?: string;\n      body?: BodyInit;\n      headers?: HeadersInit;\n    },\n  ): Promise<T>;\n\n  /**\n   * A helper function to fetch a response from the IA API and get a JSON object\n   *\n   * This allows you to just pass the path to the API and get the response instead\n   * of the full URL. If you need a full URL, use `fetchApiResponse` instead.\n   *\n   * @param path string\n   * @param options?: { includeCredentials?: boolean }\n   */\n  fetchIAApiResponse<T>(\n    path: string,\n    options?: { includeCredentials?: boolean },\n  ): Promise<T>;\n}\n"]}

package/dist/src/ia-fetch-handler.d.ts

@@ -0,0 +1,36 @@
+import { FetchRetrierInterface } from './utils/fetch-retrier';
+import type { FetchHandlerInterface } from './fetch-handler-interface';
+/**
+ * The FetchHandler adds some common helpers:
+ * - retry the request if it fails
+ * - add `reCache=1` to the request if it's in the current url so the backend sees it
+ * - add convenience method for fetching/decoding an API response by just the path
+ */
+export declare class IaFetchHandler implements FetchHandlerInterface {
+    private iaApiBaseUrl?;
+    private fetchRetrier;
+    private searchParams?;
+    constructor(options?: {
+        iaApiBaseUrl?: string;
+        fetchRetrier?: FetchRetrierInterface;
+        searchParams?: string;
+    });
+    /** @inheritdoc */
+    fetchIAApiResponse<T>(path: string, options?: {
+        includeCredentials?: boolean;
+    }): Promise<T>;
+    /** @inheritdoc */
+    fetchApiResponse<T>(url: string, options?: {
+        includeCredentials?: boolean;
+        method?: string;
+        body?: BodyInit;
+        headers?: HeadersInit;
+    }): Promise<T>;
+    /** @inheritdoc */
+    fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;
+    /**
+     * Since RequestInfo can be either a `Request` or `string`, we need to change
+     * the way we add search params to it depending on the input.
+     */
+    private addSearchParams;
+}

package/dist/src/ia-fetch-handler.js

@@ -0,0 +1,70 @@
+import { FetchRetrier } from './utils/fetch-retrier';
+/**
+ * The FetchHandler adds some common helpers:
+ * - retry the request if it fails
+ * - add `reCache=1` to the request if it's in the current url so the backend sees it
+ * - add convenience method for fetching/decoding an API response by just the path
+ */
+export class IaFetchHandler {
+    constructor(options) {
+        this.fetchRetrier = new FetchRetrier();
+        if (options === null || options === void 0 ? void 0 : options.iaApiBaseUrl)
+            this.iaApiBaseUrl = options.iaApiBaseUrl;
+        if (options === null || options === void 0 ? void 0 : options.fetchRetrier)
+            this.fetchRetrier = options.fetchRetrier;
+        if (options === null || options === void 0 ? void 0 : options.searchParams) {
+            this.searchParams = options.searchParams;
+        }
+        else {
+            this.searchParams = window.location.search;
+        }
+    }
+    /** @inheritdoc */
+    async fetchIAApiResponse(path, options) {
+        const url = `${this.iaApiBaseUrl}${path}`;
+        return this.fetchApiResponse(url, options);
+    }
+    /** @inheritdoc */
+    async fetchApiResponse(url, options) {
+        const requestInit = {};
+        if (options === null || options === void 0 ? void 0 : options.includeCredentials)
+            requestInit.credentials = 'include';
+        if (options === null || options === void 0 ? void 0 : options.method)
+            requestInit.method = options.method;
+        if (options === null || options === void 0 ? void 0 : options.body)
+            requestInit.body = options.body;
+        if (options === null || options === void 0 ? void 0 : options.headers)
+            requestInit.headers = options.headers;
+        const response = await this.fetch(url, requestInit);
+        const json = await response.json();
+        return json;
+    }
+    /** @inheritdoc */
+    async fetch(input, init) {
+        let finalInput = input;
+        const urlParams = new URLSearchParams(this.searchParams);
+        if (urlParams.get('reCache') === '1') {
+            finalInput = this.addSearchParams(input, { reCache: '1' });
+        }
+        return this.fetchRetrier.fetchRetry(finalInput, init);
+    }
+    /**
+     * Since RequestInfo can be either a `Request` or `string`, we need to change
+     * the way we add search params to it depending on the input.
+     */
+    addSearchParams(input, params) {
+        const urlString = typeof input === 'string' ? input : input.url;
+        const url = new URL(urlString, window.location.href);
+        for (const [key, value] of Object.entries(params)) {
+            url.searchParams.set(key, value);
+        }
+        if (typeof input === 'string') {
+            return url.href;
+        }
+        else {
+            const newRequest = new Request(url.href, input);
+            return newRequest;
+        }
+    }
+}
+//# sourceMappingURL=ia-fetch-handler.js.map

package/dist/src/ia-fetch-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ia-fetch-handler.js","sourceRoot":"","sources":["../../src/ia-fetch-handler.ts"],"names":[],"mappings":"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","sourcesContent":["import { FetchRetrier, FetchRetrierInterface } from './utils/fetch-retrier';\nimport type { FetchHandlerInterface } from './fetch-handler-interface';\n\n/**\n * The FetchHandler adds some common helpers:\n * - retry the request if it fails\n * - add `reCache=1` to the request if it's in the current url so the backend sees it\n * - add convenience method for fetching/decoding an API response by just the path\n */\nexport class IaFetchHandler implements FetchHandlerInterface {\n  private iaApiBaseUrl?: string;\n\n  private fetchRetrier: FetchRetrierInterface = new FetchRetrier();\n\n  private searchParams?: string;\n\n  constructor(options?: {\n    iaApiBaseUrl?: string;\n    fetchRetrier?: FetchRetrierInterface;\n    searchParams?: string;\n  }) {\n    if (options?.iaApiBaseUrl) this.iaApiBaseUrl = options.iaApiBaseUrl;\n    if (options?.fetchRetrier) this.fetchRetrier = options.fetchRetrier;\n    if (options?.searchParams) {\n      this.searchParams = options.searchParams;\n    } else {\n      this.searchParams = window.location.search;\n    }\n  }\n\n  /** @inheritdoc */\n  async fetchIAApiResponse<T>(\n    path: string,\n    options?: {\n      includeCredentials?: boolean;\n    },\n  ): Promise<T> {\n    const url = `${this.iaApiBaseUrl}${path}`;\n    return this.fetchApiResponse(url, options);\n  }\n\n  /** @inheritdoc */\n  async fetchApiResponse<T>(\n    url: string,\n    options?: {\n      includeCredentials?: boolean;\n      method?: string;\n      body?: BodyInit;\n      headers?: HeadersInit;\n    },\n  ): Promise<T> {\n    const requestInit: RequestInit = {};\n    if (options?.includeCredentials) requestInit.credentials = 'include';\n    if (options?.method) requestInit.method = options.method;\n    if (options?.body) requestInit.body = options.body;\n    if (options?.headers) requestInit.headers = options.headers;\n    const response = await this.fetch(url, requestInit);\n    const json = await response.json();\n    return json as T;\n  }\n\n  /** @inheritdoc */\n  async fetch(input: RequestInfo, init?: RequestInit): Promise<Response> {\n    let finalInput = input;\n    const urlParams = new URLSearchParams(this.searchParams);\n    if (urlParams.get('reCache') === '1') {\n      finalInput = this.addSearchParams(input, { reCache: '1' });\n    }\n    return this.fetchRetrier.fetchRetry(finalInput, init);\n  }\n\n  /**\n   * Since RequestInfo can be either a `Request` or `string`, we need to change\n   * the way we add search params to it depending on the input.\n   */\n  private addSearchParams(\n    input: RequestInfo,\n    params: Record<string, string>,\n  ): RequestInfo {\n    const urlString = typeof input === 'string' ? input : input.url;\n    const url = new URL(urlString, window.location.href);\n\n    for (const [key, value] of Object.entries(params)) {\n      url.searchParams.set(key, value);\n    }\n\n    if (typeof input === 'string') {\n      return url.href;\n    } else {\n      const newRequest = new Request(url.href, input);\n      return newRequest;\n    }\n  }\n}\n"]}

package/dist/src/utils/fetch-retrier.d.ts

@@ -0,0 +1,36 @@
+import type { AnalyticsHandlerInterface } from '@internetarchive/analytics-manager';
+/**
+ * A class that retries a fetch request.
+ */
+export interface FetchRetrierInterface {
+    /**
+     * Execute a fetch with retry.
+     *
+     * @param requestInfo RequestInfo
+     * @param init Optional RequestInit
+     * @param retries Optional number of retries to attempt
+     * @returns Promise<Response>
+     */
+    fetchRetry(requestInfo: RequestInfo, init?: RequestInit, retries?: number): Promise<Response>;
+}
+/** @inheritdoc */
+export declare class FetchRetrier implements FetchRetrierInterface {
+    private analyticsHandler;
+    private sleep;
+    private retryCount;
+    private retryDelay;
+    constructor(options?: {
+        analyticsHandler?: AnalyticsHandlerInterface;
+        retryCount?: number;
+        retryDelay?: number;
+        sleepFn?: (ms: number) => Promise<void>;
+    });
+    /** @inheritdoc */
+    fetchRetry(requestInfo: RequestInfo, init?: RequestInit, retries?: number): Promise<Response>;
+    private isContentBlockerError;
+    private readonly eventCategory;
+    private logRetryEvent;
+    private logFailureEvent;
+    private log404Event;
+    private logContentBlockingEvent;
+}

package/dist/src/utils/fetch-retrier.js

@@ -0,0 +1,94 @@
+import { AnalyticsHandler } from '@internetarchive/analytics-manager';
+import { promisedSleep } from './promised-sleep';
+/** @inheritdoc */
+export class FetchRetrier {
+    constructor(options) {
+        this.analyticsHandler = new AnalyticsHandler({ enableAnalytics: true });
+        this.sleep = promisedSleep; // default sleep function
+        this.retryCount = 2;
+        this.retryDelay = 1000;
+        this.eventCategory = 'offshootFetchRetry';
+        if (options === null || options === void 0 ? void 0 : options.analyticsHandler)
+            this.analyticsHandler = options.analyticsHandler;
+        if (options === null || options === void 0 ? void 0 : options.retryCount)
+            this.retryCount = options.retryCount;
+        if (options === null || options === void 0 ? void 0 : options.retryDelay)
+            this.retryDelay = options.retryDelay;
+        if (options === null || options === void 0 ? void 0 : options.sleepFn)
+            this.sleep = options.sleepFn; // override if provided
+    }
+    /** @inheritdoc */
+    async fetchRetry(requestInfo, init, retries = this.retryCount) {
+        const urlString = typeof requestInfo === 'string' ? requestInfo : requestInfo.url;
+        const retryNumber = this.retryCount - retries + 1;
+        try {
+            const response = await fetch(requestInfo, init);
+            if (response.ok)
+                return response;
+            // don't retry on a 404 since this will never succeed
+            if (response.status === 404) {
+                this.log404Event(urlString);
+                return response;
+            }
+            if (retries > 0) {
+                await this.sleep(this.retryDelay);
+                this.logRetryEvent(urlString, retryNumber, response.statusText, response.status);
+                return this.fetchRetry(requestInfo, init, retries - 1);
+            }
+            this.logFailureEvent(urlString, response.status);
+            return response;
+        }
+        catch (error) {
+            // if a content blocker is detected, log it and don't retry
+            if (this.isContentBlockerError(error)) {
+                this.logContentBlockingEvent(urlString, error);
+                throw error;
+            }
+            if (retries > 0) {
+                await this.sleep(this.retryDelay);
+                // intentionally duplicating the error message here since we want something
+                // in the status code even though we won't have an actual code
+                this.logRetryEvent(urlString, retryNumber, error, error);
+                return this.fetchRetry(requestInfo, init, retries - 1);
+            }
+            this.logFailureEvent(urlString, error);
+            throw error;
+        }
+    }
+    isContentBlockerError(error) {
+        // all of the content blocker errors are `TypeError`
+        if (!(error instanceof TypeError))
+            return false;
+        const message = error.message.toLowerCase();
+        return message.includes('content blocker');
+    }
+    logRetryEvent(urlString, retryNumber, status, code) {
+        this.analyticsHandler.sendEvent({
+            category: this.eventCategory,
+            action: 'retryingFetch',
+            label: `retryNumber: ${retryNumber} / ${this.retryCount}, code: ${code}, status: ${status}, url: ${urlString}`,
+        });
+    }
+    logFailureEvent(urlString, error) {
+        this.analyticsHandler.sendEvent({
+            category: this.eventCategory,
+            action: 'fetchFailed',
+            label: `error: ${error}, url: ${urlString}`,
+        });
+    }
+    log404Event(urlString) {
+        this.analyticsHandler.sendEvent({
+            category: this.eventCategory,
+            action: 'status404NotRetrying',
+            label: `url: ${urlString}`,
+        });
+    }
+    logContentBlockingEvent(urlString, error) {
+        this.analyticsHandler.sendEvent({
+            category: this.eventCategory,
+            action: 'contentBlockerDetectedNotRetrying',
+            label: `error: ${error}, url: ${urlString}`,
+        });
+    }
+}
+//# sourceMappingURL=fetch-retrier.js.map

package/dist/src/utils/fetch-retrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-retrier.js","sourceRoot":"","sources":["../../../src/utils/fetch-retrier.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AnalyticsHandlerInterface } from '@internetarchive/analytics-manager';\nimport { AnalyticsHandler } from '@internetarchive/analytics-manager';\nimport { promisedSleep } from './promised-sleep';\n\n/**\n * A class that retries a fetch request.\n */\nexport interface FetchRetrierInterface {\n  /**\n   * Execute a fetch with retry.\n   *\n   * @param requestInfo RequestInfo\n   * @param init Optional RequestInit\n   * @param retries Optional number of retries to attempt\n   * @returns Promise<Response>\n   */\n  fetchRetry(\n    requestInfo: RequestInfo,\n    init?: RequestInit,\n    retries?: number,\n  ): Promise<Response>;\n}\n\n/** @inheritdoc */\nexport class FetchRetrier implements FetchRetrierInterface {\n  private analyticsHandler = new AnalyticsHandler({ enableAnalytics: true });\n  private sleep = promisedSleep; // default sleep function\n\n  private retryCount = 2;\n\n  private retryDelay = 1000;\n\n  constructor(options?: {\n    analyticsHandler?: AnalyticsHandlerInterface;\n    retryCount?: number;\n    retryDelay?: number;\n    sleepFn?: (ms: number) => Promise<void>; // <-- add this!\n  }) {\n    if (options?.analyticsHandler)\n      this.analyticsHandler = options.analyticsHandler;\n    if (options?.retryCount) this.retryCount = options.retryCount;\n    if (options?.retryDelay) this.retryDelay = options.retryDelay;\n    if (options?.sleepFn) this.sleep = options.sleepFn; // override if provided\n  }\n\n  /** @inheritdoc */\n  public async fetchRetry(\n    requestInfo: RequestInfo,\n    init?: RequestInit,\n    retries: number = this.retryCount,\n  ): Promise<Response> {\n    const urlString =\n      typeof requestInfo === 'string' ? requestInfo : requestInfo.url;\n    const retryNumber = this.retryCount - retries + 1;\n\n    try {\n      const response = await fetch(requestInfo, init);\n      if (response.ok) return response;\n      // don't retry on a 404 since this will never succeed\n      if (response.status === 404) {\n        this.log404Event(urlString);\n        return response;\n      }\n      if (retries > 0) {\n        await this.sleep(this.retryDelay);\n        this.logRetryEvent(\n          urlString,\n          retryNumber,\n          response.statusText,\n          response.status,\n        );\n        return this.fetchRetry(requestInfo, init, retries - 1);\n      }\n      this.logFailureEvent(urlString, response.status);\n      return response;\n    } catch (error) {\n      // if a content blocker is detected, log it and don't retry\n      if (this.isContentBlockerError(error)) {\n        this.logContentBlockingEvent(urlString, error);\n        throw error;\n      }\n\n      if (retries > 0) {\n        await this.sleep(this.retryDelay);\n        // intentionally duplicating the error message here since we want something\n        // in the status code even though we won't have an actual code\n        this.logRetryEvent(urlString, retryNumber, error, error);\n        return this.fetchRetry(requestInfo, init, retries - 1);\n      }\n\n      this.logFailureEvent(urlString, error);\n      throw error;\n    }\n  }\n\n  private isContentBlockerError(error: unknown): boolean {\n    // all of the content blocker errors are `TypeError`\n    if (!(error instanceof TypeError)) return false;\n    const message = error.message.toLowerCase();\n    return message.includes('content blocker');\n  }\n\n  private readonly eventCategory = 'offshootFetchRetry';\n\n  private logRetryEvent(\n    urlString: string,\n    retryNumber: number,\n    status: unknown,\n    code: unknown,\n  ) {\n    this.analyticsHandler.sendEvent({\n      category: this.eventCategory,\n      action: 'retryingFetch',\n      label: `retryNumber: ${retryNumber} / ${this.retryCount}, code: ${code}, status: ${status}, url: ${urlString}`,\n    });\n  }\n\n  private logFailureEvent(urlString: string, error: unknown) {\n    this.analyticsHandler.sendEvent({\n      category: this.eventCategory,\n      action: 'fetchFailed',\n      label: `error: ${error}, url: ${urlString}`,\n    });\n  }\n\n  private log404Event(urlString: string) {\n    this.analyticsHandler.sendEvent({\n      category: this.eventCategory,\n      action: 'status404NotRetrying',\n      label: `url: ${urlString}`,\n    });\n  }\n\n  private logContentBlockingEvent(urlString: string, error: unknown) {\n    this.analyticsHandler.sendEvent({\n      category: this.eventCategory,\n      action: 'contentBlockerDetectedNotRetrying',\n      label: `error: ${error}, url: ${urlString}`,\n    });\n  }\n}\n"]}

package/dist/src/utils/promised-sleep.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Asynchronously pause execution for a given number of milliseconds.
+ *
+ * Used for waiting for some asynchronous updates.
+ *
+ * Usage:
+ * await promisedSleep(100)
+ *
+ * @export
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export declare function promisedSleep(ms: number): Promise<void>;