@ingridab/sdk

Vanilla JS SDK for embedding Ingrid Experience Kit compounds into any web application. Framework-agnostic; for a React-flavoured binding see @ingridab/sdk-react.

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 initIngrid, { createAddressMolecule } from '@ingridab/sdk';

const ingrid = await initIngrid({
  token: 'your-auth-token',
  siteId: 'your-site-id',
  locale: 'en-US',
  molecules: [createAddressMolecule({ mode: 'addressForm' })],
});

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

Listening to events

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

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

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

unsubscribe();

Runtime updates

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

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

// Tear it all down
ingrid.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 initIngrid, { withDefaultProvider } from '@ingridab/sdk';

const ingrid = await initIngrid({
  token,
  siteId,
  locale: 'en-US',
  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