@internetarchive/fetch-handler 1.0.1

package/dist/src/utils/promised-sleep.js

@@ -0,0 +1,16 @@
+/**
+ * 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 function promisedSleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=promised-sleep.js.map

package/dist/src/utils/promised-sleep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promised-sleep.js","sourceRoot":"","sources":["../../../src/utils/promised-sleep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC","sourcesContent":["/**\n * Asynchronously pause execution for a given number of milliseconds.\n *\n * Used for waiting for some asynchronous updates.\n *\n * Usage:\n * await promisedSleep(100)\n *\n * @export\n * @param {number} ms\n * @returns {Promise<void>}\n */\nexport function promisedSleep(ms: number): Promise<void> {\n  return new Promise(resolve => setTimeout(resolve, ms));\n}\n"]}

package/dist/test/fetch-retrier.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/fetch-retrier.test.js

@@ -0,0 +1,139 @@
+import { expect } from '@open-wc/testing';
+import sinon from 'sinon';
+import { FetchRetrier } from '../src/utils/fetch-retrier';
+import { MockAnalyticsHandler } from './mocks/mock-analytics-handler';
+describe('FetchRetrier', () => {
+    let fetchStub;
+    let sleepStub;
+    let analytics;
+    beforeEach(() => {
+        analytics = new MockAnalyticsHandler();
+        fetchStub = sinon.stub(globalThis, 'fetch');
+        sleepStub = sinon.stub().resolves(); // stubbed promisedSleep
+    });
+    afterEach(() => {
+        fetchStub.restore();
+    });
+    it('returns response on first success', async () => {
+        fetchStub.resolves(new Response('ok', { status: 200 }));
+        const retrier = new FetchRetrier({
+            analyticsHandler: analytics,
+            sleepFn: sleepStub,
+        });
+        const res = await retrier.fetchRetry('https://foo.org/data');
+        expect(res.status).to.equal(200);
+        expect(fetchStub.callCount).to.equal(1);
+        expect(sleepStub.callCount).to.equal(0);
+        expect(analytics.events.length).to.equal(0);
+    });
+    it('does not retry on 404 and logs event', async () => {
+        fetchStub.resolves(new Response('not found', { status: 404 }));
+        const retrier = new FetchRetrier({
+            analyticsHandler: analytics,
+            sleepFn: sleepStub,
+        });
+        const res = await retrier.fetchRetry('https://foo.org/404');
+        expect(res.status).to.equal(404);
+        expect(fetchStub.callCount).to.equal(1);
+        expect(sleepStub.callCount).to.equal(0);
+        expect(analytics.events[0].action).to.equal('status404NotRetrying');
+    });
+    it('retries on 500 and logs retry/failure events', async () => {
+        fetchStub.onCall(0).resolves(new Response('fail', { status: 500 }));
+        fetchStub.onCall(1).resolves(new Response('fail again', { status: 500 }));
+        fetchStub.onCall(2).resolves(new Response('still fail', { status: 500 }));
+        const retrier = new FetchRetrier({
+            analyticsHandler: analytics,
+            retryCount: 2,
+            retryDelay: 1,
+            sleepFn: sleepStub,
+        });
+        const res = await retrier.fetchRetry('https://foo.org/fail');
+        expect(res.status).to.equal(500);
+        expect(fetchStub.callCount).to.equal(3);
+        expect(sleepStub.callCount).to.equal(2);
+        expect(analytics.events.some(e => e.action === 'retryingFetch')).to.be.true;
+        expect(analytics.events.some(e => e.action === 'fetchFailed')).to.be.true;
+    });
+    it('retries on fetch error and eventually succeeds', async () => {
+        fetchStub.onCall(0).rejects(new Error('Network error'));
+        fetchStub.onCall(1).resolves(new Response('ok', { status: 200 }));
+        const retrier = new FetchRetrier({
+            analyticsHandler: analytics,
+            retryCount: 1,
+            retryDelay: 1,
+            sleepFn: sleepStub,
+        });
+        const res = await retrier.fetchRetry('https://foo.org/retry');
+        expect(res.status).to.equal(200);
+        expect(fetchStub.callCount).to.equal(2);
+        expect(sleepStub.calledOnce).to.be.true;
+        expect(analytics.events.some(e => e.action === 'retryingFetch')).to.be.true;
+    });
+    it('throws and logs when retries are exhausted due to network error', async () => {
+        fetchStub.rejects(new Error('Boom'));
+        const retrier = new FetchRetrier({
+            analyticsHandler: analytics,
+            retryCount: 1,
+            retryDelay: 1,
+            sleepFn: sleepStub,
+        });
+        try {
+            await retrier.fetchRetry('https://foo.org/networkfail');
+            throw new Error('Should have thrown');
+        }
+        catch (err) {
+            expect(err.message).to.equal('Boom');
+        }
+        expect(fetchStub.callCount).to.equal(2);
+        expect(sleepStub.callCount).to.equal(1);
+        expect(analytics.events.some(e => e.action === 'fetchFailed')).to.be.true;
+    });
+    it('detects content blocker error and does not retry', async () => {
+        const blockerError = new TypeError('Content Blocker denied request');
+        fetchStub.rejects(blockerError);
+        const retrier = new FetchRetrier({
+            analyticsHandler: analytics,
+            retryCount: 2,
+            sleepFn: sleepStub,
+        });
+        try {
+            await retrier.fetchRetry('https://foo.org/blocked');
+            throw new Error('Should have thrown');
+        }
+        catch (err) {
+            expect(err).to.equal(blockerError);
+        }
+        expect(fetchStub.callCount).to.equal(1);
+        expect(sleepStub.callCount).to.equal(0);
+        expect(analytics.events.some(e => e.action === 'contentBlockerDetectedNotRetrying')).to.be.true;
+    });
+    it('calls sleepFn on retry with correct delay', async () => {
+        fetchStub.onCall(0).resolves(new Response(null, { status: 500 }));
+        fetchStub.onCall(1).resolves(new Response('ok', { status: 200 }));
+        const retrier = new FetchRetrier({
+            analyticsHandler: analytics,
+            retryCount: 2,
+            retryDelay: 1234,
+            sleepFn: sleepStub,
+        });
+        const res = await retrier.fetchRetry('https://foo.org/retry-with-sleep');
+        expect(res.status).to.equal(200);
+        expect(sleepStub.calledOnce).to.be.true;
+        expect(sleepStub.calledWith(1234)).to.be.true;
+    });
+    it('sleeps for each retry attempt', async () => {
+        fetchStub.resolves(new Response(null, { status: 500 }));
+        const retrier = new FetchRetrier({
+            analyticsHandler: analytics,
+            retryCount: 2,
+            retryDelay: 300,
+            sleepFn: sleepStub,
+        });
+        const res = await retrier.fetchRetry('https://foo.org/retry-fail');
+        expect(res.status).to.equal(500);
+        expect(sleepStub.callCount).to.equal(2);
+        expect(sleepStub.alwaysCalledWith(300)).to.be.true;
+    });
+});
+//# sourceMappingURL=fetch-retrier.test.js.map

package/dist/test/fetch-retrier.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-retrier.test.js","sourceRoot":"","sources":["../../test/fetch-retrier.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { expect } from '@open-wc/testing';\nimport sinon from 'sinon';\nimport { FetchRetrier } from '../src/utils/fetch-retrier';\nimport { MockAnalyticsHandler } from './mocks/mock-analytics-handler';\n\ndescribe('FetchRetrier', () => {\n  let fetchStub: sinon.SinonStub;\n  let sleepStub: sinon.SinonStub;\n  let analytics: MockAnalyticsHandler;\n\n  beforeEach(() => {\n    analytics = new MockAnalyticsHandler();\n    fetchStub = sinon.stub(globalThis, 'fetch');\n    sleepStub = sinon.stub().resolves(); // stubbed promisedSleep\n  });\n\n  afterEach(() => {\n    fetchStub.restore();\n  });\n\n  it('returns response on first success', async () => {\n    fetchStub.resolves(new Response('ok', { status: 200 }));\n    const retrier = new FetchRetrier({\n      analyticsHandler: analytics,\n      sleepFn: sleepStub,\n    });\n\n    const res = await retrier.fetchRetry('https://foo.org/data');\n\n    expect(res.status).to.equal(200);\n    expect(fetchStub.callCount).to.equal(1);\n    expect(sleepStub.callCount).to.equal(0);\n    expect(analytics.events.length).to.equal(0);\n  });\n\n  it('does not retry on 404 and logs event', async () => {\n    fetchStub.resolves(new Response('not found', { status: 404 }));\n    const retrier = new FetchRetrier({\n      analyticsHandler: analytics,\n      sleepFn: sleepStub,\n    });\n\n    const res = await retrier.fetchRetry('https://foo.org/404');\n\n    expect(res.status).to.equal(404);\n    expect(fetchStub.callCount).to.equal(1);\n    expect(sleepStub.callCount).to.equal(0);\n    expect(analytics.events[0].action).to.equal('status404NotRetrying');\n  });\n\n  it('retries on 500 and logs retry/failure events', async () => {\n    fetchStub.onCall(0).resolves(new Response('fail', { status: 500 }));\n    fetchStub.onCall(1).resolves(new Response('fail again', { status: 500 }));\n    fetchStub.onCall(2).resolves(new Response('still fail', { status: 500 }));\n\n    const retrier = new FetchRetrier({\n      analyticsHandler: analytics,\n      retryCount: 2,\n      retryDelay: 1,\n      sleepFn: sleepStub,\n    });\n\n    const res = await retrier.fetchRetry('https://foo.org/fail');\n\n    expect(res.status).to.equal(500);\n    expect(fetchStub.callCount).to.equal(3);\n    expect(sleepStub.callCount).to.equal(2);\n    expect(analytics.events.some(e => e.action === 'retryingFetch')).to.be.true;\n    expect(analytics.events.some(e => e.action === 'fetchFailed')).to.be.true;\n  });\n\n  it('retries on fetch error and eventually succeeds', async () => {\n    fetchStub.onCall(0).rejects(new Error('Network error'));\n    fetchStub.onCall(1).resolves(new Response('ok', { status: 200 }));\n\n    const retrier = new FetchRetrier({\n      analyticsHandler: analytics,\n      retryCount: 1,\n      retryDelay: 1,\n      sleepFn: sleepStub,\n    });\n\n    const res = await retrier.fetchRetry('https://foo.org/retry');\n\n    expect(res.status).to.equal(200);\n    expect(fetchStub.callCount).to.equal(2);\n    expect(sleepStub.calledOnce).to.be.true;\n    expect(analytics.events.some(e => e.action === 'retryingFetch')).to.be.true;\n  });\n\n  it('throws and logs when retries are exhausted due to network error', async () => {\n    fetchStub.rejects(new Error('Boom'));\n\n    const retrier = new FetchRetrier({\n      analyticsHandler: analytics,\n      retryCount: 1,\n      retryDelay: 1,\n      sleepFn: sleepStub,\n    });\n\n    try {\n      await retrier.fetchRetry('https://foo.org/networkfail');\n      throw new Error('Should have thrown');\n    } catch (err: any) {\n      expect(err.message).to.equal('Boom');\n    }\n\n    expect(fetchStub.callCount).to.equal(2);\n    expect(sleepStub.callCount).to.equal(1);\n    expect(analytics.events.some(e => e.action === 'fetchFailed')).to.be.true;\n  });\n\n  it('detects content blocker error and does not retry', async () => {\n    const blockerError = new TypeError('Content Blocker denied request');\n    fetchStub.rejects(blockerError);\n\n    const retrier = new FetchRetrier({\n      analyticsHandler: analytics,\n      retryCount: 2,\n      sleepFn: sleepStub,\n    });\n\n    try {\n      await retrier.fetchRetry('https://foo.org/blocked');\n      throw new Error('Should have thrown');\n    } catch (err: any) {\n      expect(err).to.equal(blockerError);\n    }\n\n    expect(fetchStub.callCount).to.equal(1);\n    expect(sleepStub.callCount).to.equal(0);\n    expect(\n      analytics.events.some(\n        e => e.action === 'contentBlockerDetectedNotRetrying',\n      ),\n    ).to.be.true;\n  });\n\n  it('calls sleepFn on retry with correct delay', async () => {\n    fetchStub.onCall(0).resolves(new Response(null, { status: 500 }));\n    fetchStub.onCall(1).resolves(new Response('ok', { status: 200 }));\n\n    const retrier = new FetchRetrier({\n      analyticsHandler: analytics,\n      retryCount: 2,\n      retryDelay: 1234,\n      sleepFn: sleepStub,\n    });\n\n    const res = await retrier.fetchRetry('https://foo.org/retry-with-sleep');\n\n    expect(res.status).to.equal(200);\n    expect(sleepStub.calledOnce).to.be.true;\n    expect(sleepStub.calledWith(1234)).to.be.true;\n  });\n\n  it('sleeps for each retry attempt', async () => {\n    fetchStub.resolves(new Response(null, { status: 500 }));\n\n    const retrier = new FetchRetrier({\n      analyticsHandler: analytics,\n      retryCount: 2,\n      retryDelay: 300,\n      sleepFn: sleepStub,\n    });\n\n    const res = await retrier.fetchRetry('https://foo.org/retry-fail');\n\n    expect(res.status).to.equal(500);\n    expect(sleepStub.callCount).to.equal(2);\n    expect(sleepStub.alwaysCalledWith(300)).to.be.true;\n  });\n});\n"]}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,50 @@
+import { expect } from '@open-wc/testing';
+import { IaFetchHandler } from '../src/ia-fetch-handler';
+class MockFetchRetrier {
+    async fetchRetry(requestInfo, init, retries) {
+        this.init = init;
+        this.requestInfo = requestInfo;
+        this.retries = retries;
+        return new Response(JSON.stringify({ boop: 'snoot' }), { status: 200 });
+    }
+}
+describe('Fetch Handler', () => {
+    describe('fetch', () => {
+        it('adds reCache=1 if it is in the current url', async () => {
+            const fetchRetrier = new MockFetchRetrier();
+            const fetchHandler = new IaFetchHandler({
+                fetchRetrier: fetchRetrier,
+                searchParams: '?reCache=1',
+            });
+            await fetchHandler.fetch('https://foo.org/api/v1/snoot');
+            expect(fetchRetrier.requestInfo).to.equal('https://foo.org/api/v1/snoot?reCache=1');
+        });
+    });
+    describe('fetchIAApiResponse', () => {
+        it('prepends the IA basehost to the url when making a request', async () => {
+            const endpoint = '/foo/service/endpoint.php';
+            const fetchRetrier = new MockFetchRetrier();
+            const fetchHandler = new IaFetchHandler({
+                iaApiBaseUrl: 'www.example.com',
+                fetchRetrier: fetchRetrier,
+            });
+            await fetchHandler.fetchIAApiResponse(endpoint);
+            expect(fetchRetrier.requestInfo).to.equal('www.example.com/foo/service/endpoint.php');
+        });
+    });
+    describe('fetchApiResponse', () => {
+        it('adds credentials: include if requested', async () => {
+            const endpoint = '/foo/service/endpoint.php';
+            const fetchRetrier = new MockFetchRetrier();
+            const fetchHandler = new IaFetchHandler({
+                iaApiBaseUrl: 'www.example.com',
+                fetchRetrier: fetchRetrier,
+            });
+            await fetchHandler.fetchApiResponse(endpoint, {
+                includeCredentials: true,
+            });
+            expect(fetchRetrier.init).to.deep.equal({ credentials: 'include' });
+        });
+    });
+});
+//# sourceMappingURL=ia-fetch-handler.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ia-fetch-handler.test.js","sourceRoot":"","sources":["../../test/ia-fetch-handler.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAGzD,MAAM,gBAAgB;IAKpB,KAAK,CAAC,UAAU,CACd,WAAwB,EACxB,IAAkB,EAClB,OAAgB;QAEhB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1E,CAAC;CACF;AAED,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE;QACrB,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;YAC1D,MAAM,YAAY,GAAG,IAAI,gBAAgB,EAAE,CAAC;YAC5C,MAAM,YAAY,GAAG,IAAI,cAAc,CAAC;gBACtC,YAAY,EAAE,YAAY;gBAC1B,YAAY,EAAE,YAAY;aAC3B,CAAC,CAAC;YACH,MAAM,YAAY,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;YACzD,MAAM,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,KAAK,CACvC,wCAAwC,CACzC,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAClC,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;YACzE,MAAM,QAAQ,GAAG,2BAA2B,CAAC;YAC7C,MAAM,YAAY,GAAG,IAAI,gBAAgB,EAAE,CAAC;YAC5C,MAAM,YAAY,GAAG,IAAI,cAAc,CAAC;gBACtC,YAAY,EAAE,iBAAiB;gBAC/B,YAAY,EAAE,YAAY;aAC3B,CAAC,CAAC;YACH,MAAM,YAAY,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAChD,MAAM,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,KAAK,CACvC,0CAA0C,CAC3C,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAChC,EAAE,CAAC,wCAAwC,EAAE,KAAK,IAAI,EAAE;YACtD,MAAM,QAAQ,GAAG,2BAA2B,CAAC;YAC7C,MAAM,YAAY,GAAG,IAAI,gBAAgB,EAAE,CAAC;YAC5C,MAAM,YAAY,GAAG,IAAI,cAAc,CAAC;gBACtC,YAAY,EAAE,iBAAiB;gBAC/B,YAAY,EAAE,YAAY;aAC3B,CAAC,CAAC;YACH,MAAM,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE;gBAC5C,kBAAkB,EAAE,IAAI;aACzB,CAAC,CAAC;YACH,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;QACtE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { expect } from '@open-wc/testing';\nimport { IaFetchHandler } from '../src/ia-fetch-handler';\nimport { FetchRetrierInterface } from '../src/utils/fetch-retrier';\n\nclass MockFetchRetrier implements FetchRetrierInterface {\n  requestInfo?: RequestInfo;\n  init?: RequestInit;\n  retries?: number;\n\n  async fetchRetry(\n    requestInfo: RequestInfo,\n    init?: RequestInit,\n    retries?: number,\n  ): Promise<Response> {\n    this.init = init;\n    this.requestInfo = requestInfo;\n    this.retries = retries;\n    return new Response(JSON.stringify({ boop: 'snoot' }), { status: 200 });\n  }\n}\n\ndescribe('Fetch Handler', () => {\n  describe('fetch', () => {\n    it('adds reCache=1 if it is in the current url', async () => {\n      const fetchRetrier = new MockFetchRetrier();\n      const fetchHandler = new IaFetchHandler({\n        fetchRetrier: fetchRetrier,\n        searchParams: '?reCache=1',\n      });\n      await fetchHandler.fetch('https://foo.org/api/v1/snoot');\n      expect(fetchRetrier.requestInfo).to.equal(\n        'https://foo.org/api/v1/snoot?reCache=1',\n      );\n    });\n  });\n\n  describe('fetchIAApiResponse', () => {\n    it('prepends the IA basehost to the url when making a request', async () => {\n      const endpoint = '/foo/service/endpoint.php';\n      const fetchRetrier = new MockFetchRetrier();\n      const fetchHandler = new IaFetchHandler({\n        iaApiBaseUrl: 'www.example.com',\n        fetchRetrier: fetchRetrier,\n      });\n      await fetchHandler.fetchIAApiResponse(endpoint);\n      expect(fetchRetrier.requestInfo).to.equal(\n        'www.example.com/foo/service/endpoint.php',\n      );\n    });\n  });\n\n  describe('fetchApiResponse', () => {\n    it('adds credentials: include if requested', async () => {\n      const endpoint = '/foo/service/endpoint.php';\n      const fetchRetrier = new MockFetchRetrier();\n      const fetchHandler = new IaFetchHandler({\n        iaApiBaseUrl: 'www.example.com',\n        fetchRetrier: fetchRetrier,\n      });\n      await fetchHandler.fetchApiResponse(endpoint, {\n        includeCredentials: true,\n      });\n      expect(fetchRetrier.init).to.deep.equal({ credentials: 'include' });\n    });\n  });\n});\n"]}

package/dist/test/mocks/mock-analytics-handler.d.ts

@@ -0,0 +1,20 @@
+import type { AnalyticsEvent } from '@internetarchive/analytics-manager';
+import type { AnalyticsHandlerInterface } from '@internetarchive/analytics-manager';
+export type MockAnalyticsEvent = AnalyticsEvent & {
+    bucketType: '1%' | '100%';
+    additionalEventParams?: object;
+};
+export declare class MockAnalyticsHandler implements AnalyticsHandlerInterface {
+    events: MockAnalyticsEvent[];
+    sendPing(values: Record<string, any>): void;
+    sendEvent(event: MockAnalyticsEvent): void;
+    send_event(category: string, action: string, label?: string, additionalEventParams?: object): void;
+    sendEventNoSampling(event: AnalyticsEvent): void;
+    trackIaxParameter(location: string): void;
+    trackPageView(options?: {
+        mediaType?: string;
+        mediaLanguage?: string;
+        primaryCollection?: string;
+        page?: string;
+    }): void;
+}

package/dist/test/mocks/mock-analytics-handler.js

@@ -0,0 +1,28 @@
+export class MockAnalyticsHandler {
+    constructor() {
+        this.events = [];
+    }
+    sendPing(values) { }
+    sendEvent(event) {
+        const thisEvent = Object.assign({}, event, { bucketType: '1%' });
+        this.events.push(thisEvent);
+    }
+    send_event(category, action, label, additionalEventParams) {
+        this.events.push({
+            category,
+            action,
+            label,
+            bucketType: '1%',
+            additionalEventParams: { ...additionalEventParams },
+        });
+    }
+    sendEventNoSampling(event) {
+        this.events.push({
+            ...event,
+            bucketType: '100%',
+        });
+    }
+    trackIaxParameter(location) { }
+    trackPageView(options) { }
+}
+//# sourceMappingURL=mock-analytics-handler.js.map

package/dist/test/mocks/mock-analytics-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-analytics-handler.js","sourceRoot":"","sources":["../../../test/mocks/mock-analytics-handler.ts"],"names":[],"mappings":"AAOA,MAAM,OAAO,oBAAoB;IAAjC;QACE,WAAM,GAAyB,EAAE,CAAC;IAkCpC,CAAC;IAhCC,QAAQ,CAAC,MAA2B,IAAS,CAAC;IAC9C,SAAS,CAAC,KAAyB;QACjC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9B,CAAC;IACD,UAAU,CACR,QAAgB,EAChB,MAAc,EACd,KAAc,EACd,qBAA8B;QAE9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,QAAQ;YACR,MAAM;YACN,KAAK;YACL,UAAU,EAAE,IAAI;YAChB,qBAAqB,EAAE,EAAE,GAAG,qBAAqB,EAAE;SACpD,CAAC,CAAC;IACL,CAAC;IACD,mBAAmB,CAAC,KAAqB;QACvC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,GAAG,KAAK;YACR,UAAU,EAAE,MAAM;SACc,CAAC,CAAC;IACtC,CAAC;IACD,iBAAiB,CAAC,QAAgB,IAAS,CAAC;IAC5C,aAAa,CAAC,OAKb,IAAS,CAAC;CACZ","sourcesContent":["import type { AnalyticsEvent } from '@internetarchive/analytics-manager';\nimport type { AnalyticsHandlerInterface } from '@internetarchive/analytics-manager';\n\nexport type MockAnalyticsEvent = AnalyticsEvent & {\n  bucketType: '1%' | '100%';\n  additionalEventParams?: object;\n};\nexport class MockAnalyticsHandler implements AnalyticsHandlerInterface {\n  events: MockAnalyticsEvent[] = [];\n\n  sendPing(values: Record<string, any>): void {}\n  sendEvent(event: MockAnalyticsEvent): void {\n    const thisEvent = Object.assign({}, event, { bucketType: '1%' });\n    this.events.push(thisEvent);\n  }\n  send_event(\n    category: string,\n    action: string,\n    label?: string,\n    additionalEventParams?: object,\n  ): void {\n    this.events.push({\n      category,\n      action,\n      label,\n      bucketType: '1%',\n      additionalEventParams: { ...additionalEventParams },\n    });\n  }\n  sendEventNoSampling(event: AnalyticsEvent): void {\n    this.events.push({\n      ...event,\n      bucketType: '100%',\n    } as unknown as MockAnalyticsEvent);\n  }\n  trackIaxParameter(location: string): void {}\n  trackPageView(options?: {\n    mediaType?: string;\n    mediaLanguage?: string;\n    primaryCollection?: string;\n    page?: string;\n  }): void {}\n}\n"]}

package/dist/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/vite.config.js

@@ -0,0 +1,25 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+// https://vitejs.dev/config/
+export default defineConfig({
+    base: './',
+    root: resolve(__dirname, './demo'),
+    build: {
+        /**
+         * This is the directory where the built files will be placed
+         * that we upload to GitHub Pages.
+         */
+        outDir: '../ghpages/demo',
+        emptyOutDir: true,
+        manifest: true,
+        rollupOptions: {
+            input: {
+                main: resolve(__dirname, 'demo/index.html'),
+            },
+            output: {
+                entryFileNames: 'app-root.js',
+            },
+        },
+    },
+});
+//# sourceMappingURL=vite.config.js.map

package/dist/vite.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.config.js","sourceRoot":"","sources":["../vite.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE/B,6BAA6B;AAC7B,eAAe,YAAY,CAAC;IAC1B,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC;IAClC,KAAK,EAAE;QACL;;;WAGG;QACH,MAAM,EAAE,iBAAiB;QACzB,WAAW,EAAE,IAAI;QACjB,QAAQ,EAAE,IAAI;QACd,aAAa,EAAE;YACb,KAAK,EAAE;gBACL,IAAI,EAAE,OAAO,CAAC,SAAS,EAAE,iBAAiB,CAAC;aAC5C;YACD,MAAM,EAAE;gBACN,cAAc,EAAE,aAAa;aAC9B;SACF;KACF;CACF,CAAC,CAAC","sourcesContent":["import { defineConfig } from 'vite';\nimport { resolve } from 'path';\n\n// https://vitejs.dev/config/\nexport default defineConfig({\n  base: './',\n  root: resolve(__dirname, './demo'),\n  build: {\n    /**\n     * This is the directory where the built files will be placed\n     * that we upload to GitHub Pages.\n     */\n    outDir: '../ghpages/demo',\n    emptyOutDir: true,\n    manifest: true,\n    rollupOptions: {\n      input: {\n        main: resolve(__dirname, 'demo/index.html'),\n      },\n      output: {\n        entryFileNames: 'app-root.js',\n      },\n    },\n  },\n});\n"]}

package/eslint.config.mjs

@@ -0,0 +1,53 @@
+import typescriptEslint from '@typescript-eslint/eslint-plugin';
+import html from 'eslint-plugin-html';
+import tsParser from '@typescript-eslint/parser';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import js from '@eslint/js';
+import { FlatCompat } from '@eslint/eslintrc';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+export default [
+  ...compat.extends('plugin:@typescript-eslint/recommended'),
+  {
+    plugins: {
+      '@typescript-eslint': typescriptEslint,
+      html,
+    },
+
+    languageOptions: {
+      parser: tsParser,
+    },
+
+    settings: {
+      'import/resolver': {
+        node: {
+          extensions: ['.ts', '.tsx'],
+          moduleDirectory: ['node_modules', 'src', 'demo'],
+        },
+      },
+    },
+
+    rules: {
+      '@typescript-eslint/no-unsafe-function-type': 'warn',
+      '@typescript-eslint/no-unused-vars': 'warn',
+      '@typescript-eslint/no-explicit-any': 'warn',
+    },
+  },
+  {
+    ignores: ['**/*.js', '**/*.mjs', '**/*.d.ts'],
+  },
+  {
+    files: ['**/*.test.ts'],
+    rules: {
+      '@typescript-eslint/no-unused-expressions': 'off',
+    },
+  },
+];

package/index.ts

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

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@internetarchive/fetch-handler",
+  "description": "A custom service for handling API requests",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/internetarchive/fetch-handler.git"
+  },
+  "license": "AGPL-3.0-only",
+  "author": "Internet Archive",
+  "version": "1.0.1",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "scripts": {
+    "start": "tsc && concurrently -k -r \"tsc --watch --preserveWatchOutput\" \"wds\"",
+    "prepare": "rimraf dist && tsc && husky install",
+    "build": "tsc",
+    "lint": "eslint . && prettier \"**/*.ts\" --check",
+    "format": "eslint . --fix && prettier \"**/*.ts\" --write",
+    "circular": "madge --circular --extensions ts .",
+    "test": "tsc && npm run lint && npm run circular && wtr --coverage",
+    "test:watch": "tsc && concurrently -k -r \"tsc --watch --preserveWatchOutput\" \"wtr --watch\"",
+    "ghpages:build": "rimraf ghpages && npm run prepare && vite build",
+    "ghpages:publish": "npm run ghpages:prepare -e $(git branch --show-current)",
+    "ghpages:prepare": "npm run ghpages:build && touch ghpages/.nojekyll && npm run ghpages:generate",
+    "ghpages:generate": "gh-pages -t -d ghpages -m \"Build for $(git log --pretty=format:\"%h %an %ai %s\" -n1) [skip ci]\""
+  },
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@internetarchive/analytics-manager": "^0.1.5",
+    "lit": "^2.8.0"
+  },
+  "devDependencies": {
+    "@open-wc/eslint-config": "^12.0.3",
+    "@open-wc/testing": "^4.0.0",
+    "@types/mocha": "^10.0.10",
+    "@typescript-eslint/eslint-plugin": "^8.19.1",
+    "@typescript-eslint/parser": "^8.19.1",
+    "@web/dev-server": "^0.4.6",
+    "@web/test-runner": "^0.20.0",
+    "concurrently": "^9.1.2",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-html": "^8.1.2",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-lit": "^1.15.0",
+    "eslint-plugin-lit-a11y": "^4.1.4",
+    "eslint-plugin-no-only-tests": "^3.3.0",
+    "eslint-plugin-wc": "^2.2.0",
+    "gh-pages": "^6.3.0",
+    "husky": "^9.1.7",
+    "madge": "^8.0.0",
+    "prettier": "^3.4.2",
+    "rimraf": "^6.0.1",
+    "sinon": "^19.0.2",
+    "ts-lit-plugin": "^2.0.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "arrowParens": "avoid"
+  },
+  "lint-staged": {
+    "*.ts": [
+      "eslint --fix",
+      "prettier --write",
+      "git add"
+    ]
+  }
+}

package/renovate.json

@@ -0,0 +1,6 @@
+{
+  "extends": [
+    "config:base",
+    ":preserveSemverRanges"
+  ]
+}

package/src/fetch-handler-interface.ts

@@ -0,0 +1,39 @@
+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/src/ia-fetch-handler.ts

@@ -0,0 +1,94 @@
+import { FetchRetrier, 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 class IaFetchHandler implements FetchHandlerInterface {
+  private iaApiBaseUrl?: string;
+
+  private fetchRetrier: FetchRetrierInterface = new FetchRetrier();
+
+  private searchParams?: string;
+
+  constructor(options?: {
+    iaApiBaseUrl?: string;
+    fetchRetrier?: FetchRetrierInterface;
+    searchParams?: string;
+  }) {
+    if (options?.iaApiBaseUrl) this.iaApiBaseUrl = options.iaApiBaseUrl;
+    if (options?.fetchRetrier) this.fetchRetrier = options.fetchRetrier;
+    if (options?.searchParams) {
+      this.searchParams = options.searchParams;
+    } else {
+      this.searchParams = window.location.search;
+    }
+  }
+
+  /** @inheritdoc */
+  async fetchIAApiResponse<T>(
+    path: string,
+    options?: {
+      includeCredentials?: boolean;
+    },
+  ): Promise<T> {
+    const url = `${this.iaApiBaseUrl}${path}`;
+    return this.fetchApiResponse(url, options);
+  }
+
+  /** @inheritdoc */
+  async fetchApiResponse<T>(
+    url: string,
+    options?: {
+      includeCredentials?: boolean;
+      method?: string;
+      body?: BodyInit;
+      headers?: HeadersInit;
+    },
+  ): Promise<T> {
+    const requestInit: RequestInit = {};
+    if (options?.includeCredentials) requestInit.credentials = 'include';
+    if (options?.method) requestInit.method = options.method;
+    if (options?.body) requestInit.body = options.body;
+    if (options?.headers) requestInit.headers = options.headers;
+    const response = await this.fetch(url, requestInit);
+    const json = await response.json();
+    return json as T;
+  }
+
+  /** @inheritdoc */
+  async fetch(input: RequestInfo, init?: RequestInit): Promise<Response> {
+    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.
+   */
+  private addSearchParams(
+    input: RequestInfo,
+    params: Record<string, string>,
+  ): RequestInfo {
+    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;
+    }
+  }
+}