@financial-times/privacy-legislation-client 0.0.0-beta.1

package/README.md

@@ -0,0 +1,45 @@
+# Privacy Legislation Client
+
+## What it is
+
+A module that reports which privacy-related legislation applies in the user's current
+location.
+
+Available for both server and client: see [example](../../examples/legislation-client/README.md)
+
+## Usage
+
+Typical usage would be to add the module to your app, call the imported method
+and then update the UI in line with any applicable legal requirements:
+
+```js
+import { fetchLegislation, buildConsentPageUrl } from "@financial-times/privacy-legislation-client";
+
+function onPageLoad() {
+  /**
+   * `legislation`: a Set of applicable laws: "ccpa", "gdpr", etc
+   * `region`: Identifies countries or subdivisions - "GB", "US-CA"
+   */ 
+  const { legislation, region } = await fetchLegislation();
+
+  // Contruct a standardised URL for the Consent Page, embedding legislation  & referrer
+  const url = buildConsentPageUrl({ url: "...", legislation })
+
+  if(legislation.has("ccpa")) {
+    insertCCPALink(url)
+  }
+
+  if(legislation.has("gdpr")) {
+    ...
+  }
+}
+```
+
+## How it works
+
+This module is a lightweight wrapper over the Fetch API that hits
+`https://privacy.ft.com/api/v1/compliance-region.json`, and exposes the comma-delimted response as a property called `legislation` in the form of a `Set`.
+
+The abstraction allows us to change implementation details like the API's URL, version, etc. without impacting consumers
+
+See the [legislation-api](../../vcl/legislation-api/README.md) for more details

package/dist/main.cjs

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const API_URL = "https://privacy.ft.com/api/v1";
+const API_ENDPOINTS = {
+  complianceRegion: "/compliance-region.json"
+};
+function formatResponse(obj) {
+  return {
+    region: obj.region,
+    legislation: new Set(obj.legislation.split(","))
+  };
+}
+function sessionStorageOk() {
+  const test = "test";
+  try {
+    sessionStorage.setItem(test, test);
+    sessionStorage.removeItem(test);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+function getHostname(referrer) {
+  if (referrer) {
+    try {
+      return new URL(referrer).hostname;
+    } catch (err) {
+      return referrer;
+    }
+  }
+  return typeof window === "undefined" ? "" : window.location.hostname;
+}
+async function fetchLegislation() {
+  const complianceStr = sessionStorageOk() && sessionStorage.getItem("user-compliance");
+  const complianceObj = complianceStr && JSON.parse(complianceStr);
+  if (complianceObj) {
+    return Promise.resolve(formatResponse(complianceObj));
+  } else {
+    const url = `${API_URL}${API_ENDPOINTS.complianceRegion}`;
+    const res = await fetch(url);
+    const compliance = await (res.ok ? res.json() : Promise.reject(res));
+    if (sessionStorageOk()) {
+      sessionStorage.setItem("user-compliance", JSON.stringify(compliance));
+    }
+    return formatResponse(compliance);
+  }
+}
+function buildConsentPageUrl({
+  url,
+  legislation,
+  referrer
+}) {
+  const decoratedUrl = new URL(url);
+  const hostname = getHostname(referrer);
+  for (const id of legislation) {
+    decoratedUrl.searchParams.append("legislation", id);
+  }
+  if (hostname) {
+    decoratedUrl.searchParams.set("referrer", hostname.toLowerCase());
+  }
+  return decoratedUrl.toString();
+}
+exports.API_ENDPOINTS = API_ENDPOINTS;
+exports.API_URL = API_URL;
+exports.buildConsentPageUrl = buildConsentPageUrl;
+exports.fetchLegislation = fetchLegislation;

package/dist/main.d.ts

@@ -0,0 +1,32 @@
+export declare const API_ENDPOINTS: {
+    complianceRegion: string;
+};
+
+export declare const API_URL = "https://privacy.ft.com/api/v1";
+
+/**
+ * Embed legislationIds and referrer as params to `url`
+ * Allows customisation (e.g. skinning, granularity of consent, etc) of the destination page
+ *
+ * This method provides a standardised way to interface with x-privacy-manager
+ */
+export declare function buildConsentPageUrl({ url, legislation, referrer, }: {
+    url: string;
+    legislation: Set<string>;
+    referrer?: string;
+}): string;
+
+/**
+ * Return a promise resolving to an object containing information about the
+ * user's legal protections: *
+ * - region: A string consisting of a country code or country-region ("GB", "US-CA")
+ * - legislation: A Set of the applicable legislationIds
+ */
+export declare function fetchLegislation(): Promise<RegionalCompliance>;
+
+export declare type RegionalCompliance = {
+    region: string;
+    legislation: Set<string>;
+};
+
+export { }

package/dist/main.js

@@ -0,0 +1,66 @@
+const API_URL = "https://privacy.ft.com/api/v1";
+const API_ENDPOINTS = {
+  complianceRegion: "/compliance-region.json"
+};
+function formatResponse(obj) {
+  return {
+    region: obj.region,
+    legislation: new Set(obj.legislation.split(","))
+  };
+}
+function sessionStorageOk() {
+  const test = "test";
+  try {
+    sessionStorage.setItem(test, test);
+    sessionStorage.removeItem(test);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+function getHostname(referrer) {
+  if (referrer) {
+    try {
+      return new URL(referrer).hostname;
+    } catch (err) {
+      return referrer;
+    }
+  }
+  return typeof window === "undefined" ? "" : window.location.hostname;
+}
+async function fetchLegislation() {
+  const complianceStr = sessionStorageOk() && sessionStorage.getItem("user-compliance");
+  const complianceObj = complianceStr && JSON.parse(complianceStr);
+  if (complianceObj) {
+    return Promise.resolve(formatResponse(complianceObj));
+  } else {
+    const url = `${API_URL}${API_ENDPOINTS.complianceRegion}`;
+    const res = await fetch(url);
+    const compliance = await (res.ok ? res.json() : Promise.reject(res));
+    if (sessionStorageOk()) {
+      sessionStorage.setItem("user-compliance", JSON.stringify(compliance));
+    }
+    return formatResponse(compliance);
+  }
+}
+function buildConsentPageUrl({
+  url,
+  legislation,
+  referrer
+}) {
+  const decoratedUrl = new URL(url);
+  const hostname = getHostname(referrer);
+  for (const id of legislation) {
+    decoratedUrl.searchParams.append("legislation", id);
+  }
+  if (hostname) {
+    decoratedUrl.searchParams.set("referrer", hostname.toLowerCase());
+  }
+  return decoratedUrl.toString();
+}
+export {
+  API_ENDPOINTS,
+  API_URL,
+  buildConsentPageUrl,
+  fetchLegislation
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@financial-times/privacy-legislation-client",
+  "description": "",
+  "version": "0.0.0-beta.1",
+  "private": false,
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "types": "./dist/main.d.ts",
+  "main": "./dist/main.cjs",
+  "module": "./dist/main.js",
+  "exports": {
+    ".": {
+      "import": "./dist/main.js",
+      "require": "./dist/main.cjs"
+    }
+  },
+  "devDependencies": {
+    "jest-fetch-mock": "^3.0.3",
+    "jsdom": "^22.1.0",
+    "msw": "^1.3.2",
+    "npm-run-all": "4.1.5",
+    "vite": "^4.5.0",
+    "vite-plugin-dts": "^3.6.3",
+    "vitest": "^0.34.6"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest"
+  }
+}