@fiskil/link

Fiskil Link SDK (@fiskil/link)

The Fiskil Link SDK (@fiskil/link) makes it easy to embed a Fiskil Auth Session inside your web application. An Auth Session is how end-users connect their bank or financial institution to share Consumer Data Right (CDR) data through the Fiskil platform.

This SDK handles the complete consent process and returns the outcome of the data sharing process - and you only need to provide a Fiskil auth_session_id to initiate and handle the result in your app. Once the user approves CDR sharing, your backend can listen for Fiskil webhooks and then begin fetching CDR data through Fiskil’s Banking or Energy APIs.

Installation

Install the package with your preferred package manager:

npm i @fiskil/link
# or
pnpm add @fiskil/link

Quick start (ESM/TypeScript)

Note that to use this SDK, you’ll need a Fiskil team account. If you don't have an account, you can get in touch for a quick demo. If you’re new to Fiskil platform, start with the Quick Start Guide.

Before launching the consent flow, your backend must create an Auth Session through the Fiskil API. Pass the resulting auth_session_id into the SDK to start the flow in your application.

import { link, type LinkError } from '@fiskil/link';

// Start the consent flow
const flow = link('auth_session_id');

try {
  const result = await flow;
  console.log(result.consents);
} catch (err) {
  const linkError = err as LinkError;
  console.log('Link Error code:', linkError.code);
} 

// to cancel the consent flow programmatically
// flow.close();

API Reference

link(sessionId, options?)

Creates and mounts the consent UI element. Returns a LinkFlow object, which is both:

• a Promise that resolves with the flow result, and
• a controller with .close() to cancel the flow programmatically.

Result

The LinkFlow resolves with the success payload:

type LinkResult = {
  redirectURL?: string;
  consents: string[];
};

• Resolved result includes redirectURL (if configured) and consents, an array of consent IDs that can be used to fetch user data from the Fiskil platform.
• On failure, the promise rejects with a LinkError (see Error Handling).

Completion messages must contain one or more non-blank string IDs. Invalid consents are ignored without falling back to consentID; the SDK waits for a valid result or timeout.

Migrating to 1.0.0

Breaking change: replace result.consentID with result.consents, an array of consent IDs, and handle each ID. redirectURL remains optional.

Legacy completion messages are still supported: the SDK converts consentID to consents: [consentID].

The SDK adds its package version to the iframe URL as sdkVersion. No configuration is required.

Error Handling

The promise rejects with a LinkError if any error encountered during consent flow.

interface LinkError extends Error {
  name: 'LinkError';
  code: LinkErrorCode;
  details?: unknown;
}

Note: For LINK_INVALID_SESSION, the iframe remains mounted. You can close it programmatically with .close(). For AUTH_SESSION_INVALID, the iframe is removed when the promise rejects.

UMD / CDN Usage

<script src="https://cdn.jsdelivr.net/npm/@fiskil/[email protected]/dist/fiskil-link.umd.js"></script>
<script>
  const flow = FiskilLink.link('session_123');
  flow.then((res) => console.log('done', res)).catch(console.error);
  // flow.close();
</script>