@google-psat/common 0.9.0-1

package/dist-types/index.d.ts

@@ -0,0 +1,29 @@
+export { default as isFirstParty } from './utils/isFirstParty';
+export { default as filterFramesWithCookies } from './utils/filterFramesWithCookies';
+export { default as filterCookiesByFrame } from './utils/filterCookiesByFrame';
+export { default as getCookieKey } from './utils/getCookieKey';
+export { default as findAnalyticsMatch, emptyAnalytics, } from './utils/findAnalyticsMatch';
+export { default as calculateEffectiveExpiryDate } from './utils/calculateEffectiveExpiryDate';
+export { default as sanitizeCsvRecord } from './utils/sanitizeCsvRecord';
+export { parseUrl } from './utils/parseUrl';
+export { default as fetchLocalData } from './utils/fetchLocalData';
+export * from './data';
+export { default as parseResponseReceivedExtraInfo } from './utils/parseResponseReceivedExtraInfo';
+export { default as parseRequestWillBeSentExtraInfo } from './utils/parseRequestWillBeSentExtraInfo';
+export { default as getDomainFromUrl } from './utils/getDomainFromUrl';
+export { default as extractUrl } from './utils/extractUrl';
+export { default as noop } from './utils/noop';
+export { default as getDevToolWorker } from './worker/devToolWorker';
+export { default as executeTaskInDevToolWorker } from './worker/executeTaskInDevToolWorker';
+export { default as getValueByKey } from './utils/getValueByKey';
+export * from './utils/contextSelector';
+export { default as addUTMParams, type MediumType } from './utils/addUTMParams';
+export { default as delay } from './utils/delay';
+export { default as mergeDeep } from './utils/mergeDeep';
+export { default as resolveWithTimeout } from './utils/resolveWithTimeout';
+export { default as deriveBlockingStatus } from './utils/deriveBlockingStatus';
+export { default as getLegendDescription } from './utils/getLegendDescription';
+export * from './worker/enums';
+export * from './utils/generateReports';
+export * from './cookies.types';
+export * from './libraryDetection.types';

package/dist-types/libraryDetection.types.d.ts

@@ -0,0 +1,51 @@
+/// <reference types="react" />
+export type DetectedSignature = {
+    feature: {
+        type: 'link';
+        text: string;
+        url: string;
+    };
+    subItems: {
+        type: 'subitems';
+        items: {
+            sourceLocation: string;
+            snippet: string;
+        }[];
+    };
+};
+export type LibraryData = {
+    [key: string]: {
+        signatureMatches?: number;
+        moduleMatch?: number;
+        matches?: DetectedSignature[];
+        domQuerymatches?: [string] | null;
+    };
+};
+export type ScriptTagUnderCheck = {
+    origin: string | null;
+    content: string;
+    type?: string;
+};
+export type DetectionFunctions = (arg0: ScriptTagUnderCheck, arg1: DetectedSignature[], arg2: number, arg3?: number) => {
+    signatureMatches: number;
+    matches: DetectedSignature[];
+    moduleMatch?: number;
+};
+export type LibraryMatchers = {
+    name?: string;
+    component: React.FC;
+    signatures?: {
+        strongMatches: {
+            signature: string;
+            helpUrl: string;
+        }[];
+        weakMatches: {
+            signature: string;
+            helpUrl: string;
+        }[];
+    };
+    domainsToSkip?: string[];
+    helpUrl: string;
+    detectionFunction?: DetectionFunctions;
+    domQueryFunction?: (externalDocument?: Document | null) => string[];
+};

package/dist-types/utils/addUTMParams.d.ts

@@ -0,0 +1,3 @@
+export type MediumType = 'extension' | 'cli';
+declare const addUTMParams: (url: string, medium?: MediumType) => string;
+export default addUTMParams;

package/dist-types/utils/calculateEffectiveExpiryDate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Calculate effective expiry date for a cookie.
+ * For example we get expiration date as 1733319706, 1704961011.109784, -1 or empty etc.
+ * @param date {Date | number | string | undefined} The date that needs to be converted for expiration.
+ * @returns {string} The date of expiry for cookie.
+ */
+declare function calculateEffectiveExpiryDate(date: Date | number | string | undefined): string;
+export default calculateEffectiveExpiryDate;

package/dist-types/utils/contextSelector/createContext.d.ts

@@ -0,0 +1,2 @@
+declare const createContext: <T>(defaultValue: T) => import("use-context-selector").Context<T>;
+export default createContext;

package/dist-types/utils/contextSelector/index.d.ts

@@ -0,0 +1,2 @@
+export { default as useContextSelector } from './useContextSelector';
+export { default as createContext } from './createContext';

package/dist-types/utils/contextSelector/shallowEqual.d.ts

@@ -0,0 +1 @@
+export declare const shallowEqual: (a: unknown, b: unknown) => boolean;

package/dist-types/utils/contextSelector/useContextSelector.d.ts

@@ -0,0 +1,23 @@
+/**
+ * External dependencies
+ */
+import { type Context } from 'use-context-selector';
+interface EqualityFn {
+    (a: unknown, b: unknown): boolean;
+}
+/**
+ * This hook returns a part of the context value by selector.
+ * It will trigger a re-render only if the selected value has changed.
+ *
+ * By default, a shallow equals of the selected context value is used to
+ * determine if a re-render is needed.
+ * @param context Context.
+ * @param selector Returns a fragment of the context
+ * that the consumer is interested in.
+ * @param equalityFn Used to compare the
+ * selected context value. If the context fragment has not changed, a re-render
+ * will not be triggered. This is {shallowEqual} by default.
+ * @returns The selected context value fragment.
+ */
+declare function useContextSelector<T, S>(context: Context<T>, selector: (value: T) => S, equalityFn?: EqualityFn): S;
+export default useContextSelector;

package/dist-types/utils/delay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Delay by using setTimeout.
+ * @param ms delay in miliseconds
+ * @returns a promise that will resolve in given amount of miliseconds
+ */
+declare function delay(ms: number): Promise<unknown>;
+export default delay;

package/dist-types/utils/deriveBlockingStatus.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal dependencies.
+ */
+import { CookieData } from '../cookies.types';
+/**
+ * @param networkEvents Cookie network events
+ * @returns blocking status object
+ */
+export default function deriveBlockingStatus(networkEvents: CookieData['networkEvents']): CookieData['blockingStatus'];

package/dist-types/utils/extractUrl.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Extracts the URL from the given string.
+ * @param url - The string containing the URL.
+ * @returns The extracted URL or an empty string if the URL cannot be parsed.
+ */
+export default function extractUrl(url: string): import("tldts-core").IResult;

package/dist-types/utils/fetchLocalData.d.ts

@@ -0,0 +1,2 @@
+declare const fetchLocalData: (path: string) => Promise<any>;
+export default fetchLocalData;

package/dist-types/utils/filterCookiesByFrame.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Internal dependencies.
+ */
+import { TabCookies } from '../cookies.types';
+interface TabFrames {
+    [key: string]: {
+        frameIds: string[];
+    };
+}
+declare const filterCookiesByFrame: (cookies: TabCookies | null, tabFrames: TabFrames | null, frameUrl: string | null) => import("../cookies.types").CookieTableData[];
+export default filterCookiesByFrame;

package/dist-types/utils/filterFramesWithCookies.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies.
+ */
+import { FramesWithCookies, TabCookies, TabFrames } from '../cookies.types';
+declare const filterFramesWithCookies: (tabCookies: TabCookies | null, tabFrames: TabFrames | null) => FramesWithCookies;
+export default filterFramesWithCookies;

package/dist-types/utils/findAnalyticsMatch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Internal dependencies.
+ */
+import { CookieAnalytics, CookieDatabase } from '../cookies.types';
+export declare const emptyAnalytics: {
+    platform: string;
+    category: string;
+    name: string;
+    domain: string;
+    description: string;
+    retention: string;
+    dataController: string;
+    gdprUrl: string;
+    wildcard: string;
+};
+/**
+ * Finds analytics in cookie DB for a cookie name.
+ * @param {string} key cookie name to be matched.
+ * @param {CookieDatabase} dictionary cookieDB for finding matches.
+ * @returns {boolean} Flag for match
+ */
+declare const findAnalyticsMatch: (key: string, dictionary: CookieDatabase) => CookieAnalytics;
+export default findAnalyticsMatch;

package/dist-types/utils/generateReports/generateAllCookiesCSV.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Internal dependencies
+ */
+import { type CompleteJson } from '../../cookies.types';
+export declare const COOKIES_DATA_HEADER: (() => string)[];
+declare const generateAllCookiesCSV: (siteAnalysisData: CompleteJson) => string;
+export default generateAllCookiesCSV;

package/dist-types/utils/generateReports/generateCookiesWithIssuesCSV.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Internal dependencies
+ */
+import type { CompleteJson } from '../../cookies.types';
+export declare const COOKIES_WITH_ISSUES_DATA_HEADERS: (() => string)[];
+declare const generateCookiesWithIssuesCSV: (siteAnalysisData: CompleteJson) => string;
+export default generateCookiesWithIssuesCSV;

package/dist-types/utils/generateReports/generateSummaryDataCSV.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import type { CompleteJson } from '../../cookies.types';
+declare const generateSummaryDataCSV: (siteAnalysisData: CompleteJson) => string;
+export default generateSummaryDataCSV;

package/dist-types/utils/generateReports/generateTechnologyCSV.d.ts

@@ -0,0 +1,3 @@
+import { CompleteJson } from '../../cookies.types';
+declare const generateTechnologyCSV: (siteAnalysisData: CompleteJson) => string;
+export default generateTechnologyCSV;

package/dist-types/utils/generateReports/index.d.ts

@@ -0,0 +1,4 @@
+export { default as generateCookiesWithIssuesCSV } from './generateCookiesWithIssuesCSV';
+export { default as generateAllCookiesCSV } from './generateAllCookiesCSV';
+export { default as generateSummaryDataCSV } from './generateSummaryDataCSV';
+export { default as generateTechnologyCSV } from './generateTechnologyCSV';

package/dist-types/utils/getCookieKey.d.ts

@@ -0,0 +1,6 @@
+/**
+ * External dependencies.
+ */
+import { type Cookie as ParsedCookie } from 'simple-cookie';
+declare const getCookieKey: (parsedCookie: ParsedCookie) => string;
+export default getCookieKey;

package/dist-types/utils/getDomainFromUrl.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the domain of a cookie from the url.
+ * @param url {string} the url the cookies is associated with.
+ * @returns {string} domain of the cookie.
+ */
+export default function getDomainFromUrl(url: string): string;

package/dist-types/utils/getLegendDescription.d.ts

@@ -0,0 +1,2 @@
+declare const getLegendDescription: (legendDescription: string | string[]) => string;
+export default getLegendDescription;

package/dist-types/utils/getValueByKey.d.ts

@@ -0,0 +1,2 @@
+declare const getValueByKey: (keys: string, data: any) => any;
+export default getValueByKey;

package/dist-types/utils/isFirstParty.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Identifies if a cookie's domain is first party by comparing it with the domain of the given URL.
+ * @param {string | undefined} cookieDomain - The URL of the server that is setting/updating the cookie.
+ * @param {string} tabUrl - The top-level URL (URL in the tab's address bar).
+ * @returns {boolean | null} - true if the cookie is first party, false if it's third party, or null if a bad tab URL was passed.
+ */
+declare const isFirstParty: (cookieDomain: string | undefined, tabUrl: string) => boolean | null;
+export default isFirstParty;

package/dist-types/utils/mergeDeep.d.ts

@@ -0,0 +1,2 @@
+declare const mergeDeep: (target: any, source: any) => any;
+export default mergeDeep;

package/dist-types/utils/noop.d.ts

@@ -0,0 +1,2 @@
+declare const noop: () => void;
+export default noop;

package/dist-types/utils/parseRequestWillBeSentExtraInfo.d.ts

@@ -0,0 +1,19 @@
+/**
+ * External dependencies
+ */
+import type { Protocol } from 'devtools-protocol';
+/**
+ * Internal dependencies.
+ */
+import { type CookieData, type CookieDatabase } from '../cookies.types';
+/**
+ * Parses Network.requestWillBeSentExtraInfo to get extra information about a cookie.
+ * @param {object} associatedCookies Cookies associated with the request being parsed.
+ * @param {object} cookieDB Cookie database to find analytics from.
+ * @param {string} requestUrl The request url.
+ * @param {string} tabUrl - The top-level URL (URL in the tab's address bar).
+ * @param {string[]} frameIds The request to which the frame is associated to.
+ * @param {string} requestId - The requestId of the request being processed
+ * @returns {object} parsed cookies.
+ */
+export default function parseRequestWillBeSentExtraInfo(associatedCookies: Protocol.Network.RequestWillBeSentExtraInfoEvent['associatedCookies'], cookieDB: CookieDatabase, requestUrl: string, tabUrl: string, frameIds: string[], requestId: string): CookieData[];

package/dist-types/utils/parseResponseReceivedExtraInfo.d.ts

@@ -0,0 +1,16 @@
+import type { Protocol } from 'devtools-protocol';
+import { type CookieData, type CookieDatabase } from '../cookies.types';
+/**
+ * Parse Network.responseReceivedExtraInfo for extra information about a cookie.
+ * @param {object} headers Headers of resonse to be parsed to get extra information about a cookie.
+ * @param {object} blockedCookies Blocked Cookies associated with the response being parsed.
+ * @param {object} exemptedCookies Blocked Cookies associated with the response being parsed.
+ * @param {string|undefined} cookiePartitionKey Partittion key for the response.
+ * @param {string} requestUrl The associated request URL.
+ * @param {string} tabUrl - The top-level URL (URL in the tab's address bar).
+ * @param {object} cookieDB Cookie database to find analytics from.
+ * @param {string[]} frameIds - The frameId the following cookies are associated to.
+ * @param {string} requestId - The requestId of the request being processed
+ * @returns {object} parsed cookies.
+ */
+export default function parseResponseReceivedExtraInfo(headers: Protocol.Network.ResponseReceivedExtraInfoEvent['headers'], blockedCookies: Protocol.Network.ResponseReceivedExtraInfoEvent['blockedCookies'], exemptedCookies: Protocol.Network.ResponseReceivedExtraInfoEvent['exemptedCookies'], cookiePartitionKey: Protocol.Network.ResponseReceivedExtraInfoEvent['cookiePartitionKey'], requestUrl: string, tabUrl: string, cookieDB: CookieDatabase, frameIds: string[], requestId: string): CookieData[];

package/dist-types/utils/parseUrl.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Parses a URL string and returns a new URL object.
+ * If the URL is invalid, it returns null.
+ * @param {string} url - The URL string to parse.
+ * @returns {URL | null} - The parsed URL object or null if the URL is invalid.
+ */
+export declare const parseUrl: (url: string) => URL | null;

package/dist-types/utils/resolveWithTimeout.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Time a promise.
+ * @param {Promise<T>} promise - A promise that need to be timed.
+ * @param resolveInto
+ * @param {number} timeout - Time for the timeout in milliseconds.
+ * @returns {Promose<T|string>} - The parsed URL object or null if the URL is invalid.
+ */
+export default function resolveWithTimeout<T>(promise: Promise<T>, resolveInto: T, timeout: number): Promise<T | string>;

package/dist-types/utils/sanitizeCsvRecord.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts a string value to a valid CSV record.
+ * @see https://datatracker.ietf.org/doc/html/rfc4180
+ * @param {string} record - a string value that need to be converted into a CSV record.
+ * @returns {URL | null} - The parsed URL object or null if the URL is invalid.
+ */
+declare const sanitizeCsvRecord: (record: unknown) => string;
+export default sanitizeCsvRecord;

package/dist-types/worker/devToolWorker.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get the devTool worker instance. If it doesn't exist, it creates a new one.
+ * @returns {Worker} The DevTool worker instance.
+ */
+declare const getDevToolWorker: () => Worker;
+export default getDevToolWorker;

package/dist-types/worker/enums.d.ts

@@ -0,0 +1,3 @@
+export declare enum LIBRARY_DETECTION_WORKER_TASK {
+    DETECT_SIGNATURE_MATCHING = "DetectSignatureMatching"
+}

package/dist-types/worker/executeTaskInDevToolWorker.d.ts

@@ -0,0 +1,11 @@
+import type { LibraryData } from '../libraryDetection.types';
+import { LIBRARY_DETECTION_WORKER_TASK } from './enums';
+/**
+ * Execute a task using a web worker.
+ * This is a highlevel abstraction over webworker.
+ * @param {string} task - The predefined task to be executed by the worker.
+ * @param {unknown} payload - The payload or data required for the task.
+ * @param {Function} onMessage callback.
+ */
+declare const executeTaskInDevToolWorker: (task: LIBRARY_DETECTION_WORKER_TASK, payload: unknown, onMessage: (dataFromThread: LibraryData) => void) => void;
+export default executeTaskInDevToolWorker;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@google-psat/common",
+  "version": "0.9.0-1",
+  "description": "A package for common utilities that are being used in multiple packages",
+  "main": "dist/index.js",
+  "types": "dist-types/index.d.ts",
+  "source": "src/index.ts",
+  "customExports": {
+    ".": {
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc-watch",
+    "build:remove": "rimraf dist dist-types tsconfig.tsbuildinfo",
+    "publish:local": "npm publish --registry=http://localhost:4873",
+    "publish:remote": "npm publish --access=public --registry=https://registry.npmjs.org",
+    "unpublish:local": "npm unpublish --registry=http://localhost:4873 --force",
+    "unpublish:remote": "npm unpublish --registry=https://registry.npmjs.org --force"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GoogleChromeLabs/ps-analysis-tool",
+    "directory": "packages/common"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": {
+    "name": "Google"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/GoogleChromeLabs/ps-analysis-tool/issues"
+  },
+  "homepage": "https://github.com/GoogleChromeLabs/ps-analysis-tool",
+  "dependencies": {
+    "@google-psat/i18n": "*",
+    "tldts": "^6.0.14"
+  },
+  "devDependencies": {
+    "devtools-protocol": "^0.0.1282316"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "target": "es6",
+    "lib": ["es2021"],
+    "module": "commonjs",
+    "outDir": "dist",
+    "declarationDir": "dist-types",
+    "composite": true,
+    "strict": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node"
+  },
+  "exclude": ["**/tests/**/*.ts", "dist/**", "dist-types/**"],
+  "references": [{ "path": "../i18n" }]
+}