@ingridab/sdk

Vanilla JS SDK for embedding Ingrid Experience Kit compounds into any web application.

The initial release ships the address molecule; additional molecules will be made available in future releases.

Install

pnpm add @ingridab/sdk

Usage

Initialize the SDK with your credentials and the molecules to render, then mount the returned compound into a container element in the DOM.

import ingrid, { createAddressMolecule } from '@ingridab/sdk';

const instance = await ingrid.init({
  token: 'your-auth-token',
  refreshToken: () => fetch('/your-backend/ingrid-token').then(r => r.json()),
  siteId: 'your-site-id',
  locale: 'en-US',
  countryCode: 'US',
  currency: 'USD',
  molecules: [createAddressMolecule({ mode: 'addressForm' })],
});

await instance.compound.mount('#ingrid-container');

Auth

The refreshToken parameter on ingrid.init is optional. Use it with short-lived Ingrid API tokens, which are preferred. The callback should call your backend, fetch a fresh Ingrid API token server-side, and return it with its expiration timestamp: { accessToken, expiresAt }.

Listening to events

The compound exposes a catch-all on(event, callback) API. Subscriptions return an unsubscribe function.

const unsubscribe = instance.compound.on('addressSubmit', ({ payload }) => {
  console.log('submitted address', payload);
});

instance.compound.on('ready', () => {
  console.log('compound mounted and interactive');
});

unsubscribe();

Runtime updates

// Change locale across the mounted experience
await instance.setLocale('sv-SE');

// Update theme tokens without remounting
instance.compound.update({
  styles: {
    '--color-bg-primary': '#0050ff',
  },
});

// Tear it all down
instance.compound.unmount();

Data providers

The SDK ships with default data providers that talk to Ingrid's hosted API. You can override individual services at init time - useful when you want to route requests through your own backend, inject auth, mock data in tests, or extend the default behaviour with logging.

import ingrid, { createAddressMolecule, withDefaultProvider } from '@ingridab/sdk';

const instance = await ingrid.init({
  token,
  siteId,
  locale: 'en-US',
  countryCode: 'US',
  currency: 'USD',
  molecules: [createAddressMolecule({ mode: 'addressForm' })],
  dataProviders: {
    services: {
      address: {
        // Replace the default implementation entirely.
        listSuggestions: async args => {
          const res = await fetch('/api/address/suggestions', {
            method: 'POST',
            body: JSON.stringify(args.params),
          });
          return res.json();
        },
        // Or wrap the default with `withDefaultProvider` to extend it.
        validateAddress: withDefaultProvider(defaultFn => async args => {
          console.log('validating address', args.params);
          return defaultFn(args);
        }),
      },
    },
  },
});

The request/response shapes used by the providers mirror Ingrid's public REST API. Refer to the OpenAPI specification for endpoint contracts, payload fields, and error responses:

https://docs.ingrid.com/developer-resources/ingrid-api/openapi