# New York Times (nytimes) FidesJS Extensions

Extensions for `fides.js` tailored for the New York Times (NYT) integration. This package provides wrappers and configuration to support TCF and GPP experiences with NYT-specific behavior in NYT environments.

## Setup

Install dependencies and build locally:

```bash
npm ci
npm run download:build   # updates lib files and builds to dist
```

Start a local example server:

```bash
npm run start:tcf   # serves the TCF wrapper example
# or
npm run start:gpp   # serves the GPP wrapper example
```

## Features

### TCF wrapper (`ext.js`)

Wrapper around the generic `fides-tcf.js` CMP bundle with NYT-specific behavior:

- Custom stylesheet (`ext.css`) to apply NYT styles
- API overrides via `options.apiOptions`:
  - `savePreferencesFn`: disables Fides API persistence and instead stores the `fides_string` and a boolean GDPR preference to NYT PURR APIs (TCF Prefs `v2/tcf` and GDPR Prefs `v2/preferences`)
  - `getPreferencesFn`: fetches a saved `fides_string` from NYT PURR
  - `patchNoticesServedFn`: disables calls to `/api/v1/notices-served` (tracked by NYT analytics and the custom save function instead)
  - `getPrivacyExperienceFn`: fetches the experience from the Fides API via the NYT Fastly endpoint, forcing `region=eea` and omitting `fides_user_device_id` to maximize caching
- Geolocation disabled (`options.isGeolocationEnabled: false`) and forced EEA: `geolocation: { location: "EEA", country: "EEA" }`. Geolocation is performed by NYT's PURR executor in Fastly, and therefore the FidesJS script should always assume EEA and TCF.
- Overlay and TCF enabled (`options.isOverlayEnabled: true`, `options.tcfEnabled: true`)
- Additional NYT logic:
  - Auto-detect NYT non‑production environments (dev, stg, sbx subdomains) and default to development endpoints.
  - `fides_env` URL parameter (`dev`/`prd`) to explicitly choose API environment. This can be enabled like so: `www.nytimes.com?fides_env=dev` or `www.nytimes.com?fides_env=prd`.
  - Respect a global `window.fides_embed` flag to force embedded mode for specific NYT pages (e.g., the NYT Privacy Hub). This is used to workaround a technical problem for the NYT; they set this variable to `true` when rendering the Privacy Hub page (<https://www.nytimes.com/privacy/manage-settings>), but were unable to use our other override methods because those would conflict with their mobile apps (which set their own cookies) or hybrid apps (which set a `window.config.tc_info` object).

### GPP wrapper (`ext-gpp.js`)

Wrapper around base `fides.js` for the GPP framework:

- Custom stylesheet (`ext.css`) to apply NYT styles
- Hardcoded US geolocation: `geolocation: { location: "US", country: "US" }`
- `savePreferencesFn` and `getPreferencesFn` disabled
- Uses a custom `getPrivacyExperienceFn` that builds the URL from `FIDES_API_FASTLY_URL` and `FIDES_API_PRIVACY_EXPERIENCE_PATH`
- TCF support disabled (`tcfEnabled: false`)

## Release process

Release artifacts are produced per-wrapper and shared securely with NYT.

1. Bump `package.json` version (e.g., `2.22.0`). For prereleases, follow npm semver (e.g., when requirements.txt has `2.22.0rc5` use `2.22.0-rc5` in package.json).
1. `npm run download:build` to sync `lib` files and build `dist/fides-nytimes.js` and `dist/fides-gpp-nytimes.js`

### TCF (`dist/fides-nytimes.js`)

1. `npm run start:tcf` and complete a smoke test (see Testing with NYT VPN)
1. Share the new release via 1Password:
    1. Open the 1Password Desktop App and open the "Ethyca <> NYTimes" vault
    1. Create a "New Item" with type "Secure Note"
    1. Title it as "fides-nytimes.js (version 2.20.0-rc5)", updated with current version
    1. Click "Add More > Attach a file" and upload the `dist/fides-nytimes.js` file
    1. Create a "Share" link, expire in 30 days and available to "Anyone with the link" (no need to be overly secure since it will be published publicly)
    1. Include the link in the Release Guide doc for NYT

### GPP (`dist/fides-gpp-nytimes.js`)

1. `npm run start:gpp` and complete a smoke test (see Testing with NYT VPN)
1. Share the new release via 1Password:
    1. Open the 1Password Desktop App and open the "Ethyca <> NYTimes" vault
    1. Create a "New Item" with type "Secure Note"
    1. Title it as "fides-gpp-nytimes.js (version 2.20.0-rc5)", updated with current version
    1. Click "Add More > Attach a file" and upload the `dist/fides-gpp-nytimes.js` file
    1. Create a "Share" link, expire in 30 days and available to "Anyone with the link" (no need to be overly secure since it will be published publicly)
    1. Include the link in the Release Guide doc for NYT

## Testing with local Fides

Testing locally should not be used to verify releases, only for testing development work.

### TCF (`fides-nytimes.js`)

1. Run the `fidesplus` server locally.
1. If needed, create a TCF experience via [Admin-UI](http://localhost:8080).
1. In `fidesplus` add `http://localhost:3003` to `FIDES__SECURITY__CORS_ORIGINS` in `.env` OR if you started fidesplus with seed data, you'll need to add `http://localhost:3003` as a domain in `http://localhost:8080/settings/domains`
1. In this package, change the `start:tcf` script to use port 3003 instead of 3001.
1. Update `privacyCenterUrl` in `ext.js` to your local Privacy Center (e.g., `http://localhost:3001`).
1. Update `FIDES_API_FASTLY_URL_DEV` in `ext.js` to your local Fides API (e.g., `http://localhost:8080/api/v1`).
1. Run `npm run download` or copy distribution files directly from `clients/fides-js/dist/` in this repo, `npm run build`, and `npm run start:tcf` from the `clients/fides-js-extensions/nytimes` directory.

### GPP (`fides-gpp-nytimes.js`)

1. Run the `fidesplus` server locally.
1. If needed, create a TCF experience via [Admin-UI](http://localhost:8080) (for testing cross-behavior).
1. In `fidesplus` add `http://localhost:3003` to `FIDES__SECURITY__CORS_ORIGINS` in `.env` OR if you started fidesplus with seed data, you'll need to add `http://localhost:3003` as a domain in `http://localhost:8080/settings/domains`
1. In this package, use port 3003 for `start:gpp`.
1. Update `privacyCenterUrl` in `ext-gpp.js` (e.g., `http://localhost:3001`).
1. Update `FIDES_API_FASTLY_URL_DEV` in `ext-gpp.js` (e.g., `http://localhost:8080/api/v1`).
1. Run `npm run download` or copy distribution files directly from `clients/fides-js/dist/` in this repo, `npm run build`, and `npm run start:gpp` from the `clients/fides-js-extensions/nytimes` directory.

## Testing with NYT VPN

Testing with the NYT VPN should be done as the final verification step before publishing bundles.

### TCF (`fides-nytimes.js`) w/ VPN

1. Connect to the NYT VPN (see "How-To" guide here: <https://ethyca.atlassian.net/wiki/spaces/EN/pages/2801434626/NYT+Staging+Environment+Guides>).
1. `npm run start:tcf` to launch `http://localhost:3001`.
1. In the Developer Tools > Network tab, verify a successful `privacy-experience` call to the staging API.
1. Delete the `fides_consent` cookie.
1. Add `?google_console=1` to the URL and load the page to open up the Google Publisher Console. Verify:
   1. Google Publisher Console > Page Request tab shows: "An IAB Transparency & Consent v2 Consent Management Provider was detected"
   1. In the Developer Tools > Network tab, `ads?` request includes `gdpr: 1`
1. Click "Accept all" in the banner and verify:
   1. In the Developer Tools > Network tab, `ads?` request includes `gdpr_consent` set to the TC string
   1. `window.Fides.fides_string` returns the TC string; save it for override testing
1. Refresh page, and click "Manage Consent" to open the TCF modal
1. Click "Reject all" in the TCF modal, refresh the page, and confirm:
    1. In the Developer Tools > Network tab, find the `ads?` request and check for query param `gdpr_consent:` and that it is set to the (new, opt-out) TC string
1. Add "?fides_embed=true" to the URL, refresh the page, and confirm:
    1. In the test page, the embedded Layer 2 modal displays with the current "reject all" preferences
1. Add "?fides_embed=true&fides_string={string}" to the URL, using the "Accept all" string from earlier testing, refresh the page, and confirm:
    1. In the test page, the embedded Layer 2 modal displays with the overridden "accept all" preferences
1. Use `ctrl` + `c` to stop the server and remove the container automatically

### GPP (`fides-gpp-nytimes.js`) w/ VPN

1. Connect to the NYT VPN (see "How-To" guide here: <https://ethyca.atlassian.net/wiki/spaces/EN/pages/2801434626/NYT+Staging+Environment+Guides>).
1. `npm run start:gpp` to launch `http://localhost:3001`.
1. In the Developer Tools > Network tab, verify a successful `privacy-experience` call to the staging API.
1. In the console, run `__gpp('ping', (data) => { console.log({ data }) })` to confirm GPP API availability.
1. View notices via `Fides.consent` and note the `notice_key` for the next step.
1. Test overrides using Fides.encodeNoticeConsentString({ your_notice_key: 0|1 }) where `0` is false and `1` is true. (eg. `Fides.encodeNoticeConsentString({ targeted_advertising_gpp_us_national: 0 })`).
1. Set a `fides_string` cookie in the format ",,,notice-consent-string-here" using the encoded string from the previous step (eg. `document.cookie = "fides_string=,,,eyJ0YXJnZXRlZF9hZHZlcnRpc2luZ19ncHBfdXNfbmF0aW9uYWwiOjF9; path=/";`).
1. Reload the page and confirm the GPP string and `window.Fides.consent` reflect the override.
1. Use `ctrl` + `c` to stop the server and remove the container automatically

## NYT Staging Preview Environment Deployment Process

1. Checkout the <https://github.com/nytimes/news> repo locally (this requires a GitHub PAT that is [authorized for SAML SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on))
1. Create a new branch for testing, e.g. `git checkout -b ns-update-fides-2-23-0`
1. Change your working directory to the `projects/fides` subproject within the `news` repo: `cd ~/git/news/projects/fides`
1. Copy the latest `fides-nytimes.js` release to the NYT project: `cp ~/git/fidesplus/clients/fides-js-extensions/nytimes/dist/fides-nytimes.js public/fides.js`
1. Commit your updates, push to the NYT GitHub, and open a Draft Pull Request: <https://github.com/nytimes/news/pulls>
1. Click on the Drone CI action `continuous-integration/drone/pr` to open the build in Drone CI and monitor it's progress; however, note that your initial commit will fail in CI, because snapshot tests need to be updated to pass. Frustratingly, this can't be done in the initial commit due to some bugginess with how they've setup their actions!
1. Generate the sha-tagged version (`lib/public/fides-{sha}.js`) locally that will be uploaded to NYT's GCS static assets: `./buildPublic.sh`
1. Replace the hardcoded `static-assets/fides-*.js` URL in the NYT test snapshots (`Document.test.js.snap` and `Head.test.js.snap`) with the new sha
1. Commit your updates, push to the NYT GitHub, and monitor the (second!) Drone CI build
1. Once the Drone CI succeeds (in particular, the `vi-deploy-pull-request` stage) you should be able to access your preview environment from the link in the PR, e.g. {branch-name}.sbx.nytimes.com/?fides-toggle=true&fides-override=true
