@ingridab/sdk 0.1.0-alpha.1 → 0.1.0

package/dist/index.d.ts

@@ -138,87 +138,6 @@ declare type Address_2 = {
     type?: AddressType;
 };
 
-/**
- * @description Represents an address suitable for delivery.
- */
-declare type AddressAddress = {
-    /**
-     * @description \nRefers to a ISO-3166 alpha 2 country code.
-     * @type string
-     */
-    country_code: string;
-    /**
-     * @description Refers to a first-level administrative subdivision code (ISO-3166-2) without the country_code prefix.\nExample: region for Washington, D.C. = `DC` (from `US-DC`).\nException: for some countries (e.g. Mexico, Hong Kong) we store the subdivision name instead.\nExample: region for Hong Kong = `Kowloon`.
-     * @type string | undefined
-     */
-    region_code?: string;
-    /**
-     * @description Refers to a second-level administrative subdivision below the region (ISO-3166-2), without the country_code prefix.\nExample: region for Washington State = `WA` (from `US-WA`), subregion for King County = `033` (from `US-WA-033`).\nException: for some countries (e.g. Mexico, Hong Kong) we store the subdivision name instead.\nExample: subregion within Hong Kong/Kowloon = `Tsim Sha Tsui`.
-     * @type string | undefined
-     */
-    subregion_code?: string;
-    /**
-     * @description Refers to a postal code or zipcode.
-     * @type string | undefined
-     */
-    postal_code?: string;
-    /**
-     * @description Refers to a city, postal_town or locality.
-     * @type string | undefined
-     */
-    city?: string;
-    /**
-     * @description List of strings, each a part of the address, e.g., street name, street number, building name, floor.
-     * @type array | undefined
-     */
-    address_lines?: string[];
-    /**
-     * @description Street name of the address.
-     * @type string | undefined
-     */
-    street?: string;
-    /**
-     * @description Street number of the address.
-     * @type string | undefined
-     */
-    street_number?: string;
-    /**
-     * @description Apartment number of the address.
-     * @type string | undefined
-     */
-    apartment_number?: string;
-    /**
-     * @description Building name of the address.
-     * @type string | undefined
-     */
-    building_name?: string;
-    /**
-     * @description Floor number of the address.
-     * @type string | undefined
-     */
-    floor_number?: string;
-    /**
-     * @description PO Box identifier of the address.
-     * @type string | undefined
-     */
-    po_box_id?: string;
-    /**
-     * @description Full name associated with the address, for example company name.
-     * @type string | undefined
-     */
-    name?: string;
-    /**
-     * @description Care of information associated with the address.
-     * @type string | undefined
-     */
-    care_of?: string;
-    /**
-     * @description Represents a latitude/longitude pair.\nUnless specified otherwise, this must conform to the WGS84 standard.\nValues must be within normalized ranges.
-     * @type object | undefined
-     */
-    coordinates?: AddressCoordinates;
-};
-
 /**
  * @description Types of modifications the validation API made to the original address.
  */
@@ -231,23 +150,42 @@ declare type AddressChangeEnum =
 | 'componentsAdded'
 | 'componentsRemoved';
 
-/**
- * @description Represents a latitude/longitude pair.\nUnless specified otherwise, this must conform to the WGS84 standard.\nValues must be within normalized ranges.
- */
-declare type AddressCoordinates = {
-    /**
-     * @description The latitude in degrees. Must be within the range -90.0 to +90.0, inclusive.
-     * @type number, double
-     */
-    lat: number;
-    /**
-     * @description The longitude in degrees. Must be within the range -180.0 to +180.0, inclusive.
-     * @type number, double
-     */
-    lng: number;
+declare type AddressContactEntry = {
+    /** The unique identifier of the contact entry. */
+    id?: string;
+
+    /** The name of the contact person. */
+    recipientName?: string;
+
+    /** The company name associated with the contact. */
+    companyName?: string;
+
+    /** The address of the contact. */
+    address?: Address_2;
+
+    /** The email address of the contact. */
+    email?: string;
+
+    /** The VAT number associated with the contact. */
+    vatNumber?: string;
+
+    /** The VAT type associated with the vat number, e.g. "SE_EU" or "GB_VAT" */
+    vatType?: string;
+
+    /** A phone number in E164 format, e.g. "+1234567890" */
+    phoneNumber?: string;
+
+    /** Additional form values associated with the contact */
+    additionalFormValues?: AddressContactEntryAdditionalFormValue[];
 };
 
-declare type AddressDebugParams = Pick<ParticleParamsMap['address'], 'customization'>;
+declare type AddressContactEntryAdditionalFormValue = {
+    /** The key under which the value is stored. Can be referenced in the form configuration */
+    formFieldKey: string;
+
+    /** The value of the form field. */
+    value: string;
+};
 
 /**
  * @description Response containing the full address resolved from a prediction ID.
@@ -259,161 +197,106 @@ declare type AddressDetailsResponse = {
     address: Address_2;
 };
 
-declare type AddressParticleInputState = DeepPartial<V1AlphaAddressContact>;
-
-declare type AddressParticleParams = {
-    mode: 'postalCode' | 'addressForm';
-    prefillAddress?: RecipientContact;
-    customization?: {
-        address?: { vatTypes?: string[] };
-        addressBook?: { displayMode?: 'off' | 'inline' | 'popup' };
-        suggestions?: { displayMode?: 'inline' | 'popup' };
-    };
-};
-
-declare const addressParticleParamsValidator = z.object({
-    mode: z.enum(['postalCode', 'addressForm']),
-    prefillAddress: recipientContactValidator.optional(),
-    customization: z
-    .object({
-        address: z
-        .object({
-            vatTypes: z.array(z.string()).optional(), // TODO: TBD - we'll probably need multiselect input to handle this in the Playground
-        })
-        .optional(),
-        addressBook: z
-        .object({
-            displayMode: z.enum(['off', 'inline', 'popup']).optional(),
-        })
-        .optional(),
-        suggestions: z
-        .object({
-            displayMode: z.enum(['inline', 'popup']).optional(),
-        })
-        .optional(),
-    })
-    .optional(),
-}) satisfies z.ZodType<AddressParticleParams>;
-
-declare type AddressPresetParams = Pick<ParticleParamsMap['address'], 'mode' | 'prefillAddress'>;
-
 /**
- * @description The contact to create.
+ * @description Response containing the complete form configuration for a localized address form.\nIncludes field definitions, validation rules, and visual layout instructions.
  */
-declare type AddressServiceCreateContactMutationRequest = V1AlphaAddressContact;
-
-declare type AddressServiceCreateContactPathParams = {
+declare type AddressFormResponse = {
     /**
-     * @description The resource id of the address book the contact should belong to.\nTypically this is the customer ID.
-     * @pattern [^/]+
-     * @type string
+     * @description Metadata about the form configuration including locale and text direction.
      */
-    address_book_id: string;
-};
-
-/**
- * @description A successful response.
- */
-declare type AddressServiceDeleteContact200 = object;
-
-declare type AddressServiceDeleteContactPathParams = {
+    meta: FormMeta;
     /**
-     * @description The resource id of the address book the contact belongs to.\nTypically this is the customer ID.
-     * @pattern [^/]+
-     * @type string
+     * @description Pre-filled values for the form fields.\nKeys correspond to the keys in the `fields` object.\nThis is often populated if a `postalCode` was sent in the request.
+     * @type object | undefined
      */
-    address_book_id: string;
+    values?: object;
     /**
-     * @description The contact ID to delete.
-     * @pattern [^/]+
-     * @type string
+     * @description Dictionary defining the behavior of each input field.\nKeys are unique field identifiers (e.g., `postalCode`, `locality`).
+     * @type object
      */
-    contact_id: string;
-};
-
-declare type AddressServiceListContactsPathParams = {
+    fields: object;
     /**
-     * @description The resource id of the set of contacts to retrieve.\nTypically this is the customer ID.
-     * @pattern [^/]+
-     * @type string
+     * @description Defines the visual grid of the form.\nClients should loop through this array to render the UI.\n- Outer array: Rows (stack vertically)\n- Inner array: Columns (stack horizontally / flex)
+     * @type array
      */
-    address_book_id: string;
+    layout: string[][];
 };
 
-declare type AddressServiceListContactsQueryParams = {
-    /**
-     * @description Country code defined as ISO 3166-1 alpha-2, country code of the addresses.
-     * @type string | undefined
-     */
-    country_code?: string;
+declare type AddressFormService = {
+    getAddressFormConfig: DataResolver<
+        { params: GetAddressFormQuery['QueryParams']; token: string },
+    GetAddressFormQuery['Response']
+    >;
 };
 
+/* Excluded from this release type: AddressMoleculeCustomization */
+
+declare type AddressMoleculeInputState = Partial<AddressContactEntry>;
+
 /**
- * @description The contact to update.
+ * Configuration params passed to the address molecule.
+ *
+ * @example
+ * ```ts
+ * const params: AddressMoleculeParams = {
+ *   mode: 'addressForm',
+ *   customization: {
+ *     addressBook: { displayMode: 'popup' },
+ *     suggestions: { displayMode: 'inline' },
+ *   },
+ * };
+ * ```
  */
-declare type AddressServiceUpdateContactMutationRequest = {
-    /**
-     * @description Represents an address suitable for delivery.
-     * @type object
-     */
-    address: AddressAddress;
-    /**
-     * @description The email address of the contact.
-     * @type string | undefined
-     */
-    email?: string;
-    /**
-     * @description A phone number, including region and optional extension.
-     * @type object | undefined
-     */
-    phone_number?: ContactPhoneNumber_2;
-    /**
-     * @description Full name associated with the contact.
-     * @type string | undefined
-     */
-    name?: string;
-    /**
-     * @description First name associated with the contact.
-     * @type string | undefined
-     */
-    first_name?: string;
-    /**
-     * @description Last name associated with the contact.
-     * @type string | undefined
-     */
-    last_name?: string;
-    /**
-     * @description National ID number associated with the contact.
-     * @type string | undefined
-     */
-    national_id_number?: string;
-    /**
-     * @description Company name associated with the contact.
-     * @type string | undefined
-     */
-    company_name?: string;
-    /**
-     * @description VAT number associated with the contact.
-     * @type string | undefined
-     */
-    vat?: string;
-    /**
-     * @description Customs number associated with the contact.
-     * @type string | undefined
-     */
-    customs_number?: string;
+declare type AddressMoleculeParams = {
+    /** The rendering mode for the address molecule. Currently `'addressForm'` is supported. */
+    mode: 'addressForm';
+    customization?: AddressMoleculePublicCustomization;
+};
+
+/* Excluded from this release type: addressMoleculeParamsValidator */
+
+/* Excluded from this release type: AddressMoleculePrivateCustomization */
+
+/**
+ * Customization flags - exposed to SDK consumers via {@link AddressMoleculeParams}.
+ */
+declare type AddressMoleculePublicCustomization = {
+    /** Customization options for the address book picker. */
+    addressBook?: {
+        /**
+         * Controls how the address book is presented.
+         *
+         * @defaultValue `'inline'`
+         */
+        displayMode?: 'off' | 'inline' | 'popup';
+        /**
+         * Controls how users select an address entry:
+         * `'radio'` renders a radio button on each entry, `'disabled'` hides it.
+         *
+         * @defaultValue `'radio'`
+         */
+        selectionControl?: 'radio' | 'disabled';
+    };
+    /** Customization options for address autocomplete suggestions. */
+    suggestions?: {
+        /**
+         * Controls how address suggestions are presented.
+         *
+         * @defaultValue `'popup'`
+         */
+        displayMode?: 'inline' | 'popup';
+    };
 };
 
 declare type AddressSuggestionsService = {
     list: DataResolver<
-        { params: AutocompleteAddressQuery['QueryParams']; token: string; siteId: string },
+        { params: AutocompleteAddressQuery['QueryParams']; token: string },
     AutocompleteAddressQuery['Response']
     >;
     resolve: DataResolver<
         {
-        params: GetAddressDetailsQuery['PathParams'];
+        params: GetAddressDetailsQuery['PathParams'] & GetAddressDetailsQuery['QueryParams'];
         token: string;
-        siteId: string;
     },
     GetAddressDetailsQuery['Response']
     >;
@@ -425,7 +308,7 @@ declare type AddressTypeEnum = 'unknown' | 'residential' | 'commercial';
 
 declare type AddressValidationService = {
     validateAddress: DataResolver<
-        { payload: ValidateAddressMutation['Request']; token: string; siteId: string },
+        { payload: ValidateAddressMutation['Request']; token: string },
     ValidateAddressMutation['Response']
     >;
 };
@@ -676,6 +559,11 @@ declare type AutocompleteAddressQueryParams = {
      * @type string
      */
     countryCode: CountryCode;
+    /**
+     * @description Site identifier, referring to which site the autocompletion is performed for.
+     * @type string
+     */
+    siteId: string;
     /**
      * @description The text typed by the user. Ignored if `containerId` is provided.
      * @type string | undefined
@@ -716,10 +604,10 @@ declare type BaseKey<K> = K extends `${infer B}_${Intl.LDMLPluralRule}` ? B : K;
  * as possible for MVP purposes
  */
 
-declare type BaseParticleDef<K extends ParticleType> = {
+declare type BaseMoleculeDef<K extends MoleculeType> = {
     type: K;
-    customization?: ParticleCustomizationConfig<K>;
-    params: ParticleParamsMap[K];
+    customization?: DeepPartial<MoleculeCustomizationConfig<K>>;
+    params: MoleculeParamsMap[K];
 };
 
 /**
@@ -743,31 +631,13 @@ declare type ContactPhoneNumber = {
     extension?: string;
 };
 
-/**
- * @description A phone number, including region and optional extension.
- */
-declare type ContactPhoneNumber_2 = {
-    /**
-     * @description \nThe country code where the delivery will occur (ISO 3166-1 alpha-2).
-     * @type string
-     */
-    country_code: string;
-    /**
-     * @description The main phone number, formatted as per the region\'s conventions.
-     * @type string
-     */
-    number: string;
-    /**
-     * @description An optional phone number extension.
-     * @type string | undefined
-     */
-    extension?: string;
-};
-
 declare type ContactsService = {
     listContactBookEntries: DataResolver<
         {
-        params: AddressServiceListContactsPathParams & AddressServiceListContactsQueryParams;
+        params: {
+            addressBookId: string;
+            countryCode?: string;
+        };
         token: string;
     },
         {
@@ -776,24 +646,24 @@ declare type ContactsService = {
     >;
     getContactBookEntry: DataResolver<
         {
-        params: { entry_id: string; address_book_id: string };
+        params: { id: string; addressBookId: string };
         token: string;
     },
-        { address: V1AlphaAddressContact } | null
+    AddressContactEntry
     >;
     upsertContactBookEntry: DataResolver<
         {
-        payload:
-        | AddressServiceCreateContactMutationRequest
-        | AddressServiceUpdateContactMutationRequest;
-        params: AddressServiceCreateContactPathParams;
+        payload: AddressContactEntry;
+        params: {
+            addressBookId: string;
+        };
         token: string;
     },
-    V1AlphaAddressContact
+    AddressContactEntry
     >;
     deleteContactBookEntry: DataResolver<
-        { params: AddressServiceDeleteContactPathParams; token: string },
-    AddressServiceDeleteContact200
+        { params: { addressBookId: string; id: string }; token: string },
+    object
     >;
 };
 
@@ -813,9 +683,11 @@ declare type Coordinates = {
  */
 declare type CountryCode = string;
 
-declare interface CountrySelectorDebugParams {
-    name: string;
-}
+declare const countrySelectorMoleculeParamsValidator = z.object({
+    mode: z.enum(['select']),
+    name: z.string(),
+    customization: z.object({}).optional(),
+}) satisfies z.ZodType<CountrySelectorParams>;
 
 declare type CountrySelectorParams = {
     mode: 'select';
@@ -823,36 +695,62 @@ declare type CountrySelectorParams = {
     customization?: Record<never, never>;
 };
 
-declare const countrySelectorParticleParamsValidator = z.object({
-    mode: z.enum(['select']),
-    name: z.string(),
-    customization: z.object({}).optional(),
-}) satisfies z.ZodType<CountrySelectorParams>;
-
-declare interface CountrySelectorPresetParams {
-    mode: ParticleParamsMap['countrySelector']['mode'];
-}
-
-export declare const createAddressMolecule: ({ mode, prefillAddress }: AddressPresetParams) => ({ customization }: AddressDebugParams) => {
+/**
+ * Creates a molecule configuration for the address particle.
+ *
+ * Renders an address form that collects and validates the shopper's shipping address.
+ *
+ * @param params - Configuration for the address particle. See `AddressParticleParams`.
+ * @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: [
+ *     createAddressMolecule({
+ *       mode: 'addressForm'
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const createAddressMolecule: ({ mode, customization }: MoleculeParamsMap["address"]) => {
     type: "address";
-    customization: {
-        address?: {
-            vatTypes?: string[];
-        };
-        addressBook?: {
-            displayMode?: "off" | "inline" | "popup";
-        };
-        suggestions?: {
-            displayMode?: "inline" | "popup";
-        };
-    } | undefined;
+    customization: AddressMoleculePublicCustomization | undefined;
     params: {
-        mode: "postalCode" | "addressForm";
-        prefillAddress: RecipientContact | undefined;
+        mode: "addressForm";
     };
 };
 
-export declare const createCountrySelectorMolecule: ({ mode }: CountrySelectorPresetParams) => ({ name }: CountrySelectorDebugParams) => {
+/**
+ * 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";
@@ -860,7 +758,31 @@ export declare const createCountrySelectorMolecule: ({ mode }: CountrySelectorPr
     };
 };
 
-export declare const createDeliveryMolecule: ({ mode }: DeliveryPresetParams) => ({ name, customization }: DeliveryDebugParams) => {
+/**
+ * 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?: {
@@ -906,7 +828,31 @@ export declare const createDeliveryMolecule: ({ mode }: DeliveryPresetParams) =>
     };
 };
 
-export declare const createFreeShippingIndicatorMolecule: () => ({ name, customization }: FreeShippingIndicatorDebugParams) => {
+/**
+ * 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;
@@ -1060,11 +1006,6 @@ declare type DeliveryCoordinates = {
     lng: number;
 };
 
-declare interface DeliveryDebugParams {
-    name: string;
-    customization?: ParticleCustomizationConfig<'delivery'>;
-}
-
 /**
  * @description The DeliveryCategory represents a grouping of delivery options that share the same type and other characteristics.
  */
@@ -1385,6 +1326,67 @@ declare type DeliveryLineItem = {
     attributes?: string[];
 };
 
+declare type DeliveryMoleculeParams = {
+    mode: 'active' | 'passive';
+    name: string;
+    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;
+        };
+    };
+};
+
+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>;
+
 /**
  * @description Constraints on the node\'s handoff.
  */
@@ -1466,67 +1468,6 @@ declare type DeliveryOptionOrigin = {
     external_id?: string;
 };
 
-declare type DeliveryParticleParams = {
-    mode: 'active' | 'passive';
-    name: string;
-    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;
-        };
-    };
-};
-
-declare const deliveryParticleParamsValidator = 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<DeliveryParticleParams>;
-
 /**
  * @description The PickupLocation represents a physical location from which a delivery can be retrieved.
  */
@@ -1578,10 +1519,6 @@ declare type DeliveryPickupLocation = {
     distances?: PickupLocationDistances;
 };
 
-declare interface DeliveryPresetParams {
-    mode: ParticleParamsMap['delivery']['mode'];
-}
-
 /**
  * @description ReturnPromise contains promise for returns and exchanges for a user and a cart.
  */
@@ -1821,7 +1758,7 @@ declare type Event_2<T> = { payload: T };
 
 declare type EventsMap = {
     countryChange: (event: Event_2<{ country_code: string }>) => void;
-    addressSubmit: (event: Event_2<AddressParticleInputState>) => void;
+    addressSubmit: (event: Event_2<AddressMoleculeInputState>) => void;
     selectionChange: (event: Event_2<{ deliveryId: string; categoryId: string }>) => void;
     ready: () => void;
     error: (error: unknown) => void;
@@ -1839,20 +1776,26 @@ declare type ExceptionStatus = {
     status?: string;
 };
 
-declare interface FreeShippingIndicatorDebugParams {
-    name: string;
-    customization?: ParticleCustomizationConfig<'freeShippingIndicator'>;
-}
-
-declare type FreeShippingIndicatorParams = {
-    name: string;
-    deliveryId?: string;
-    customization?: {
-        showExhaustedLevelsMessage?: boolean;
-    };
+/**
+ * @description Metadata about the form configuration.
+ */
+declare type FormMeta = {
+    /**
+     * @description ISO 3166-1 alpha-2 country code for this form configuration.
+     */
+    countryCode: CountryCode;
+    /**
+     * @description Text direction. `rtl` (Right-to-Left) is critical for\nlanguages like Arabic or Hebrew.
+     */
+    direction: TextDirection;
+    /**
+     * @description IETF language tag for the localized labels.
+     * @type string
+     */
+    language: string;
 };
 
-declare const freeShippingIndicatorParticleParamsValidator = z.object({
+declare const freeShippingIndicatorMoleculeParamsValidator = z.object({
     name: z.string(),
     deliveryId: z.string().optional(),
     customization: z
@@ -1862,6 +1805,14 @@ declare const freeShippingIndicatorParticleParamsValidator = z.object({
     .optional(),
 }) satisfies z.ZodType<FreeShippingIndicatorParams>;
 
+declare type FreeShippingIndicatorParams = {
+    name: string;
+    deliveryId?: string;
+    customization?: {
+        showExhaustedLevelsMessage?: boolean;
+    };
+};
+
 /**
  * @description Readiness specifies a time range when the goods will be ready for shipment.
  */
@@ -1909,9 +1860,58 @@ declare type GetAddressDetailsPathParams = {
 declare type GetAddressDetailsQuery = {
     Response: GetAddressDetails200;
     PathParams: GetAddressDetailsPathParams;
+    QueryParams: GetAddressDetailsQueryParams;
     Errors: GetAddressDetails400 | GetAddressDetails404 | GetAddressDetails500;
 };
 
+declare type GetAddressDetailsQueryParams = {
+    /**
+     * @description Site identifier, referring to which site the address is resolved for.
+     * @type string
+     */
+    siteId: string;
+};
+
+/**
+ * @description The request has succeeded.
+ */
+declare type GetAddressForm200 = AddressFormResponse;
+
+/**
+ * @description The server could not understand the request due to invalid syntax.
+ */
+declare type GetAddressForm400 = AtlasErrorsBadRequestError;
+
+/**
+ * @description Server error
+ */
+declare type GetAddressForm500 = AtlasErrorsServerError;
+
+declare type GetAddressFormQuery = {
+    Response: GetAddressForm200;
+    QueryParams: GetAddressFormQueryParams;
+    Errors: GetAddressForm400 | GetAddressForm500;
+};
+
+declare type GetAddressFormQueryParams = {
+    /**
+     * @description ISO 3166-1 alpha-2 country code (e.g., SE, US, GB).
+     * @pattern ^[A-Z]{2}$
+     * @type string
+     */
+    countryCode: CountryCode;
+    /**
+     * @description Site identifier, referring to which site the form configurations are related to.
+     * @type string
+     */
+    siteId: string;
+    /**
+     * @description Optional postal code. If provided, the response `values` object\nmay contain pre-filled city/state data.
+     * @type string | undefined
+     */
+    postalCode?: string;
+};
+
 declare type GetDeliverySessionArgs = z.infer<typeof deliveryArgsSchema>;
 
 declare type GetTrackingDataArgs = z.infer<typeof trackingArgsSchema>;
@@ -1947,19 +1947,131 @@ declare type GetTrackingDataResponseOptions = {
     ica_bankid_flow?: boolean;
 };
 
-declare function initIngrid(params: Params): Promise<{
-    compound: {
-        mount: (containerSelector: string, options?: {
-            signal?: AbortSignal;
-        }) => Promise<void>;
-        unmount: (callback?: (() => void) | undefined) => void;
-        update: (newConfig: Partial<UpdatableConfig>) => void;
-        on: <K extends keyof EventsMap>(event: K, callback: EventsMap[K]) => () => boolean;
+/**
+ * The Ingrid SDK namespace.
+ *
+ * @example
+ * ```ts
+ * 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 instance.compound.mount('#ingrid-container');
+ * ```
+ *
+ * @public
+ */
+declare const ingrid: {
+    /**
+     * Initializes the Ingrid Experience Kit.
+     *
+     * Fetches the remote release index and site configuration, bootstraps SDK state,
+     * and returns an {@link IngridInstance} ready to mount into the DOM.
+     *
+     * @param params - See {@link IngridInitParams}.
+     * @returns A promise resolving to an {@link IngridInstance}.
+     *
+     * @public
+     */
+    init: typeof init;
+};
+export default ingrid;
+
+/**
+ * The compound instance returned by {@link 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`. */
+    mount(containerSelector: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Unmounts the rendered experience and cleans up all resources. */
+    unmount(callback?: () => void): void;
+    /** Updates runtime configuration of the mounted experience. */
+    update(newConfig: Partial<UpdatableConfig>): void;
+    /**
+     * Subscribes to an SDK event.
+     *
+     * @returns An unsubscribe function.
+     */
+    on<K extends keyof EventsMap>(event: K, callback: EventsMap[K]): () => boolean;
+}
+
+/**
+ * Configuration passed to {@link ingrid.init}.
+ *
+ * @example
+ * ```ts
+ * const instance = await ingrid.init({
+ *   token: 'your-auth-token',
+ *   siteId: 'your-site-id',
+ *   countryCode: 'US',
+ *   currency: 'USD',
+ *   locale: 'en-US',
+ *   molecules: [createAddressMolecule({ mode: 'addressForm' })],
+ * });
+ * ```
+ *
+ * @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;
+    }>;
+    /** Ingrid site identifier. */
+    siteId: string;
+    /** The locale to use for the experience. */
+    locale: Locale;
+    /** ISO 3166-1 alpha-2 country code for the market (e.g. `'SE'`, `'DE'`). */
+    countryCode: string;
+    /** ISO 4217 currency code for the market (e.g. `'SEK'`, `'EUR'`). */
+    currency: string;
+    /** Configuration for the molecules to render. */
+    molecules: MoleculesConfig;
+    /** Optional design token overrides for the experience's visual appearance. */
+    styles?: StyleTokens;
+    /** Optional overrides for the internal data-fetching services. */
+    dataProviders?: {
+        services?: ServicesOverrides;
     };
-    setLocale: (locale: Locale) => void;
-    __internal: SDKInternal;
-}>;
-export default initIngrid;
+    /**
+     * Deployment environment.
+     *
+     * @defaultValue `'production'`
+     */
+    env?: 'production' | 'stage';
+}
+
+/**
+ * The object returned by {@link ingrid.init}, providing control over the Ingrid experience lifecycle.
+ *
+ * @public
+ */
+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. */
+    setLocale(locale: Locale): void;
+    /** Updates the active purchase country code. */
+    setPurchaseCountry(countryCode: string): void;
+    /** Updates the active currency. */
+    setCurrency(currency: string): void;
+    /* Excluded from this release type: __internal */
+}
+
+declare function init(params: IngridInitParams): Promise<IngridInstance>;
 
 declare const _internalBrand: unique symbol;
 
@@ -2182,12 +2294,42 @@ declare type LocationByValue = {
 };
 
 declare type MethodOverrides<T> = {
-    [K in keyof T]?: T[K] extends (...args: any[]) => any ? T[K] | WithDefault<T[K]> : never;
+    [K in keyof T]?: T[K] extends (...args: any[]) => any ? T[K] | WithDefaultProvider<T[K]> : never;
+};
+
+declare type MoleculeCustomizationConfig<T extends MoleculeType> = MoleculeCustomizationConfigMap[T];
+
+declare type MoleculeCustomizationConfigMap = {
+    address: AddressMoleculeCustomization;
+    countrySelector: CountrySelectorParams['customization'];
+    delivery: DeliveryMoleculeParams['customization'];
+    freeShippingIndicator: FreeShippingIndicatorParams['customization'];
+    tracking: TrackingNumberParams['customization'];
+};
+
+declare type MoleculeMapType = {
+    address: { readonly validator: typeof addressMoleculeParamsValidator };
+    countrySelector: { readonly validator: typeof countrySelectorMoleculeParamsValidator };
+    delivery: { readonly validator: typeof deliveryMoleculeParamsValidator };
+    freeShippingIndicator: {
+        readonly validator: typeof freeShippingIndicatorMoleculeParamsValidator;
+    };
+    tracking: { readonly validator: typeof trackingNumberParamsValidator };
+};
+
+declare type MoleculeParamsMap = {
+    address: AddressMoleculeParams;
+    countrySelector: CountrySelectorParams;
+    delivery: DeliveryMoleculeParams;
+    freeShippingIndicator: FreeShippingIndicatorParams;
+    tracking: TrackingNumberParams;
 };
 
 declare type MoleculesConfig = {
-    [K in ParticleType]: BaseParticleDef<K>;
-}[ParticleType][];
+    [K in MoleculeType]: BaseMoleculeDef<K>;
+}[MoleculeType][];
+
+declare type MoleculeType = keyof MoleculeMapType;
 
 declare type OperationalHours = {
     /**
@@ -2351,18 +2493,6 @@ declare type OrderCartPricesTotals = {
     tax?: number;
 };
 
-export declare interface Params {
-    styles?: StyleTokens;
-    dataProviders?: {
-        services?: ServicesOverrides;
-    };
-    token: string;
-    siteId: string;
-    locale: Locale;
-    molecules: MoleculesConfig;
-    env?: 'production' | 'stage' | 'development';
-}
-
 declare type Parcel = {
     /**
      * @type array | undefined
@@ -2449,36 +2579,6 @@ declare type Parcel = {
     tracking_number?: string;
 };
 
-declare type ParticleCustomizationConfig<T extends ParticleType> = ParticleCustomizationConfigMap[T];
-
-declare type ParticleCustomizationConfigMap = {
-    address: AddressParticleParams['customization'];
-    countrySelector: CountrySelectorParams['customization'];
-    delivery: DeliveryParticleParams['customization'];
-    freeShippingIndicator: FreeShippingIndicatorParams['customization'];
-    tracking: TrackingNumberParams['customization'];
-};
-
-declare type ParticleMapType = {
-    address: { readonly validator: typeof addressParticleParamsValidator };
-    countrySelector: { readonly validator: typeof countrySelectorParticleParamsValidator };
-    delivery: { readonly validator: typeof deliveryParticleParamsValidator };
-    freeShippingIndicator: {
-        readonly validator: typeof freeShippingIndicatorParticleParamsValidator;
-    };
-    tracking: { readonly validator: typeof trackingNumberParamsValidator };
-};
-
-declare type ParticleParamsMap = {
-    address: AddressParticleParams;
-    countrySelector: CountrySelectorParams;
-    delivery: DeliveryParticleParams;
-    freeShippingIndicator: FreeShippingIndicatorParams;
-    tracking: TrackingNumberParams;
-};
-
-declare type ParticleType = keyof ParticleMapType;
-
 /**
  * @description Distances define the walking and driving distances to the pickup location.
  */
@@ -2680,6 +2780,7 @@ declare type RawTranslationKey =
 | 'address.delete'
 | 'address.delete_confirmation.banner.content'
 | 'address.delete_confirmation.banner.title'
+| 'address.delete_confirmation.warning_text'
 | 'address.edit'
 | 'address.edit.billing.aria.label'
 | 'address.edit.delivery.aria.label'
@@ -2726,6 +2827,7 @@ declare type RawTranslationKey =
 | 'address.form.field.vat.label'
 | 'address.form.field.vat_type.label'
 | 'address.form.field_optional'
+| 'address.form.search.enter_manually'
 | 'address.form.validation.address_line.invalid'
 | 'address.form.validation.phone_number.invalid'
 | 'address.form.validation.postal_code.invalid'
@@ -2734,8 +2836,12 @@ declare type RawTranslationKey =
 | 'address.form.validation.street_number.required'
 | 'address.form.vat_other_country'
 | 'address.list.add_new_address'
+| 'address.list.save'
 | 'address.list.save_and_continue'
 | 'address.list.title'
+| 'address.popup.address_form.title'
+| 'address.popup.deleting.title'
+| 'address.popup.list.title'
 | 'address.save'
 | 'address.save_anyway'
 | 'address.suggestion.address_incorrect.description'
@@ -2856,25 +2962,6 @@ declare type RawTranslationKey =
 | 'time.wednesday'
 | 'tracking.track_delivery_with';
 
-declare type RecipientContact = {
-    first_name?: string;
-    last_name?: string;
-    contact_id?: string;
-    address: {
-        country_code: string;
-        region_code?: string;
-        postal_code?: string;
-        city?: string;
-        address_lines?: string[];
-    };
-    email?: string;
-    phone_number?: {
-        country_code: string;
-        number: string;
-        extension?: string;
-    };
-};
-
 declare type RecursiveObjectValues<T> = T extends object ? RecursiveObjectValues<T[keyof T]> : T;
 
 declare interface SDKInternal {
@@ -2935,14 +3022,34 @@ declare type Services = {
         formatMessage: TranslationsService['formatMessage'];
         registerTranslations: TranslationsService['registerTranslations'];
     };
+    /**
+     * Services for contact book management, address autocomplete, and address validation.
+     *
+     * @example
+     * ```ts
+     * const entries = await services.address.listContactBookEntries({
+     *   params: { addressBookId: 'book_123' },
+     *   token: authToken,
+     * });
+     * ```
+     */
     address: {
+        /** Fetches a paginated list of address book entries for the given address book. */
         listContactBookEntries: ContactsService['listContactBookEntries'];
+        /** Fetches a single address book entry by ID. Returns `null` if not found. */
         getContactBookEntry: ContactsService['getContactBookEntry'];
+        /** Creates or updates an address book entry. */
         upsertContactBookEntry: ContactsService['upsertContactBookEntry'];
+        /** Deletes an address book entry. */
         deleteContactBookEntry: ContactsService['deleteContactBookEntry'];
+        /** Fetches a list of address autocomplete suggestions matching a partial query. */
         listSuggestions: AddressSuggestionsService['list'];
+        /** Resolves the full address details for a selected autocomplete suggestion. */
         resolveSuggestion: AddressSuggestionsService['resolve'];
+        /** Validates an address against the backend validation service. */
         validateAddress: AddressValidationService['validateAddress'];
+        /** Fetches configuration for rendering the address form for a specific country. */
+        getAddressFormConfig: AddressFormService['getAddressFormConfig'];
     };
 };
 
@@ -3021,6 +3128,13 @@ declare type StepEnum =
 
 declare type StyleTokens = Partial<Record<ThemeCssVariables, string>>;
 
+/**
+ * @description Text direction for form rendering.
+ */
+declare type TextDirection = TextDirectionEnum;
+
+declare type TextDirectionEnum = 'ltr' | 'rtl';
+
 declare type ThemeCssVariables = `--${RecursiveObjectValues<typeof variableNames>}`;
 
 declare const trackingArgsSchema = z.union([
@@ -3060,67 +3174,6 @@ declare interface UpdatableConfig {
     styles?: StyleTokens;
 }
 
-/**
- * @description Contact represents generic contact information.
- */
-declare type V1AlphaAddressContact = {
-    /**
-     * @description The identifier of the contact.
-     * @type string | undefined
-     */
-    contact_id?: string;
-    /**
-     * @description Represents an address suitable for delivery.
-     * @type object
-     */
-    address: AddressAddress;
-    /**
-     * @description The email address of the contact.
-     * @type string | undefined
-     */
-    email?: string;
-    /**
-     * @description A phone number, including region and optional extension.
-     * @type object | undefined
-     */
-    phone_number?: ContactPhoneNumber_2;
-    /**
-     * @description Full name associated with the contact.
-     * @type string | undefined
-     */
-    name?: string;
-    /**
-     * @description First name associated with the contact.
-     * @type string | undefined
-     */
-    first_name?: string;
-    /**
-     * @description Last name associated with the contact.
-     * @type string | undefined
-     */
-    last_name?: string;
-    /**
-     * @description National ID number associated with the contact.
-     * @type string | undefined
-     */
-    national_id_number?: string;
-    /**
-     * @description Company name associated with the contact.
-     * @type string | undefined
-     */
-    company_name?: string;
-    /**
-     * @description VAT number associated with the contact.
-     * @type string | undefined
-     */
-    vat?: string;
-    /**
-     * @description Customs number associated with the contact.
-     * @type string | undefined
-     */
-    customs_number?: string;
-};
-
 /**
  * @description Represents an address suitable for delivery.
  */
@@ -3271,6 +3324,11 @@ declare type ValidateAddressMutationRequest = ValidateAddressRequest;
  * @description Request to validate and standardize an address.
  */
 declare type ValidateAddressRequest = {
+    /**
+     * @description Site identifier, referring to which site we validate the address for.
+     * @type string
+     */
+    siteId: string;
     /**
      * @description The address to validate against postal reference data.
      */
@@ -3491,6 +3549,7 @@ declare const variableNames: {
         readonly '350': "size-350";
         readonly '400': "size-400";
         readonly '600': "size-600";
+        readonly '700': "size-700";
         readonly '800': "size-800";
         readonly '1000': "size-1000";
         readonly '1200': "size-1200";
@@ -3559,11 +3618,48 @@ declare type VerificationLevel = VerificationLevelEnum;
 
 declare type VerificationLevelEnum = 'premise' | 'street' | 'locality' | 'none';
 
-declare type WithDefault<T extends (...args: any[]) => any> = {
-    readonly __tag: 'withDefault';
+/**
+ * Opaque wrapper produced by {@link withDefaultProvider}.
+ * Carries a factory that receives the SDK's built-in implementation and returns the override.
+ *
+ * @public
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+declare type WithDefaultProvider<T extends (...args: any[]) => any> = {
+    readonly __tag: 'withDefaultProvider';
     readonly factory: (defaultFn: T) => T;
 };
 
-export declare const withDefault: <T extends (...args: any[]) => any>(factory: (defaultFn: T) => T) => WithDefault<T>;
+/**
+ * Wraps a service method override so it has access to the SDK's built-in implementation.
+ * Use this instead of a plain function replacement when you want to extend the default
+ * behaviour (e.g. add logging, modify the response) rather than replace it entirely.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * const instance = await ingrid.init({
+ *   // ...
+ *   dataProviders: {
+ *     services: {
+ *       address: {
+ *         listSuggestions: withDefaultProvider((defaultFn) => async (args) => {
+ *           console.log('Fetching suggestions for', args.params);
+ *           const result = await defaultFn(args);
+ *           console.log('Got', result.length, 'suggestions');
+ *           return result;
+ *         }),
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const withDefaultProvider: <T extends (...args: any[]) => any>(factory: (defaultFn: T) => T) => WithDefaultProvider<T>;
 
 export { }