@innovint/cellar-frame-api

v1.1.0

Published

2 months ago

The InnoVint cellar frame API allows communication between an external site's content (loaded in an iframe) and the InnoVint application. The API provides methods for showing or hiding a button in the InnoVint application, and reacting to the button being

0High
0Medium
0Low

kamshak

InnoVint Cellar Frame API

Installation

To start using the InnoVint iFrame API in your app, include the following script tag in your HTML file:

<script type="module">
	import { IFrameApi } from 'https://cdn.skypack.dev/@innovint/cellar-frame-api';
	const innovint = new IFrameApi();
</script>

Alternatively install the package via npm and use it in your bundled app:

import { IFrameApi } from '@innovint/cellar-frame-api';

const iFrameApi = new IFrameApi();
iFrameApi.onOpen$.subscribe((location) => {
	console.log('iFrame opened:', location);
});

Usage Example

Method 1: With a bundler (e.g. when using React, Angular, ...)

// Use the InnoVint iFrame API
import { IFrameApi } from '@innovint/cellar-frame-api';

const innovint = new IFrameApi();

// Subscribe to onOpen$ observable
innovint.onOpen$.subscribe((location) => {
	console.log('iFrame opened:', location);
});

// Subscribe to onClose$ observable
innovint.onClose$.subscribe(() => {
	console.log('iFrame closed');
});

// Set the button visibility and text based on location.state
innovint.setShouldShowButton((location) => {
	if (location.state === 'home.winery.lots') {
		return { show: true, buttonText: 'Expand' };
	}
	return { show: false, buttonText: '' };
});

// Get the current URL of the iFrame
const url = innovint.getCurrentUrl();
console.log('Current URL:', url);

// Close iFrame
innovint.close();

Method 2: Without a bundler / via script tag

<!doctype html>
<html lang="en">
	<head>
		<script type="module">
			import { IFrameApi } from 'https://cdn.skypack.dev/@innovint/cellar-frame-api';
			const innovint = new IFrameApi();
			innovint.onOpen$.subscribe((location) => {
				document.querySelector('pre').innerHTML = JSON.stringify(location, null, 2);
			});
		</script>
	</head>
	<body>
		<pre></pre>
	</body>
</html>

Demo application

A runnable demo using the code from method 2 is available. To use the demo paste the URL (https://cellar-frame-demo.web.app/) as Developer iFrame URL inside InnoVint (Settings -> Cellar Frame).

Methods

`setShouldShowButton(fn: Function): void`

Sets a callback function to inform InnoVint whether the expand button should be displayed, as well as the button's text.

fn: A callback function receiving a location object (containing href, state, and stateParams properties) and returning an object with show (boolean) and buttonText (string) properties.

`close(): void`

Closes the iFrame. No parameters are required.

`getCurrentUrl(): string`

Returns the current URL of the iFrame as a string.

Observables

`onOpen$`: Subject

An RxJS Subject that triggers when the iFrame is opened, passing an object containing the current href, state, and stateParams.

Important: href, state and stateParams describe the internal routing structure inside the InnoVint webapp. They are not guaranteed to be stable and may change at any time without notice.

`onClose$`: Subject

An RxJS Subject that triggers when the iFrame is closed.

Tips for cellar frame applications

Security

Because the cellar frame is served from your own origin, InnoVint’s authentication layer does not automatically protect the iframe’s content. Treat the page you load inside the frame as a stand-alone application and secure it yourself:

Add an authentication gate (e.g. SSO, JWT, session cookie, OAuth token) that matches your company’s security policy.
Use HTTPS and set the SameSite attribute on any cookies you create.
Validate every request your backend receives from the frame, even if the user is already logged in to InnoVint.
Keep sensitive operations in your backend and expose only safe, scoped endpoints to the frame.

SSO

Single Sign-On (SSO) providers often set the X-Frame-Options header to DENY or SAMEORIGIN to prevent their login pages from being embedded in iframes. This security measure blocks the standard redirect flow inside the cellar frame.

To work around this limitation, consider these approaches:

Popup-based login: Initiate the SSO flow in a separate popup window using window.open(). After successful authentication, communicate back to the cellar frame via window.postMessage.
Whitelist your domain: Some providers let you configure a list of trusted domains where the X-Frame-Options restriction is relaxed. Known providers that support this include:
- Auth0 (configure "Allowed Web Origins")
- Okta (add the domain to the "Trusted Origins" list)
- OneLogin (under Trusted Origins)

For Microsoft Entra please refer to https://learn.microsoft.com/en-us/entra/msal/javascript/browser/iframe-usage

Check your provider’s documentation for the exact setting names and steps to add your cellar-frame URL to the whitelist.

Interacting with InnoVint

To read data from InnoVint or want to push updates back use you can use the InnoVint API: https://sutter.innovint.us/api/v1/docs/

Authenticate with a personal access token (PAT), then call the endpoints you need. Keep the PAT server-side and treat it as a password; we recommend that you never ship tokens to the browser.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme