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 } from '@fiskil/link';

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

try {
  const result = await flow;
  console.log(result.consentID);
} 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.

| Option | Type | Description | | --------------- | ------ | --------------------------- | | allowedOrigin | string | Restrict postMessage origin (recommended in production). | | timeoutMs | number | Rejects if no message received within this time. defaults to 600000 (10 min) |

Result

The LinkFlow resolves with the success payload:

type LinkResult = {
  redirectURL?: string;
  consentID?: string;
};

• Resolved result includes redirectURL (as configured) and a consentID which can be used to fetch user data from fiskil platform.
• On failure, the promise rejects with a LinkError (see Error Handling).

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;
}

| Error Code | Description | | ----------------------------------- | ------------------------------------------------------| | LINK_NOT_FOUND | Container element not found in DOM | | LINK_TIMEOUT | Flow exceeded timeout duration specified in options | | LINK_USER_CANCELLED | User cancelled or flow was closed programmatically | | LINK_ORIGIN_MISMATCH | Message received from unexpected origin | | LINK_INTERNAL_ERROR | Unrecognized error encountered during the consent flow | | LINK_INVALID_SESSION | The specified auth session is invalid | | CONSENT_UPSTREAM_PROCESSING_ERROR | Upstream processing error during consent flow | | CONSENT_ENDUSER_DENIED | User denied consent during consent flow | | CONSENT_OTP_FAILURE | OTP verification failed during consent flow | | CONSENT_ENDUSER_INELIGIBLE | User is ineligible for data sharing | | CONSENT_TIMEOUT | Consent process timed out |

Note: For LINK_INVALID_SESSION, the iframe remains mounted. You can close it programmatically with .close().

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>