@ingridab/sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,7 @@
 # @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`](../sdk-react).
+application.
 
 The initial release ships the `address` molecule; additional molecules will
 be made available in future releases.
@@ -19,29 +18,37 @@ Initialize the SDK with your credentials and the molecules to render, then
 mount the returned compound into a container element in the DOM.
 
 ```ts
-import initIngrid, { createAddressMolecule } from '@ingridab/sdk';
+import ingrid, { createAddressMolecule } from '@ingridab/sdk';
 
-const ingrid = await initIngrid({
+const instance = await ingrid.init({
   token: 'your-auth-token',
   siteId: 'your-site-id',
   locale: 'en-US',
+  countryCode: 'US',
+  currency: 'USD',
   molecules: [createAddressMolecule({ mode: 'addressForm' })],
 });
 
-await ingrid.compound.mount('#ingrid-container');
+await instance.compound.mount('#ingrid-container');
 ```
 
+### Auth
+
+`refreshToken` is optional. Use it with short-lived Ingrid API tokens, which are
+preferred. The callback should call your backend and return a fresh token issued by the
+integrator with its expiration timestamp: `{ accessToken, expiresAt }`.
+
 ### Listening to events
 
 The compound exposes a catch-all `on(event, callback)` API. Subscriptions
 return an unsubscribe function.
 
 ```ts
-const unsubscribe = ingrid.compound.on('addressSubmit', ({ payload }) => {
+const unsubscribe = instance.compound.on('addressSubmit', ({ payload }) => {
   console.log('submitted address', payload);
 });
 
-ingrid.compound.on('ready', () => {
+instance.compound.on('ready', () => {
   console.log('compound mounted and interactive');
 });
 
@@ -52,17 +59,17 @@ unsubscribe();
 
 ```ts
 // Change locale across the mounted experience
-ingrid.setLocale('sv-SE');
+instance.setLocale('sv-SE');
 
 // Update theme tokens without remounting
-ingrid.compound.update({
+instance.compound.update({
   styles: {
-    '--ingrid-color-primary': '#0050ff',
+    '--color-bg-primary': '#0050ff',
   },
 });
 
 // Tear it all down
-ingrid.compound.unmount();
+instance.compound.unmount();
 ```
 
 ## Data providers
@@ -73,12 +80,14 @@ route requests through your own backend, inject auth, mock data in tests, or
 extend the default behaviour with logging.
 
 ```ts
-import initIngrid, { withDefaultProvider } from '@ingridab/sdk';
+import ingrid, { createAddressMolecule, withDefaultProvider } from '@ingridab/sdk';
 
-const ingrid = await initIngrid({
+const instance = await ingrid.init({
   token,
   siteId,
   locale: 'en-US',
+  countryCode: 'US',
+  currency: 'USD',
   molecules: [createAddressMolecule({ mode: 'addressForm' })],
   dataProviders: {
     services: {

package/dist/index.d.ts

@@ -224,15 +224,13 @@ declare type AddressFormResponse = {
 
 declare type AddressFormService = {
     getAddressFormConfig: DataResolver<
-        { params: GetAddressFormQuery['QueryParams']; token: string },
+        { params: GetAddressFormQuery['QueryParams'] } & SDKManagedTokenArg,
     GetAddressFormQuery['Response']
     >;
 };
 
 /* Excluded from this release type: AddressMoleculeCustomization */
 
-declare type AddressMoleculeInputState = Partial<AddressContactEntry>;
-
 /**
  * Configuration params passed to the address molecule.
  *
@@ -248,8 +246,8 @@ declare type AddressMoleculeInputState = Partial<AddressContactEntry>;
  * ```
  */
 declare type AddressMoleculeParams = {
-    /** The rendering mode for the address molecule. Currently `'addressForm'` is supported. */
-    mode: 'addressForm';
+    /** The rendering mode for the address molecule. Currently `'addressForm'` and `'searchDriven'` are supported. */
+    mode: 'addressForm' | 'searchDriven';
     customization?: AddressMoleculePublicCustomization;
 };
 
@@ -266,7 +264,7 @@ declare type AddressMoleculePublicCustomization = {
         /**
          * Controls how the address book is presented.
          *
-         * @defaultValue `'inline'`
+         * @defaultValue `'off'`
          */
         displayMode?: 'off' | 'inline' | 'popup';
         /**
@@ -290,14 +288,13 @@ declare type AddressMoleculePublicCustomization = {
 
 declare type AddressSuggestionsService = {
     list: DataResolver<
-        { params: AutocompleteAddressQuery['QueryParams']; token: string },
+        { params: AutocompleteAddressQuery['QueryParams'] } & SDKManagedTokenArg,
     AutocompleteAddressQuery['Response']
     >;
     resolve: DataResolver<
         {
         params: GetAddressDetailsQuery['PathParams'] & GetAddressDetailsQuery['QueryParams'];
-        token: string;
-    },
+    } & SDKManagedTokenArg,
     GetAddressDetailsQuery['Response']
     >;
 };
@@ -308,7 +305,7 @@ declare type AddressTypeEnum = 'unknown' | 'residential' | 'commercial';
 
 declare type AddressValidationService = {
     validateAddress: DataResolver<
-        { payload: ValidateAddressMutation['Request']; token: string },
+        { payload: ValidateAddressMutation['Request'] } & SDKManagedTokenArg,
     ValidateAddressMutation['Response']
     >;
 };
@@ -598,12 +595,6 @@ declare type AutocompleteFocusEnum =
  */
 declare type BaseKey<K> = K extends `${infer B}_${Intl.LDMLPluralRule}` ? B : K;
 
-/**
- * TODO: this will come from the site config most probably and
- * the shape of the model will be different - for now it's kept as simple
- * as possible for MVP purposes
- */
-
 declare type BaseMoleculeDef<K extends MoleculeType> = {
     type: K;
     customization?: DeepPartial<MoleculeCustomizationConfig<K>>;
@@ -638,8 +629,7 @@ declare type ContactsService = {
             addressBookId: string;
             countryCode?: string;
         };
-        token: string;
-    },
+    } & SDKManagedTokenArg,
         {
         entries: { id: string; label: string; secondaryLabel: string }[];
     }
@@ -647,8 +637,7 @@ declare type ContactsService = {
     getContactBookEntry: DataResolver<
         {
         params: { id: string; addressBookId: string };
-        token: string;
-    },
+    } & SDKManagedTokenArg,
     AddressContactEntry
     >;
     upsertContactBookEntry: DataResolver<
@@ -657,12 +646,11 @@ declare type ContactsService = {
         params: {
             addressBookId: string;
         };
-        token: string;
-    },
+    } & SDKManagedTokenArg,
     AddressContactEntry
     >;
     deleteContactBookEntry: DataResolver<
-        { params: { addressBookId: string; id: string }; token: string },
+        { params: { addressBookId: string; id: string } } & SDKManagedTokenArg,
     object
     >;
 };
@@ -696,19 +684,21 @@ declare type CountrySelectorParams = {
 };
 
 /**
- * Creates a molecule configuration for the address particle.
+ * Creates a molecule configuration for the address molecule.
  *
  * Renders an address form that collects and validates the shopper's shipping address.
  *
- * @param params - Configuration for the address particle. See `AddressParticleParams`.
+ * @param params - Configuration for the address molecule. See `AddressMoleculeParams`.
  * @returns A molecule descriptor to pass to the `molecules` array in {@link IngridInitParams}.
  *
  * @example
  * ```ts
- * const ingrid = await initIngrid({
+ * const instance = await ingrid.init({
  *   token: 'your-auth-token',
  *   siteId: 'your-site-id',
  *   locale: 'en-US',
+ *   countryCode: 'US',
+ *   currency: 'USD',
  *   molecules: [
  *     createAddressMolecule({
  *       mode: 'addressForm'
@@ -723,142 +713,7 @@ export declare const createAddressMolecule: ({ mode, customization }: MoleculePa
     type: "address";
     customization: AddressMoleculePublicCustomization | undefined;
     params: {
-        mode: "addressForm";
-    };
-};
-
-/**
- * Creates a molecule configuration for the country selector particle.
- *
- * Renders a country picker that allows the shopper to select their delivery country.
- * Changing the country refreshes available delivery options.
- *
- * @param params - Configuration for the country selector particle. See `CountrySelectorParams`.
- * @returns A molecule descriptor to pass to the `molecules` array in {@link IngridInitParams}.
- *
- * @example
- * ```ts
- * const ingrid = await initIngrid({
- *   token: 'your-auth-token',
- *   siteId: 'your-site-id',
- *   locale: 'en-US',
- *   molecules: [
- *     createCountrySelectorMolecule({ mode: 'select', name: 'country-picker' }),
- *   ],
- * });
- * ```
- *
- * @public
- */
-export declare const createCountrySelectorMolecule: ({ mode, name, }: MoleculeParamsMap["countrySelector"]) => {
-    type: "countrySelector";
-    params: {
-        mode: "select";
-        name: string;
-    };
-};
-
-/**
- * Creates a molecule configuration for the delivery particle.
- *
- * Renders a delivery options selector where the shopper can browse and choose a shipping method.
- * Use `mode: 'active'` for a checkout flow where the shopper makes a selection, and
- * `mode: 'passive'` for a read-only summary display.
- *
- * @param params - Configuration for the delivery particle. See `DeliveryParticleParams`.
- * @returns A molecule descriptor to pass to the `molecules` array in {@link IngridInitParams}.
- *
- * @example
- * ```ts
- * const ingrid = await initIngrid({
- *   token: 'your-auth-token',
- *   siteId: 'your-site-id',
- *   locale: 'en-US',
- *   molecules: [
- *     createDeliveryMolecule({ mode: 'active', name: 'main-delivery' }),
- *   ],
- * });
- * ```
- *
- * @public
- */
-export declare const createDeliveryMolecule: ({ mode, name, customization, }: MoleculeParamsMap["delivery"]) => {
-    type: "delivery";
-    customization: {
-        choice?: {
-            carrierInstructions?: "off" | "inline" | "popup";
-            gaplessAddonsList?: boolean;
-            gaplessCarrierList?: boolean;
-            gaplessDeliveryList?: boolean;
-            labels?: "off" | "chips" | "text";
-            showAddons?: boolean;
-            showCustomInfoText?: boolean;
-            showCustomText?: boolean;
-            showDiscountedPrice?: boolean;
-            showFreeShippingIndicator?: boolean;
-            showPrice?: boolean;
-            showRadioIndicator?: boolean;
-            showReturnPromise?: boolean;
-            showShippingLogo?: boolean;
-        };
-        location?: {
-            gaplessList?: boolean;
-            mapDefaultVisible?: boolean;
-            mapDefaultZoom?: number;
-            mapFitboundsMaxZoom?: number;
-            mapPosition?: "start" | "end";
-            mapToggleEnabled?: boolean;
-        };
-        productList?: {
-            defaultView?: "off" | "list" | "summary";
-            showImage?: boolean;
-            showMetadata?: boolean;
-            showPrice?: boolean;
-            showQuantity?: boolean;
-            summaryText?: "none" | "products" | "firstProductAndMore";
-        };
-        summary?: {
-            previewAddons?: boolean;
-            showFreeShippingIndicator?: boolean;
-        };
-    } | undefined;
-    params: {
-        mode: "active" | "passive";
-        name: string;
-    };
-};
-
-/**
- * Creates a molecule configuration for the free shipping indicator particle.
- *
- * Renders a progress bar or message showing how close the shopper is to qualifying
- * for free shipping. Pair it with a delivery molecule that has `showFreeShippingIndicator`
- * enabled, or use it standalone via the `deliveryId` param.
- *
- * @param params - Configuration for the free shipping indicator particle. See `FreeShippingIndicatorParams`.
- * @returns A molecule descriptor to pass to the `molecules` array in {@link IngridInitParams}.
- *
- * @example
- * ```ts
- * const ingrid = await initIngrid({
- *   token: 'your-auth-token',
- *   siteId: 'your-site-id',
- *   locale: 'en-US',
- *   molecules: [
- *     createFreeShippingIndicatorMolecule({ name: 'free-shipping' }),
- *   ],
- * });
- * ```
- *
- * @public
- */
-export declare const createFreeShippingIndicatorMolecule: ({ name, customization, }: MoleculeParamsMap["freeShippingIndicator"]) => {
-    type: "freeShippingIndicator";
-    customization: {
-        showExhaustedLevelsMessage?: boolean;
-    } | undefined;
-    params: {
-        name: string;
+        mode: "addressForm" | "searchDriven";
     };
 };
 
@@ -935,8 +790,6 @@ declare type DeliveryAddon = {
     readonly description?: string;
 };
 
-declare const deliveryArgsSchema = z.object({ sessionId: z.string(), token: z.string() });
-
 /**
  * @description DeliveryType defines the method or mode of delivery.\n\n - DELIVERY_TYPE_UNSPECIFIED: Delivery type is unspecified or unknown.\n - DELIVERY: Delivery to a customer\'s home or address.\n - PICKUP: Delivery to a service point or locker.\n - MAILBOX: Delivery to a customer\'s mailbox.\n - INSTORE: Delivery to a merchant\'s store for in-store pickup.
  * @default DELIVERY_TYPE_UNSPECIFIED
@@ -1371,18 +1224,6 @@ declare type DeliveryMoleculeParams = {
 
 declare const deliveryMoleculeParamsValidator = z.object({
     customization: deliveryCustomizationValidator,
-
-    // TODO: the passive `mode` has hardcoded logic, but IMHO the behaviour should come from granular config (components + policies), not from `mode` branches.
-    // Just an simple example:
-    //  components: {
-    //    continue_button: { display: 'hidden' },
-    //    pickup_location: { display: 'popup', interaction: 'preview' // or edit }
-    //  }
-    //
-    //  actionPolicy: {
-    //    select_item: 'deny'
-    //  }
-    //
     mode: z.enum(['active', 'passive']),
     name: z.string(),
 }) satisfies z.ZodType<DeliveryMoleculeParams>;
@@ -1756,9 +1597,24 @@ declare type ETDTimeUnitEnum =
 
 declare type Event_2<T> = { payload: T };
 
-declare type EventsMap = {
+/**
+ * Map of all events emitted by the Ingrid compound.
+ *
+ * | Event             | When it fires                                  |
+ * | ----------------- | ---------------------------------------------- |
+ * | `ready`           | Compound is mounted and interactive            |
+ * | `addressSubmit`   | Shopper confirms the address form              |
+ * | `countryChange`   | Shopper selects a different country            |
+ * | `selectionChange` | Shopper selects a delivery option              |
+ * | `error`           | An error occurs during mount or at runtime     |
+ *
+ * @remarks Event names and payload shapes may evolve before the stable release.
+ *
+ * @public
+ */
+export declare type EventsMap = {
     countryChange: (event: Event_2<{ country_code: string }>) => void;
-    addressSubmit: (event: Event_2<AddressMoleculeInputState>) => void;
+    addressSubmit: (event: Event_2<Partial<AddressContactEntry>>) => void;
     selectionChange: (event: Event_2<{ deliveryId: string; categoryId: string }>) => void;
     ready: () => void;
     error: (error: unknown) => void;
@@ -1912,9 +1768,11 @@ declare type GetAddressFormQueryParams = {
     postalCode?: string;
 };
 
-declare type GetDeliverySessionArgs = z.infer<typeof deliveryArgsSchema>;
+declare type GetDeliverySessionArgs = { sessionId: string } & SDKManagedTokenArg;
 
-declare type GetTrackingDataArgs = z.infer<typeof trackingArgsSchema>;
+declare type GetTrackingDataArgs =
+| ({ locale: Locale } & SDKManagedTokenArg)
+| { email: string; tos_id: string; locale: Locale };
 
 declare type GetTrackingDataResponse = {
     /**
@@ -1983,13 +1841,20 @@ declare const ingrid: {
 export default ingrid;
 
 /**
- * The compound instance returned by {@link ingrid.init}, used to control the lifecycle
+ * The compound instance returned by `ingrid.init`, used to control the lifecycle
  * of the rendered Ingrid experience.
  *
  * @public
  */
 export declare interface IngridCompound {
-    /** Mounts the Ingrid experience into the DOM element matching `containerSelector`. */
+    /**
+     * Mounts the Ingrid experience into the DOM element matching `containerSelector`.
+     *
+     * @param containerSelector - CSS selector for the container element to mount into.
+     * @param options - Optional mount options.
+     * @param options.signal - An `AbortSignal` to cancel the mount. If the signal fires before
+     *   the compound finishes loading, the mount is silently abandoned and no error is thrown.
+     */
     mount(containerSelector: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -1998,9 +1863,11 @@ export declare interface IngridCompound {
     /** Updates runtime configuration of the mounted experience. */
     update(newConfig: Partial<UpdatableConfig>): void;
     /**
-     * Subscribes to an SDK event.
+     * Subscribes to an SDK event. See {@link EventsMap} for available events and their payloads.
      *
-     * @returns An unsubscribe function.
+     * @param event - The event name to subscribe to.
+     * @param callback - Called each time the event fires.
+     * @returns An unsubscribe function - call it to stop listening.
      */
     on<K extends keyof EventsMap>(event: K, callback: EventsMap[K]): () => boolean;
 }
@@ -2023,13 +1890,14 @@ export declare interface IngridCompound {
  * @public
  */
 export declare interface IngridInitParams {
-    /** Authentication token for the Ingrid API. */
-    token: string;
-    /** Optional function to refresh the authentication token when it expires. */
-    refreshToken?: () => Promise<{
-        accessToken: string;
-        expiresAt: number;
-    }>;
+    /** Initial token for Ingrid built-in providers. */
+    token?: string;
+    /**
+     * Optional callback for short-lived Ingrid API tokens, which are preferred.
+     * Call your backend to issue and return a fresh Ingrid API token along with its expiration timestamp
+     * expiration timestamp: `{ accessToken, expiresAt }`.
+     */
+    refreshToken?: () => Promise<TokenRefreshResult>;
     /** Ingrid site identifier. */
     siteId: string;
     /** The locale to use for the experience. */
@@ -2062,7 +1930,10 @@ export declare interface IngridInitParams {
 export declare interface IngridInstance {
     /** The compound instance used to mount, unmount, and update the Ingrid experience. */
     compound: IngridCompound;
-    /** Updates the active locale for the experience. */
+    /**
+     * Updates the active locale for the experience.
+     * If the locale is not supported, falls back to `'en-US'`.
+     */
     setLocale(locale: Locale): void;
     /** Updates the active purchase country code. */
     setPurchaseCountry(countryCode: string): void;
@@ -2293,7 +2164,7 @@ declare type LocationByValue = {
     display_name?: string;
 };
 
-declare type MethodOverrides<T> = {
+export declare type MethodOverrides<T> = {
     [K in keyof T]?: T[K] extends (...args: any[]) => any ? T[K] | WithDefaultProvider<T[K]> : never;
 };
 
@@ -2968,6 +2839,11 @@ declare interface SDKInternal {
     readonly [_internalBrand]: never;
 }
 
+declare type SDKManagedTokenArg = {
+    /** @deprecated This is an internal SDK-managed token for builtin providers. Do not rely on this directly. Custom providers should implement their own authentication mechanism if needed.*/
+    token?: string;
+};
+
 /**
  * @description Response containing a list of address predictions from the autocomplete endpoint.
  */
@@ -3029,7 +2905,6 @@ declare type Services = {
      * ```ts
      * const entries = await services.address.listContactBookEntries({
      *   params: { addressBookId: 'book_123' },
-     *   token: authToken,
      * });
      * ```
      */
@@ -3053,6 +2928,14 @@ declare type Services = {
     };
 };
 
+/**
+ * Per-domain overrides for the SDK's internal data-fetching services.
+ * Each key maps to a domain (e.g. `address`), and each value is a partial map of
+ * method overrides for that domain. Supply a plain function to replace the default
+ * implementation entirely, or use {@link withDefaultProvider} to wrap it.
+ *
+ * @public
+ */
 export declare type ServicesOverrides = {
     [Domain in keyof Services]?: MethodOverrides<Services[Domain]>;
 };
@@ -3137,10 +3020,17 @@ declare type TextDirectionEnum = 'ltr' | 'rtl';
 
 declare type ThemeCssVariables = `--${RecursiveObjectValues<typeof variableNames>}`;
 
-declare const trackingArgsSchema = z.union([
-z.object({ token: z.string(), locale: z.enum(localeList) }),
-z.object({ email: z.string(), tos_id: z.string(), locale: z.enum(localeList) }),
-]);
+/** Value returned by the SDK `refreshToken` callback. */
+declare type TokenRefreshResult = {
+    /** Fresh short-lived Ingrid API token. */
+    accessToken: string;
+    /**
+     * Expiry time for `accessToken` as a Unix epoch timestamp in milliseconds.
+     * The SDK uses this to refresh auth before expiry. If the value is stale,
+     * invalid, or affected by clock skew, the SDK refreshes reactively on 401 response.
+     */
+    expiresAt: number;
+};
 
 declare type TrackingData = GetTrackingDataResponse;
 
@@ -3169,8 +3059,13 @@ declare type TranslationsService = {
     ) => void;
 };
 
-/** @public */
-declare interface UpdatableConfig {
+/**
+ * Runtime configuration that can be updated on a mounted compound via {@link IngridCompound.update}.
+ *
+ * @public
+ */
+export declare interface UpdatableConfig {
+    /** Design token overrides to apply to the rendered experience without remounting. */
     styles?: StyleTokens;
 }
 
@@ -3637,7 +3532,7 @@ declare type WithDefaultProvider<T extends (...args: any[]) => any> = {
  *
  * @param factory - Receives the SDK's default implementation as `defaultFn`.
  *   Return a new function that calls `defaultFn` wherever you want the original behaviour.
- * @returns A {@link WithDefaultProvider} wrapper understood by the SDK's service resolver.
+ * @returns A `WithDefaultProvider` wrapper understood by the SDK's service resolver.
  *
  * @example
  * ```ts