first commit

WeTransfer · Jul 8, 2024 · 7ba8996 · 7ba8996
commit 7ba8996
Show file tree

Hide file tree

Showing 25 changed files with 1,708 additions and 0 deletions.
diff --git a/.babelrc b/.babelrc
@@ -0,0 +1,3 @@
+{
+  "presets": ["@nx/js/babel"]
+}
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -0,0 +1,27 @@
+{
+  "extends": ["../../.eslintrc.client-base.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.tsx", "*.ts"],
+      "parser": "@typescript-eslint/parser",
+      "parserOptions": {
+        "project": ["libs/frame-events-api/tsconfig.*?.json"]
+      }
+    },
+    {
+      "files": ["ParentFrame.ts", "ChildFrame.ts"],
+      "rules": {
+        "no-console": "off",
+        "@typescript-eslint/no-explicit-any": "off"
+      }
+    },
+    {
+      "files": ["*.spec.ts"],
+      "rules": {
+        "@typescript-eslint/no-empty-function": "off",
+        "@typescript-eslint/ban-ts-comment": "off"
+      }
+    }
+  ]
+}
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+coverage
+*.vscode
+build
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,116 @@
+# Changelog
+
+This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+
+## [2.2.5](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.2.5) (2024-05-15)
+
+
+
+## [2.2.4](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.2.4) (2024-04-24)
+
+
+
+## [2.2.3](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.2.3) (2024-04-10)
+
+
+
+## [2.2.2](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.2.2) (2024-03-19)
+
+
+
+## [2.2.1](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.2.1) (2024-03-13)
+
+
+### Bug Fixes
+
+* **desktop-web-renderer:** send action API method ([#935](https://github.com/WeTransfer/adtech-monorepo/issues/935)) ([8f339f3](https://github.com/WeTransfer/adtech-monorepo/commit/8f339f3026d703f530f9c49ab1643063ea624c52))
+
+
+
+# [2.2.0](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.2.0) (2024-03-05)
+
+
+### Features
+
+* **frame-events-api:** clone third-party script inline content ([#916](https://github.com/WeTransfer/adtech-monorepo/issues/916)) ([c524b7b](https://github.com/WeTransfer/adtech-monorepo/commit/c524b7b75308f74e304ef9f237c278f38d63ddf8))
+
+
+
+## [2.1.2](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.1.2) (2024-02-29)
+
+
+
+## [2.1.1](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.1.1) (2023-12-07)
+
+# [2.1.0](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.1.0) (2023-10-09)
+
+### Features
+
+- **frame-events-api:** new event emitter helper ([#789](https://github.com/WeTransfer/adtech-monorepo/issues/789)) ([b01ee2b](https://github.com/WeTransfer/adtech-monorepo/commit/b01ee2ba91d1b92424588e2979c30b7c6f1cf075))
+
+## [2.0.6](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.0.6) (2023-05-04)
+
+## [2.0.5](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.0.5) (2023-05-01)
+
+## [2.0.4](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.0.4) (2023-04-25)
+
+## [2.0.3](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.0.3) (2023-04-12)
+
+## [2.0.2](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.0.2) (2023-04-12)
+
+### Bug Fixes
+
+- **ad-sdk:** update parent api state ([#552](https://github.com/WeTransfer/adtech-monorepo/issues/552)) ([975891d](https://github.com/WeTransfer/adtech-monorepo/commit/975891db5ed7e9cf022214d6022b3c5ebdedf458))
+
+## [2.0.1](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.0.1) (2023-03-30)
+
+# [2.0.0](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@2.0.0) (2023-01-24)
+
+- [ADT-745]: upgrade nx (#440) ([bc2ef3a](https://github.com/WeTransfer/adtech-monorepo/commit/bc2ef3accd24f723a3316a795e2b62bc903bb618)), closes [#440](https://github.com/WeTransfer/adtech-monorepo/issues/440) [#ADT-745](https://github.com/WeTransfer/adtech-monorepo/issues/ADT-745) [#ADT-745](https://github.com/WeTransfer/adtech-monorepo/issues/ADT-745)
+
+### BREAKING CHANGES
+
+- wallpaper.unmount is not supported anymore
+
+- upgrade packages (fix ReactCSSTransition error with react 18)
+
+- specify node version via nvmrc
+
+- align version with transfer FE - needed for rewire-ts
+
+- downgrade react to keep being compatible with FE
+
+- nvm file conflicts with husky, revert node setup
+
+- update @jscutlery/semver
+
+- use lts/fermium to support rewire
+
+- review - remove test inclusion
+
+- cast wallpaper for ts compilation
+
+- fix import.media.url outside of module with publicPath
+
+- removed unneeded packages - added by @nrwl/web
+
+# [1.1.0](https://github.com/WeTransfer/adtech-monorepo/compare/[email protected]@1.1.0) (2023-01-04)
+
+### Features
+
+- **mobile-web:** request new ad ([#435](https://github.com/WeTransfer/adtech-monorepo/issues/435)) ([ab048ef](https://github.com/WeTransfer/adtech-monorepo/commit/ab048efeb0868b610915bc1fcb24a4d49cf3f43a))
+
+# 1.0.0 (2022-12-13)
+
+### Features
+
+- **frame-events-api:** enable several placements per app ([#389](https://github.com/WeTransfer/adtech-monorepo/issues/389)) ([a22568b](https://github.com/WeTransfer/adtech-monorepo/commit/a22568bd17bba5a49ee7aa91c0d05438d8138522))
+- **frame-events-api:** rename-padre-y-marco clean ([#376](https://github.com/WeTransfer/adtech-monorepo/issues/376)) ([57c2486](https://github.com/WeTransfer/adtech-monorepo/commit/57c248609f595be61b49d6f9ebb36a0130ba985e))
+
+### BREAKING CHANGES
+
+- **frame-events-api:** Frames must agree on a placement name
+
+- Use query parameters to define placement
+
+- Docs and cleanup
diff --git a/README.md b/README.md
@@ -0,0 +1,136 @@
+# frame-events-api
+
+Frame Events API is a library for establishing secure parent and child 2-way communication when working with iframes and the `window.postMessage` method.
+
+## How it works
+
+The library consists in two classes, `ParentFrame`, to be instantiated in the parent document and `ChildFrame`, to be run in the embedded document. They both make use of the `Window.postMessage()` method and the `onmessage` event handler.
+
+[Receiver and emitter diagram](./docs/event_flow.drawio)
+
+When a ParentFrame instance defines an interface it sends a ready event to the ChildFrame instance in the embedded document. When the ChildFrame instance receives the ready event it runs the subscriber callback.
+
+[Subscriber callback diagram](./docs/subscriber_callback.drawio)
+
+## Using ParentFrame
+
+```typescript
+new ParentFrame(options);
+```
+
+### Options
+
+| Name      | Type                |            |
+| --------- | ------------------- | ---------- |
+| child     | `HTMLIFrameElement` | `required` |
+| methods   | `object`            |            |
+| listeners | `string[]`          |            |
+| scripts   | `string[]`          |            |
+
+#### child
+
+A child is a `HTMLIFrameElement` that is embedding a document with a ChildFrame instance into the parent document. This iframe must be attached to the DOM and ready to receive events.
+
+When building your iframe source you must specify the parent origin in order to establish a secure connection.
+
+```html
+<iframe
+  src="https://example.com/embedded-document/index.html?_origin=http://parentorigin&_placement=myPlacement"
+></iframe>
+```
+
+#### methods
+
+This is an object with methods that can be fired by the embedded document. When defining method make sure you:
+
+- Don't use any reserved words like `ready`.
+- Add descriptive meaningful function names, they will later be exposed.
+- By design, the methods provided can only take one parameter.
+
+#### listeners
+
+Listeners is an array of event names that you are opening for subscription in the embedded document.
+
+#### scripts
+
+An array of html script tags that you want to ad to the embedded document head.
+
+## Using ChildFrame
+
+```typescript
+new ChildFrame(myCallbackMethod);
+```
+
+### Options
+
+| Name     | Type       |            |                                             |
+| -------- | ---------- | ---------- | ------------------------------------------- |
+| callback | `function` | `required` | Fires when the parent sends the ready event |
+
+#### callback
+
+A function that will execute when the ChildFrame instance gets the ready signal from the parent frame. This function takes as an argument all event names you can listen to and every command you can execute.
+
+## Example
+
+In the main document:
+
+```typescript
+const state = {
+  counter: 0,
+};
+const myAPI = new ParentFrame({
+  child: document.querySelector('iframe'),
+  methods: {
+    updateCounter: function () {
+      state.counter = state.counter++;
+      this.send('counterUpdated', {
+        counter: state.counter,
+      });
+    },
+  },
+  listeners: ['counterUpdated'],
+  scripts: ['<script src=""></script>', '<script src=""></script>'],
+});
+```
+
+Remember to pass the parent origin and the placement as query parameters: `_origin=PARENT_HOST&_placement=PLACEMENT_NAME`:
+
+```html
+<iframe
+  src="http://childorigin/embedded.html?_origin=http://parentorigin&_placement=myPlacement"
+></iframe>
+```
+
+In the embedded document:
+
+```typescript
+const myChildAPI = new ChildFrame(function (data) {
+  // Communication was succesfully established
+  const { listeners, methods } = data;
+
+  // Listen for events
+  myChildAPI.listeners.counterUpdated((event) => {});
+
+  // Fire commands
+  document.querySelector('button').addEventListener('click', function () {
+    myChildAPI.run.updateCounter();
+  });
+});
+```
+
+## Known Issues
+
+- IntelliSense won't work due to how we add the methods to the namespace.
+
+## Build
+
+```
+  nx build frame-events-api --prod
+```
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test frame-events-api` to execute the unit tests via [Jest](https://jestjs.io).
diff --git a/docs/event_flow.drawio b/docs/event_flow.drawio
@@ -0,0 +1,77 @@
+<mxfile host="65bd71144e">
+    <diagram id="C5RBs43oDa-KdzZeNtuy" name="Page-1">
+        <mxGraphModel dx="874" dy="1012" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+            <root>
+                <mxCell id="WIyWlLk6GJQsqaUBKTNV-0"/>
+                <mxCell id="WIyWlLk6GJQsqaUBKTNV-1" parent="WIyWlLk6GJQsqaUBKTNV-0"/>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-27" style="edgeStyle=orthogonalEdgeStyle;rounded=0;jumpSize=6;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-BQQGJLSlea04yl4FD3H-26" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="389" y="150" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-28" value="postMessage" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="-BQQGJLSlea04yl4FD3H-27" vertex="1" connectable="0">
+                    <mxGeometry x="-0.0947" y="-2" relative="1" as="geometry">
+                        <mxPoint as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-26" value="Event Emitter" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+                    <mxGeometry x="79" y="130" width="120" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-29" style="edgeStyle=orthogonalEdgeStyle;rounded=0;jumpSize=6;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;startArrow=classic;startFill=1;endArrow=none;endFill=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-BQQGJLSlea04yl4FD3H-31" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="389" y="250" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-30" value="onmessage" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="-BQQGJLSlea04yl4FD3H-29" vertex="1" connectable="0">
+                    <mxGeometry x="-0.0947" y="-2" relative="1" as="geometry">
+                        <mxPoint as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-31" value="Event Receiver" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+                    <mxGeometry x="79" y="230" width="120" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-36" style="edgeStyle=orthogonalEdgeStyle;rounded=0;jumpSize=6;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-BQQGJLSlea04yl4FD3H-35" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="419" y="250" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-40" value="postMessage" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="-BQQGJLSlea04yl4FD3H-36" vertex="1" connectable="0">
+                    <mxGeometry x="-0.1684" y="-4" relative="1" as="geometry">
+                        <mxPoint as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-35" value="Event Emitter" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+                    <mxGeometry x="609" y="230" width="120" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-37" style="edgeStyle=orthogonalEdgeStyle;rounded=0;jumpSize=6;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;startArrow=classic;startFill=1;endArrow=none;endFill=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" source="-BQQGJLSlea04yl4FD3H-38" edge="1">
+                    <mxGeometry relative="1" as="geometry">
+                        <mxPoint x="419" y="150" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-39" value="onmessage" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" parent="-BQQGJLSlea04yl4FD3H-37" vertex="1" connectable="0">
+                    <mxGeometry x="-0.1263" y="-3" relative="1" as="geometry">
+                        <mxPoint as="offset"/>
+                    </mxGeometry>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-38" value="Event Receiver" style="rounded=1;whiteSpace=wrap;html=1;fontSize=12;glass=0;strokeWidth=1;shadow=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+                    <mxGeometry x="609" y="130" width="120" height="40" as="geometry"/>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-42" value="Parent document" style="swimlane;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+                    <mxGeometry x="39" y="90" width="200" height="200" as="geometry"/>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-43" value="Embedded document" style="swimlane;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+                    <mxGeometry x="569" y="90" width="200" height="200" as="geometry"/>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-44" value="&lt;h1&gt;Event flow&lt;/h1&gt;&lt;p&gt;2-way events&lt;/p&gt;" style="text;html=1;strokeColor=none;fillColor=none;spacing=5;spacingTop=-20;whiteSpace=wrap;overflow=hidden;rounded=0;" parent="WIyWlLk6GJQsqaUBKTNV-1" vertex="1">
+                    <mxGeometry x="39" y="10" width="190" height="80" as="geometry"/>
+                </mxCell>
+                <mxCell id="-BQQGJLSlea04yl4FD3H-45" value="" style="endArrow=none;dashed=1;html=1;rounded=0;jumpSize=6;strokeWidth=8;strokeColor=#C9C9C9;" parent="WIyWlLk6GJQsqaUBKTNV-1" edge="1">
+                    <mxGeometry width="50" height="50" relative="1" as="geometry">
+                        <mxPoint x="407" y="330" as="sourcePoint"/>
+                        <mxPoint x="407" y="50" as="targetPoint"/>
+                    </mxGeometry>
+                </mxCell>
+            </root>
+        </mxGraphModel>
+    </diagram>
+</mxfile>